Rate limits and quotas

API-key subscriptions come with predictable account-level limits. Exact numbers depend on your plan; your active limits are shown on the OneSource dashboard under Your Plan → Plan. Both limits are enforced per account and shared across every API key you create (they key on your license, not on the individual key), and they have the same shape on every plan:

Limit	Scope
Sustained request rate (req/s)	Per account, rolling 1-second window
Monthly request quota	Per account, per calendar month

Rate-limit headers

Every authenticated /api/* response carries three headers reflecting your current key state:

Header	Value
X-RateLimit-Limit	Calls allowed in the current window (per your plan).
X-RateLimit-Remaining	Calls remaining in the current window.
X-RateLimit-Reset	Unix timestamp (seconds) when the window resets.

Example:

$ curl -i https://api.onesource.io/api/chain/network-info \
    -H "Authorization: Bearer $ONESOURCE_API_KEY"
HTTP/2 200
x-ratelimit-limit: 1000
x-ratelimit-remaining: 987
x-ratelimit-reset: 1715731200
...

These headers are emitted by the API gateway on every Bearer-key response; read them on the success path and back off proactively when Remaining trends low. Calls authenticated with x402 or MPP don't carry them (those flows are per-call settled, not quota-bound).

Current enforcement

The per-second rate limit is advisory; the monthly quota is enforced. The gateway tracks your account's request rate and reports it via X-RateLimit-*, but it does not currently reject calls with 429 for exceeding the per-second rate. The monthly quota is different: once your account's monthly request count is used up, further calls are rejected until the next calendar month. In practice that means:

• The X-RateLimit-* headers are accurate and worth honoring proactively in client logic.
• Bursting past your per-second rate won't (today) get a 429 back, but sustained abuse is still subject to load-balancer-level protection.
• Don't run your account's monthly quota to zero: once it's spent, every key on the account stops authenticating until the cycle resets.

Hard per-second enforcement with 429 + Retry-After is on the roadmap. When it lands, this page will document the exact response shape; until then, the headers are the source of truth for rate, and the dashboard usage bar is the source of truth for your monthly quota.

Backoff pattern

Even without 429 from the gateway, you'll hit transient 502/503 from upstream RPC nodes and the facilitator under load. Exponential backoff with jitter handles them well:

async function callWithRetry(url: string, init: RequestInit, attempt = 0): Promise<Response> {
  const res = await fetch(url, init);
  if (res.status < 500 || attempt >= 5) return res;

  const backoff = 2 ** attempt * 500 + Math.random() * 250;
  await new Promise(r => setTimeout(r, backoff));
  return callWithRetry(url, init, attempt + 1);
}

See Error codes for the full retry catalog.

Monitoring usage

The OneSource dashboard at app.onesource.io → Your Plan → Account shows a Current Cycle Utilization bar: the share of your account's monthly request allowance used so far this cycle (aggregated across all your keys, not per key). Each API response also carries a meta.request_id you can pin to log entries on your side.

Watch the X-RateLimit-Remaining header trend in your application logs to spot drift before you exhaust the monthly cap.

When you need more

If your workload is steady-state above your rate limit or near the monthly cap:

• Spike or overflow traffic: route bursts to pay-per-call with x402 or MPP: no monthly quota, you pay per request in USDC, and it runs in parallel with your Bearer key.
• More Bearer-key capacity: the Developer plan is currently the only subscription tier, and there's no in-dashboard upgrade. If one account's quota isn't enough, run a second subscription under a different email, or move the overflow to x402 / MPP.

Free endpoints

A handful of endpoints are public and don't count against your quota:

• GET /health: liveness check
• GET /api/pricing: per-endpoint pricing
• GET /openapi.json and GET /.well-known/openapi.json: OpenAPI spec
• GET /llms.txt: LLM-optimized index