{
  "openapi": "3.1.0",
  "info": {
    "title": "GoldAPI.io Precious Metals Prices API",
    "description": "GoldAPI.io provides real-time and historical precious metals price data for gold, silver, platinum and palladium across major global currencies. Use it to build gold price widgets, bullion dealer tools, jewelry calculators, trading dashboards, portfolio apps, AI agents, automation workflows and financial applications.",
    "version": "1.0.0",
    "contact": {
      "name": "GoldAPI.io Support",
      "email": "support@goldapi.io",
      "url": "https://www.goldapi.io"
    },
    "license": {
      "name": "Commercial",
      "url": "https://www.goldapi.io/terms"
    }
  },
  "externalDocs": {
    "description": "GoldAPI.io API Documentation",
    "url": "https://www.goldapi.io/api-documentation"
  },
  "servers": [
    {
      "url": "https://www.goldapi.io",
      "description": "GoldAPI.io production API"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Prices",
      "description": "Live and historical precious metals prices"
    },
    {
      "name": "Status",
      "description": "API status and account information"
    }
  ],
  "paths": {
    "/api/{metal}/{currency}": {
      "get": {
        "tags": [
          "Prices"
        ],
        "operationId": "getLiveMetalPrice",
        "summary": "Get live precious metal price",
        "description": "Returns the latest spot price for a precious metal in the selected currency.",
        "parameters": [
          {
            "$ref": "#/components/parameters/MetalPathParameter"
          },
          {
            "$ref": "#/components/parameters/CurrencyPathParameter"
          }
        ],
        "responses": {
          "200": {
            "description": "Latest precious metal spot price.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LivePriceResponse"
                },
                "examples": {
                  "liveGoldUsd": {
                    "summary": "Live gold price in USD",
                    "value": {
                      "timestamp": 1716000000,
                      "metal": "XAU",
                      "currency": "USD",
                      "exchange": "FOREXCOM",
                      "symbol": "FOREXCOM:XAUUSD",
                      "prev_close_price": 2380.12,
                      "open_price": 2382.44,
                      "low_price": 2374.91,
                      "high_price": 2395.63,
                      "open_time": 1715990400,
                      "price": 2391.72,
                      "ch": 11.6,
                      "chp": 0.49
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/api/{metal}/{currency}/{date}": {
      "get": {
        "tags": [
          "Prices"
        ],
        "operationId": "getHistoricalMetalPrice",
        "summary": "Get historical precious metal price",
        "description": "Returns the historical spot price for a precious metal in the selected currency for a specific date.",
        "parameters": [
          {
            "$ref": "#/components/parameters/MetalPathParameter"
          },
          {
            "$ref": "#/components/parameters/CurrencyPathParameter"
          },
          {
            "name": "date",
            "in": "path",
            "required": true,
            "description": "Historical date in YYYYMMDD format.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{8}$",
              "examples": [
                "20250101"
              ]
            },
            "examples": {
              "newYearsDay2025": {
                "summary": "January 1, 2025",
                "value": "20250101"
              },
              "endOfYear2024": {
                "summary": "December 31, 2024",
                "value": "20241231"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Historical precious metal spot price.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HistoricalPriceResponse"
                },
                "examples": {
                  "historicalGoldUsd": {
                    "summary": "Historical gold price in USD",
                    "value": {
                      "timestamp": 1735689600,
                      "date": "20250101",
                      "metal": "XAU",
                      "currency": "USD",
                      "exchange": "FOREXCOM",
                      "symbol": "FOREXCOM:XAUUSD",
                      "prev_close_price": 2624.18,
                      "open_price": 2624.18,
                      "low_price": 2624.18,
                      "high_price": 2624.18,
                      "open_time": 1735689600,
                      "price": 2624.18,
                      "ch": 0,
                      "chp": 0
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/api/status": {
      "get": {
        "tags": [
          "Status"
        ],
        "operationId": "getApiStatus",
        "summary": "Get API status",
        "description": "Returns API status or account/request information if available.",
        "responses": {
          "200": {
            "description": "API status response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusResponse"
                },
                "examples": {
                  "ok": {
                    "summary": "Status check succeeded",
                    "value": {
                      "result": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-access-token",
        "description": "GoldAPI.io API key. Pass your key as the x-access-token request header."
      }
    },
    "parameters": {
      "MetalPathParameter": {
        "name": "metal",
        "in": "path",
        "required": true,
        "description": "Precious metal symbol.",
        "schema": {
          "$ref": "#/components/schemas/MetalSymbol"
        },
        "examples": {
          "gold": {
            "summary": "Gold",
            "value": "XAU"
          },
          "silver": {
            "summary": "Silver",
            "value": "XAG"
          },
          "platinum": {
            "summary": "Platinum",
            "value": "XPT"
          },
          "palladium": {
            "summary": "Palladium",
            "value": "XPD"
          }
        }
      },
      "CurrencyPathParameter": {
        "name": "currency",
        "in": "path",
        "required": true,
        "description": "Currency code used to quote the metal price.",
        "schema": {
          "$ref": "#/components/schemas/CurrencyCode"
        },
        "examples": {
          "usd": {
            "summary": "US dollar",
            "value": "USD"
          },
          "aud": {
            "summary": "Australian dollar",
            "value": "AUD"
          },
          "eur": {
            "summary": "Euro",
            "value": "EUR"
          },
          "aed": {
            "summary": "UAE dirham",
            "value": "AED"
          }
        }
      }
    },
    "schemas": {
      "MetalSymbol": {
        "type": "string",
        "description": "Precious metal symbol.",
        "enum": [
          "XAU",
          "XAG",
          "XPT",
          "XPD"
        ]
      },
      "CurrencyCode": {
        "type": "string",
        "description": "Supported quote currency.",
        "enum": [
          "AED",
          "AUD",
          "BTC",
          "CAD",
          "CHF",
          "CNY",
          "CZK",
          "EGP",
          "EUR",
          "GBP",
          "HKD",
          "INR",
          "JOD",
          "JPY",
          "KRW",
          "KWD",
          "MXN",
          "MYR",
          "OMR",
          "PLN",
          "RUB",
          "SAR",
          "SGD",
          "THB",
          "USD",
          "ZAR"
        ]
      },
      "LivePriceResponse": {
        "type": "object",
        "description": "Live precious metal spot price response.",
        "properties": {
          "timestamp": {
            "type": "integer",
            "description": "Unix timestamp for the returned price.",
            "examples": [
              1716000000
            ]
          },
          "metal": {
            "$ref": "#/components/schemas/MetalSymbol"
          },
          "currency": {
            "$ref": "#/components/schemas/CurrencyCode"
          },
          "exchange": {
            "type": "string",
            "description": "Exchange or data source identifier.",
            "examples": [
              "FOREXCOM"
            ]
          },
          "symbol": {
            "type": "string",
            "description": "Market symbol for the metal and currency pair.",
            "examples": [
              "FOREXCOM:XAUUSD"
            ]
          },
          "prev_close_price": {
            "type": "number",
            "description": "Previous close price."
          },
          "open_price": {
            "type": "number",
            "description": "Open price."
          },
          "low_price": {
            "type": "number",
            "description": "Low price for the current session."
          },
          "high_price": {
            "type": "number",
            "description": "High price for the current session."
          },
          "open_time": {
            "type": "integer",
            "description": "Unix timestamp for the session open time."
          },
          "price": {
            "type": "number",
            "description": "Latest spot price."
          },
          "ch": {
            "type": "number",
            "description": "Absolute price change."
          },
          "chp": {
            "type": "number",
            "description": "Percentage price change."
          }
        },
        "additionalProperties": true
      },
      "HistoricalPriceResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/LivePriceResponse"
          },
          {
            "type": "object",
            "description": "Historical precious metal spot price response.",
            "properties": {
              "date": {
                "type": "string",
                "description": "Historical date in YYYYMMDD format when present.",
                "pattern": "^[0-9]{8}$",
                "examples": [
                  "20250101"
                ]
              }
            },
            "additionalProperties": true
          }
        ]
      },
      "StatusResponse": {
        "type": "object",
        "description": "API status or account/request information response.",
        "properties": {
          "result": {
            "type": "boolean",
            "description": "Whether the status check succeeded.",
            "examples": [
              true
            ]
          }
        },
        "additionalProperties": true
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Error response.",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error name or category.",
            "examples": [
              "Unauthorized"
            ]
          },
          "message": {
            "type": "string",
            "description": "Human-readable error message.",
            "examples": [
              "Invalid or missing API key"
            ]
          },
          "statusCode": {
            "type": "integer",
            "description": "HTTP status code.",
            "examples": [
              401
            ]
          }
        },
        "additionalProperties": true
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request parameters.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "badRequest": {
                "summary": "Invalid request",
                "value": {
                  "error": "Bad Request",
                  "message": "Invalid metal, currency or date parameter",
                  "statusCode": 400
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Invalid or missing API key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "unauthorized": {
                "summary": "Unauthorized",
                "value": {
                  "error": "Unauthorized",
                  "message": "Invalid or missing API key",
                  "statusCode": 401
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Requested resource was not found.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "notFound": {
                "summary": "Not found",
                "value": {
                  "error": "Not Found",
                  "message": "The requested resource was not found",
                  "statusCode": 404
                }
              }
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Rate limit exceeded.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "tooManyRequests": {
                "summary": "Rate limit exceeded",
                "value": {
                  "error": "Too Many Requests",
                  "message": "Rate limit exceeded",
                  "statusCode": 429
                }
              }
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Unexpected server error.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "serverError": {
                "summary": "Internal server error",
                "value": {
                  "error": "Internal Server Error",
                  "message": "An unexpected error occurred",
                  "statusCode": 500
                }
              }
            }
          }
        }
      }
    }
  }
}