Make your first Narwhal API request

Learn how to authenticate, request market data, and read the response.

This guide shows you how to make Gold and FX requests with the Narwhal REST API.

Before you begin

The website is live. Public API traffic remains disabled while we finish hardening the backend. You can still build against the request and response shapes below.

Set up your API key

Every API request requires a key. Send it as a Bearer token in the Authorization header—never in the URL.

Terminal

export NARWHAL_API_KEY="nw_live_..."

Request a gold price

Pass the quote currency in the path. This request returns the price of one troy ounce of gold in US dollars.

Request

curl --request GET \
  --url https://api.narwhalapi.com/v1/gold/spot/USD \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

Response shape

{
  "symbol": "XAU-USD",
  "price": "3371.42",
  "bid": "3371.31",
  "ask": "3371.53",
  "currency": "USD",
  "unit": "troy_ounce",
  "timestamp": "2026-08-22T06:29:41Z",
  "stale": false
}

Request exchange rates

Pass the base currency in the path and the quote currencies in currencies. Each rate includes its own timestamp and stale flag.

Request

curl --request GET \
  --url "https://api.narwhalapi.com/v1/fx/rates/USD?currencies=EUR,JPY" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

Response shape

{
  "base": "USD",
  "market_session": "open",
  "rates": [
    {
      "currency": "EUR",
      "rate": "0.9200",
      "timestamp": "2026-08-22T06:29:41Z",
      "stale": false
    }
  ]
}

Read the response

Narwhal returns typed JSON without a generic data wrapper.

Rule	What it means
`timestamp`	When the returned market value applies.
`stale`	Whether that value exceeds its documented freshness rule.
Decimal strings	Prices, rates, and quantities avoid binary floating-point surprises.
`null`	Missing means missing. It never becomes zero.

Quota headers on successful responses

X-Request-IDX-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Reset

Handle errors by status and code

Check the HTTP status first, then use code in application logic. detail is for logs and debugging.

RFC 9457 problem response

{
  "ok": false,
  "type": "https://narwhalapi.com/problems/invalid-query",
  "title": "Invalid query",
  "status": 400,
  "detail": "currencies must contain supported ISO codes",
  "code": "invalid_query",
  "request_id": "019d1af4-8f33-7b21-91af-ef535f2dcf50"
}

Need help? Contact support.

See what's new in the changelog.

LLM? Read llms.txt.