Skip to main content
Olympus stands apart from the world below, and Olympex stands apart from your funds. For swaps, the API computes routes and returns unsigned transaction calldata; custody, signing and broadcasting stay with your application and your users. For limit orders and DCA, the maker authorizes Olympex once per token pair and limits it with a token allowance, and Olympex executes the orders within that limit. This page describes those boundaries, how requests to the API are authenticated, and what your integration is responsible for.

​
Non-custodial by design

  • No custody. Olympex never takes custody of user or integrator funds. A swap moves assets from account, through the Olympex aggregator contract at swap.to, in a transaction your wallet signs. An order execution moves them from the maker’s wallet, through the Olympex order contract, and sends the output back to the maker.
  • No keys. No endpoint accepts, generates or stores a wallet private key or seed phrase.
  • No broadcasting of your swaps. POST /swap returns calldata and never sends it. Single-chain requests accept a dryRun flag for compatibility, and it has no effect.
  • Allowances you control. The contracts in the swap path can spend your tokens only up to the allowance you grant to contractToApprove. The order contract can spend a maker’s tokens only up to the allowance the maker grants it, and only for pairs the maker has signed.
Your API credentials authenticate calls to the API. They can’t sign for any wallet. They do control the orders created with your API key: a leaked credential lets someone call the API as your account, including creating, changing and cancelling those orders, and the maker’s allowance to the order contract is what limits the result. A leak needs an immediate response, described in Credential lifecycle.

​
Calldata is bound and short-lived

The calldata from POST /swap is built for one sender and one moment:
  • Bound to account. Send it from the account you passed to /swap. Another Olympex swap from the same account can invalidate earlier calldata, so build and send one swap at a time per account.
  • Expiring. The calldata carries an on-chain expiry, 5 minutes on most routes, and some routes include a market maker’s firm quote that expires within seconds. Don’t store or queue it: request it right before you send.
  • Protected by a minimum. Single-chain calldata reverts if the swap would deliver less than minOutAmount.
There is no testnet. Calldata from POST /swap is real mainnet calldata, and broadcasting it moves funds.

​
Check before you sign

Before a wallet signs a swap transaction, check that:
  1. from is the account you sent to /swap.
  2. to matches swap.to, the Olympex aggregator contract, exactly as /swap returned it. Record the address you see for each chain; if it changes unexpectedly, stop and confirm with partners@olympex.io before signing.
  3. value is "0" for ERC-20 input. For native-token input, value is the native amount the transaction sends, in wei: compare it with the amount the user agreed to.
  4. For single-chain swaps, minOutAmount is within your slippage of outAmount.
  5. Any approval goes to contractToApprove. It isn’t always the same address as to.
  6. eth_estimateGas for the transaction succeeds. A 200 from /swap doesn’t guarantee that the calldata executes, and a transaction that reverts still costs gas. See Falling back with aggregatorOrder.

​
Approvals

  • For ERC-20 input to a swap, check the current allowance of contractToApprove first. If it is lower than the input amount, approve the exact input amount, in base units. Never approve an unlimited amount: an open allowance outlives the swap and exposes your whole balance of that token if the spender is ever compromised.
  • Some tokens, such as USDT, require you to set the allowance to 0 before setting a new non-zero value.
  • Native-token input needs no approval.
  • Set allowances you no longer need back to 0.
The order contract for limit orders and DCA is a different spender, with its own allowance. The next section covers it.

​
Order signatures and allowances

A limit order or a DCA strategy needs two authorizations from the maker’s wallet: a signature over the token pair, and an allowance to the Olympex order contract. This is what each one allows:
  • The signature authorizes one pair. It lets the Olympex order contract execute swaps of the token sold for the token bought from the maker’s wallet.
  • It doesn’t bind the terms. It covers no amount, price, expiry, chain or specific order. Olympex enforces the amounts, prices and expiry of your orders when it executes them.
  • It outlives your orders. It stays valid after you cancel an order, and the same signature serves limit orders and DCA for that pair.
  • The allowance is the on-chain limit. The order contract can’t spend more of a token than the maker’s allowance to it. That limit applies whatever an order says, including an order changed through a leaked credential.
  • The order contract is an upgradeable proxy operated by Olympex.
