{"openapi":"3.1.0","info":{"title":"MetalAPI","version":"1.0.0","description":"MetalAPI is a JSON REST API with real-time and historical prices for precious metals (gold XAU, silver XAG, platinum XPT, palladium XPD), industrial metals, energy, 57 currencies and 13 cryptocurrencies, plus an MCP server for AI assistants.\n\nIn `rates`, the key `<BASE><SYMBOL>` (e.g. `USDXAU`) is the price of one unit of the symbol in the base currency (USD per troy ounce of gold); the plain key (`XAU`) is its inverse, kept for compatibility with older clients.","termsOfService":"https://metalapi.com/terms","contact":{"name":"MetalAPI support","url":"https://metalapi.com/contact","email":"info@mbclabs.uk"}},"externalDocs":{"url":"https://metalapi.com/docs"},"servers":[{"url":"https://metalapi.com/api/v1"}],"security":[{"apiKeyQuery":[]},{"bearer":[]},{"apiKeyHeader":[]}],"paths":{"/latest":{"get":{"operationId":"latest","summary":"Latest rates","description":"Current rates for every requested symbol. The data you receive is as fresh as your plan's update interval allows (daily on Free, down to 5 seconds on Enterprise).\n\nAdd `XAU-BID` / `XAU-ASK` (any metal or currency) to `currencies` for the book (Standard plan and above).\n\n`timestamp` is the time of the data, not of the request.","parameters":[{"name":"base","in":"query","required":false,"description":"Currency or symbol the rates are expressed in. Default `USD`. Any supported symbol works, e.g. `EUR`, `TRY`, `XAU`.","schema":{"type":"string"},"example":"EUR"},{"name":"currencies","in":"query","required":false,"description":"Comma-separated symbols to return (alias: `symbols`). Default: all symbols. Unknown codes are ignored.","schema":{"type":"string"},"example":"XAU,XAG,EUR"},{"name":"unit","in":"query","required":false,"description":"Weight unit for metals: `troy_oz` (default), `gram`, `kilogram`, `ounce`, `pound`, `metric_ton`, `short_ton`. Ignored for currencies, energy and crypto.","schema":{"type":"string"},"example":"gram"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"timestamp":1792834892,"date":"2026-10-24","base":"USD","rates":{"XAU":0.0002501319,"USDXAU":3997.89,"XAG":0.0185392857,"USDXAG":53.94,"EUR":0.8925,"USDEUR":1.1204},"rate_limit":{"limit":10000,"remaining":9875,"reset":1793491200,"used":125,"plan":"Standard","reset_date":"2026-11-01T00:00:00.000Z"}}}}},"default":{"description":"Error (see the error codes in the API documentation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/historical":{"get":{"operationId":"historical","summary":"Historical rates","description":"Closing rates for a past day. Use `/yesterday` as a shortcut, or `/historical?date=YYYY-MM-DD`. For weekends and holidays the most recent trading day's close is returned.\n\nHistory: currencies since 1999-01-04, metals and energy since 2000, crypto since 2014.","parameters":[{"name":"date","in":"query","required":true,"description":"Day in `YYYY-MM-DD` (UTC).","schema":{"type":"string"},"example":"2024-01-15"},{"name":"base","in":"query","required":false,"description":"Currency or symbol the rates are expressed in. Default `USD`. Any supported symbol works, e.g. `EUR`, `TRY`, `XAU`.","schema":{"type":"string"},"example":"EUR"},{"name":"currencies","in":"query","required":false,"description":"Comma-separated symbols to return (alias: `symbols`). Default: all symbols. Unknown codes are ignored.","schema":{"type":"string"},"example":"XAU,XAG,EUR"},{"name":"unit","in":"query","required":false,"description":"Weight unit for metals: `troy_oz` (default), `gram`, `kilogram`, `ounce`, `pound`, `metric_ton`, `short_ton`. Ignored for currencies, energy and crypto.","schema":{"type":"string"},"example":"gram"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"timestamp":1705276800,"historical":true,"date":"2024-01-15","base":"USD","rates":{"XAU":0.0004874244,"USDXAU":2051.6,"XAG":0.0431741646,"USDXAG":23.162},"rate_limit":{"...":"..."}}}}},"default":{"description":"Error (see the error codes in the API documentation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/convert":{"get":{"operationId":"convert","summary":"Convert","description":"Convert an amount from one symbol to another, at the latest rate or on a given date.","parameters":[{"name":"from","in":"query","required":true,"description":"Symbol to convert from.","schema":{"type":"string"},"example":"USD"},{"name":"to","in":"query","required":true,"description":"Symbol to convert to.","schema":{"type":"string"},"example":"XAU"},{"name":"amount","in":"query","required":true,"description":"Amount to convert (decimal).","schema":{"type":"string"},"example":"1000"},{"name":"date","in":"query","required":false,"description":"Optional `YYYY-MM-DD` for a historical conversion.","schema":{"type":"string"}},{"name":"unit","in":"query","required":false,"description":"Weight unit for metals: `troy_oz` (default), `gram`, `kilogram`, `ounce`, `pound`, `metric_ton`, `short_ton`. Ignored for currencies, energy and crypto.","schema":{"type":"string"},"example":"gram"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"query":{"from":"USD","to":"XAU","amount":1000,"unit":"gram"},"info":{"timestamp":1792834892,"rate":0.0077799,"quote":0.0077799},"date":"2026-10-24","result":7.7799,"rate_limit":{"...":"..."}}}}},"default":{"description":"Error (see the error codes in the API documentation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/timeframe":{"get":{"operationId":"timeframe","summary":"Timeframe","description":"Daily closing rates between two dates (inclusive). `/timeseries` is an alias that returns `\"timeseries\": true`. Maximum range: 30 days on Free, 365 days on paid plans.","parameters":[{"name":"start_date","in":"query","required":true,"description":"`YYYY-MM-DD`","schema":{"type":"string"}},{"name":"end_date","in":"query","required":true,"description":"`YYYY-MM-DD`","schema":{"type":"string"}},{"name":"base","in":"query","required":false,"description":"Currency or symbol the rates are expressed in. Default `USD`. Any supported symbol works, e.g. `EUR`, `TRY`, `XAU`.","schema":{"type":"string"},"example":"EUR"},{"name":"currencies","in":"query","required":false,"description":"Comma-separated symbols to return (alias: `symbols`). Default: all symbols. Unknown codes are ignored.","schema":{"type":"string"},"example":"XAU,XAG,EUR"},{"name":"unit","in":"query","required":false,"description":"Weight unit for metals: `troy_oz` (default), `gram`, `kilogram`, `ounce`, `pound`, `metric_ton`, `short_ton`. Ignored for currencies, energy and crypto.","schema":{"type":"string"},"example":"gram"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"timeframe":true,"start_date":"2026-10-19","end_date":"2026-10-23","base":"USD","rates":{"2026-10-19":{"XAU":0.0002403788,"USDXAU":4160.1},"2026-10-20":{"XAU":0.0002413943,"USDXAU":4142.6},"2026-10-21":{"XAU":0.0002409639,"USDXAU":4150},"2026-10-22":{"XAU":0.0002462812,"USDXAU":4060.4},"2026-10-23":{"XAU":0.0002495072,"USDXAU":4007.9}},"rate_limit":{"...":"..."}}}}},"default":{"description":"Error (see the error codes in the API documentation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/change":{"get":{"operationId":"change","summary":"Change","description":"How each rate moved between two dates, as absolute and percentage change.","parameters":[{"name":"start_date","in":"query","required":true,"description":"`YYYY-MM-DD`","schema":{"type":"string"}},{"name":"end_date","in":"query","required":true,"description":"`YYYY-MM-DD`","schema":{"type":"string"}},{"name":"base","in":"query","required":false,"description":"Currency or symbol the rates are expressed in. Default `USD`. Any supported symbol works, e.g. `EUR`, `TRY`, `XAU`.","schema":{"type":"string"},"example":"EUR"},{"name":"currencies","in":"query","required":false,"description":"Comma-separated symbols to return (alias: `symbols`). Default: all symbols. Unknown codes are ignored.","schema":{"type":"string"},"example":"XAU,XAG,EUR"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"change":true,"start_date":"2026-01-02","end_date":"2026-10-23","base":"USD","rates":{"XAU":{"start_rate":0.0002309682,"end_rate":0.0002495072,"change":0.000018539,"change_pct":8.02665},"USDXAU":{"start_rate":4329.6,"end_rate":4007.9,"change":-321.7,"change_pct":-7.43025}},"rate_limit":{"...":"..."}}}}},"default":{"description":"Error (see the error codes in the API documentation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ohlc":{"get":{"operationId":"ohlc","summary":"Open / High / Low / Close","description":"Daily OHLC for a date (default: today, intraday so far). Both directions are returned: `USDXAU` in USD per unit and `XAU` as the inverse.","parameters":[{"name":"date","in":"query","required":false,"description":"`YYYY-MM-DD` or `latest` (default).","schema":{"type":"string"}},{"name":"base","in":"query","required":false,"description":"Currency or symbol the rates are expressed in. Default `USD`. Any supported symbol works, e.g. `EUR`, `TRY`, `XAU`.","schema":{"type":"string"},"example":"EUR"},{"name":"currencies","in":"query","required":false,"description":"Comma-separated symbols to return (alias: `symbols`). Default: all symbols. Unknown codes are ignored.","schema":{"type":"string"},"example":"XAU,XAG,EUR"},{"name":"unit","in":"query","required":false,"description":"Weight unit for metals: `troy_oz` (default), `gram`, `kilogram`, `ounce`, `pound`, `metric_ton`, `short_ton`. Ignored for currencies, energy and crypto.","schema":{"type":"string"},"example":"gram"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"ohlc":true,"date":"2026-10-23","base":"USD","rates":{"USDXAU":{"open":4042.2,"high":4050.2,"low":3989.1,"close":4007.9},"XAU":{"open":0.00024739,"high":0.000250683,"low":0.000246901,"close":0.000249507}},"rate_limit":{"...":"..."}}}}},"default":{"description":"Error (see the error codes in the API documentation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/carat":{"get":{"operationId":"carat","summary":"Gold by karat","description":"Gold price for jewellery karats (purity = karat / 24). Paid plans.","parameters":[{"name":"carat","in":"query","required":false,"description":"`24` (default), `23`, `22`, `21`, `20`, `18`, `16`, `14`, `12`, `10`, `9`, `8` or `all`.","schema":{"type":"string"}},{"name":"base","in":"query","required":false,"description":"Currency or symbol the rates are expressed in. Default `USD`. Any supported symbol works, e.g. `EUR`, `TRY`, `XAU`.","schema":{"type":"string"},"example":"EUR"},{"name":"unit","in":"query","required":false,"description":"Weight unit for metals: `troy_oz` (default), `gram`, `kilogram`, `ounce`, `pound`, `metric_ton`, `short_ton`. Ignored for currencies, energy and crypto.","schema":{"type":"string"},"example":"gram"},{"name":"date","in":"query","required":false,"description":"Optional `YYYY-MM-DD`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"carat":"22","date":"2026-10-24","base":"EUR","timestamp":1792834892,"rates":{"XAU22K":{"price":105.5297,"unit":"gram","carat":"22","purity":0.916667}},"rate_limit":{"...":"..."}}}}},"default":{"description":"Error (see the error codes in the API documentation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/symbols":{"get":{"operationId":"symbols","summary":"Symbols","description":"Every supported symbol and its name. Add `details=1` for category and unit.\n\nFree — does not count towards your quota.","parameters":[{"name":"details","in":"query","required":false,"description":"`1` to return an array with `code`, `name`, `category`, `unit`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"symbols":{"XAU":"Gold","XAG":"Silver","XPT":"Platinum","XPD":"Palladium","XCU":"Copper","USD":"US Dollar","EUR":"Euro","BTC":"Bitcoin"},"rate_limit":{"...":"..."}}}}},"default":{"description":"Error (see the error codes in the API documentation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/usage":{"get":{"operationId":"usage","summary":"Usage","description":"Your requests this month and what is left.\n\nFree — does not count towards your quota.","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"usage":{"requests_made":125,"requests_quota":10000,"requests_remaining":9875,"plan":"standard","period_start":"2026-10-01T00:00:00.000Z","period_end":"2026-11-01T00:00:00.000Z"},"result":{"plan":"Standard","used":125,"total":10000,"remaining":9875},"rate_limit":{"...":"..."}}}}},"default":{"description":"Error (see the error codes in the API documentation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKeyQuery":{"type":"apiKey","in":"query","name":"api_key"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"},"bearer":{"type":"http","scheme":"bearer","description":"Your API key as a Bearer token"}},"schemas":{"Error":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"integer"},"type":{"type":"string"},"info":{"type":"string"},"upgrade_url":{"type":"string","format":"uri"}},"required":["code","type","info"]}}}}}}