API conventions

​

Requests

​

Methods

​

Bodies and signing

• Content-Type: application/json on every request, including GET, DELETE and the public endpoints. Without it, or with another type such as curl’s default application/x-www-form-urlencoded, the gateway base64-encodes a body before Olympex reads it, and the request fails with 403 (Invalid body hash) on a signed endpoint or 400 (Invalid JSON body) on a public one.
• UTF-8. Encode the body as UTF-8 JSON.
• Send the bytes you signed. On POST and PATCH, serialize the body once as canonical JSON (keys sorted at every level, no whitespace), hash that string, and send the same string. Sign requests has the algorithm and reference code.
• Sign the empty string when there is no body. GET and DELETE send no body, and the signature covers the empty string: its bodyHash is 47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU.
• The signature covers the whole request: the method, the path (including /api/v1), the canonical query and the body hash, with the timestamp and the nonce. Headers signed for one request are rejected on any other. Sign right before you send, and never log or share the headers.
• Sign every attempt. Each signature carries a nonce, which the server rejects if it has seen it in the last 5 minutes, and a timestamp it accepts within ±300 seconds of its own clock. The nonce makes each set of headers usable once. A retry needs a new signature, and your server clock must stay synchronized.

​

Response envelope

type Meta = { requestId: string; version: string; accountType?: string; apiKeyId?: string }; // both absent on public endpoints and unknown routes
type ErrorDetail = { field?: string; message: string };

type Envelope<T> =
  | { success: true; data: T; meta: Meta }
  | { success: false; error: { code: string; message: string; details: ErrorDetail[] }; meta: Meta };

​

Amounts

​

Values you send

​

Values you receive

// npm install viem
import { formatUnits } from "viem";

// quote.outAmount for 10 USDT to USDC on Polygon. USDC has 6 decimals.
console.log(formatUnits(BigInt("9979975"), 6)); // 9.979975

from decimal import Decimal

# quote.outAmount for 10 USDT to USDC on Polygon. USDC has 6 decimals.
print(Decimal("9979975").scaleb(-6))  # 9.979975

​

Addresses

• Addresses are accepted in lowercase or EIP-55 checksum form, as 0x and 40 hex digits. A mixed-case address whose checksum is wrong returns 400 VALIDATION_ERROR with the detail "Must be a valid EVM address", which catches most typos.
• The chain’s native token uses this pseudo-address wherever a token address is expected, in either casing:
  0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
  
  GET /tokens lists it in lowercase, 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee, so compare it case-insensitively.
• Limit orders and DCA strategies can’t sell the native token: inTokenAddress and tokenAddressFrom must be ERC-20 tokens. Use the wrapped token, for example WETH, WBNB or WPOL.
• Olympex resolves token decimals server-side. You never send them.
• Responses don’t normalize addresses. GET /tokens returns addresses in varying case. On single-chain quotes, routes[].subRoutes[].from and to are token addresses as the source reports them: case varies, and the native token can appear as 0xeeee… or the zero address. middlewareRoute can use checksummed addresses in the same quote, and can show a native token as the pseudo-address or the zero address, depending on the provider. Compare addresses case-insensitively.
• Limit orders and DCA strategies store the maker’s accountTo exactly as you send it, and the ?accountTo= list filters match case-sensitively. Always send the EIP-55 checksummed form.
• feeRecipient can’t be the zero address.

​

Chain IDs

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [
      {
        "field": "chainId",
        "message": "Invalid input: expected number, received string"
      }
    ]
  },
  "meta": {
    "requestId": "E7ee3hLMoAMEZxg=",
    "version": "v1",
    "accountType": "integrator",
    "apiKeyId": "00000000-0000-4000-8000-000000000000"
  }
}

​

IDs

• Olympex assigns every ID. Limit order and DCA strategy IDs are UUIDs, for example afc47108-d059-473c-b2e1-5f2ca7951466. DCA order IDs are strings that Olympex creates as a strategy runs. Treat every ID as an opaque string, and pass it in the path: /limit-order/{id}.
• IDs are scoped to your API key. A limit order or DCA strategy belongs to the API key that created it, and a DCA order belongs to its strategy’s key. Lists return only your key’s resources. An ID that doesn’t exist or belongs to another API key returns 404 NOT_FOUND.
• Keep the key with the ID. If you use more than one API key, store which key created each order or strategy. meta.apiKeyId in the create response names it.

​

Booleans and enums

• Booleans are JSON true and false. The string "true" is rejected.
• Enum values are case-sensitive. mode is "single-chain" or "cross-chain"; orderBy and gasMultiplier values are uppercase, for example "MAX_OUT_AMOUNT" and "MEDIUM".
• Limit order, DCA strategy and DCA order statuses are lowercase, for example "pending" and "cancelled". Each endpoint page lists the values.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [
      {
        "field": "params.includeGasInfo",
        "message": "Invalid input: expected boolean, received string"
      },
      {
        "field": "params.orderBy",
        "message": "Invalid option: expected one of \"MAX_ESTIMATE_GAS\"|\"MAX_OUT_AMOUNT\"|\"MIN_ESTIMATE_GAS\""
      }
    ]
  },
  "meta": {
    "requestId": "ENiSJiGxoAMEJ5Q=",
    "version": "v1",
    "accountType": "integrator",
    "apiKeyId": "00000000-0000-4000-8000-000000000000"
  }
}

