Glossary

Terms used across the Olympex documentation, in alphabetical order. Field names appear exactly as they do in requests and responses.

​

Aggregator ID

aggregatorId names the liquidity source or cross-chain provider behind a route. A quote returns it, and you pass it unchanged to POST /swap to build calldata for the same route. Single-chain values are okx, oneInch, openOceanV3, openOceanV4, zeroExV2AllowanceHolder, uniswapV3Hermes and uniswapV4Hermes. Cross-chain values are the cross-chain providers. See Aggregation and routing.

​

Aggregator order

aggregatorOrder lists the sources that returned a single-chain quote, best first. The first entry is the quote’s aggregatorId. Use the others as fallbacks when /swap fails for the first.

​

Allowance

The amount of an ERC-20 token that a spender may transfer from a wallet, set with the token’s approve function. Olympex uses two kinds of spender:

• Swaps. Before you send a swap with ERC-20 input, the allowance for contractToApprove must cover the input amount. Approve the exact amount.
• Limit orders and DCA. The maker’s allowance for the order contract is the on-chain limit on what its orders can spend. Every order that sells the same token on the same chain draws on it, so approve the sum they need. Set it to 0 to stop every order that sells the token.

Never approve an unlimited amount. For tokens such as USDT that require it, set the allowance to 0 before a new non-zero value. See Order signatures and allowances.

​

API account

The account that POST /accounts creates. It holds one API key ID, one secret key and one passphrase, and every signed request runs as that account. Limit orders and DCA strategies belong to the account that created them. Integrator fees apply only to signed requests from API accounts.

​

API key ID

A UUID that identifies your API account. POST /accounts returns it as apiKey, you send it in x-api-key-id on every signed request, and responses to signed requests echo it as meta.apiKeyId. It can’t sign anything: signing needs the secret key. Keep it out of client code and public places anyway. An order or strategy ID created with another API key ID returns 404 NOT_FOUND. See Credentials.

​

Base units

An integer amount in a token’s smallest unit: the human-readable amount multiplied by 10 to the power of the token’s decimals. USDC has 6 decimals, so "10034668" is 10.034668 USDC. outAmount, toTokenAmount, minimumReceived, minOutAmount, protocolFeeAmount and integratorMarginAmount are in base units. See API conventions.

​

Base URL

The URL that every endpoint path is appended to. It ends in /api/v1. The API reference overview gives it in full.

​

Body hash

bodyHash is the SHA-256 hash of the canonical request body, encoded as unpadded base64url. It is the last line of the signed message and of x-value-info, so the signature covers the body. A GET or DELETE has no body and is signed over the empty string, whose bodyHash is 47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU. A body that doesn’t match it is rejected with 403 FORBIDDEN "Invalid body hash".

​

Bridge

The protocol that carries funds from the source chain to the destination chain in a cross-chain transfer. The cross-chain provider chooses it, and bridgeInfo.displayName in the quote names it.

​

Calldata

The encoded data of the transaction that executes a route. POST /swap returns it as data for single-chain swaps and as calldata for cross-chain transfers, together with the to address and the value to send. It is real mainnet calldata, bound to the account it was built for, with an on-chain expiry of 5 minutes on most routes; a market maker’s firm quote inside some routes expires within seconds. A 200 from /swap doesn’t guarantee that it executes: run eth_estimateGas before you send.

​

Canonical JSON

The exact form of the request body that Olympex hashes: object keys sorted at every level and no whitespace, as produced by JSON.stringify(sortKeysDeep(body)). Sign the canonical form and send exactly those bytes. See Sign requests.

​

Canonical query

The form of the query string that the signature covers: parameters decoded, sorted by key and then by value, percent-encoded per RFC 3986 and joined with &. It is the empty string when there is no query. For example, ?status=pending&chainId=137 signs as chainId=137&status=pending. See Sign requests.

​

Chain ID

The EVM chain identifier, such as 137 for Polygon. It is a JSON integer in every request and response: in a request body, a string such as "137" returns 400 VALIDATION_ERROR. API conventions lists every field. See Supported chains and tokens.

​

contractToApprove

The ERC-20 spender for a swap, returned by POST /swap. Before you send a swap with ERC-20 input, make sure its allowance covers the input amount. It can differ from the transaction’s to address, and it isn’t the order contract that limit orders and DCA use.

​

Cross-chain provider

