Getting started

Get a key

Sign up for the Free plan (or any paid plan) — the storefront mints an API key on activation and shows it once in your client area. Keys look like ag_live_… (or ag_test_… in a sandbox).

Make your first request

Send the key in X-API-Key (or Authorization: Bearer). Query-string keys are rejected on purpose — they leak into logs.

curl https://api.<DOMAIN>/v1/spot/gold \
  -H "X-API-Key: ag_live_yourkeyhere"

Read the rate-limit headers

Every keyed response carries your current budget, so you can back off before you're throttled instead of guessing.

Header	Meaning
X-RateLimit-Limit	Requests/min allowed on your plan
X-RateLimit-Remaining	Tokens left in the current window (floored)
X-RateLimit-Reset	Epoch seconds when the next token is available

Handle errors

Every error response is {"error", "message"} with one of these codes:

HTTP	error	When
401	missing_key	No key on a keyed route
401	invalid_key	Unknown or revoked key
403	payment_required	Key suspended
403	not_entitled	Active key, missing dashboard entitlement / WS not on plan
429	rate_limited	Token bucket empty (response includes retryAfterSeconds)
400/404	existing codes	Unchanged (unknown_metal, bad_query, …)

Stream over WebSocket

Connect to /v1/stream, then authenticate with your first message — no key in the URL. WebSocket access requires a paid plan.

> ws.connect("wss://api.<DOMAIN>/v1/stream")
< (connection open)
> {"type":"auth","key":"ag_live_yourkeyhere"}
< {"type":"auth_ok","plan":"pro","dashboard":true}
< {"type":"snapshot","payload":[ …every tracked metal… ]}
< {"type":"update","payload":[ …only metals that changed… ]}

No auth within 10s, a bad/revoked key, a suspended key, or a plan without WS/dashboard each get one JSON error frame and a close code (4001–4004) — see the reference below for the full table.