{"openapi":"3.1.0","info":{"title":"MetalpriceAPI (BYOK) API","version":"0.1.0","description":"MetalpriceAPI (BYOK) lets an AI assistant read your own MetalpriceAPI data through the MetalpriceAPI API with a key you supply (MetalpriceAPI key). Read-only: 10 tools (list_symbols, get_latest_rates, get_historical_rates, get_hourly_rates, get_ohlc, convert_currency, get_timeframe_rates, get_rate_change, get_carat_prices, get_usage). The BYOK key travels with each request, is used for that one...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-metalpriceapi.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-metalpriceapi/docs"},"termsOfService":"https://connectorbay.com/byok-metalpriceapi/terms"},"servers":[{"url":"https://byok-metalpriceapi.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-metalpriceapi/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_symbols":{"post":{"operationId":"list_symbols","summary":"List every supported currency and metal code with its name. This call does not count toward the monthly quota. Use for \"","description":"List every supported currency and metal code with its name. This call does not count toward the monthly quota. Use for \"Which currency and metal symbols does MetalpriceAPI support\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_symbolsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_latest_rates":{"post":{"operationId":"get_latest_rates","summary":"Get the latest (plan-delayed) rates for forex currencies and precious metals relative to a base currency. Metals are per","description":"Get the latest (plan-delayed) rates for forex currencies and precious metals relative to a base currency. Metals are per troy ounce unless a unit is chosen; keys starting with the base code (such as USDXAU) are the inverse price. Use for \"What is the gold price in euros right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"base":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":"USD","description":"Three-letter base currency or metal code the rates are relative to (default USD).","title":"Base"},"currencies":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated currency or metal codes to limit the answer to, for example 'EUR,XAU,XAG'. Empty returns everything.","title":"Currencies"},"unit":{"anyOf":[{"enum":["troy_oz","gram","kilogram"],"type":"string"},{"type":"null"}],"default":null,"description":"Weight unit for metal rates (paid plans): troy_oz, gram or kilogram. Empty means troy ounce.","title":"Unit"}},"title":"get_latest_ratesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_historical_rates":{"post":{"operationId":"get_historical_rates","summary":"Get the rates of one past day. Yesterday's data is available from 00:05 GMT. Use for \"What was the silver price on 2025-","description":"Get the rates of one past day. Yesterday's data is available from 00:05 GMT. Use for \"What was the silver price on 2025-03-14\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"date":{"description":"A date as YYYY-MM-DD, or the word 'yesterday'.","maxLength":200,"title":"Date","type":"string"},"base":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":"USD","description":"Three-letter base currency or metal code the rates are relative to (default USD).","title":"Base"},"currencies":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated currency or metal codes to limit the answer to, for example 'EUR,XAU,XAG'. Empty returns everything.","title":"Currencies"},"unit":{"anyOf":[{"enum":["troy_oz","gram","kilogram"],"type":"string"},{"type":"null"}],"default":null,"description":"Weight unit for metal rates (paid plans): troy_oz, gram or kilogram. Empty means troy ounce.","title":"Unit"}},"required":["date"],"title":"get_historical_ratesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_hourly_rates":{"post":{"operationId":"get_hourly_rates","summary":"Get hourly rates for ONE currency or metal over a date range (free plans up to 2 days, paid up to 7; history starts 2025","description":"Get hourly rates for ONE currency or metal over a date range (free plans up to 2 days, paid up to 7; history starts 2025-06-19). Use for \"Show hourly gold prices for 2025-11-03\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"currency":{"description":"A single currency or metal code, for example XAU.","maxLength":10,"title":"Currency","type":"string"},"base":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":"USD","description":"Three-letter base currency or metal code the rates are relative to (default USD).","title":"Base"},"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"First day, YYYY-MM-DD (default today). Do not combine with start/end timestamps.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Last day, YYYY-MM-DD (default today).","title":"End Date"},"unit":{"anyOf":[{"enum":["troy_oz","gram","kilogram"],"type":"string"},{"type":"null"}],"default":null,"description":"Weight unit for metal rates (paid plans): troy_oz, gram or kilogram. Empty means troy ounce.","title":"Unit"}},"required":["currency"],"title":"get_hourly_ratesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_ohlc":{"post":{"operationId":"get_ohlc","summary":"Get the open, high, low and close rate of a currency pair for one UTC day (the previous day is available from 00:05 GMT)","description":"Get the open, high, low and close rate of a currency pair for one UTC day (the previous day is available from 00:05 GMT). Use for \"What were the open, high, low and close for gold in USD on 2025-01-28\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"base":{"description":"Base currency or metal code, for example XAU.","maxLength":10,"title":"Base","type":"string"},"currency":{"description":"Quote currency or metal code, for example USD.","maxLength":10,"title":"Currency","type":"string"},"date":{"description":"Day as YYYY-MM-DD.","maxLength":10,"title":"Date","type":"string"},"unit":{"anyOf":[{"enum":["troy_oz","gram","kilogram"],"type":"string"},{"type":"null"}],"default":null,"description":"Weight unit for metal rates (paid plans): troy_oz, gram or kilogram. Empty means troy ounce.","title":"Unit"}},"required":["base","currency","date"],"title":"get_ohlcArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/convert_currency":{"post":{"operationId":"convert_currency","summary":"Convert an amount between two currencies or metals at the live rate, or at a historical rate for a given date. Use for \"","description":"Convert an amount between two currencies or metals at the live rate, or at a historical rate for a given date. Use for \"How many ounces of gold is 5000 USD worth\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"to":{"description":"Currency or metal code to convert to.","maxLength":10,"title":"To","type":"string"},"amount":{"description":"Amount to convert.","title":"Amount","type":"number"},"from_currency":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":"USD","description":"Currency or metal code to convert from (default USD).","title":"From Currency"},"date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Optional date YYYY-MM-DD to use the historical rate.","title":"Date"},"unit":{"anyOf":[{"enum":["troy_oz","gram","kilogram"],"type":"string"},{"type":"null"}],"default":null,"description":"Weight unit for metal rates (paid plans): troy_oz, gram or kilogram. Empty means troy ounce.","title":"Unit"}},"required":["to","amount"],"title":"convert_currencyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_timeframe_rates":{"post":{"operationId":"get_timeframe_rates","summary":"Get daily rates for a date range of at most 365 days. Use for \"Show daily silver rates for April 2025\".","description":"Get daily rates for a date range of at most 365 days. Use for \"Show daily silver rates for April 2025\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"description":"First day, YYYY-MM-DD.","maxLength":10,"title":"Start Date","type":"string"},"end_date":{"description":"Last day, YYYY-MM-DD.","maxLength":10,"title":"End Date","type":"string"},"base":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":"USD","description":"Three-letter base currency or metal code the rates are relative to (default USD).","title":"Base"},"currencies":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated currency or metal codes to limit the answer to, for example 'EUR,XAU,XAG'. Empty returns everything.","title":"Currencies"},"unit":{"anyOf":[{"enum":["troy_oz","gram","kilogram"],"type":"string"},{"type":"null"}],"default":null,"description":"Weight unit for metal rates (paid plans): troy_oz, gram or kilogram. Empty means troy ounce.","title":"Unit"}},"required":["start_date","end_date"],"title":"get_timeframe_ratesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_rate_change":{"post":{"operationId":"get_rate_change","summary":"Get the start rate, end rate, absolute change and percent change per currency or metal between two dates or over a perio","description":"Get the start rate, end rate, absolute change and percent change per currency or metal between two dates or over a period. Use for \"How much did gold change over the last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"First day, YYYY-MM-DD (ignored when date_type is set).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Last day, YYYY-MM-DD (ignored when date_type is set).","title":"End Date"},"date_type":{"anyOf":[{"enum":["recent","yesterday","week","month","year"],"type":"string"},{"type":"null"}],"default":null,"description":"Shortcut period overriding the dates: recent, yesterday, week, month or year.","title":"Date Type"},"base":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":"USD","description":"Three-letter base currency or metal code the rates are relative to (default USD).","title":"Base"},"currencies":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated currency or metal codes to limit the answer to, for example 'EUR,XAU,XAG'. Empty returns everything.","title":"Currencies"}},"title":"get_rate_changeArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_carat_prices":{"post":{"operationId":"get_carat_prices","summary":"Get the gold price per gram for each carat (24k down to 6k) in a base currency, live or for a date (paid plans). Use for","description":"Get the gold price per gram for each carat (24k down to 6k) in a base currency, live or for a date (paid plans). Use for \"What is a gram of 18k gold in USD today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"base":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":"USD","description":"Three-letter base currency or metal code the rates are relative to (default USD).","title":"Base"},"currency":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":"XAU","description":"Metal code to price (default XAU, gold).","title":"Currency"},"date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Optional date YYYY-MM-DD for historical carat prices.","title":"Date"}},"title":"get_carat_pricesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_usage":{"post":{"operationId":"get_usage","summary":"Show the key's plan name and this month's used, total and remaining request quota. This call does not count toward the q","description":"Show the key's plan name and this month's used, total and remaining request quota. This call does not count toward the quota. Use for \"How much of my MetalpriceAPI quota is left this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_usageArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}