​

Optional and empty fields

• An optional response field can be missing or null. Treat both as “not provided”.
• integratorFeeBreakdown is present on every quote. It reports the Olympex protocol fee, which applies even when you don’t send fees, and your fee: integratorMarginBps equals fees.feeBps, and is 0 when you don’t send fees.
• dataFeeTransaction appears only when the single-chain quote request sets includeGasInfo: true.
• /tx-status returns fromTxHash, toTxHash, amounts, token addresses and bridgeHash only when the provider reports them. errorMsg is always null in a 200, because a provider error comes back as 500 TX_STATUS_ERROR. Display detailStatus instead.
• GET /transactions/{hash} returns blockNumber and gasUsed as null, and confirmations as 0, until the transaction is mined.
• A limit order’s txHash is an empty string until the order executes, reasonFail is an empty array unless execution failed, and deletedAt is an empty string until you cancel the order.
• A DCA strategy omits minPrice and maxPrice when you didn’t set them. A DCA order carries amountReceived, executionPrice and transactionHash once it executes, and errorMessage when it fails.
• Lists that have no entries are empty arrays, for example "market": [] or "data": [].

​

Casing

​

Timestamps

​

Lists

• No pagination. Each list endpoint returns every match in one response. Use the filters to keep responses small.
• Unsorted unless stated. Sort limit orders by createdAt yourself when the order matters.

  Endpoint	Order	Filters
  GET /chains	Ascending numeric chain ID	None
  GET /tokens	Unsorted	chainId (required)
  GET /limit-order	Unsorted	status, chainId, accountTo
  GET /dca-order/strategies	Newest first	status, accountTo
  GET /dca-order/strategies/{id}/orders	Oldest first	None

• Filters combine with AND. accountTo matches case-sensitively.
• Unknown query parameters. The order and strategy lists ignore unknown query parameters, so a misspelt filter such as ?acountTo= returns the full list. Send each parameter once: a repeated parameter matches nothing. GET /chains ignores query parameters too, while GET /tokens rejects any parameter other than chainId.
• Cancelled limit orders stay in the list. Filter by ?status= to see one status only, for example pending.
• Only your API key’s resources. See IDs.

​

Errors

​

Error envelope

{
  "success": false,
  "error": {
    "code": "NO_ROUTE",
    "message": "No route found for this pair and amount. Providers may also be temporarily unavailable; retrying later can succeed.",
    "details": [
      {
        "message": "The quote could be retrieved but the route is not available"
      }
    ]
  },
  "meta": {
    "requestId": "E7ef-j_MoAMEPBw=",
    "version": "v1",
    "accountType": "integrator",
    "apiKeyId": "00000000-0000-4000-8000-000000000000"
  }
}

​

Error codes

​

Not found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Limit order not found",
    "details": []
  },
  "meta": {
    "requestId": "EdjeXjypoAMEbrQ=",
    "version": "v1",
    "accountType": "integrator",
    "apiKeyId": "00000000-0000-4000-8000-000000000000"
  }
}

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "No route for GET /api/v1/quote",
    "details": []
  },
  "meta": {
    "requestId": "E7edogG4IAMEPYA=",
    "version": "v1"
  }
}

​

Gateway responses

​

Retries

• GET, PATCH and DELETE are safe to repeat.
• PATCH and DELETE /limit-order/{id} return 409 CONFLICT once the order isn’t pending, so a repeated DELETE whose first attempt went through returns 409: read the order to confirm it is cancelled. Don’t retry a 409 unchanged.
• 422 NO_ROUTE from POST /quotes can be temporary: retry with backoff, then change the amount or pair. On POST /swap, a 422 NO_ROUTE or 500 SWAP_ERROR means that source can’t build the route now: build again with the next aggregatorId in the quote’s aggregatorOrder.
• POST /limit-order, POST /dca-order/strategies and POST /accounts create a new resource on every success. After a timeout, don’t retry them blindly: list your orders or strategies and match on your own fields first.

​

Request IDs

• Every Olympex envelope carries meta.requestId. Log it with the HTTP status and error.code for every failed call.
• Gateway responses have no meta.requestId, but the response carries an apigw-requestid header with an ID. On Olympex responses that header has the same value as meta.requestId. Browsers can’t read the header on cross-origin calls, so read it from a server or a terminal.
• The reference helpers in Sign requests report no request ID for a gateway response, such as a 401 or 403 with only message. Log the apigw-requestid response header yourself for those. With curl, add -i or -D - to print the response headers.
• Include the request ID when you contact support. It is the fastest way to find your request.

​

Timeouts

​

Forward compatibility

• Ignore unknown response fields. Within v1, responses can gain new fields, and token, order and strategy objects can carry fields you don’t use. Don’t fail validation on a field you don’t recognize.
• Handle unknown error codes by HTTP status. New error.code values can be added.
• Pass aggregatorId through. Send /swap the exact value the quote returned instead of hardcoding one.
• Treat unknown transfer statuses as in progress. /tx-status reports each provider’s own status values. Get cross-chain transfer status lists the success and failure values.
• Treat unknown order statuses as not final. A limit order, DCA strategy or DCA order status you don’t recognize means the resource can still change: keep polling it.

​

What’s next