The 20 assets with the largest 24-hour change, ranked by percent_change.24h descending — this endpoint is not paginated, so result carries items and nothing else.

Query parameters

• bygainersDefaultgainersThe only value this version serves, and it is matched case-insensitively — GAINERS and Gainers both work, as everywhere else in this API — after surrounding whitespace is trimmed, so %20gainers%20 works too. Omitting it, or sending it blank or all-whitespace, gives you the default; anything else is a 400, including searched

What is on the board

A coin appears when it clears both floors: market cap and 24-hour volume. The floors are configuration, not contract — they are tuned against live data and may move without a version change. Coins with no market cap at all are not on the board.

Twenty is a ceiling, not a promise. The floors decide who is on the board, so a quiet market — or a tightening of the floors — returns fewer rows, and an empty board ("items": []) is a valid response rather than an error.

The board is a ranking, not a filter for positive change. Nothing requires percent_change.24h to be above zero: in a broad decline the board is the twenty that fell least, and every 24h on it can be negative. Render the sign. A client that labels this list "gainers" and colours it green will show a red list under a green heading on those days — the ranking is still correct, the label is not. (Why the query does not exclude negative change is recorded in design/20260917-trending-board-semantics.md.)

Volume is not screened for wash trading. A coin can reach the board on manufactured volume; treat the board as "what the market data says", not as an endorsement.

by=searched is not implemented. The upstream table has no actor column, so a search-ranked board could be inflated by anyone; it waits on an upstream change.

Response

Item fields are identical to /quotes — same type, same rules, same string handling for every money-shaped value.

result has no page, total_page or total. Every other listing endpoint has them; this one does not, because a board of at most 20 rows has no pages to report. result is still an object, so a client can model it with the same shape it uses for an error response.

Examples

by is the only parameter this endpoint reads. There is no paging, no sort and no fields — an unknown parameter is ignored rather than rejected.

# The board. by defaults to gainers, so this is the usual call
curl -H "X-Api-Key: <your-api-key>" \
  "https://open-api.coinworldcap.com/openapi/v1/trending"

# The same board, named explicitly
curl -H "X-Api-Key: <your-api-key>" \
  "https://open-api.coinworldcap.com/openapi/v1/trending?by=gainers"

# Any other board is a 400 with message_key BAD_REQUEST — searched included
curl -H "X-Api-Key: <your-api-key>" \
  "https://open-api.coinworldcap.com/openapi/v1/trending?by=searched"

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

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