> ## Documentation Index > Fetch the complete documentation index at: https://docs.olympex.io/llms.txt > Use this file to discover all available pages before exploring further. # List tokens > List the tokens Olympex lists on a chain, with each token's address, symbol, decimals and logo. `GET /tokens?chainId=137` returns the tokens Olympex lists on one chain: each token's address, symbol, name, decimals and logo. Use it to fill a token picker and to convert amounts between human-readable units and base units. Take `chainId` from [`GET /chains`](/api-reference/chains/list-chains), and cache the result: the list is large and changes rarely. Signed endpoint with no request body. Send `Content-Type: application/json` and the four headers `x-api-key-id`, `x-value-info`, `x-passphrase` and `x-signature` described in [Sign requests](/authentication/sign-requests), signed over the method, the path, the canonical query and the empty string. The query parameter `chainId` is required and must be a positive integer, for example `/tokens?chainId=137`; it is signed as the canonical query, and any other query parameter returns `400 VALIDATION_ERROR`. The response is `data.chainId` (a number) and `data.tokens`, an unsorted, unpaginated array of objects with `address`, `symbol`, `name`, `decimals`, `icon` and sometimes `logoURI`. Compare addresses case-insensitively and identify tokens by address, never by symbol: symbols aren't unique, and some carry a `_` suffix such as `STRK_1`. The native token is listed in lowercase, `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`. `icon` can be an empty string. ## Choose the chain * `chainId` is required and must be a positive integer. Take it from [`GET /chains`](/api-reference/chains/list-chains), which returns integers: `137` becomes `?chainId=137`. * Send `chainId` as a plain decimal integer: `?chainId=137`. `GET /tokens` also reads some other spellings, such as `0x89` or `137.0`, as 137. Don't rely on them. * `chainId` is the only query parameter. A missing, empty or non-numeric `chainId`, or any other query parameter, returns `400 VALIDATION_ERROR` `Invalid query parameters`. `error.details` reports an unknown parameter under `field` `chainId`, for example `"Unrecognized key: \"foo\""`. * A chain that isn't enabled returns `400 VALIDATION_ERROR` with the message `Chain is not enabled`. * The response echoes the chain as a number in `data.chainId`. * The query string is part of the signature: sign `chainId=137` as the canonical query, and the empty string as the body, as for every `GET`. ## Cache the list The list holds hundreds of tokens per chain. It comes in one response, unsorted, unpaginated and uncompressed, even when you send `Accept-Encoding: gzip`, and it changes rarely. There is no `ETag` or `Last-Modified` header, so you can't make a conditional request: refresh the list on a schedule. * Cache it per chain on your side, for example for 24 hours, instead of calling `GET /tokens` for every page view or quote. * Sort it yourself for display. * Every enabled chain has a token list. An empty `tokens` array or a `500 TOKEN_LIST_ERROR` means the list couldn't be read, not that the chain has no tokens: keep using your cached list and retry with backoff. ## Match tokens by address * **Identify a token by its address, never by its symbol.** Symbols aren't unique. * **Compare addresses case-insensitively.** Address casing varies between entries. Lowercase both sides, and key your cache by the lowercase address. * **The native token** is listed as `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`, the lowercase form of `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`. [`POST /quotes`](/api-reference/quotes/get-quote) and [`POST /swap`](/api-reference/swap/build-swap) accept it in either casing, so compare it case-insensitively. Limit orders and DCA can't sell it: use the wrapped token, for example WETH on Ethereum (`0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`), WBNB on BNB Chain (`0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c`) or WPOL on Polygon (`0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270`). * **POL on Polygon.** The Polygon list also carries `0x0000000000000000000000000000000000001010`, POL's system contract, with the same symbol. Don't offer it: it can't be approved, and quotes can route it at prices unrelated to POL. Use the native pseudo-address for POL. * **Symbols are labels, not identifiers.** When several listed tokens share a symbol, some carry a numeric suffix such as `STRK_1` or `USDP_2`, and the number can change when the list is refreshed. A few symbols also differ from the contract's `symbol()` in case or have trailing spaces. Before you display a symbol, trim it and drop a trailing `_`. Where you need the token's real symbol, as a limit order's `tokenASymbol` and `tokenBSymbol` do, read `symbol()` from the token contract. * **Logos.** `icon` is a logo URL, usually on `cdn.olympex.io`, or an empty string when there is no logo. Some URLs point to third-party hosts that may not serve the image, so show a fallback when a logo is empty or fails to load. Load logos with an `` element: the CDN sends no CORS headers, so a browser `fetch` can't read them. Some entries also carry `logoURI`. * **Other fields** can appear on an entry. Ignore the ones you don't use. A listed token doesn't mean every pair has a route: request a [quote](/api-reference/quotes/get-quote) to confirm a pair. The list doesn't limit what you can trade either: quotes, swaps, limit orders and DCA strategies accept any valid token address, listed or not. The list has no ranking or verification flag. ## Convert amounts with decimals `decimals` converts between the two units the API uses. [Conventions](/api-reference/conventions#amounts) lists the unit of every amount field. | Amount | Unit | What to do | | - | - | - | | `params.amount` on quotes and swaps, limit order `amount`, DCA `totalAmount` | Human-readable | Send it as is. Olympex resolves the decimals. | | Quote and swap outputs such as `quote.outAmount` | Base units | Divide by 10 to the power of `decimals` to display it. | | Token allowances and balances on-chain | Base units | Multiply a human-readable amount by 10 to the power of `decimals` before you approve it. | USDC on Polygon has 6 decimals: a `quote.outAmount` of `"10034668"` is 10.034668 USDC, and an allowance of 10 USDC is `10000000` base units. Use integer or decimal arithmetic, never floating point. ```bash cURL theme={null} # List the tokens Olympex lists on Polygon (chain ID 137). # Needs openssl, curl and OLYMPEX_API_KEY_ID, OLYMPEX_SECRET_KEY, OLYMPEX_PASSPHRASE. METHOD=GET ENDPOINT=/tokens QUERY='chainId=137' BODY='' # GET has no body: the signature covers the empty string TS="${OLYMPEX_TIMESTAMP:-$(date +%s)}" NONCE="${OLYMPEX_NONCE:-$(openssl rand -hex 12)}" BODY_HASH="$(printf '%s' "$BODY" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')" VALUE_INFO="$(printf '%s\n%s\n%s' "$TS" "$NONCE" "$BODY_HASH")" MESSAGE="$(printf 'OLPX-HMAC-SHA256-V2\n%s\n%s\n%s\n%s\n%s\n%s' "$TS" "$NONCE" "$METHOD" "/api/v1$ENDPOINT" "$QUERY" "$BODY_HASH")" curl -sS -X "$METHOD" "https://api-rest.olympex.io/api/v1$ENDPOINT${QUERY:+?$QUERY}" \ -H "content-type: application/json" \ -H "x-api-key-id: $OLYMPEX_API_KEY_ID" \ -H "x-value-info: $(printf '%s' "$VALUE_INFO" | openssl base64 -A)" \ -H "x-passphrase: $OLYMPEX_PASSPHRASE" \ -H "x-signature: $(printf '%s' "$MESSAGE" | openssl dgst -sha256 -hmac "$OLYMPEX_SECRET_KEY" -binary | od -An -v -tx1 | tr -d ' \n')" ``` ```ts TypeScript theme={null} // npm install viem import { formatUnits } from "viem"; import { olympexRequest } from "./sign-request.ts"; // /authentication/sign-requests type Token = { address: string; symbol: string; name: string; decimals: number; icon: string; logoURI?: string }; const { tokens } = await olympexRequest<{ chainId: number; tokens: Token[] }>("GET", "/tokens?chainId=137"); // Casing varies between entries and symbols aren't unique: key by lowercase address. const byAddress = new Map(tokens.map((token) => [token.address.toLowerCase(), token])); const usdc = byAddress.get("0x3c499c542cef5e3811e1192ce70d8cc03d5c3359"); // USDC on Polygon if (usdc) console.log(usdc.symbol, formatUnits(10034668n, usdc.decimals)); // USDC 10.034668 ``` ```python Python theme={null} from decimal import Decimal from sign_request import olympex_request # /authentication/sign-requests tokens = olympex_request("GET", "/tokens?chainId=137")["tokens"] # Casing varies between entries and symbols aren't unique: key by lowercase address. by_address = {token["address"].lower(): token for token in tokens} usdc = by_address.get("0x3c499c542cef5e3811e1192ce70d8cc03d5c3359") # USDC on Polygon if usdc: print(usdc["symbol"], Decimal("10034668").scaleb(-usdc["decimals"])) # USDC 10.034668 ``` ```json 200 theme={null} { "success": true, "data": { "chainId": 137, "tokens": [ { "address": "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359", "decimals": 6, "icon": "https://cdn.olympex.io/tokens/images/137/0x3c499c542cef5e3811e1192ce70d8cc03d5c3359.png", "name": "USD Coin", "symbol": "USDC" }, { "address": "0x7ceb23fd6bc0add59e62ac25578270cff1b9f619", "decimals": 18, "icon": "https://cdn.olympex.io/tokens/images/137/0x7ceb23fd6bc0add59e62ac25578270cff1b9f619.png", "name": "Wrapped Ether", "symbol": "WETH" }, { "address": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f", "decimals": 6, "icon": "https://cdn.olympex.io/tokens/images/137/0xc2132d05d31c914a87c6611c10748aeb04b58e8f.png", "name": "Tether USD", "symbol": "USDT" } ] }, "meta": { "requestId": "EdjZqgk0IAMEVaA=", "version": "v1", "accountType": "integrator", "apiKeyId": "00000000-0000-4000-8000-000000000000" } } ``` ```json 400 chainId missing theme={null} { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Invalid query parameters", "details": [ { "field": "chainId", "message": "Invalid input: expected number, received NaN" } ] }, "meta": { "requestId": "EdjZwh0voAMEVlA=", "version": "v1", "accountType": "integrator", "apiKeyId": "00000000-0000-4000-8000-000000000000" } } ``` ```json 400 Chain not enabled theme={null} { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Chain 324 is not enabled", "details": [] }, "meta": { "requestId": "Edt2TjlIIAMEZkw=", "version": "v1", "accountType": "integrator", "apiKeyId": "00000000-0000-4000-8000-000000000000" } } ``` ```json 403 Gateway theme={null} { "message": "Forbidden" } ``` ```json 500 theme={null} { "success": false, "error": { "code": "TOKEN_LIST_ERROR", "message": "Unexpected token list handler error", "details": [ { "message": "Unknown error" } ] }, "meta": { "requestId": "EdjZ2hkzIAMEb0A=", "version": "v1", "accountType": "integrator", "apiKeyId": "00000000-0000-4000-8000-000000000000" } } ``` ## OpenAPI ````yaml api-reference/openapi.json GET /tokens openapi: 3.0.3 info: title: Olympex REST API version: 1.0.0 description: >- Aggregated swap quotes and transactions, limit orders and DCA strategies on EVM chains, plus the chain and token catalog. Every response uses the same envelope, except the API gateway's own responses (`{"message": …}`): `401` or `403` when the signed headers are missing or rejected, `429` when it throttles requests, and `500` or `503` when it can't get a response from Olympex in time. Chain IDs are integers on every endpoint. Signed endpoints require four signed headers; see [Sign requests](https://docs.olympex.io/authentication/sign-requests). termsOfService: https://docs.olympex.io/legal/terms contact: name: Olympex partnerships email: partners@olympex.io url: https://docs.olympex.io servers: - url: https://api-rest.olympex.io/api/v1 description: Olympex REST API v1 security: [] tags: - name: Accounts description: Create API credentials. - name: Quotes description: Aggregated single-chain and cross-chain quotes. - name: Swap description: Unsigned transaction calldata for a quoted route. - name: TxStatus description: Track a cross-chain transfer after you broadcast it. - name: Transactions description: On-chain status of a transaction you broadcast. - name: Chains and tokens description: Enabled chains and the tokens listed on each. - name: Limit orders description: Orders that Olympex executes when the market reaches your price. - name: DCA description: Strategies that buy a token in equal orders over time. - name: Docs description: Machine-readable API description. paths: /tokens: get: tags: - Chains and tokens summary: List tokens description: >- Returns the tokens Olympex lists on one chain: address, symbol, name, decimals and logo. The list is large (hundreds of tokens) and changes rarely, so cache it on your side. No request body: sign the empty string. The query string is signed in canonical form. operationId: listTokens parameters: - name: chainId in: query required: true description: >- Chain ID, for example `137`. It must be one of the chains from `GET /chains`. No other query parameters are allowed. schema: type: integer minimum: 1 example: 137 responses: '200': description: >- Tokens on the chain. Three entries shown; the real list has hundreds. content: application/json: schema: $ref: '#/components/schemas/TokensSuccessResponse' example: success: true data: chainId: 137 tokens: - address: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359' decimals: 6 icon: >- https://cdn.olympex.io/tokens/images/137/0x3c499c542cef5e3811e1192ce70d8cc03d5c3359.png name: USD Coin symbol: USDC - address: '0x7ceb23fd6bc0add59e62ac25578270cff1b9f619' decimals: 18 icon: >- https://cdn.olympex.io/tokens/images/137/0x7ceb23fd6bc0add59e62ac25578270cff1b9f619.png name: Wrapped Ether symbol: WETH - address: '0xc2132d05d31c914a87c6611c10748aeb04b58e8f' decimals: 6 icon: >- https://cdn.olympex.io/tokens/images/137/0xc2132d05d31c914a87c6611c10748aeb04b58e8f.png name: Tether USD symbol: USDT meta: requestId: EdjZqgk0IAMEVaA= version: v1 accountType: integrator apiKeyId: 00000000-0000-4000-8000-000000000000 '400': description: >- `chainId` is missing or not a positive integer, an unknown query parameter was sent, or the chain is not enabled. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing: summary: chainId missing value: success: false error: code: VALIDATION_ERROR message: Invalid query parameters details: - field: chainId message: 'Invalid input: expected number, received NaN' meta: requestId: EdjZwh0voAMEVlA= version: v1 accountType: integrator apiKeyId: 00000000-0000-4000-8000-000000000000 disabled: summary: Chain not enabled value: success: false error: code: VALIDATION_ERROR message: Chain 324 is not enabled details: [] meta: requestId: Edt2TjlIIAMEZkw= version: v1 accountType: integrator apiKeyId: 00000000-0000-4000-8000-000000000000 '401': description: >- A signing header is missing. The gateway answers with `{"message":"Unauthorized"}` before your request reaches Olympex; the handler answers with the `UNAUTHORIZED` envelope when the authorizer context is missing. content: application/json: schema: oneOf: - $ref: '#/components/schemas/GatewayError' - $ref: '#/components/schemas/ErrorResponse' example: message: Unauthorized '403': description: >- Authentication failed: unknown key, wrong passphrase, invalid signature, timestamp outside the ±300 s window, reused nonce, or inactive account (gateway `{"message":"Forbidden"}`). The handler answers with the `FORBIDDEN` envelope when the signed `bodyHash` is not the hash of an empty body. content: application/json: schema: oneOf: - $ref: '#/components/schemas/GatewayError' - $ref: '#/components/schemas/ErrorResponse' examples: gateway: summary: Signature rejected by the gateway value: message: Forbidden bodyHash: summary: Body does not match the signed hash value: success: false error: code: FORBIDDEN message: Invalid body hash details: [] meta: requestId: ENXGDhsXIAMEMEw= version: v1 accountType: integrator apiKeyId: 00000000-0000-4000-8000-000000000000 '404': description: >- Unknown path or wrong method (`NOT_FOUND`). `error.message` names the method and path. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: NOT_FOUND message: No route for GET /api/v1/quote details: [] meta: requestId: E7edogG4IAMEPYA= version: v1 '500': description: >- Olympex could not complete the request (`TOKEN_LIST_ERROR` or `INTERNAL_ERROR`), or the gateway could not get a response (`{"message":"Internal Server Error"}`), which also happens on the first request after a quiet period. Retry with backoff. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorResponse' - $ref: '#/components/schemas/GatewayError' example: success: false error: code: TOKEN_LIST_ERROR message: Unexpected token list handler error details: - message: Unknown error meta: requestId: EdjZ2hkzIAMEb0A= version: v1 accountType: integrator apiKeyId: 00000000-0000-4000-8000-000000000000 '503': description: >- The gateway could not get a response in time (the integration timeout is about 30 seconds) or the service is briefly unavailable. Returned by the gateway. Retry with backoff. content: application/json: schema: $ref: '#/components/schemas/GatewayError' example: message: Service Unavailable security: - ApiKeyId: [] ValueInfo: [] Passphrase: [] Signature: [] components: schemas: TokensSuccessResponse: type: object required: - success - data - meta properties: success: type: boolean enum: - true data: type: object required: - chainId - tokens properties: chainId: type: integer description: The requested chain, as a number. tokens: type: array items: $ref: '#/components/schemas/Token' description: >- Every token Olympex lists on the chain, unsorted and unpaginated. The list can be empty. meta: $ref: '#/components/schemas/Meta' ErrorResponse: type: object required: - success - error - meta properties: success: type: boolean enum: - false error: $ref: '#/components/schemas/ErrorBody' meta: $ref: '#/components/schemas/Meta' GatewayError: type: object required: - message description: >- Returned by the API gateway itself: `401` or `403` when the signed headers are missing or rejected, `429` when it throttles requests, and `500` or `503` when it can't get a response from Olympex in time. It has no `success`, `error` or `meta`. properties: message: type: string example: Forbidden Token: type: object required: - address - symbol description: >- One token from the list. Fields other than these can appear; ignore the ones you don't use. properties: address: type: string description: >- Token contract address. Casing varies between entries: compare addresses case-insensitively. The chain's native token (ETH, BNB, POL) is listed as `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`, the lowercase form of `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`; quotes and swaps accept either casing. symbol: type: string description: >- Token symbol, for example `USDC`. Symbols are not unique, and a few carry a suffix that tells duplicates apart (`STRK_1`) or differ in case or spacing from the token contract. Identify tokens by address, and read `symbol()` from the contract where you need the token's real symbol (limit orders do). name: type: string description: Token name. decimals: type: integer description: >- Token decimals. Use them to convert between human-readable amounts and base units. icon: type: string description: >- Logo URL, usually on `cdn.olympex.io`, or an empty string when there is no logo. Some URLs point to third-party hosts that may not serve the image: show a fallback when a logo fails to load. logoURI: type: string description: Logo URL, present on some entries in addition to `icon`. Meta: type: object required: - requestId - version properties: requestId: type: string description: Unique ID for this request. Include it when you contact support. version: type: string default: v1 description: API version that served the request. accountType: type: string description: >- Account type resolved by the signature check, for example `integrator`. Present when the request was authenticated; absent on the `404` for an unknown path or method. apiKeyId: type: string format: uuid description: >- The API key ID that signed the request. Present when the request was authenticated; absent on the `404` for an unknown path or method. ErrorBody: type: object required: - code - message - details properties: code: type: string description: >- Machine-readable error code. `VALIDATION_ERROR` (400), `UNAUTHORIZED` (401), `FORBIDDEN` (403), `NOT_FOUND` (404, also for an unknown path or method), `CONFLICT` (409), `NO_ROUTE` (422), and for 500: `QUOTE_ERROR`, `CROSS_CHAIN_QUOTE_ERROR`, `SWAP_ERROR`, `CROSS_CHAIN_SWAP_ERROR`, `SUPPORT_CHAIN_ERROR`, `ENABLED_CHAINS_ERROR`, `TOKEN_LIST_ERROR`, `TX_STATUS_ERROR`, `INTERNAL_ERROR`. Olympex can add codes: handle an unknown code by its HTTP status. message: type: string description: Human-readable summary. Don't parse it. details: type: array items: $ref: '#/components/schemas/ErrorDetail' ErrorDetail: type: object additionalProperties: true description: >- Validation errors carry `field` and `message`; other errors carry `message` only. properties: field: type: string description: >- Dot path of the invalid field, for example `params.chainId`. Empty for the top level. message: type: string securitySchemes: ApiKeyId: type: apiKey in: header name: x-api-key-id description: >- Your API key ID (UUID). See [Sign requests](https://docs.olympex.io/authentication/sign-requests). ValueInfo: type: apiKey in: header name: x-value-info description: >- Base64 of `timestamp + "\n" + nonce + "\n" + bodyHash`, where `timestamp` is Unix seconds, `nonce` is 24 new hexadecimal characters and `bodyHash` is the unpadded base64url SHA-256 of the canonical body. Passphrase: type: apiKey in: header name: x-passphrase description: Your account passphrase. Treat it like the secret key. Signature: type: apiKey in: header name: x-signature description: >- Lowercase hex HMAC-SHA256 (signature v2), keyed with your secret key string (UTF-8, not decoded), of seven lines joined with `\n`, with no trailing newline: `OLPX-HMAC-SHA256-V2`, `timestamp`, `nonce`, the uppercase method, `path`, `canonicalQuery` and `bodyHash`. `path` is the request path including `/api/v1`, without the query string, for example `/api/v1/limit-order/`. `canonicalQuery` is the query parameters decoded (`+` is a space), sorted by key and then by value, re-encoded per RFC 3986 and joined with `&`, or the empty string when there is no query. Headers signed for one request are rejected on any other. See [Sign requests](https://docs.olympex.io/authentication/sign-requests). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.