Every category we track — "Layer 1", "Memes", "DeFi" — with its newest market aggregate: total market cap, 24-hour volume, how many coins are in it, its share of the categorised market, and the three coins inside it that moved most in the last 24 hours.

market is never null here. This is the opposite call from /exchanges, and worth reading before you write a null check that will never fire: a category appears in this response only if we hold a current aggregate for it, so a present item always has a present market. See Which categories appear.

Query parameters

• idcsv of integersUp to 100. Exact match
• slugcsv of stringsUp to 100. Unique upstream — a single slug is a single-row lookup, unlike /exchanges. URL-encode it: see the warning below
• pageinteger ≥ 1Page mode. Takes precedence over limit/offset
• sizeinteger 1–100Default20Page mode only. Over 100 is a 400, not a truncation
• limitinteger 1–100Default20Offset mode
• offsetinteger ≥ 0Default0Offset mode. Max 100000
• sortid | name | slug | market_cap | volume_24h, optionally :asc / :descDefaultmarket_cap:descNot id:asc. See the note below

Filters are ANDed. There is no symbol — a category has no ticker — and sending one is ignored, like any parameter this endpoint does not read.

⚠️ URL-encode slug before you put it in a query string. Real slugs contain characters that a URL does not treat as data. lending-&-borrowing is a live category slug, and ?slug=lending-&-borrowing is parsed as two parameters — slug=lending- plus a stray -borrowing — so you get a 200 with an empty list and no error at all. Send ?slug=lending-%26-borrowing. Parentheses are safe but common too (bnb-smart-chain-(bep20)). Every HTTP client can do this for you; the failure is silent, so it is worth checking that yours did.

The default sort is different here, and on /chains, from every other list in this API. The others default to id:asc; these two default to market_cap:desc. A leaderboard whose first page is ordered by whatever was catalogued first is not a leaderboard. Pass sort=id explicitly if you want the old behaviour.

sort=volume is a 400 here. /exchanges spells that key volume; on /categories and /chains it is volume_24h, because on these two endpoints every sort key is named after the field it orders by — market_cap orders by market.market_cap, and volume_24h orders by market.volume_24h.

Which categories appear

A category is in the response when all three of these hold:

1. it is live upstream (not disabled, not deleted);
2. we hold at least one market snapshot for it; and
3. its newest snapshot is within one hour of the newest snapshot in the whole table.

The third rule is what keeps abandoned groups off the board. Snapshots are written every ten minutes for every group at once, so under normal operation this excludes nothing — 291 of 291 categories passed it when the rule was measured. It exists for the case where upstream stops aggregating one particular group: that group keeps its old rows, stops being updated, and would otherwise sit in a public ranking looking exactly like a live one. On /chains the same rule removes three groups today.

Note what it does not do. The window is relative, so if upstream stops writing altogether, every group ages together and the whole list is still returned — with numbers frozen at whenever the last run happened. We log that condition on our side; there is nothing in the response that marks it, and market.snapshot_time is what you should check if it matters to you.

Response

Item fields

What market_cap_share actually measures. It is this category's market cap divided by the sum of every categorised coin's market cap — and a coin that belongs to three categories is counted three times in that denominator. So the shares within one snapshot add up to 1, but each one is lower than the category's true share of the market, by roughly the average number of categories a coin belongs to.

Two consequences worth stating plainly. It is not "dominance" in the usual sense — this is not BTC-dominance-style share of total crypto market cap, and it is not comparable with such a figure. And /categories and /chains compute their denominators separately, so a share on one is not comparable with a share on the other. If you want a true share of the whole market, divide market.market_cap by /global's total_market_cap yourself.

top_gainers can be short. It carries at most three coins, and fewer when one of the coins upstream picked is no longer in our coin directory — a delisting between the snapshot and your request, for example. We drop such an entry rather than return a coin with no name. An empty array is a valid response; it does not mean the category is empty (coins_count answers that).

Not implemented

description and title are not returned, nor is CoinMarketCap provenance (external_id, source) or the internal display flags. title in particular is not a second name for the category: it is the page heading our own website uses ("Top DeFi Tokens by Market Capitalization"), filled in for five categories and equal to name for the rest — our presentation copy rather than a property of the category. There is no logo: upstream has no image for a category, and nothing to derive one from — /chains has one only because a chain has a native coin. There is no rank field: the default market_cap:desc ordering reproduces it exactly, and a stored rank would contradict its own position as soon as you changed the sort or paged. There is no tvl, and that is not an oversight — upstream's column of that name holds a copy of the market cap rather than a locked value. Volume change percentages (1h, 24h, 7d, 30d) are not in this version. Adding a field later is non-breaking; removing one is not.

Examples

/categories reads id, slug, page, size, limit, offset and sort. Any other parameter is ignored.

# Default listing: 20 categories, biggest market cap first
curl -H "X-Api-Key: <your-api-key>" \
  "https://open-api.coinworldcap.com/openapi/v1/categories"

# One category by slug — unique upstream, so this is a lookup
curl -H "X-Api-Key: <your-api-key>" \
  "https://open-api.coinworldcap.com/openapi/v1/categories?slug=layer-1"

# Busiest categories by 24-hour volume
curl -H "X-Api-Key: <your-api-key>" \
  "https://open-api.coinworldcap.com/openapi/v1/categories?sort=volume_24h:desc&limit=10"

# Show the response headers, including X-Request-Id
curl -i -H "X-Api-Key: <your-api-key>" \
  "https://open-api.coinworldcap.com/openapi/v1/categories?limit=1"

Anything other than a 200 is in Errors, which covers every endpoint here.