> For the complete documentation index, see [llms.txt](https://docs.yifi.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.yifi.io/api-reference/tokens.md).

# Tokens

Token catalog with search and filters (`GET /v1/tokens`)

## List supported tokens

> Token catalog from the coins cache, sorted by internal popularity (not exposed on the item).\
> \
> \*\*Pagination:\*\* if \*\*neither\*\* \`limit\` nor \`offset\` is sent, the handler returns \*\*all\*\* matching tokens. The JSON still includes \`limit: 20\` and \`offset: 0\` in that case — those fields do not mean the list was sliced. If either \`limit\` or \`offset\` is sent, results are sliced (\`limit\` default 20, max 100).\
> \
> \- \`network\` — must equal \`GET /v1/chains\` → \`id\` (slug), case-insensitive. Aliases (\`ERC20\`, display names) are \*\*not\*\* accepted on this query. Unknown slug → empty list.\
> \- \`engine\` — \`cex\` keeps tokens with \`engineSupport\` containing \`off-chain\`; \`dex\` keeps \`on-chain\`. There is no \`private\` filter.\
> \- \`supportsFixedRate\` — boolean (\`true\`/\`1\` / \`false\`/\`0\`).\
> \- \`search\` — ranked match on ticker, name, contract address; extra terms can resolve a network alias inside the search string. Can be combined with \`network\`.

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0"},"tags":[{"name":"Tokens","description":"Token catalog with search and filters (`GET /v1/tokens`)"}],"servers":[{"url":"https://api.yifi.io","description":"Production"},{"url":"https://api-dev.yifi.io","description":"Development / Staging"}],"paths":{"/v1/tokens":{"get":{"description":"Token catalog from the coins cache, sorted by internal popularity (not exposed on the item).\n\n**Pagination:** if **neither** `limit` nor `offset` is sent, the handler returns **all** matching tokens. The JSON still includes `limit: 20` and `offset: 0` in that case — those fields do not mean the list was sliced. If either `limit` or `offset` is sent, results are sliced (`limit` default 20, max 100).\n\n- `network` — must equal `GET /v1/chains` → `id` (slug), case-insensitive. Aliases (`ERC20`, display names) are **not** accepted on this query. Unknown slug → empty list.\n- `engine` — `cex` keeps tokens with `engineSupport` containing `off-chain`; `dex` keeps `on-chain`. There is no `private` filter.\n- `supportsFixedRate` — boolean (`true`/`1` / `false`/`0`).\n- `search` — ranked match on ticker, name, contract address; extra terms can resolve a network alias inside the search string. Can be combined with `network`.","operationId":"getTokens","parameters":[{"name":"search","required":false,"in":"query","description":"Search by ticker, name, contract address, or network alias inside the query string (e.g. `usdt trc`).","schema":{"type":"string"}},{"name":"network","required":false,"in":"query","description":"Filter by canonical chain **`id`** (slug) — must match `/v1/chains[].id` exactly ignoring case (e.g. `ETH`, `BTC`). Aliases such as `ERC20` or network names alone are **not** accepted here.","schema":{"type":"string"}},{"name":"supportsFixedRate","required":false,"in":"query","description":"Filter to tokens that support fixed-rate exchanges","schema":{"type":"boolean"}},{"name":"engine","required":false,"in":"query","description":"Filter by supported swap engine:\n\n- `cex` – off-chain CEX providers\n\n- `dex` – on-chain DEX aggregators","schema":{"type":"string","enum":["cex","dex"]}},{"name":"limit","required":false,"in":"query","description":"Page size (1–100). Applied only when `limit` or `offset` is present. If both are omitted, **all** matches are returned.","schema":{"minimum":1,"maximum":100,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Pagination offset. Applied only when `limit` or `offset` is present.","schema":{"minimum":0,"type":"number"}}],"responses":{"200":{"description":"Paginated token list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenListApiResponseDto"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable code (`COIN_NOT_FOUND`, `RATE_EXPIRED`, `INVALID_API_KEY`, `HTTP_EXCEPTION` for class-validator, …)"},"message":{"description":"Human-readable message. Class-validator 400s may return a string **array** of constraint texts.","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"details":{"description":"Present for some validation (4xx) errors when thrown with `details`.","oneOf":[{"type":"object","additionalProperties":true},{"type":"array"}]}},"required":["code","message","requestId","timestamp"]}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable code (`COIN_NOT_FOUND`, `RATE_EXPIRED`, `INVALID_API_KEY`, `HTTP_EXCEPTION` for class-validator, …)"},"message":{"description":"Human-readable message. Class-validator 400s may return a string **array** of constraint texts.","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"details":{"description":"Present for some validation (4xx) errors when thrown with `details`.","oneOf":[{"type":"object","additionalProperties":true},{"type":"array"}]}},"required":["code","message","requestId","timestamp"]}}}}}}},"summary":"List supported tokens","tags":["App","Tokens"]}}},"components":{"schemas":{"TokenListApiResponseDto":{"type":"object","properties":{"tokens":{"type":"array","items":{"$ref":"#/components/schemas/PublicTokenItemApiDto"}},"totalTokens":{"type":"number","description":"Number of token objects in this response page (matches `tokens.length`)"},"limit":{"type":"number","description":"Page size for this response"},"offset":{"type":"number","description":"Pagination offset"},"total":{"type":"number","description":"Total tokens matching filters before pagination"}},"required":["tokens","totalTokens","limit","offset","total"]},"PublicTokenItemApiDto":{"type":"object","properties":{"uuid":{"type":"string","description":"Internal coin UUID (used by workflows; not required on public query params)"},"network":{"type":"string","description":"Canonical chain slug (`GET /v1/chains` → `id`)"},"ticker":{"type":"string","description":"Token ticker"},"name":{"type":"string","description":"Display name"},"supportsFixedRate":{"type":"boolean","description":"Whether any catalogued route supports a fixed rate for this asset"},"contractAddress":{"type":"object","description":"Contract address; `null` for native coins","nullable":true},"engineSupport":{"description":"Engines that support this token: `on-chain` (DEX), `off-chain` (CEX), and sometimes `private`","type":"array","items":{"type":"string"}},"logoUrlCoin":{"type":"string","description":"Token logo URL"},"regexAddress":{"type":"string","description":"JavaScript regex source used to validate addresses of this asset (`receiveAddress` / `refundAddress` on swap)"},"explorerAddressUrl":{"type":"string","description":"Block-explorer URL template for an address"},"explorerTransactionUrl":{"type":"string","description":"Block-explorer URL template for a transaction"},"decimals":{"type":"object","nullable":true,"description":"Token decimals"},"logoUrlsNetwork":{"type":"object","nullable":true,"description":"Network / chain logo URL"},"coingeckoCoinId":{"type":"object","nullable":true,"description":"CoinGecko coin id (`bitcoin`, `ethereum`, `usd-coin`)"},"currentPriceUsd":{"type":"object","nullable":true,"description":"Spot price in USD from CoinGecko (numeric string)"}},"required":["uuid","network","ticker","name","supportsFixedRate","contractAddress"]}}}}
```