> ## 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. # Glossary > Definitions of the terms, fields and credentials used across the Olympex API documentation, in alphabetical order. 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`](/api-reference/swap/build-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](#cross-chain-provider). See [Aggregation and routing](/concepts/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`](#contracttoapprove) must cover the input amount. Approve the exact amount. * **Limit orders and DCA.** The [maker](#maker)'s allowance for the [order contract](#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](/concepts/order-authorization#the-allowance-is-the-on-chain-limit). ## API account The account that [`POST /accounts`](/api-reference/accounts/create-account) 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](/authentication/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](/api-reference/conventions). ## Base URL The URL that every endpoint path is appended to. It ends in `/api/v1`. The [API reference overview](/api-reference/overview#base-url) 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`](/api-reference/swap/build-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](/authentication/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](/authentication/sign-requests#canonical-query). ## 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](/api-reference/conventions#chain-ids) lists every field. See [Supported chains and tokens](/concepts/supported-chains). ## `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](#allowance) covers the input amount. It can differ from the transaction's `to` address, and it isn't the [order contract](#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](/concepts/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`](/api-reference/transactions/get-transaction-status). ## DCA order One execution of a [DCA strategy](#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](/concepts/dca). ## DCA strategy A plan to spend `totalAmount` of `tokenAddressFrom` in `iterations` equal [DCA orders](#dca-order), one every `frequency` seconds, buying `tokenAddressTo` on the same chain. You create it with [`POST /dca-order/strategies`](/api-reference/dca/create-dca-strategy), 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](#allowance). See [DCA strategies](/concepts/dca). ## 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](/authentication/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](/authentication/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](/concepts/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](/concepts/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](/concepts/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](/authentication/sign-requests#known-answer-vector) 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`](/api-reference/limit-orders/create-limit-order), and Olympex executes it from the [maker](#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](/concepts/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](/concepts/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](#order-signature) and approves the [order contract](#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](#allowance) for the [order contract](#order-contract), and sends the output back to the maker. See [Security model](/concepts/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](/api-reference/openapi-spec). ## Order contract The Olympex contract that executes limit orders and DCA orders from the [maker](#maker)'s wallet, and the spender the maker approves for them. It has one address per chain, listed in [The order contract](/concepts/order-authorization#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`](#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](#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](#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](/concepts/order-authorization). ## 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](/concepts/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](/concepts/limit-orders#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`](/api-reference/quotes/get-quote). 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](/concepts/limit-orders#reference-price). ## Request ID `meta.requestId` identifies a request. Every enveloped response carries one, errors included. [Gateway responses](#gateway-response) carry none; their `apigw-requestid` response header identifies the request instead. Include the ID when you contact [Support](/resources/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](/authentication/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](/authentication/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](#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}`](/api-reference/transactions/get-transaction) 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](/concepts/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](/get-started/create-an-api-key#create-a-key-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](/get-started/create-an-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 1018 wei, and one gwei is 109 wei. The `gasPrice` hint is in whole gwei. `value` in a `/swap` response, and `effectiveGasPrice` and `transactionFee` in `dataFeeTransaction`, are in wei. ## Related Answers to common integration questions. Amounts, addresses, chain IDs and errors across endpoints. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.