Docs · Chand.API Reference

Quick start

Every endpoint is a plain GET request that returns application/json. The relative paths below resolve against the base URL https://chand.pages.dev.

cURL

curl -s https://chand.pages.dev/api

JavaScript

const res = await fetch("https://chand.pages.dev/api");

if (!res.ok) {
  throw new Error(`Chand.API returned ${res.status}`);
}

const data = await res.json();

console.log(data.updated);         // "August 14, 2025 09:30"
console.log(data.fiat.USD.sell);   // 92500
console.log(data.gold.azadi.sell); // 54320000

Python

import requests

res = requests.get("https://chand.pages.dev/api", timeout=10)
res.raise_for_status()
data = res.json()

print(data["fiat"]["USD"]["sell"])
print(data["gold"]["emami"]["sell"])

Values are integers in Iranian Toman. All prices are returned as plain numbers with no separators or currency symbols — for example 92500 means 92,500 Toman.

Endpoints

All three endpoints scrape the same upstream feed and differ only in how they shape the response. Pick the schema that matches your integration.

Endpoint	Status	Response shape
/api	Recommended	`{ sell, buy, icon }` objects with SVG icons
/legacy	Supported	Objects for fiat & coins, scalars for bullion
/deprecated	Deprecated	Scalars only, no icon assets

New integrations should use /api. /legacy and /deprecated exist only for older clients and may be removed in a future major version.

GET

/api

Recommended

The primary endpoint. Returns fiat currencies, gold coins, and bullion as { sell, buy, icon } objects, plus a single crypto and market entry.

Open live JSON

200 OK · response (truncated)

{
  "_comment": "Chand.API v1.0.1 — Homepage: chand.pages.dev — Source data: bonbast.com — Responses are cached for 60s and are free to use with attribution.",
  "success": true,
  "updated": "August 14, 2025 09:30",
  "fiat": {
    "USD": {
      "sell": 92500,
      "buy": 92100,
      "icon": "https://raw.githubusercontent.com/.../flags/us.svg"
    }
  },
  "gold": {
    "azadi": {
      "sell": 54320000,
      "buy": 54100000,
      "icon": "https://platform.tgju.org/files/images/gold-1697963734.png"
    },
    "gram18": {
      "sell": 7460000,
      "icon": "https://platform.tgju.org/files/images/gold-bar-1-1622253841.png"
    }
  },
  "crypto": {
    "bitcoin": {
      "sell": 6421000000000,
      "icon": "https://alanchand.com/assets/img/crypto/BTC.svg"
    }
  },
  "market": {
    "bourse": {
      "sell": 2105000,
      "icon": "https://static.tgju.org/images/no-icon.png"
    }
  }
}

GET

/legacy

Supported

Backward‑compatible schema. Fiat currencies and gold coins keep their sell/buy/icon objects, but gram18, mithqal, ounce, bitcoin, and bourse are returned as raw scalars instead of objects.

Open live JSON

200 OK · response (truncated)

{
  "_comment": "Chand.API v1.0.1 — Homepage: chand.pages.dev — Source data: bonbast.com — Responses are cached for 60s and are free to use with attribution.",
  "success": true,
  "updated": "August 14, 2025 09:30",
  "fiat": {
    "USD": { "sell": 92500, "buy": 92100, "icon": "https://.../us.svg" }
  },
  "gold": {
    "azadi":  { "sell": 54320000, "buy": 54100000, "icon": "https://.../gold.png" },
    "gram18": 7460000,
    "mithqal": 32000000,
    "ounce": 2105000
  },
  "crypto": { "bitcoin": 6421000000000 },
  "market": { "bourse": 2105000 }
}

GET

/deprecated

Deprecated

The original minimal schema. Every value is a scalar and no icon fields are emitted at all, which keeps payloads small for older clients that never rendered flags or coin artwork.

Open live JSON

200 OK · response (truncated)

{
  "_comment": "Chand.API v1.0.1 — Homepage: chand.pages.dev — Source data: bonbast.com — Responses are cached for 60s and are free to use with attribution.",
  "success": true,
  "updated": "August 14, 2025 09:30",
  "fiat": {
    "USD": { "sell": 92500, "buy": 92100 }
  },
  "gold": {
    "azadi":   { "sell": 54320000, "buy": 54100000 },
    "gram18":  7460000,
    "mithqal": 32000000,
    "ounce":   2105000
  },
  "crypto": { "bitcoin": 6421000000000 },
  "market": { "bourse": 2105000 }
}

Response schema

Top‑level fields returned by /api. Object schemas below use TypeScript notation.

Field	Type	Description
`_comment`	string	Always the first key. Site information, source attribution, and cache notice.
`success`	boolean	`true` on success, `false` on failure.
`updated`	string	Upstream last‑modified time as `"Month DD, YYYY HH:MM"` in UTC. Empty string if unavailable.
`fiat`	object	Map of ISO currency code → rate object. Only codes present upstream are included.
`gold`	object	Gold coins plus bullion entries (`gram18`, `mithqal`, `ounce`).
`crypto`	object	Cryptocurrency rates. Currently exposes `bitcoin`.
`market`	object	Tehran Stock Exchange data. Currently exposes `bourse` (TEDPIX).

