> ## 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.
# API reference overview
> The Olympex REST API on one page: base URL, endpoints, response envelope, authentication, the API console, the OpenAPI spec and versioning.
The Olympex REST API returns aggregated swap quotes, builds unsigned transaction calldata and tracks your transactions and cross-chain transfers. It also lists the chains and tokens Olympex supports, and manages limit orders and DCA strategies that Olympex executes for you. [`GET /chains`](/api-reference/chains/list-chains) returns the EVM chains Olympex has enabled.
Swaps are non-custodial: Olympex never holds your funds or broadcasts a swap, and you sign and send every swap transaction from your own wallet. Limit orders and DCA strategies work differently. Olympex executes them on-chain: it pulls the tokens from the maker wallet under the allowance that wallet granted to the Olympex order contract, and sends the output back to that wallet. [Order signatures and allowances](/concepts/order-authorization) explains the signature and the allowance that control this.
## Base URL
Every endpoint lives under one base URL:
```text theme={null}
https://api-rest.olympex.io/api/v1
```
Requests and responses are JSON. Endpoints use `GET`, `POST`, `PATCH` and `DELETE`: `POST` and `PATCH` send a JSON body, and `GET` and `DELETE` send none. Send `Content-Type: application/json` on every request, including the public ones and those without a body. Without it, or with another type such as curl's default `application/x-www-form-urlencoded`, a request with a body fails with `403` (`Invalid body hash`) on a signed endpoint or `400` (`Invalid JSON body`) on a public one.
## Endpoints
Every endpoint is signed except `POST /accounts`, which is public and needs only `Content-Type: application/json`. Signed endpoints also need the four signed headers described in [Authentication](#authentication).
### Accounts and authentication
| Method | Path | What it does | Reference |
| - | - | - | - |
| `POST` | `/accounts` | Public. Creates an API account and returns its API key ID and secret key. | [Create an account](/api-reference/accounts/create-account) |
### Quotes and swaps
| Method | Path | What it does | Reference |
| - | - | - | - |
| `POST` | `/quotes` | Finds the best single-chain or cross-chain route and its expected output. | [Get a quote](/api-reference/quotes/get-quote) |
| `POST` | `/swap` | Builds unsigned transaction calldata for a quoted route. Never broadcasts. | [Build a swap](/api-reference/swap/build-swap) |
| `POST` | `/tx-status` | Returns the status of a cross-chain transfer you broadcast. | [Get cross-chain transfer status](/api-reference/transactions/get-transaction-status) |
| `GET` | `/transactions/{hash}` | Returns the on-chain status of a transaction you broadcast (`?chainId=`): `pending`, `success`, `reverted` or `not_found`. | [Get on-chain transaction status](/api-reference/transactions/get-transaction) |
### Chains and tokens
| Method | Path | What it does | Reference |
| - | - | - | - |
| `GET` | `/chains` | Lists the IDs of the chains Olympex has enabled. | [List chains](/api-reference/chains/list-chains) |
| `GET` | `/tokens` | Lists the tokens on one chain (`?chainId=`), with their decimals. | [List tokens](/api-reference/tokens/list-tokens) |
| `POST` | `/support-chain` | Reports whether Olympex supports one chain. | [Check chain support](/api-reference/chains/check-chain-support) |
### Limit orders
| Method | Path | What it does | Reference |
| - | - | - | - |
| `GET` | `/limit-order` | Lists your limit orders, optionally filtered by status, chain or maker. | [List limit orders](/api-reference/limit-orders/list-limit-orders) |
| `POST` | `/limit-order` | Creates an order to sell a token when the market reaches `priceTrigger` or better. | [Create a limit order](/api-reference/limit-orders/create-limit-order) |
| `GET` | `/limit-order/{id}` | Returns one limit order. Poll it to follow the order's `status`. | [Get a limit order](/api-reference/limit-orders/get-limit-order) |
| `PATCH` | `/limit-order/{id}` | Changes the price, amount, expiry, slippage or gas price of a pending order. | [Update a limit order](/api-reference/limit-orders/update-limit-order) |
| `DELETE` | `/limit-order/{id}` | Cancels a pending order. The order stays readable. | [Cancel a limit order](/api-reference/limit-orders/cancel-limit-order) |
### DCA
| Method | Path | What it does | Reference |
| - | - | - | - |
| `GET` | `/dca-order/strategies` | Lists your DCA strategies, newest first, each with its orders. | [List DCA strategies](/api-reference/dca/list-dca-strategies) |
| `POST` | `/dca-order/strategies` | Creates a strategy that spends a total amount in equal orders over time. | [Create a DCA strategy](/api-reference/dca/create-dca-strategy) |
| `GET` | `/dca-order/strategies/{id}` | Returns one strategy, without its orders. | [Get a DCA strategy](/api-reference/dca/get-dca-strategy) |
| `PATCH` | `/dca-order/strategies/{id}` | Cancels a strategy or changes its price bounds. | [Update a DCA strategy](/api-reference/dca/update-dca-strategy) |
| `GET` | `/dca-order/strategies/{id}/orders` | Lists a strategy's orders, oldest first. | [List a strategy's orders](/api-reference/dca/list-dca-strategy-orders) |
| `GET` | `/dca-order/orders/{id}` | Returns one DCA order. | [Get a DCA order](/api-reference/dca/get-dca-order) |
The service also serves its own OpenAPI document and Swagger UI at the public `GET /openapi.json` and `GET /docs`. [OpenAPI specification](/api-reference/openapi-spec#service-hosted-spec-and-swagger-ui) explains why to build against the curated spec instead.
## How the endpoints fit together
### Swaps
1. **Create credentials once.** `POST /accounts` returns an API key ID and a secret key. The password you send becomes your passphrase.
2. **Pick a chain and tokens.** `GET /chains` returns the enabled chains, and `GET /tokens` the tokens on each one with their decimals. Cache both.
3. **Quote.** `POST /quotes` returns the best route and the `aggregatorId` of the liquidity source that produced it.
4. **Build the transaction.** `POST /swap` takes the same pair and amount, your wallet `account` and that `aggregatorId`, and returns calldata.
5. **Check it, then send it right away.** For an ERC-20 input, approve `contractToApprove` for the exact amount if the allowance is too low. Run `eth_estimateGas` on the exact transaction: a `200` from `/swap` doesn't guarantee that the calldata executes. If the estimate reverts, build again with the next `aggregatorId` in the quote's `aggregatorOrder`, or request a new quote for a cross-chain swap. Then sign and broadcast from `account` at once. The calldata expires on-chain, after 5 minutes on most routes, and sooner on routes that include a market maker's firm quote.
6. **Track it.** Poll `GET /transactions/{hash}` with the chain ID until `status` is `success` or `reverted`, or read the receipt from your RPC. For a cross-chain transfer, then poll `POST /tx-status` with the source transaction hash, the source chain ID and the `dexHash` from `/swap`.
`POST /support-chain` checks a single chain at runtime. The guides walk through each flow: [Execute a swap](/guides/execute-a-swap) and [Cross-chain swap end-to-end](/guides/cross-chain-swap-end-to-end).
### Limit orders and DCA
1. **Authorize the pair.** The maker wallet signs one message per token pair, and approves the Olympex order contract for what its open orders need. [Order signatures and allowances](/concepts/order-authorization) shows both steps.
2. **Create.** `POST /limit-order` creates an order that executes when the market reaches `priceTrigger` or better. `POST /dca-order/strategies` creates a strategy that spends `totalAmount` in `iterations` equal orders, one every `frequency` seconds. Nothing moves on-chain when you create either one.
3. **Follow it.** Poll `GET /limit-order/{id}` for the order's `status`. For a strategy, list its orders with `GET /dca-order/strategies/{id}/orders`.
4. **Change or cancel.** `PATCH /limit-order/{id}` and `DELETE /limit-order/{id}` act only on a pending order: on any other status they return `409 CONFLICT`. `PATCH /dca-order/strategies/{id}` with `{"status":"cancelled"}` stops a strategy.
The guides walk through both: [Place a limit order](/guides/create-a-limit-order) and [Run a DCA strategy](/guides/build-a-dca-strategy).
## Response envelope
Every endpoint returns the same envelope, whatever its method, and every success is HTTP `200`, including creates (`POST`) and cancels (`DELETE`). `success` tells you which of `data` or `error` is present.
```json Success theme={null}
{
"success": true,
"data": true,
"meta": {
"requestId": "ENUlxjCsIAMEMUA=",
"version": "v1",
"accountType": "integrator",
"apiKeyId": "00000000-0000-4000-8000-000000000000"
}
}
```
```json Error theme={null}
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request body",
"details": [
{
"field": "params.chainId",
"message": "Invalid input: expected number, received string"
},
{
"field": "params.inTokenAddress",
"message": "Must be a valid EVM address"
},
{
"field": "params.amount",
"message": "Invalid input: expected string, received number"
},
{
"field": "params.gasPrice",
"message": "Invalid input: expected string, received undefined"
}
]
},
"meta": {
"requestId": "ENUlmg3dIAMEMEw=",
"version": "v1",
"accountType": "integrator",
"apiKeyId": "00000000-0000-4000-8000-000000000000"
}
}
```
| Field | Description |
| - | - |
| `success` | `true` on success, `false` on error. Branch on it, not on the value of `data`: `POST /support-chain` returns `"data": false` for an unsupported chain. |
| `data` | The result, on success: an object for most endpoints, an array for list endpoints, and a boolean for `/support-chain`. |
| `error` | `code`, `message` and `details`, on error. `code` is stable and machine-readable; `message` is for humans. |
| `meta.requestId` | Unique ID of the request. Log it, and include it when you contact support. |
| `meta.version` | API version that served the request: `v1`. |
| `meta.accountType` | On signed endpoints: the account type resolved from your signature, `integrator` for accounts created with `POST /accounts`. |
| `meta.apiKeyId` | On signed endpoints: the API key ID that signed the request. |
The API gateway in front of Olympex can also answer on its own, for example when a signing header is missing or a request runs past the gateway timeout. Those responses carry only a `message` field. [Conventions](/api-reference/conventions#errors) covers both shapes, every error code and the gateway responses.
## Authentication
Olympex authenticates each signed request with an HMAC-SHA256 signature over the method, the path, the query, a timestamp, a single-use nonce and a hash of the body. `POST /accounts` gives you the three credentials: an API key ID, a secret key (a random string, shown once) and the passphrase you chose.
| Header | Value |
| - | - |
| `x-api-key-id` | Your API key ID. |
| `x-value-info` | Standard base64, on one line, of `timestamp`, `nonce` and `bodyHash` joined with newlines. |
| `x-passphrase` | Your passphrase. |
| `x-signature` | Lowercase hex HMAC-SHA256, keyed with your secret key, of the signed message: `OLPX-HMAC-SHA256-V2`, `timestamp`, `nonce`, the method, the path, the canonical query and `bodyHash`, joined with newlines. |
`timestamp` is the current Unix time in seconds, `nonce` is 24 new random hexadecimal characters, and `bodyHash` is the unpadded base64url SHA-256 of the exact body you send: the empty string for a `GET` or `DELETE`, which has no body. The method is uppercase. The path is the URL path you call, starting with `/api/v1`, without the query string. The canonical query is the query string with its parameters decoded, sorted by key and then by value, and percent-encoded again per RFC 3986, or the empty string when there is none. Headers signed for one request don't work on another, and each nonce works once. [Sign requests](/authentication/sign-requests) has the full algorithm and reference code.
`GET` and `DELETE` requests have no body: sign the empty string. The signature also covers the method, the path and the query, so headers signed for one request are rejected on any other. Sign right before you send, and treat each set of signed headers as a single-use credential.
Keep the secret key and the passphrase on your server. The passphrase travels in every request. Never ship either one in a browser, mobile or desktop app.
[Credentials](/authentication/credentials) explains what each credential is and how to store it.
## API console
The [API console](/api-reference/console) signs requests in your browser and sends them straight to the API, so you can call every signed endpoint without writing code. Every signed endpoint page also has a **Try it** console, and [Create an account](/api-reference/accounts/create-account) has the one-click key creator. If your browser blocks a request, use the console's [Copy as cURL](/api-reference/console#copy-as-curl) or [create a key from a terminal](/get-started/create-an-api-key#create-a-key-from-a-terminal). Use a test API key: these pages are hosted by Mintlify and load analytics. Limit orders and DCA strategies you create from the console are real.
## OpenAPI specification
The API is described by an OpenAPI 3.0.3 document with examples:
```text theme={null}
https://docs.olympex.io/api-reference/openapi.json
```
The endpoint pages in this reference are generated from it. [OpenAPI specification](/api-reference/openapi-spec) shows how to generate a typed client and add request signing to it.
## How to read an endpoint page
| Section | What it tells you |
| - | - |
| **Summary** | What the endpoint does and how it connects to the other endpoints. |
| **Try it** | On signed endpoints, a console that signs and sends the request from your browser. |
| **Guidance** | Units, parameter and body rules, and the flow around the call. |
| **Parameters**, **Body** and **Response** | Every path parameter, query parameter and field, generated from the OpenAPI spec, with types, required flags and descriptions. |
| **Request examples** | cURL, TypeScript and Python, using the [reference signers](/authentication/sign-requests). |
| **Response examples** | Examples from the OpenAPI spec, plus the gateway responses you can receive. |
## Versioning
* The API version is part of the path (`/api/v1`), and every endpoint reports it in `meta.version`.
* Within `v1`, responses can gain new fields and `error.code` can gain new values. Ignore fields you don't recognize, and handle an unknown code by its HTTP status.
* Treat `aggregatorId` as an opaque string and pass it back exactly as the quote returned it. `/tx-status` reports each provider's own status values: match the documented success and failure values and treat anything else as in progress.
* Treat a limit order, DCA strategy or DCA order `status` you don't recognize as not final.
[Conventions](/api-reference/conventions#forward-compatibility) lists the full set of forward-compatibility rules.
## Where to start
Create a key, sign a request and get your first quote.
The signing algorithm, reference code in three languages and two known-answer vectors.
Sign and send any endpoint from your browser.
Methods, amounts, chain IDs, IDs, errors and request IDs.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.