# carbium-tokens

> Free public REST API for Solana token metadata, part of the Carbium ecosystem. Search, single-mint lookup, 500-mint batch resolve, and a cached logo proxy across ~2M SPL & Token-2022 mints. No auth, CORS-permissive, rate-limited per IP. Registry kept fresh via Yellowstone gRPC + Metaplex/Token-2022 enrichment.

Base URL: https://tokens.carbium.io

## Endpoints

- [GET /tokens](https://tokens.carbium.io/endpoints#search): Search the registry by symbol, name, or mint. Query params: `q` (text), `limit` (1–200, default 50), `page` (1-indexed), `include_token22` (default true). Empty query returns top-by-volume. Returns `{ items, page, limit, total }`. Rate limit 60/min/IP.
- [GET /tokens/:mint](https://tokens.carbium.io/endpoints#lookup): Look up one mint by base58 address. Returns a single token row, or 404 if not yet indexed. Rate limit 180/min/IP.
- [POST /tokens/batch](https://tokens.carbium.io/endpoints#batch): Resolve up to 500 mints in one call. Body `{ "mints": ["<base58>", ...] }`. Returns `{ items, unknown }` — unknown mints are auto-enqueued for enrichment. Rate limit 20/min/IP.
- [GET /img/:mint](https://tokens.carbium.io/endpoints#img): Cached logo proxy. Always returns 200 with an image (falls back to an "Unknown" SVG) so `<img>` never breaks. Rate limit 600/min/IP.

## Token row shape

Every token-returning endpoint uses the same object: `mint`, `symbol`, `name`, `decimals`, `logo_url`, `logo_status` (ok|unchecked|broken|missing), `is_token22`, `daily_volume_usd`, `first_seen_at`, `last_seen_at`, `supply`, `mint_authority`, `freeze_authority`, `metaplex_uri`, `update_authority`, `seller_fee_basis_points`, `token_standard`, `description`, `external_url`, `extensions`, `tags`.

## Docs

- [Human-readable API reference](https://tokens.carbium.io/endpoints): Full reference with param tables, response schema, rate limits, and live curl/JavaScript/Python examples.
- [OpenAPI 3.1 spec](https://tokens.carbium.io/openapi.json): Machine-readable contract for the four public endpoints.

## Notes

- Authentication: none required.
- CORS: permissive (`*`) — callable directly from a browser, curl, or a server.
- Rate limits are per-IP sliding windows; 429 responses carry a `Retry-After` header. Global fallback 300/min/IP across all routes. Need higher limits? Contact Carbium to allow-list partner IPs.
- Operational endpoints (`/healthz`, `/version`, `/enqueue`) are internal and not part of the public API.