> ## 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.
# How Olympex works
> The request lifecycle from quote to settlement, and from order to execution: what the Olympex API does, what your application does, and where funds move.
The view from Olympus is simple. For a swap, your server asks Olympex for a route, Olympex compares the prices its liquidity sources offer and returns the winner as unsigned transaction calldata, and your wallet decides whether to sign and send it. For a limit order or a DCA strategy, you describe the trade once, and Olympex executes it later from the maker's wallet, within the allowance the maker grants. Olympex never holds your keys, and funds move only in a transaction you broadcast or in an order execution the maker has authorized.
## The API surface
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.
| Endpoint | Auth | What it does |
| - | - | - |
| [`POST /accounts`](/api-reference/accounts/create-account) | Public | Creates an API account and returns its API key ID and secret key. |
| [`GET /chains`](/api-reference/chains/list-chains) | Signed | Lists the chains Olympex has enabled. |
| [`GET /tokens`](/api-reference/tokens/list-tokens) | Signed | Lists the tokens Olympex lists on one chain. |
| [`POST /support-chain`](/api-reference/chains/check-chain-support) | Signed | Tells you whether Olympex supports a chain. |
| [`POST /quotes`](/api-reference/quotes/get-quote) | Signed | Quotes a swap on one chain or a transfer between two chains. |
| [`POST /swap`](/api-reference/swap/build-swap) | Signed | Builds unsigned transaction calldata for a route. Never broadcasts. |
| [`POST /tx-status`](/api-reference/transactions/get-transaction-status) | Signed | Reports the status of a cross-chain transfer. |
| [`GET /transactions/{hash}`](/api-reference/transactions/get-transaction) | Signed | Reports a transaction's on-chain status: pending, success, reverted or not found. |
| [`/limit-order`](/api-reference/limit-orders/list-limit-orders) and `/limit-order/{id}` | Signed | `GET`, `POST`, `PATCH` and `DELETE`: creates, lists, reads, updates and cancels limit orders. |
| [`/dca-order/strategies`](/api-reference/dca/list-dca-strategies), its sub-paths and `/dca-order/orders/{id}` | Signed | `GET`, `POST` and `PATCH`: creates, lists, reads, updates and cancels DCA strategies, and lists and reads their orders. |
Signed endpoints need four headers computed from your API key ID, secret key and passphrase. [Sign requests](/authentication/sign-requests) has the algorithm and reference code for TypeScript, Python and bash.
## The swap lifecycle
[`GET /chains`](/api-reference/chains/list-chains) returns the IDs of the enabled chains, and [`GET /tokens`](/api-reference/tokens/list-tokens) the tokens Olympex lists on each one. [Supported chains and tokens](/concepts/supported-chains) covers both, and where cross-chain transfers can start.
[`POST /quotes`](/api-reference/quotes/get-quote) with `mode: "single-chain"` or `mode: "cross-chain"`, the token pair, a human-readable `amount` and a `slippage` percentage. For a single-chain quote, Olympex asks each of its liquidity sources for a price and returns the winner: its `aggregatorId`, the expected `outAmount` in base units of the output token, and `aggregatorOrder`, the sources that quoted, best first. A cross-chain quote returns the provider, the bridge and the expected amount on the destination chain. The quote is not reserved.
[`POST /swap`](/api-reference/swap/build-swap) with the same pair and amount, the `aggregatorId` from the quote and the `account` that sends the transaction. The response holds everything you need to send: `to` (the Olympex aggregator contract), `data` (`calldata` for cross-chain), `value` in wei, and `contractToApprove`. Single-chain responses also return `minOutAmount`, the output below which the transaction reverts.
For ERC-20 input, approve `contractToApprove` for the exact input amount. Estimate gas with your RPC, then your wallet signs and sends `{to, data, value, gas}` from `account`. If the estimate reverts, don't send: build the swap again with the next source in `aggregatorOrder`, or request a new quote. Send right after `/swap`: the calldata carries an on-chain expiry, 5 minutes on most routes, and it is bound to `account`.
A single-chain swap settles in one transaction: read its receipt from your RPC, or poll [`GET /transactions/{hash}`](/api-reference/transactions/get-transaction). For a cross-chain transfer, poll [`POST /tx-status`](/api-reference/transactions/get-transaction-status) with the source transaction hash, the source chain ID and the `dexHash` from `/swap` until the provider reports success or failure.
## The order lifecycle
[Limit orders](/concepts/limit-orders) and [DCA strategies](/concepts/dca) run after you create them. They use the same chains and tokens as swaps, on the chains that have an [order contract](/concepts/order-authorization#the-order-contract).
The maker's wallet signs the token pair once. The signature lets the Olympex order contract swap that pair for the maker, and the same signature serves limit orders and DCA. [Order signatures and allowances](/concepts/order-authorization) has the code.
The maker approves the order contract for what its open orders need: for a limit order, `amount` plus the execution gas cost in the token sold; for a DCA strategy, `totalAmount`. The allowance is the on-chain limit on what Olympex can spend.
[`POST /limit-order`](/api-reference/limit-orders/create-limit-order) or [`POST /dca-order/strategies`](/api-reference/dca/create-dca-strategy), with the signature. Nothing moves on-chain yet.
When a limit order's price is reached, or as a DCA strategy's orders run, Olympex pulls the amount from the maker's wallet through the order contract, swaps it and sends the output to the maker. Olympex pays the gas and is reimbursed in tokens: in the token sold for limit orders, and out of the token bought for DCA.
Poll [`GET /limit-order/{id}`](/api-reference/limit-orders/get-limit-order) for a limit order, or [`GET /dca-order/strategies/{id}/orders`](/api-reference/dca/list-dca-strategy-orders) for a strategy's orders, until each reaches a final status.
## Who does what
| Stage | Olympex | Your application |
| - | - | - |
| Authenticate | The API gateway verifies the signed headers before the request reaches Olympex. | Signs every request with the secret key and a new nonce. |
| Quote | Queries the liquidity sources, ranks their quotes and returns the winner. | Chooses the pair, amount and slippage, and shows the quote to the user. |
| Build | Returns unsigned calldata bound to `account`. | Checks `to`, `value` and `minOutAmount` before anyone signs. |
| Execute a swap | Nothing. The API never signs or broadcasts the swap transaction. | Approves the input token, estimates gas, signs and broadcasts. |
| Execute an order | Executes limit orders and DCA orders from the maker's wallet, within its allowance, and pays the gas up front. | Signs the pair once, keeps the allowance at what open orders need, and cancels orders it no longer wants. |
| Track | Relays the cross-chain provider's status, and reports a transaction's receipt status and the status of orders. | Polls `/tx-status` and the order endpoints, and reads the receipt for single-chain swaps from its RPC or `GET /transactions/{hash}`. |
## Responses
Every response from Olympex uses the same envelope. `meta.requestId` identifies the request: log it, and include it when you contact support. `meta.apiKeyId` is the API key ID that signed the request.
```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"
}
]
},
"meta": {
"requestId": "ENUlmg3dIAMEMEw=",
"version": "v1",
"accountType": "integrator",
"apiKeyId": "00000000-0000-4000-8000-000000000000"
}
}
```
Requests the API gateway rejects before they reach Olympex, such as a missing signing header or a rejected signature, return only `{"message": "…"}`, with no `meta.requestId`. Their `apigw-requestid` response header carries the request ID instead; browsers can't read it on cross-origin calls. [Errors and retries](/authentication/errors-and-retries) covers every code and how to handle it.
## Non-custodial by design
* **For swaps, Olympex returns data, not transactions it controls.** `POST /swap` builds unsigned calldata and never broadcasts it. The `dryRun` flag that single-chain requests accept has no effect.
* **Swap funds move only when your wallet signs.** The transaction goes from `account` to `swap.to`, the Olympex aggregator contract, and only after you broadcast it. Approvals for swaps go to `contractToApprove`, for the exact amount.
* **Orders move funds only within the maker's authorization.** Olympex executes limit orders and DCA orders from the maker's wallet, but only for token pairs the maker has signed, and only up to the allowance the maker has granted the order contract. Setting that allowance to `0` stops them.
* **API credentials can't sign for any wallet.** They authenticate calls to the API. A leaked credential lets someone call the API as you, including creating, changing and cancelling the orders under your API key, which the maker's allowance still limits. It needs immediate action: see [Security model](/concepts/security-model).
## What the API does and does not do
| Does | Does not |
| - | - |
| Quote single-chain swaps across several liquidity sources and pick a winner. | Take custody of funds, or hold private keys or seed phrases. |
| Quote cross-chain transfers through `okx` or `rango` for API accounts. | Sign or broadcast your swap transactions. `POST /swap` returns calldata only. |
| Build unsigned calldata for the route you choose. | Reserve a quote or hold a price between calls. |
| Execute limit orders and DCA strategies from the maker's wallet, within the allowance the maker grants. | Spend more of a token than the maker's allowance to the order contract. |
| Report the on-chain status of a transaction you broadcast, and the status of cross-chain transfers, limit orders and DCA orders. | Decode a transaction or check which contract it called: `GET /transactions/{hash}` reports only its receipt status. |
| Apply your integrator fee on quotes and swaps signed by an API account. | Push status updates. You poll `POST /tx-status`, `GET /transactions/{hash}` and the order endpoints. |
| List the enabled chains and the tokens Olympex lists on each one. | Offer a testnet. Every quote, every calldata and every order targets mainnet. |
| Estimate gas and fees for display. | Vet tokens for you. You decide which token addresses your product offers. |
There is no testnet. Calldata from `POST /swap` is real mainnet calldata, and broadcasting it moves funds. Limit orders and DCA strategies are real orders that Olympex executes against the maker's allowance. Test with small amounts from a wallet you control.
## What this means for your integration
* Keep the path from quote to broadcast short: request `/swap` right after the quote, and send the transaction right after `/swap`.
* Keep API credentials on your server and signing keys in the wallet. The two never need to meet.
* For limit orders and DCA, keep the maker's allowance to the order contract at what open orders need: it is the on-chain limit on what Olympex can spend.
* Log `meta.requestId` for every call, or the `apigw-requestid` header for gateway responses, so support can trace any request you report.
## Related
How Olympex chooses the winning route and how to read it.
Sell at a target price, executed by Olympex.
Spread a purchase over equal orders.
What Olympex can and can't do with funds and credentials.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.