Olympex doesn’t check the signature when you create an order: verify it yourself before you send it. The maker must be an externally owned account, because only 65-byte ECDSA signatures are accepted. Order signatures and allowances has the signing code and the contract address on each chain. Allowance hygiene for the order contract:
  • Approve only what the maker’s open orders need, never an unlimited amount. The allowance is shared by every open limit order and active DCA strategy that sells the same token on the same chain, so approve their sum.
  • Lower the allowance when you cancel orders or strategies. Cancelling through the API doesn’t change it.
  • To stop every order that sells a token, set the allowance to 0. Do it immediately if you suspect a credential leak.
  • Approve only the order contract address published for the chain. It isn’t the contractToApprove that POST /swap returns.

​
How requests are authenticated

An API account has three credentials: Every signed request carries four headers: 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 has the full algorithm and reference code. These checks run on every signed request: The signature proves the request was made with your secret key and binds it to its method, path, query and body, so any change to them is detectable. GET and DELETE requests have no body, so their signature covers the hash of the empty string. The timestamp and nonce checks limit how long, and how often, a signed request is accepted. The signature covers the method, the path, the canonical query, the timestamp, the nonce and the body hash. It doesn’t cover the other headers. Headers signed for one request are rejected on any other method, path or query, and each set is accepted once, until its timestamp is more than 300 seconds old. Treat signed headers as single-use credentials for the one request you signed them for:
  • Sign each request right before you send it.
  • Never log, store or share signed headers.
  • Use a new nonce for every request. The nonce makes each set of headers usable once, within 5 minutes.
The passphrase travels in x-passphrase on every signed request, so any log or trace that records request headers exposes it. Protect it exactly like the secret key.

​
Credential lifecycle

New accounts can call signed endpoints immediately; there is no activation step. Credentials don’t expire. The API has no rotation, revocation, deletion or scoping feature, and requests aren’t restricted by source IP address. Because credentials can’t be replaced in place, keep them in one secrets manager so that replacing them is a single change. Choose a passphrase of at least 24 random characters from a password manager, in printable ASCII with no leading or trailing spaces. Credentials explains why other values can create an account you can’t use. If a credential leaks:
1

Stop open orders (if you use limit orders or DCA)

Set each maker’s allowance to the order contract to 0 for every token its open orders sell: that stops execution on-chain. Then list the limit orders and DCA strategies created with the leaked credentials, record their IDs and cancel them. Do it before the account is deactivated: a new account can’t see orders created with another API key.
2

Deactivate the account

Email partners@olympex.io with your API key ID and ask for the account to be deactivated. Never send the secret key or the passphrase.
3

Create a new account

Create new credentials with POST /accounts, for example from a terminal as shown in Create a test API key, and store them in your secrets manager.
4

Replace and verify

Deploy the new credentials, confirm that signed requests succeed, then delete the old credentials from every system that held them. Create again, under the new account, any orders you still want, and set the allowances to what they need.

​
Transport and handling

  • HTTPS only. The API is served over HTTPS; plain HTTP connections to the API host are refused.
  • Server-side only. Call signed endpoints from your server. Never ship the secret key or passphrase in a browser, mobile or desktop app.
  • Out of logs. Redact x-passphrase and x-signature in HTTP client logs, error reports and traces, and never commit credentials to a repository.
  • Accurate clocks. Keep your server clock synchronized, for example with NTP. Timestamps more than 300 seconds from server time are rejected.

​
Shared responsibility

​
Security reviews and reports

For security questionnaires, or to report a suspected vulnerability, contact partners@olympex.io. Include the meta.requestId, or the apigw-requestid response header for gateway responses, of any request your report concerns. The privacy notice describes how Olympex handles data.

​
What this means for your integration

  • Treat the passphrase exactly like the secret key: both stay on your server, in a secrets manager, out of logs. Treat signed headers as single-use, and never log them.
  • Verify every transaction before it is signed, and approve exact amounts only.
  • For limit orders and DCA, keep the allowance to the order contract at what open orders need, and set it to 0 to stop them all.
  • Prepare your leak response before you need it: stop open orders, deactivate through partners@olympex.io, create a new account, redeploy.

Sign requests

The signing algorithm and reference code.

Order signatures and allowances

The pair signature, the allowance and the order contract.

Execute a swap

Approve, estimate gas and send safely.

Going to production

The checklist before real volume.