Skip to content

Rate limits and API keys

View as Markdown

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.

CallerRequestsResponse bytes
Without an API key10 weighted requests/s per IP address5 MiB/s per IP address
With an API key100 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.
    • DebugReExecute costs 50.
    • So without a key, ListTransactions is 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.
  1. Open dev.thru.org/keys and sign in with GitHub, Google or X.
  2. Name the key and create it.
    • Optionally, restrict it to your browser origins.
  3. 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 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.
  • 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
ProtocolResponse
gRPC, gRPC-Web, ConnectStatus RESOURCE_EXHAUSTED (8)
Other HTTP429 Too Many Requests with a JSON body

Every rate-limited response has these headers:

  • retry-after: 1
  • x-ratelimit-limit
  • x-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 has getKeyUrl, keyed and retryAfterSeconds.
  • 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).