Data Rate Limits

The public Carbium Token Index API is free and rate-limited.

Rate limits protect the public surface while keeping the common builder path open: search, lookup, batch resolve, and load token logos without an API key.

Current public limits

These limits are per IP on the public no-key surface.

📘

Do not treat the public free limits as a replacement for a production data contract. If your product needs higher sustained throughput, talk to Carbium instead of designing around limit bypasses.

What happens when you hit a limit

If your client sends too many requests, expect an HTTP 429 Too Many Requests response. Your integration should back off and retry later instead of immediately retrying in a tight loop.

Recommended behavior:

• respect Retry-After if the response includes it
• add exponential backoff for backend jobs
• cache successful responses locally
• batch multiple mint lookups with POST /tokens/batch
• debounce search input in browser UIs
• avoid resolving the same mint repeatedly in a render loop

Use batch resolves before single-mint loops

If you have more than a few mint addresses, use POST /tokens/batch.

Good:

curl -X POST 'https://tokens.carbium.io/tokens/batch' \
  -H 'content-type: application/json' \
  -d '{"mints":["So11111111111111111111111111111111111111112","EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"]}'

Avoid hot loops like this in production:

for (const mint of mints) {
  await fetch(`https://tokens.carbium.io/tokens/${mint}`);
}

A batch request can resolve up to 500 mint addresses and returns both resolved items and unknown mints.

Browser search guidance

For search boxes and token selectors:

• debounce user input before calling GET /tokens
• wait until the query has enough characters to be useful
• cache recent searches in memory
• cancel stale requests when the user keeps typing
• cap limit to the number of results your UI can actually display

Example policy: wait 200–300ms after typing stops, then call GET /tokens?q=...&limit=20.

Logo guidance

GET /img/:mint has a higher route budget because image loading can fan out quickly in token lists.

Still, production UIs should:

• use browser caching normally
• lazy-load images where possible
• use a local fallback icon for missing logos
• avoid rendering hundreds of offscreen images at once
• avoid adding cache-busting query strings unless required

Backend cache guidance

For backend services, a simple local cache is usually enough:

The goal is not to make data stale forever. The goal is to avoid repeating the same read every time a component renders.

When you need more

The public limits are designed for discovery, development, small apps, and reasonable frontend/backend usage. If your product needs sustained high-volume enrichment, custom datasets, commercial guarantees, or dedicated support, contact Carbium for a data access path.