API reference overview

The Olympex REST API returns aggregated swap quotes, builds unsigned transaction calldata and tracks your transactions and cross-chain transfers. It also lists the chains and tokens Olympex supports, and manages limit orders and DCA strategies that Olympex executes for you. GET /chains returns the EVM chains Olympex has enabled. Swaps are non-custodial: Olympex never holds your funds or broadcasts a swap, and you sign and send every swap transaction from your own wallet. Limit orders and DCA strategies work differently. Olympex executes them on-chain: it pulls the tokens from the maker wallet under the allowance that wallet granted to the Olympex order contract, and sends the output back to that wallet. Order signatures and allowances explains the signature and the allowance that control this.

Base URL

Every endpoint lives under one base URL:

https://api-rest.olympex.io/api/v1

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

Every endpoint is signed except POST /accounts, which is public and needs only Content-Type: application/json. Signed endpoints also need the four signed headers described in Authentication.

Accounts and authentication

Method	Path	What it does	Reference
`POST`	`/accounts`	Public. Creates an API account and returns its API key ID and secret key.	Create an account

Quotes and swaps

Method	Path	What it does	Reference
`POST`	`/quotes`	Finds the best single-chain or cross-chain route and its expected output.	Get a quote
`POST`	`/swap`	Builds unsigned transaction calldata for a quoted route. Never broadcasts.	Build a swap
`POST`	`/tx-status`	Returns the status of a cross-chain transfer you broadcast.	Get cross-chain transfer status
`GET`	`/transactions/{hash}`	Returns the on-chain status of a transaction you broadcast (`?chainId=`): `pending`, `success`, `reverted` or `not_found`.	Get on-chain transaction status

Chains and tokens

Method	Path	What it does	Reference
`GET`	`/chains`	Lists the IDs of the chains Olympex has enabled.	List chains
`GET`	`/tokens`	Lists the tokens on one chain (`?chainId=`), with their decimals.	List tokens
`POST`	`/support-chain`	Reports whether Olympex supports one chain.	Check chain support

Limit orders

Method	Path	What it does	Reference
`GET`	`/limit-order`	Lists your limit orders, optionally filtered by status, chain or maker.	List limit orders
`POST`	`/limit-order`	Creates an order to sell a token when the market reaches `priceTrigger` or better.	Create a limit order
`GET`	`/limit-order/{id}`	Returns one limit order. Poll it to follow the order’s `status`.	Get a limit order
`PATCH`	`/limit-order/{id}`	Changes the price, amount, expiry, slippage or gas price of a pending order.	Update a limit order
`DELETE`	`/limit-order/{id}`	Cancels a pending order. The order stays readable.	Cancel a limit order

DCA

Method	Path	What it does	Reference
`GET`	`/dca-order/strategies`	Lists your DCA strategies, newest first, each with its orders.	List DCA strategies
`POST`	`/dca-order/strategies`	Creates a strategy that spends a total amount in equal orders over time.	Create a DCA strategy
`GET`	`/dca-order/strategies/{id}`	Returns one strategy, without its orders.	Get a DCA strategy
`PATCH`	`/dca-order/strategies/{id}`	Cancels a strategy or changes its price bounds.	Update a DCA strategy
`GET`	`/dca-order/strategies/{id}/orders`	Lists a strategy’s orders, oldest first.	List a strategy’s orders
`GET`	`/dca-order/orders/{id}`	Returns one DCA order.	Get a DCA order

The service also serves its own OpenAPI document and Swagger UI at the public GET /openapi.json and GET /docs. OpenAPI specification explains why to build against the curated spec instead.

How the endpoints fit together

Swaps

Create credentials once. POST /accounts returns an API key ID and a secret key. The password you send becomes your passphrase.
Pick a chain and tokens. GET /chains returns the enabled chains, and GET /tokens the tokens on each one with their decimals. Cache both.
Quote. POST /quotes returns the best route and the aggregatorId of the liquidity source that produced it.
Build the transaction. POST /swap takes the same pair and amount, your wallet account and that aggregatorId, and returns calldata.
Check it, then send it right away. For an ERC-20 input, approve contractToApprove for the exact amount if the allowance is too low. Run eth_estimateGas on the exact transaction: a 200 from /swap doesn’t guarantee that the calldata executes. If the estimate reverts, build again with the next aggregatorId in the quote’s aggregatorOrder, or request a new quote for a cross-chain swap. Then sign and broadcast from account at once. The calldata expires on-chain, after 5 minutes on most routes, and sooner on routes that include a market maker’s firm quote.
Track it. Poll GET /transactions/{hash} with the chain ID until status is success or reverted, or read the receipt from your RPC. For a cross-chain transfer, then poll POST /tx-status with the source transaction hash, the source chain ID and the dexHash from /swap.

POST /support-chain checks a single chain at runtime. The guides walk through each flow: Execute a swap and Cross-chain swap end-to-end.

Limit orders and DCA

Authorize the pair. The maker wallet signs one message per token pair, and approves the Olympex order contract for what its open orders need. Order signatures and allowances shows both steps.
Create. POST /limit-order creates an order that executes when the market reaches priceTrigger or better. POST /dca-order/strategies creates a strategy that spends totalAmount in iterations equal orders, one every frequency seconds. Nothing moves on-chain when you create either one.
Follow it. Poll GET /limit-order/{id} for the order’s status. For a strategy, list its orders with GET /dca-order/strategies/{id}/orders.
Change or cancel. PATCH /limit-order/{id} and DELETE /limit-order/{id} act only on a pending order: on any other status they return 409 CONFLICT. PATCH /dca-order/strategies/{id} with {"status":"cancelled"} stops a strategy.

The guides walk through both: Place a limit order and Run a DCA strategy.

