​
API keys

You don’t need a key to use the API. Without one, your requests are anonymous. With one, they’re tied to your partner account, which gives you:
  • a higher rate limit;
  • your swaps counted as yours, so you can follow them;
  • webhooks for your swaps’ status changes;
  • a partner fee on cross-chain swaps, if your account has one.
To get a key, email [email protected]. Send it in the x-api-key header:
Keys start with tern_. If a key is malformed, unknown, or revoked, or its account is suspended, the API answers 401 unauthorized. It never falls back to treating the request as anonymous. A key can’t move anyone’s funds, but anyone holding it can use your rate limit and have swaps counted as yours. Keep keys on your server where you can: a key shipped in a website or app is public.

​
Rate limits

Short bursts above the limit are allowed. If you need more, email [email protected]. Over the limit, the API answers 429 rate_limited with a Retry-After header: how many seconds to wait. To stay under it:
  • check a swap’s status every few seconds, not constantly, and stop once it’s final;
  • use webhooks if you track many swaps;
  • cache GET /v1/chains, which rarely changes.

​
Request IDs

Every response has an x-request-id header. You can send your own, up to 64 letters, digits, ., _, or -, to match Tern’s logs with yours. Otherwise Tern creates one. Include it whenever you report a problem.