Rate object

Fiat and gold‑coin entries share the same shape. Bullion, crypto, and market entries expose sell and icon only.

TypeScript

interface Rate {
  sell: number;   // selling price, Iranian Toman
  buy: number;    // buying price (fiat & coins only; falls back to `sell`)
  icon?: string;  // absolute URL — omitted on /deprecated
}

Gold entries

Key	Type	Description
`azadi`	Rate	Full Azadi gold coin (بهار آزادی).
`emami`	Rate	Emami gold coin (سکه امامی).
`halfAzadi`	Rate	Half Azadi coin (نیم سکه).
`quarterAzadi`	Rate	Quarter Azadi coin (ربع سکه).
`gerami`	Rate	One‑gram gold coin (سکه گرمی).
`gram18`	Rate	18‑karat gold per gram (طلای ۱۸ عیار).
`mithqal`	Rate	Gold mithqal (مثقال طلا).
`ounce`	Rate	Global gold ounce (انس طلا).

Keys are omitted entirely when the upstream feed has no value for them. Always guard with a check such as data.gold.ounce?.sell rather than assuming presence.

Currency codes

All 28 fiat currencies exposed under fiat. Codes are standard ISO 4217 identifiers used directly as object keys, so data.fiat.EUR.sell works as‑is.

Code	Currency	Code	Currency
`USD`	US Dollar	`AED`	UAE Dirham
`EUR`	Euro	`JPY`	Japanese Yen
`GBP`	British Pound	`TRY`	Turkish Lira
`CHF`	Swiss Franc	`CNY`	Chinese Yuan
`CAD`	Canadian Dollar	`SAR`	Saudi Riyal
`AUD`	Australian Dollar	`INR`	Indian Rupee
`SEK`	Swedish Krona	`MYR`	Malaysian Ringgit
`NOK`	Norwegian Krone	`AFN`	Afghan Afghani
`RUB`	Russian Ruble	`KWD`	Kuwaiti Dinar
`THB`	Thai Baht	`IQD`	Iraqi Dinar
`SGD`	Singapore Dollar	`BHD`	Bahraini Dinar
`HKD`	Hong Kong Dollar	`OMR`	Omani Rial
`AZN`	Azerbaijani Manat	`QAR`	Qatari Riyal
`AMD`	Armenian Dram	`DKK`	Danish Krone

On /api and /legacy each fiat entry carries an icon URL pointing to an SVG circle flag. On /deprecated the icon field is absent.

Headers & caching

Every JSON response — including error responses — sends the following headers.

Header	Value	Notes
`Content-Type`	application/json; charset=utf-8	Always UTF‑8 JSON.
`Cache-Control`	public, max-age=60, s-maxage=60	Responses are cached for 60 seconds at the browser and edge.
`Access-Control-Allow-Origin`	*	CORS is fully open — call it from any origin, including the browser.
`Access-Control-Expose-Headers`	Link	Lets browser clients read the `Link` header.
`Link`	</favicon.svg>; rel="icon"; type="image/svg+xml"	Declares the site icon for responses that have no `<head>`.

Data refreshes every 60 seconds. The upstream feed is scraped on demand and the result is cached at the edge, so polling more often than once a minute returns identical data. Polling once per minute is plenty.

Errors

Errors keep the same envelope as success responses: the site comment is still present, but success is false and an error message is included. Always branch on success and the HTTP status.

502 Bad Gateway

{
  "_comment": "Chand.API v1.0.1 — Homepage: chand.pages.dev — Source data: bonbast.com — Responses are cached for 60s and are free to use with attribution.",
  "success": false,
  "error": "Homepage returned status 522"
}

Status	Meaning	What to do
200	Success. Body contains `success: true` with rates.	Read the payload.
502	Upstream scrape failed — the source site was unreachable or returned no usable token.	Retry with backoff; treat as a transient outage.

Recommended client handling

async function getRates() {
  const res = await fetch("https://chand.pages.dev/api");
  const data = await res.json();

  if (!res.ok || !data.success) {
    throw new Error(data.error || `Request failed (${res.status})`);
  }

  return data;
}

Notes

What does _comment do?

JSON has no comment syntax, so site information is delivered as a reserved _comment key that is always the first entry in the object. It is safe to ignore; if you map over the response, skip keys beginning with an underscore.

Where does the data come from?

Rates are scraped live from bonbast.com and re‑shaped into a stable schema. If the upstream feed is unavailable the API returns 502 rather than stale or empty data.

Which currency are prices in?

All values are Iranian Toman, returned as integers. There are no decimal places and no separators.

Can I use this in production?

Yes — the API is free to use with attribution to Chand.API. There is no key, no quota, and no registration. Please respect the 60‑second cache and avoid high‑frequency polling.

Where do the icons come from?

Flags are served as SVG circle flags, gold and bullion icons come from TGJU, and the Bitcoin icon from AlanChand. Icon URLs are absolute, so hot‑linking them works directly.

Ready to integrate?

Start with the recommended endpoint — it has everything.

Open /api Back to overview

Documentation

Quick start

Endpoints

/api

/legacy

/deprecated

Response schema

Rate object

Gold entries

Currency codes

Headers & caching

Errors

Notes