Best practices and FAQ

How to build a client against the CoinWorldCap API that stays correct and inside its rate limit.

Identify by id, not by symbol

A symbol is not unique — one ticker can return several unrelated assets (/assets). Look an asset up once, by slug or by contract address, keep the id that comes back, and send that from then on. On /exchanges a slug is not unique either, so keep the exchange's id too.

Assets and RWAs share one id column, but an RWA's id finds nothing on /assets and an asset's finds nothing on /rwa. Exchanges and people are numbered separately, so the same number can name an asset and an unrelated exchange. Keep track of which endpoint an id came from. A DEX token has no numeric id to send: it is named by chain_slug and address (DEX tokens: what the endpoints share).

Poll no faster than the data changes

Each dataset is rebuilt on its own schedule, and calling more often than that spends your allowance on the same numbers. Cache a response for about its dataset's interval; Data methodology lists the intervals we publish and the field that dates each response.

To follow many assets, ask for them together: /assets, /quotes and /rwa take up to 100 ids in one id parameter. Send limit=100 with them — the default page is 20 rows — and a watchlist of 100 costs one request rather than one per asset.

Retry only what is retryable

Narrow a list instead of paging through it

offset stops at 100,000 (Errors). Filter or sort so that the rows you want come first. /dex/tokens/trades and /dex/tokens/liquidity page by cursor instead: pass next_cursor back exactly as it came until it is null.

Fetch history in ranges

With time_start, a range that holds more points than one response may carry is a 400, not a shorter answer (History: what the endpoints share). To load a long history, ask for consecutive ranges that each stay within that cap. Both ends of a range are included, so start the next range one interval after the last point you received. On /earn/history the cap counts every product: ask for one platform at a time with provider_id. For a recent chart, leave out time_start.

To keep a stored history current, ask again from a little before your newest point and replace points by time: recent points can still be revised for a while after they first appear.

Check parameter names

A query parameter an endpoint does not read is ignored, not rejected, so a misspelt filter — chain_slg=solana — returns the unfiltered list with a 200. Compare the names you send with the endpoint's parameter table.

FAQ

How often is the data rebuilt, and how old is a response? Data methodology lists the intervals we publish, and names the field that dates each response.

Why does an id return nothing? Usually one of three things. The id belongs to another family: an RWA's id sent to /assets matches nothing, because RWAs are listed by /rwa. Or a filter on a list matched nothing: that is an empty page, not a 404. Or the resource does not exist: an endpoint that returns one resource answers 404 with code 40400, and retrying will not help (Errors).

Where does each history start? It depends on the dataset, and on the asset: Data methodology lists them. A daily range that starts before the history does is not an error: it returns fewer points, or none. Hourly ranges have a limit of their own (History: what the endpoints share).

Why is an exchange missing from /exchanges? It lists centralized exchanges only; a decentralized exchange's id or slug matches nothing there (/exchanges).