The service that quotes and builds a cross-chain transfer: okx, rango or liFi. Signed requests from API accounts use okx or rango. The quote returns the provider as aggregatorId, and the provider chooses the bridge. See Cross-chain mechanics.

​

Cross-chain transfer

A swap that starts on one chain and delivers on another (mode: "cross-chain"). One quote covers the swap on the source chain, the bridge, and the swap on the destination chain. You track it with POST /tx-status.

​

DCA order

One execution of a DCA strategy. Olympex creates DCA orders as the strategy runs, each spending totalAmount / iterations of the token sold; there is no endpoint to create one. Its status is pending, executing, successful (with transactionHash, amountReceived and executionPrice), cancelled, error (with errorMessage) or expired. DCA orders are read-only: no endpoint changes or cancels one. See DCA strategies.

​

DCA strategy

A plan to spend totalAmount of tokenAddressFrom in iterations equal DCA orders, one every frequency seconds, buying tokenAddressTo on the same chain. You create it with POST /dca-order/strategies, and it starts active immediately, unless you create it with "status": "cancelled" to test without scheduling orders; finished means every order ran. totalAmount, slippage and the optional price bounds minPrice and maxPrice are JSON numbers, and the bounds are in units of tokenAddressTo per 1 tokenAddressFrom. To stop a strategy, set its status to cancelled, which can’t be undone, then lower the maker’s allowance. See DCA strategies.

​

Destination chain

The chain where a cross-chain transfer delivers the output token, set with toChainId.

​

dexHash

An identifier in the cross-chain POST /swap response that tells POST /tx-status which provider handled the transfer. Send it in lowercase.

​

Envelope

The JSON wrapper of every API response: {"success": true, "data": …, "meta": …} on success, and {"success": false, "error": …, "meta": …} on failure. Responses generated by the API gateway aren’t enveloped. See Errors and retries.

​

Error code

error.code in a failed envelope: a machine-readable value such as VALIDATION_ERROR, FORBIDDEN, NOT_FOUND or QUOTE_ERROR. error.details lists the fields at fault for validation errors. See Errors and retries.

​

Estimated gas

estimatedGas in a quote or a /swap response. In a single-chain quote it is in gas units, and "0" means the source gave no estimate. It covers only the source’s own part of the route, not the Olympex contracts, so the transaction uses more. In a /swap response it is "1500000" as a placeholder when the source gives none, and on cross-chain routes its unit depends on the provider and can be a wei amount. Use it for display only, and estimate gas yourself before you send. See Gas and fees.

​

feeBps

Your integrator fee rate, in basis points: an integer from 0 to 100, where 25 is 0.25% and 100 is 1%. You send it with feeRecipient in the top-level fees object of a quote or swap.

​

Gas limit

The maximum gas a transaction can use. gasLimit in a /swap response is estimatedGas multiplied by 2 and is unreliable: estimatedGas can be a placeholder of "1500000", "0", or a wei amount on cross-chain routes. Estimate gas with eth_estimateGas and add a buffer instead. See Gas and fees.

​

Gas multiplier

gasMultiplier scales estimatedGas in a single-chain quote when includeGasInfo is true: NONE (1×, the default), LOW (1.55×), MEDIUM (2×) or HIGH (4×).

​

Gas price hint

gasPrice, required on single-chain quotes and swaps: a string in whole gwei. Some sources use it, and some reject fractional gwei, so round up to a whole number, which gives "1" on a chain whose gas price is below 1 gwei. It doesn’t set what your transaction pays. dataFeeTransaction.effectiveGasPrice reports the gas price the fee estimate used, in wei.

​

Gateway response

A response generated by the API gateway rather than by Olympex. Its body is {"message": "…"}, with no envelope and no meta.requestId, but its apigw-requestid response header still identifies the request. Browsers can’t read that header cross-origin, so read it from a server or a terminal. The gateway returns 401 when a signing header is missing, 403 when authentication fails, 429 when it receives too many requests in a short time, and 500 or 503 when a request runs past the timeout of about 30 seconds. The first request after a quiet period can also get a 500. The OpenAPI spec calls this body GatewayError.

​

Human-readable amount

A decimal amount in whole-token units: "10" is 10 USDT. Request amount values use this form, as strings, as do fromTokenAmount, transactionFeeInToken and valueToApprove in responses. A DCA strategy’s totalAmount is also human-readable, but a JSON number.

​

Integrator fee

The fee you charge on each trade, set with the fees object (feeBps and feeRecipient) on quotes and swaps. It applies only to signed requests from API accounts. See Gas and fees.