Response envelope

Every endpoint returns the same envelope, whatever its method, and every success is HTTP 200, including creates (POST) and cancels (DELETE). success tells you which of data or error is present.

{
  "success": true,
  "data": true,
  "meta": {
    "requestId": "ENUlxjCsIAMEMUA=",
    "version": "v1",
    "accountType": "integrator",
    "apiKeyId": "00000000-0000-4000-8000-000000000000"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [
      {
        "field": "params.chainId",
        "message": "Invalid input: expected number, received string"
      },
      {
        "field": "params.inTokenAddress",
        "message": "Must be a valid EVM address"
      },
      {
        "field": "params.amount",
        "message": "Invalid input: expected string, received number"
      },
      {
        "field": "params.gasPrice",
        "message": "Invalid input: expected string, received undefined"
      }
    ]
  },
  "meta": {
    "requestId": "ENUlmg3dIAMEMEw=",
    "version": "v1",
    "accountType": "integrator",
    "apiKeyId": "00000000-0000-4000-8000-000000000000"
  }
}

Field	Description
`success`	`true` on success, `false` on error. Branch on it, not on the value of `data`: `POST /support-chain` returns `"data": false` for an unsupported chain.
`data`	The result, on success: an object for most endpoints, an array for list endpoints, and a boolean for `/support-chain`.
`error`	`code`, `message` and `details`, on error. `code` is stable and machine-readable; `message` is for humans.
`meta.requestId`	Unique ID of the request. Log it, and include it when you contact support.
`meta.version`	API version that served the request: `v1`.
`meta.accountType`	On signed endpoints: the account type resolved from your signature, `integrator` for accounts created with `POST /accounts`.
`meta.apiKeyId`	On signed endpoints: the API key ID that signed the request.

The API gateway in front of Olympex can also answer on its own, for example when a signing header is missing or a request runs past the gateway timeout. Those responses carry only a message field. Conventions covers both shapes, every error code and the gateway responses.

Authentication

Olympex authenticates each signed request with an HMAC-SHA256 signature over the method, the path, the query, a timestamp, a single-use nonce and a hash of the body. POST /accounts gives you the three credentials: an API key ID, a secret key (a random string, shown once) and the passphrase you chose.

Header	Value
`x-api-key-id`	Your API key ID.
`x-value-info`	Standard base64, on one line, of `timestamp`, `nonce` and `bodyHash` joined with newlines.
`x-passphrase`	Your passphrase.
`x-signature`	Lowercase hex HMAC-SHA256, keyed with your secret key, of the signed message: `OLPX-HMAC-SHA256-V2`, `timestamp`, `nonce`, the method, the path, the canonical query and `bodyHash`, joined with newlines.

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. GET and DELETE requests have no body: sign the empty string. The signature also covers the method, the path and the query, so headers signed for one request are rejected on any other. Sign right before you send, and treat each set of signed headers as a single-use credential.

Keep the secret key and the passphrase on your server. The passphrase travels in every request. Never ship either one in a browser, mobile or desktop app.

Credentials explains what each credential is and how to store it.

API console

The API console signs requests in your browser and sends them straight to the API, so you can call every signed endpoint without writing code. Every signed endpoint page also has a Try it console, and Create an account has the one-click key creator. If your browser blocks a request, use the console’s Copy as cURL or create a key from a terminal. Use a test API key: these pages are hosted by Mintlify and load analytics. Limit orders and DCA strategies you create from the console are real.

OpenAPI specification

The API is described by an OpenAPI 3.0.3 document with examples:

https://docs.olympex.io/api-reference/openapi.json

The endpoint pages in this reference are generated from it. OpenAPI specification shows how to generate a typed client and add request signing to it.

How to read an endpoint page

Section	What it tells you
Summary	What the endpoint does and how it connects to the other endpoints.
Try it	On signed endpoints, a console that signs and sends the request from your browser.
Guidance	Units, parameter and body rules, and the flow around the call.
Parameters, Body and Response	Every path parameter, query parameter and field, generated from the OpenAPI spec, with types, required flags and descriptions.
Request examples	cURL, TypeScript and Python, using the reference signers.
Response examples	Examples from the OpenAPI spec, plus the gateway responses you can receive.

Versioning

The API version is part of the path (/api/v1), and every endpoint reports it in meta.version.
Within v1, responses can gain new fields and error.code can gain new values. Ignore fields you don’t recognize, and handle an unknown code by its HTTP status.
Treat aggregatorId as an opaque string and pass it back exactly as the quote returned it. /tx-status reports each provider’s own status values: match the documented success and failure values and treat anything else as in progress.
Treat a limit order, DCA strategy or DCA order status you don’t recognize as not final.

Conventions lists the full set of forward-compatibility rules.

Where to start

Quickstart

Create a key, sign a request and get your first quote.

Sign requests

The signing algorithm, reference code in three languages and two known-answer vectors.

API console

Sign and send any endpoint from your browser.

Conventions

Methods, amounts, chain IDs, IDs, errors and request IDs.

​Base URL

​Endpoints

​Accounts and authentication

​Quotes and swaps

​Chains and tokens

​Limit orders

​DCA

​How the endpoints fit together

​Swaps

​Limit orders and DCA

​Response envelope

​Authentication

​API console

​OpenAPI specification

​How to read an endpoint page

​Versioning

​Where to start

Quickstart

Sign requests

API console

Conventions

Base URL

Endpoints

Accounts and authentication

Quotes and swaps

Chains and tokens

Limit orders

DCA

How the endpoints fit together

Swaps

Limit orders and DCA

Response envelope

Authentication

API console

OpenAPI specification

How to read an endpoint page

Versioning

Where to start