Rate limits and API keys
Thru’s public endpoints (rpc.betanet.thru.org and data.thru.org) accept requests without an API key at a low limit. A free API key gives your organization its own, higher limit.
Limits
Section titled “Limits”| Caller | Requests | Response bytes |
|---|---|---|
| Without an API key | 10 weighted requests/s per IP address | 5 MiB/s per IP address |
| With an API key | 100 weighted requests/s per organization (default) | 5 MiB/s per organization (default) |
- Weighted requests. Each method costs a fixed weight.
- Most methods cost 1.
- Single account, transaction and event lookups cost 2.
- Block lookups, list and batch methods cost 10.
DebugReExecutecosts 50.- So without a key,
ListTransactionsis limited to one call per second.
- Response bytes are counted only for streams and expensive methods.
- Organization limits. All keys in an organization share its limit. See yours in Thru Developers under the info button next to API keys.
Get a key
Section titled “Get a key”- Open dev.thru.org/keys and sign in with GitHub, Google or X.
- Name the key and create it.
- Optionally, restrict it to your browser origins.
- Copy it. It is shown once and looks like
thru_followed by 32 letters and digits.
Keep keys out of source control and client bundles unless you’ve restricted them to your origins.
Send the key
Section titled “Send the key”Send the key as a bearer token on every request. This works for gRPC, gRPC-Web, Connect and REST:
Authorization: Bearer thru_...-
CLI:
- Run
thru auth login. It creates a key and uses it automatically with the official RPC endpoints. - Or set
THRU_API_KEY.
- Run
-
TypeScript SDK: pass
createThruClient({ apiKey: process.env.THRU_API_KEY }). -
AI agents: run
thru auth keys create --name <name> --agent <client>to create a key and install it for the Thru MCP. Its tool calls count against your organization’s limits. -
grpcurl:
Terminal window grpcurl -H "authorization: Bearer $THRU_API_KEY" rpc.betanet.thru.org:443 thru.services.v1.QueryService/GetHeight
When you hit a limit
Section titled “When you hit a limit”| Protocol | Response |
|---|---|
| gRPC, gRPC-Web, Connect | Status RESOURCE_EXHAUSTED (8) |
| Other HTTP | 429 Too Many Requests with a JSON body |
Every rate-limited response has these headers:
retry-after: 1x-ratelimit-limitx-ratelimit-remaining
Without a key, the message names the per-IP limit you hit (weighted requests, or response bytes) and links here:
rate limit for requests without an API key exceeded (10 weighted requests/s per IP). Get a free key with higher limits at https://dev.thru.org/keys?ref=edge-429 and send it as "Authorization: Bearer thru_...". Docs: https://thru.org/docs/api-ref/rate-limits/The JSON body adds get_key_url and docs_url:
{ "error": { "code": "resource_exhausted", "message": "rate limit for requests without an API key exceeded (...)", "get_key_url": "https://dev.thru.org/keys?ref=edge-429", "docs_url": "https://thru.org/docs/api-ref/rate-limits/" }}The SDKs throw a typed error you can check for:
- TypeScript:
ThruRateLimitError, which hasgetKeyUrl,keyedandretryAfterSeconds. - Rust:
ClientError::RateLimited.
Wait at least retry-after seconds before retrying, and back off if the denials continue.
Responses to requests without a key also carry link: <https://dev.thru.org/keys?ref=edge>; rel="help".
A region-wide ceiling protects the network as a whole and applies with or without a key. When a request is denied by it, the message is rate limit exceeded, with no key link.
With a key, the message is rate limit exceeded. The limit is your organization’s (or the key’s own cap, if Thru has set one).
A key that is unknown or revoked returns UNAUTHENTICATED (401). A key used from an origin outside its allowlist returns PERMISSION_DENIED (403).