​

Integrator fee breakdown

integratorFeeBreakdown in a quote. Every quote for an API account includes it, and the protocol fee applies even when you send no fees, with integratorMarginBps 0. protocolFeeBps is the Olympex protocol fee rate in basis points, possibly fractional (15 is 0.15%), and integratorMarginBps is your feeBps. protocolFeeAmount and integratorMarginAmount are in base units of the output token for single-chain quotes, and of the source token for cross-chain quotes.

​

Known-answer vector

A fixed set of signing inputs (credentials, timestamp, nonce, method, URL and body) with the exact bodyHash, x-value-info and x-signature they produce. Sign requests publishes one with a body and one without a body and with a query, so you can test your implementation offline.

​

Limit order

An order to sell amount of inTokenAddress for outTokenAddress on one chain. The order executes when the market price of inTokenAddress, in outTokenAddress, reaches priceTrigger or better. You create it with POST /limit-order, and Olympex executes it from the maker’s wallet. Its status is pending, executing, submitted, completed (with txHash), failed (with reasonFail[]) or cancelled. You can change or cancel it only while it is pending: otherwise the call fails with 409 CONFLICT. See Limit orders.

​

Liquidity source

A DEX aggregator or DEX that Olympex requests single-chain quotes from, identified by its aggregator ID. Olympex compares the sources and returns the best route. See Aggregation and routing.

​

Maker

The wallet a limit order or DCA strategy trades for, sent as accountTo. It sells the token, receives the output, signs the order signature and approves the order contract. It must be an externally owned account (EOA): smart-contract wallets such as Safe or ERC-4337 accounts can’t sign orders. Send it in EIP-55 checksummed form, because Olympex stores it as sent and the ?accountTo= filter matches case-sensitively.

​

Minimum output

The least a swap delivers after slippage, in base units. For single-chain swaps it is minOutAmount in the /swap response, and the transaction reverts below it. For cross-chain transfers it is minimumReceived in the quote.

​

Mode

mode selects the body shape of POST /quotes and POST /swap: "single-chain" for a swap on one chain, or "cross-chain" for a transfer between two chains.

​

Native token

A chain’s gas token, such as ETH on Ethereum, POL on Polygon or BNB on BNB Chain. The API addresses it as 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE, in either casing: GET /tokens lists it in lowercase, and a cross-chain middlewareRoute can show it as the zero address. value in a /swap response is a native-token amount in wei. Limit orders and DCA can’t sell it: wrap it first.

​

Nonce

24 random hexadecimal characters in the signed message, new for every attempt, including retries. Olympex rejects a nonce it has already seen in the last 5 minutes.

​

Non-custodial

Olympex never holds your keys or takes custody of funds. For swaps, the API returns unsigned calldata, and your wallet signs and broadcasts every transaction. For limit orders and DCA, Olympex executes each swap from the maker’s wallet, within the maker’s allowance for the order contract, and sends the output back to the maker. See Security model.

​

OpenAPI specification

The machine-readable description of the API, curated by Olympex. Most of its response examples, including every /quotes and /swap example, are captured from the live API; the /tx-status success example is illustrative. Every endpoint page in the API reference is generated from it, and you can generate a typed client from it. See OpenAPI specification.

​

Order contract

The Olympex contract that executes limit orders and DCA orders from the maker’s wallet, and the spender the maker approves for them. It has one address per chain, listed in The order contract, and it is an upgradeable proxy operated by Olympex. Limit orders and DCA execute only on chains that have one. It isn’t the contractToApprove that POST /swap returns.

​

Order signature

The maker’s EIP-191 signature over keccak256(abi.encodePacked(maker, maker, tokenIn, tokenOut)), made once per token pair and sent as signature when you create a limit order or a DCA strategy. It lets the order contract execute swaps of tokenIn for tokenOut from the maker’s wallet. It doesn’t bind an amount, price, expiry, chain or order, so the maker’s allowance is the on-chain limit. It stays valid after you cancel orders, and one signature serves limit orders and DCA for the same pair. Sign the 32 bytes of the hash, not its hex string, and check the signature before you send it: Olympex doesn’t check it when you create the order. See Order signatures and allowances.

​

Passphrase

The password you send to POST /accounts, sent in x-passphrase on every signed request. Protect it exactly like the secret key. It must be printable ASCII with no leading or trailing spaces; use at least 24 random characters from a password manager. Olympex stores only a hash of it.

​

Price impact

