Nerkh API v2 Guide

Quick start

curl --fail-with-body \
  -H "Authorization: Bearer $NERKH_API_KEY" \
  -H "Origin: https://example.com" \
  https://nerkh.xhesam.com/api/latest

Authentication

Create a free account and register one exact HTTPS origin first. Then send the key in Authorization and the registered domain in Origin. Never place a key in a URL, log, or repository.

Create free account

Authorization: Bearer nrkh_xxxxxxxxxxxxxxxxxxxx
Origin: https://example.com

Endpoints

Method	Path	Purpose
GET	`/api/latest`	Latest categories and rates
GET	`/api/categories`	Category definitions
GET	`/api/categories/:category_id`	One category and its rates
GET	`/api/rates/:rate_id`	One rate
GET	`/api/history/:rate_id`	One rate's history

History parameters

Use either range or a from/to window. The maximum accepted history window is 90 days.

/api/history/price_usd?range=7d
/api/history/price_usd?range=30d
/api/history/price_usd?range=90d
/api/history/price_usd?from=2026-07-01&to=2026-07-12

Response contract

Every successful response includes version, unit, timezone, generation time, and remaining-quota metadata.

{
  "ok": true,
  "provider": "Nerkh",
  "schema_version": "1.0.0",
  "api_version": "2.0.0",
  "unit": "IRR",
  "timezone": "UTC",
  "generated_at": "2026-07-12T12:00:00Z",
  "limits": {
    "daily_limit": 100,
    "remaining": 99,
    "reset_at": "2026-07-13T00:00:00.000Z"
  }
}

Errors

HTTP	Error
400	`invalid_query / invalid_range / invalid_date`
401	`unauthorized`
403	`origin_required / origin_not_allowed`
404	`category_not_found / rate_not_found / not_found`
405	`method_not_allowed`
429	`daily_limit_exceeded`
503	`service_unavailable / data_unavailable`

Unit and timezone conversion

API values are always IRR and timestamps are always UTC. Consumers own display conversion.

const toman = response.item.price.value / 10;
const tehran = new Intl.DateTimeFormat("fa-IR", {
  dateStyle: "medium",
  timeStyle: "short",
  timeZone: "Asia/Tehran"
}).format(new Date(response.generated_at));

Security notes

Every free account has exactly one token and one exact Origin. Origin is mandatory on every request and does not replace the API key.

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
X-Request-Id