Credits, API Keys & Rate Limits

How API usage is counted

Every request you make to the Raiden Terminal API with an API key costs a fixed number of credits, set per endpoint and listed in Credits per Endpoint. This page covers how you get credits, how each request is billed, API keys, rate limits, errors and WebSocket billing.

• 1 credit ≈ 1 request served from memory: about 5 ms of work or 25 KB of JSON. Heavier endpoints cost more.
• The response headers say what each request cost.
• Browsing the Terminal website never uses credits.

Getting credits

• Free trial: 200,000 credits, once. Connect a Solana wallet and create your first API key. Trial credits don’t renew, and free trials are limited per network.
• Beta plan: 10,000,000 credits per month. Early users are on Beta. Credits renew on the 1st at 00:00 UTC, and unused monthly credits don’t carry over.
• Need more? Monthly plans are available on request while paid plans are being prepared: ask on Discord .

Response headers

These headers come with every response to a request made with a valid key: success or error, free endpoints included, and with the 402.

Responses without credit headers. Refusals that come before the price (a 403 about the key or its account, 503 credits_unavailable or keys_unavailable) and every 429 carry none.

HTTP/2 200
X-Credits-Cost: 2
X-Credits-Remaining: 199998
X-Credits-Pool: general
 
HTTP/2 402
X-Credits-Cost: 0
X-Credits-Remaining: 0
X-Credits-Pool: general
X-Credits-Warning: exhausted

Out of credits: HTTP 402

A request that costs more than what is left is refused with HTTP 402, and nothing is charged. The 402 applies from the first request over your balance, on every pool.

The JSON body tells you what happened:

• cost — the price of the refused request.
• remaining — what is left.
• code — which pool ran out (see the table below).

{
  "error": "Insufficient credits: this request costs 20 credits and your trial has 0 left. Trial credits don't renew. To keep using the API, ask Raiden for a plan on Discord and include your key id 118: https://discord.com/invite/raiden-wtf",
  "code": "trial_exhausted",
  "pool": "general",
  "plan": "trial",
  "key_id": 118,
  "cost": 20,
  "remaining": 0,
  "reset_at": null,
  "docs": "https://terminal.raiden.wtf/docs-api#credits"
}

Warnings come first. Before you run out, X-Credits-Warning reports used_50, used_80 and used_95, and the same warnings show on your API keys & credits  page.

API keys

• Up to 10 keys per account. Every key has full access: all data endpoints, plus your wallet lists, favorites and streams.
• General pool or dedicated budget. A key uses your general pool, or a dedicated monthly budget set aside for it (monthly plans). A key with a dedicated budget stops with 402 when its budget runs out and never uses the general pool.
• Rotate a key to get a new secret with the same name, budget and limits. The old secret stops working immediately.
• Revoke a key to stop it for good.
• Check your balance for free with GET /account/balance and your key: it costs 0 credits and works at 0 credits.
• Keys can’t manage keys. The other /account routes answer a key with 403 session_required.

Rate limits

• 20 requests per second, burst 40, per account. The limit is shared by all your keys: more keys never add throughput.
• Optional per-key limit. You can give a key its own lower limit. Without one, a single busy key can use the whole shared limit.
• Free trial: at most 2 heavy requests in flight (packs and the analytical endpoints). One more answers 429 too_many_concurrent (scope concurrency).

Over the rate limit you get 429 rate_limited with Retry-After (seconds), X-RateLimit-Scope (account or key) and X-RateLimit-Limit.

Errors

Error format

• Keys, credits and limits. Refusals are JSON {"error": "…", "code": "…"}: an English sentence and a stable code to branch on. Some add fields such as scope, param, max or cost.
• Other errors of the data endpoints are {"error": "…"}, some with a code as well (for example 503 warming_up below). Branch on the HTTP status.

What an error costs

• 401, 402, 403 and 429 cost 0, and so do our own errors (5xx).
• Any other error the endpoint answers itself (400, 404, …) costs 1 credit (0 on free endpoints).

Error codes

Retry-After

Retry-After is a wait in seconds. It comes only with:

• the responses marked yes in the table above;
• the sign-in and key-management limits: 429 too_many_sign_in_attempts, too_many_step_ups, too_many_changes and too_many_new_accounts;
• the website limits below: 429 hourly_volume_limit and 503 heavy_capacity.

It never comes with a 402.

WebSocket streams

Setting up custom streams is free (up to 3 per account). What costs credits is keeping a keyed connection open. See Streams (WebSocket) for the stream endpoints.

Connection billing

• Each connection opened with an API key (/ws?key=…&sub=…, or the key in an X-API-Key header) costs 1 credit per started minute, charged to the key’s pool.
• 1 credit is reserved when the connection opens, then 1 more at the start of every following minute.
• Without credits, the handshake answers HTTP 402 with the usual JSON body.

Connection limits

Close codes

Refused handshakes

A refused handshake answers HTTP with the usual JSON body:

• 403 invalid_api_key for an unknown key (or another key code from the error codes table).
• 401 invalid_stream for an unknown or inactive stream token.
• 503 with Retry-After while keys or balances are loading.

Live data on the Terminal website is free: up to 20 connections per IP address, 100 topics each.

Website limits

Browsing the Terminal website is free, but the website is not a second, keyless API.

Endpoints and parameters that need a key

Without a key, these endpoints answer 403 api_key_required, even from the browser:

• /tokens/{mint}/pack
• /wallets/{addr}/pack
• /aggregates/rug-wallets
• /sitemap-mints

Bulk parameters need a key too. Over these limits the answer is the same 403, with param and max (only param for a parameter that needs a key at any value).

Sign-in and scraping limits

• Sniper VS. Comparing wallets on Sniper VS (/versus) needs a signed-in wallet (401 login_required otherwise).
• Hourly data limit. Heavy scraping without a key runs into an hourly data limit per address (429 hourly_volume_limit with Retry-After).

Backtests and live simulations

Backtests and live simulations are free with a signed-in wallet: no credits used.

• One running backtest and one running live simulation per account. Starting another answers 409 with the running job’s id and status already_running.
• Server capacity. When every live-simulation slot on the server is taken, starting one answers 503 heavy_capacity with Retry-After.

Get a free API key →