How Olympex works

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:

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`	Public	Creates an API account and returns its API key ID and secret key.
`GET /chains`	Signed	Lists the chains Olympex has enabled.
`GET /tokens`	Signed	Lists the tokens Olympex lists on one chain.
`POST /support-chain`	Signed	Tells you whether Olympex supports a chain.
`POST /quotes`	Signed	Quotes a swap on one chain or a transfer between two chains.
`POST /swap`	Signed	Builds unsigned transaction calldata for a route. Never broadcasts.
`POST /tx-status`	Signed	Reports the status of a cross-chain transfer.
`GET /transactions/{hash}`	Signed	Reports a transaction’s on-chain status: pending, success, reverted or not found.
`/limit-order` and `/limit-order/{id}`	Signed	`GET`, `POST`, `PATCH` and `DELETE`: creates, lists, reads, updates and cancels limit orders.
`/dca-order/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 has the algorithm and reference code for TypeScript, Python and bash.

The swap lifecycle

Check the chain and tokens (optional)

GET /chains returns the IDs of the enabled chains, and GET /tokens the tokens Olympex lists on each one. Supported chains and tokens covers both, and where cross-chain transfers can start.

Get a quote

POST /quotes 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.

Build the transaction

POST /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.

Approve, sign and broadcast

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.

Track the result

A single-chain swap settles in one transaction: read its receipt from your RPC, or poll GET /transactions/{hash}. For a cross-chain transfer, poll POST /tx-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 and DCA strategies run after you create them. They use the same chains and tokens as swaps, on the chains that have an order contract.

Sign the pair

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 has the code.

Approve the order contract

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.

Create the order or strategy

POST /limit-order or POST /dca-order/strategies, with the signature. Nothing moves on-chain yet.

Olympex executes

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.

Track the result

Poll GET /limit-order/{id} for a limit order, or GET /dca-order/strategies/{id}/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.

{
  "success": true,
  "data": true,
  "meta": {
    "requestId": "ENUlxjCsIAMEMUA=",
    "version": "v1",
    "accountType": "integrator",
    "apiKeyId": "00000000-0000-4000-8000-000000000000"
  }
}

{
  "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 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.

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.

Aggregation and routing

How Olympex chooses the winning route and how to read it.

Limit orders

Sell at a target price, executed by Olympex.

DCA strategies

Spread a purchase over equal orders.

Security model

What Olympex can and can’t do with funds and credentials.

Get started

Concepts

Authentication

Guides

How Olympex works

The API surface

The swap lifecycle

The order lifecycle

Who does what

Responses

Non-custodial by design

What the API does and does not do

What this means for your integration

Aggregation and routing

Limit orders

DCA strategies

Security model

​The API surface

​The swap lifecycle

​The order lifecycle

​Who does what

​Responses

​Non-custodial by design

​What the API does and does not do

​What this means for your integration

​Related

Aggregation and routing

Limit orders

DCA strategies

Security model

The API surface

The swap lifecycle

The order lifecycle

Who does what

Responses

Non-custodial by design

What the API does and does not do

What this means for your integration

Related