EZRate API Quickstart: From API Key to Your First Live Request in 5 Minutes

This EZRate API quickstart gets you from zero to a live Tehran free-market dollar rate in five minutes. No SDK needed — any HTTP client works.

Step 1: create an account and a key

1. Go to the API page and sign up (email, Google or Telegram login).
2. Open the user panel → API keys → New key.
3. Name it after its use (e.g. “production-backend”) and, ideally, restrict it to your server IPs.
4. Copy the key and store it as an environment variable. Never commit it.

export EZRATE_KEY="paste-your-key-here"

Step 2: your first request

curl -s -H "X-API-Key: $EZRATE_KEY" \
  "https://api.ezrate.me/v1/rates?symbols=usd,eur,g18&lang=en"

{
  "data": [
    { "symbol": "usd", "code": "USD", "name": "US Dollar", "market": "tehran",
      "buy": 0, "sell": 0, "change_pct": 0.0, "sources": 12, "low_sources": false,
      "updated_at": "…", "quote": "IRT" },
    { "symbol": "eur", "…": "…" },
    { "symbol": "g18", "…": "…" }
  ],
  "meta": { "as_of": "…", "freshness_sec": 60, "quote": "IRT" }
}

The same request in your language

Python

import os, requests
r = requests.get("https://api.ezrate.me/v1/rates", params={"symbols": "usd"},
                 headers={"X-API-Key": os.environ["EZRATE_KEY"]}, timeout=10)
print(r.json()["data"][0]["sell"])

JavaScript (Node 18+)

const r = await fetch("https://api.ezrate.me/v1/rates?symbols=usd",
  { headers: { "X-API-Key": process.env.EZRATE_KEY } });
console.log((await r.json()).data[0].sell);

PHP

$ctx = stream_context_create(['http' => ['header' => "X-API-Key: ".getenv('EZRATE_KEY')]]);
$body = json_decode(file_get_contents('https://api.ezrate.me/v1/rates?symbols=usd', false, $ctx), true);
echo $body['data'][0]['sell'];

Step 3: read the response

Step 4: check your usage

curl -s -H "X-API-Key: $EZRATE_KEY" https://api.ezrate.me/v1/usage

/usage does not count against your quota. Rate-limit headers (X-RateLimit-Remaining-Day, …-Month) come with every response.

Common first-run errors

Next steps

• Full schema and every endpoint: JSON reference.
• Concepts (free market vs official, Rial vs Toman): API guide.
• Keep your key safe: securing API keys.
• Stack tutorials: Python/Django, Laravel, React.
• Gold and coins: Iran gold price API.

What to build next

With a working request you can choose a direction. For a website, add server-side caching and a small endpoint for your front end. For a spreadsheet, follow the Google Sheets or Excel guide. For a Telegram channel, the no-code poster may be all you need. Whatever you build, keep the key on the server, cache for the freshness window and show the update time next to every number — those three habits prevent most integration problems.

If something does not work, check the status code first: 401 and 403 are configuration issues, 422 means a parameter is wrong, 429 means you are calling too often. The error body always contains a machine-readable code and a human-readable message.

Security from day one

Even for a first experiment, treat the key like a password. Keep it in an environment variable, add your local .env file to .gitignore, and create separate keys for development and production so you can revoke one without affecting the other. When you move to production, restrict the key to your server IPs in the panel. If you ever paste a key into a chat, a ticket or a public repository, rotate it immediately.

These habits take two minutes to set up and save hours of cleanup later.

Related live rates: US dollar rate, 18K gold price, Emami coin price.