The gap between a pair’s market price and the average price your trade gets, caused by the trade’s size relative to the available liquidity. It is already reflected in outAmount; the API doesn’t return it as a separate figure. See Slippage and price impact.

​

Price trigger

priceTrigger in a limit order: units of outTokenAddress per 1 inTokenAddress, as a human-readable decimal string. On an order that sells WETH for USDC, "4200" is 4,200 USDC per WETH. The order executes when the market price of inTokenAddress, in outTokenAddress, reaches priceTrigger or better. See Price direction.

​

Protocol fee

The Olympex fee on a trade, reported on every quote for an API account in integratorFeeBreakdown, as protocolFeeBps (a rate in basis points: 15 is 0.15%) and protocolFeeAmount (base units). It applies even when you set no integrator fee. Read it from each response instead of hard-coding it.

​

Public endpoint

An endpoint that takes no signed headers: POST /accounts. Every other endpoint is a signed endpoint.

​

Quote

The best route Olympex finds for a swap or transfer, returned by POST /quotes. A quote isn’t reserved: request the swap right after it.

​

Reference price

A price for a limit order’s pair that Olympex finds when you create the order: it reuses a recent lookup for the same chain and token addresses, or looks up a market for the two symbols, tokenASymbol and tokenBSymbol, or identifies the tokens by address. Without one, POST /limit-order fails with 400 VALIDATION_ERROR and "Not exist reference price for this pair A/B". Send the tokens’ real symbols: Olympex doesn’t check them, so check the ones the response returns. Responses can return normalized symbols, such as ETH for WETH. See Reference price.

​

Request ID

meta.requestId identifies a request. Every enveloped response carries one, errors included. Gateway responses carry none; their apigw-requestid response header identifies the request instead. Include the ID when you contact Support.

​

Route

The path a trade takes through one or more venues. In a single-chain quote, routes[] gives each route’s percentage and its subRoutes, with the dexes used for each hop. percentage is what the source reports: later hops can appear as separate routes at 100, so the values don’t always sum to 100. Use it for display only. In subRoutes, from and to are token addresses as the source reports them; case and the native-token address vary by source.

​

Secret key

The HMAC key you sign with: a random string that POST /accounts returns once, as secretKey. Use the string as it is. It is never sent with a request. Olympex stores only an encrypted copy, and no endpoint returns it again. See Credentials.

​

Signed endpoint

An endpoint that requires signed headers: every endpoint except POST /accounts.

​

Signed headers

The four headers that authenticate a request: x-api-key-id, x-value-info, x-passphrase and x-signature, sent with content-type: application/json. See Sign requests.

​

Signed message

Seven lines joined with \n, with no trailing newline: OLPX-HMAC-SHA256-V2, timestamp, nonce, the method in uppercase, the path (with /api/v1, without the query), the canonical query (empty when there is none) and bodyHash. x-signature is its lowercase hex HMAC-SHA256, keyed with the secret key string. x-value-info carries only timestamp, nonce and bodyHash, as standard base64.

​

Single-chain swap

A swap in which both tokens are on the same chain (mode: "single-chain"). GET /transactions/{hash} returns its on-chain status; you can also read the transaction receipt from your RPC.

​

Slippage

The price movement you accept between the quote and execution, in percent: "1" is 1%. It is a string in quotes, swaps and limit orders, and a JSON number in DCA strategies. For swaps, Olympex turns it into the minimum output. It is your setting, unlike price impact, which is a property of the trade. See Slippage and price impact.

​

Source chain

The chain where a cross-chain transfer starts, set with fromChainId. You broadcast the transaction there, and pass its hash and chain ID to POST /tx-status. Transfers can start on Ethereum, Optimism, BNB Chain, Polygon, Arbitrum and Avalanche.

​

Test API key

An API account created for exploring the API, in one click from these docs or from a terminal. It is a real account on the live API; there is no sandbox or testnet. Limit orders and DCA strategies created with it are real orders. See Create a test API key.

​

Timestamp

The current Unix time in seconds: the second line of the signed message, after OLPX-HMAC-SHA256-V2, and the first line of x-value-info. Olympex rejects a timestamp more than 300 seconds from server time.

​

Wei and gwei

Units of a chain’s native token: one native token is 10¹⁸ wei, and one gwei is 10⁹ wei. The gasPrice hint is in whole gwei. value in a /swap response, and effectiveGasPrice and transactionFee in dataFeeTransaction, are in wei.

​

Related