Currency API JSON Schema: EZRate Endpoints, Headers and Error Codes
The EZRate currency API JSON schema reference: base URL, authentication, every endpoint with parameters and fields, rate-limit headers and error codes.
- Base URL `https://api.ezrate.me/v1`; authenticate with `X-API-Key` (or `Authorization: Bearer`).
- Every success response is `{ data, meta }`; every error is `{ error: { code, message, fields? }, meta? }`.
- This page documents each endpoint’s parameters and fields; plan limits are listed on the API page.
This is the technical reference for the EZRate API. It documents the currency API JSON schema for every endpoint, the headers you will see and every error code. Bookmark it next to your editor.
https://api.ezrate.me/v1. Auth: header X-API-Key: <key> (or Authorization: Bearer <key>). Success: {"data": …, "meta": {"as_of", "freshness_sec", "quote"}}. Errors: {"error": {"code", "message", "fields"?}} with HTTP status 401, 403, 404, 422 or 429. Prices default to Toman (IRT).New here? Start with the quickstart. Concepts are in the API guide.
Authentication
curl -H "X-API-Key: $EZRATE_KEY" https://api.ezrate.me/v1/assets
# or
curl -H "Authorization: Bearer $EZRATE_KEY" https://api.ezrate.me/v1/assetsThe rate object
| Field | Type | Description |
|---|---|---|
symbol | string | Lower-case identifier, e.g. usd, g18, emami, usdt |
code | string | Display code, e.g. USD |
name | string | Localised name (lang=fa|en) |
category | string | e.g. fiat, gold, coin, crypto |
market | string | tehran, herat, sulaymaniyah, dubai, istanbul… |
buy, sell | number | Prices in quote units; integers for IRT/IRR |
change_pct | number | Change over 24 hours, percent |
usd | number | Equivalent in free-market USD (where applicable) |
sources | integer | Number of sources in the latest calculation |
low_sources | boolean | True when fewer than five sources were available |
updated_at | string | ISO 8601 UTC time of the last update of this rate |
quote | string | Unit of the prices |
The meta object
| Field | Description |
|---|---|
as_of | Time of the snapshot (ISO 8601 UTC) |
freshness_sec | Data freshness of your plan; do not poll faster |
quote | Unit used in this response |
Endpoints
GET /assets
Parameters: category (optional). Returns symbol, code, name, name_fa, name_en, category, slug, unit, decimals, markets[].
GET /rates
Parameters: symbols (comma list), category, market, quote (IRT, IRR or an asset symbol), lang. Returns an array of rate objects (the reference market per asset unless market is set).
curl -H "X-API-Key: $EZRATE_KEY" "https://api.ezrate.me/v1/rates?symbols=usd,eur,g18"e=IRR&lang=en"GET /rates/{symbol}
Parameters: market, quote, lang. Returns one rate object plus markets[] with the asset in every market.
GET /history/{symbol}
Parameters: interval (1h, 1d), from, to, market, quote (IRT/IRR). Returns candles {t, o, h, l, c} (sell side, UTC) and meta {symbol, interval, market, quote, count}.
GET /convert
Parameters: from, to (asset symbols or irt/irr), amount, side (buy, sell default, mid). Returns {from, to, amount, side, rate, inverse_rate, result, as_of}.
{ "data": { "from": "usd", "to": "eur", "amount": 100, "side": "mid",
"rate": 0.0, "inverse_rate": 0.0, "result": 0.0, "as_of": "…" } }GET /cross
Parameters: base, symbols. Returns {base, side: "mid", rates: {symbol: rate}} — how many units of each symbol one unit of base is worth.
GET /global
Parameters: base (default USD). International reference rates {base, rates: {EUR: "…"}, as_of} — not Tehran prices.
GET /markets/{symbol}
Returns the asset in each market: {market, name, buy, sell, diff_pct_vs_reference, updated_at}.
GET /usage
Returns {plan, day: {used, limit}, month: {used, limit}}. Does not count against your quota.
Headers
| Header | Meaning |
|---|---|
X-RateLimit-Limit-Day / X-RateLimit-Remaining-Day | Daily quota and what is left |
X-RateLimit-Limit-Month / X-RateLimit-Remaining-Month | Monthly quota and what is left |
X-Data-Freshness | Freshness of the data you received |
Retry-After | Seconds to wait after a 429 |
Errors
{ "error": { "code": "validation_failed", "message": "…", "fields": { "quote": ["IRT, IRR or an asset symbol"] } } }| HTTP | code | When |
|---|---|---|
| 401 | invalid_api_key | Key missing, wrong or revoked |
| 403 | forbidden | Request from an IP/domain not allowed for the key |
| 404 | not_found | Unknown symbol or market, or asset not in the API |
| 422 | validation_failed | Invalid parameter; see fields |
| 429 | rate_limited | Per-second or quota limit; see Retry-After and meta.reset_at |
How to handle each one: financial API failover.
Notes
- There is no WebSocket endpoint; rates refresh every 60 seconds. See WebSocket vs REST.
- Plan quotas, freshness and history depth are listed on the API page.
- Never call the API from browsers with your key: securing API keys.
Related live rates: US dollar rate, 18K gold price, Emami coin price.
Comments (0)
Comments are shown after review. Sign-in is needed to send.
