> ## 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 chains
> List the IDs of the chains Olympex has enabled: the source of truth for which chains to offer.
`GET /chains` returns the IDs of the chains Olympex has enabled, as integers in ascending order. It is the source of truth for which chains to offer: call it instead of hard-coding which chains are enabled. It returns IDs only: take names and capabilities from [Supported chains](/concepts/supported-chains). Then get each chain's tokens with [`GET /tokens`](/api-reference/tokens/list-tokens). [`POST /support-chain`](/api-reference/chains/check-chain-support) checks a single chain against the same list.
Signed endpoint with no request body. It takes no parameters and ignores any query parameters you send. 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 and the empty string. The response is `data.chainIds`, an array of chain IDs as integers in ascending order, for example `[1,10,56,137,8453,42161,43114,59144]`. Every endpoint takes chain IDs as integers.
## Chain IDs are integers
`data.chainIds` holds integers (`137`), the type every endpoint takes: pass them unchanged to [`GET /tokens`](/api-reference/tokens/list-tokens), [`POST /quotes`](/api-reference/quotes/get-quote), [`POST /swap`](/api-reference/swap/build-swap), [`POST /support-chain`](/api-reference/chains/check-chain-support), [`POST /tx-status`](/api-reference/transactions/get-transaction-status), [`GET /transactions/{hash}`](/api-reference/transactions/get-transaction), limit orders and DCA.
[Conventions](/api-reference/conventions#chain-ids) lists every chain ID field.
## Cache the list
Call `GET /chains` when your service starts and refresh it on the same schedule as your [token lists](/api-reference/tokens/list-tokens#cache-the-list), instead of before every request. When a chain leaves the list, stop offering it.
[Supported chains](/concepts/supported-chains) shows the chains enabled today and what each one supports.
An enabled chain doesn't mean every pair has a route: request a [quote](/api-reference/quotes/get-quote) to confirm a pair. Limit orders and DCA execute only on the chains listed in [The order contract](/concepts/order-authorization#the-order-contract).
## Sign the empty string
`GET /chains` has no body, so you sign the empty string: its `bodyHash` is `47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU`. The method and the path, `/api/v1/chains`, are signed with it.
```bash cURL theme={null}
# List the chains Olympex has enabled.
# Needs openssl, curl and OLYMPEX_API_KEY_ID, OLYMPEX_SECRET_KEY, OLYMPEX_PASSPHRASE.
METHOD=GET
ENDPOINT=/chains
QUERY=''
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}
import { olympexRequest } from "./sign-request.ts"; // /authentication/sign-requests
const { chainIds } = await olympexRequest<{ chainIds: number[] }>("GET", "/chains");
const enabledChains = new Set(chainIds);
console.log(enabledChains.has(137) ? "Offer Polygon" : "Hide Polygon");
```
```python Python theme={null}
from sign_request import olympex_request # /authentication/sign-requests
chain_ids = olympex_request("GET", "/chains")["chainIds"]
enabled_chains = set(chain_ids)
print("Offer Polygon" if 137 in enabled_chains else "Hide Polygon")
```
```json 200 theme={null}
{
"success": true,
"data": {
"chainIds": [
1,
10,
56,
137,
8453,
42161,
43114,
59144
]
},
"meta": {
"requestId": "E7eeEiPDIAMEP7Q=",
"version": "v1",
"accountType": "integrator",
"apiKeyId": "00000000-0000-4000-8000-000000000000"
}
}
```
```json 403 Invalid body hash theme={null}
{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "Invalid body hash",
"details": []
},
"meta": {
"requestId": "ENXGDhsXIAMEMEw=",
"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": "ENABLED_CHAINS_ERROR",
"message": "Unexpected enabled chains handler error",
"details": [
{
"message": "Unknown error"
}
]
},
"meta": {
"requestId": "EdjY9iZkoAMEVsg=",
"version": "v1",
"accountType": "integrator",
"apiKeyId": "00000000-0000-4000-8000-000000000000"
}
}
```
## OpenAPI
````yaml api-reference/openapi.json GET /chains
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:
/chains:
get:
tags:
- Chains and tokens
summary: List enabled chains
description: >-
Returns the IDs of the chains Olympex has enabled, as integers. Use it
to decide which chains to offer before you request tokens, quotes or
orders. No request body: sign the empty string.
operationId: listChains
responses:
'200':
description: Enabled chain IDs.
content:
application/json:
schema:
$ref: '#/components/schemas/ChainsSuccessResponse'
example:
success: true
data:
chainIds:
- 1
- 10
- 56
- 137
- 8453
- 42161
- 43114
- 59144
meta:
requestId: E7eeEiPDIAMEP7Q=
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 (`ENABLED_CHAINS_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: ENABLED_CHAINS_ERROR
message: Unexpected enabled chains handler error
details:
- message: Unknown error
meta:
requestId: EdjY9iZkoAMEVsg=
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:
ChainsSuccessResponse:
type: object
required:
- success
- data
- meta
properties:
success:
type: boolean
enum:
- true
data:
type: object
required:
- chainIds
properties:
chainIds:
type: array
items:
type: integer
description: Chain IDs enabled for this API, as integers in ascending order.
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
ErrorResponse:
type: object
required:
- success
- error
- meta
properties:
success:
type: boolean
enum:
- false
error:
$ref: '#/components/schemas/ErrorBody'
meta:
$ref: '#/components/schemas/Meta'
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.