Skip to main content
Olympex is a non-custodial DEX aggregator for EVM chains. The Olympex REST API returns the best route Olympex finds across its liquidity sources for a swap on one chain or a transfer between two chains, builds the unsigned transaction that executes that route, and reports the status of cross-chain transfers until they settle. It also runs limit orders and DCA (dollar-cost averaging) strategies that Olympex executes for your users, and it lists the enabled chains and the tokens on each one. The API never asks for a private key: your wallet signs every swap you send, and orders spend only the token allowance you grant.

​
What you can build

  • Swap flows in a wallet, dApp or exchange: show the expected output and the route, then hand the calldata to the user’s wallet to sign.
  • Cross-chain transfers: one quote covers the swap on the source chain, the bridge and the swap on the destination chain, and /tx-status reports the transfer’s status until it settles.
  • Limit orders: create an order once and let Olympex execute it. The order executes when the market price of inTokenAddress, in outTokenAddress, reaches priceTrigger or better.
  • DCA strategies: spend a total amount in equal orders, one every frequency seconds, for example 100 USDC into WETH in 10 daily orders.
  • Chain and token pickers: GET /chains returns the chains Olympex has enabled, and GET /tokens returns the tokens it lists on each one, with addresses, symbols and decimals.
  • Server-side execution for treasury rebalancing and other automated flows that sign with keys you control.
  • Revenue on the flow you route: add your own integrator fee of up to 1% to quotes and swaps, paid to an address you choose.

​
Base URL

Every endpoint lives under one base URL:
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

The API has 19 endpoints. POST /accounts is public; every other endpoint requires signed headers. The full contract is published as an OpenAPI 3.0 spec. There is no SDK package: generate a client from the spec and wrap it with the reference signer, or use the signer’s own request helper.

​
How an integration works

This is the flow for a swap. Limit orders and DCA follow their own flow, described after the steps.
1

Create an API key

Create a test API key in one click, or create one from a terminal with POST /accounts if your browser blocks the call. You receive an API key ID and a secret key, a random string shown once, and the password you chose becomes your passphrase.
2

Sign every request

Each signed request carries four headers: your API key ID, your passphrase, the timestamp, nonce and body hash (x-value-info), and an HMAC-SHA256 signature over them and the request’s method, path and query, made with your secret key. A GET or DELETE has no body, so you sign the empty string. Sign requests has the algorithm and reference code in TypeScript, Python and bash.
3

Find the chains and tokens

GET /chains returns the chain IDs Olympex has enabled, and GET /tokens?chainId=137 returns each token’s address, symbol and decimals on Polygon. Both change rarely, so cache them.
4

Get a quote

POST /quotes returns the expected output (outAmount), the source that produced the best route (aggregatorId) and every source that quoted, best first (aggregatorOrder). A quote is not reserved, so move to the next step right away.
5

Build the swap

POST /swap takes the quote’s aggregatorId and the wallet that sends the transaction (account), and returns to, data (or calldata for cross-chain), value and the ERC-20 spender contractToApprove.
6

Sign and broadcast with your wallet

For ERC-20 input, approve contractToApprove for the exact amount. Estimate gas yourself with eth_estimateGas: a 200 from /swap doesn’t guarantee that the calldata executes, and if the estimate reverts, build the swap with the next source in aggregatorOrder. Then send the transaction from account immediately: the calldata is bound to that account and carries an on-chain expiry, 5 minutes on most routes. It is real mainnet calldata, so broadcasting it moves funds. Execute a swap walks through each call.
7

Track the result

For a cross-chain transfer, poll POST /tx-status with the source-chain transaction hash, the source chain ID and the dexHash from /swap. For a single-chain swap, read the transaction receipt from your RPC provider, or poll GET /transactions/{hash}.
For a limit order or a DCA strategy, the maker wallet signs the token pair once and approves the Olympex order contract. You then create the order, and poll it until it completes or you cancel it. Nothing moves when you create it: when it executes, Olympex pulls the tokens from the maker’s wallet through the order contract, swaps them and sends the output back to the same wallet. Place a limit order and Run a DCA strategy walk through each call.
Olympex is non-custodial: the API never asks for a private key. POST /swap returns unsigned calldata, and a swap moves funds only when your wallet signs and sends it. Limit orders and DCA strategies execute on-chain without another signature from your wallet, and your token allowance to the Olympex order contract caps what they can move. See Security model and Order signatures and allowances.

​
Conventions at a glance

  • Methods. Endpoints use GET, POST, PATCH and DELETE. GET and DELETE have no body. Every success returns HTTP 200, including creates and cancels.
  • Responses. Olympex answers with one envelope: {"success": true, "data": …, "meta": …} on success and {"success": false, "error": {"code", "message", "details"}, "meta": …} on failure. Responses from the API gateway (for example a rejected signature) carry only {"message": …}. See Errors and retries.
  • Amounts. You send amounts in human-readable units, never base units: "10" is 10 USDT. Quotes, swaps and limit orders take them as strings; DCA strategies take JSON numbers. Swap output amounts such as outAmount come back as integer strings in the output token’s base units ("10034668" is 10.034668 USDC).
  • Chain IDs. Every chain ID is a JSON integer (137), in requests and responses. API conventions lists every field.
  • Ownership. Limit orders and DCA strategies belong to the API key that created them. Another key can’t list, read or change them.
  • Environments. There is no sandbox or testnet. A test API key is a real account on the live API: /swap returns mainnet calldata, and an order you create can execute against the maker wallet’s allowance.
  • Support. The envelope’s meta.requestId identifies each request. Gateway responses have no meta.requestId; their apigw-requestid response header identifies the request instead. Include the ID when you contact partners@olympex.io.
API conventions covers each rule in detail.

​
Start building

Quickstart

Create a key and send your first signed requests in minutes.

Create a test API key

Get an API key ID, a secret key and a passphrase in one click.

API reference overview

Every endpoint, with request and response examples and an in-browser console.

How Olympex works

The request lifecycle from quote to settlement, and the concepts behind it: routing, slippage, gas and fees, security.