> ## 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.
# Get a limit order
> Read one limit order and poll it to follow its status until it completes, fails or is cancelled.
`GET /limit-order/{id}` returns one limit order created with your API key. Poll it to follow the order from `pending` to a final status: `completed`, `failed` or `cancelled`. A cancelled order stays readable.
Signed endpoint with no request body. Sign the method, the path and the empty string (`bodyHash` `47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU`), send no body, and send `Content-Type: application/json` and the four headers `x-api-key-id`, `x-value-info`, `x-passphrase` and `x-signature` described in [Sign requests](/authentication/sign-requests). `id` is the order ID that `POST /limit-order` returned. Final statuses: `completed` (with `txHash`), `failed` (with `reasonFail` and `attemptNumber`) and `cancelled`. `pending`, `executing`, `submitted` and any other value aren't final. Poll every 15 to 60 seconds, and stop at a cap, for example an hour after the order's `expired`: no documented status marks an expired order. An ID that doesn't exist or belongs to another API key returns `404 NOT_FOUND` "Limit order not found".
## Statuses
| `status` | Meaning | Final |
| - | - | - |
| `pending` | Waiting for the market to reach `priceTrigger`. You can [update](/api-reference/limit-orders/update-limit-order) or [cancel](/api-reference/limit-orders/cancel-limit-order) it. | No |
| `executing`, `submitted` | Olympex is executing the order. | No |
| `completed` | Executed. `txHash` is the execution transaction on `chainId`. | Yes |
| `failed` | Execution failed. `reasonFail` lists why, and `attemptNumber` counts the attempts. | Yes |
| `cancelled` | Cancelled with `DELETE /limit-order/{id}`. `deletedAt` is the time of that call. | Yes |
Treat any other value as not final, and keep polling.
## Poll until a final status
* Poll every 15 to 60 seconds, and stop at `completed`, `failed` or `cancelled`.
* Cap the poll too, for example an hour after the order's `expired`. No documented status marks an expired order, so an order can stay at a status that isn't final: check it again later, or cancel it.
* A `pending` order can wait a long time for the market to reach `priceTrigger`. Run the poll from a background job, not while a user waits.
* To follow several orders of one maker, poll [`GET /limit-order`](/api-reference/limit-orders/list-limit-orders) with `accountTo` instead: one call returns all of them.
* `GET` is safe to repeat. Sign every request again, as the reference helpers do: each set of signed headers works once.
## After a final status
* **`completed`:** the order doesn't report the amount received. Read it from the `txHash` transaction on `chainId`, with your RPC or the chain's block explorer.
* **`failed`:** `reasonFail` explains why. A failed order doesn't run again, so fix the cause, for example the maker's balance or allowance, and create a new order if you still want the trade.
* **`cancelled`:** cancelling doesn't change the maker's allowance. [Cancel a limit order](/api-reference/limit-orders/cancel-limit-order#lower-the-allowance) shows how to lower it.
## Not found
A `404 NOT_FOUND` with the message "Limit order not found" means no order with this ID belongs to your API key: the ID doesn't exist, or another API key created the order. A `404 NOT_FOUND` whose message starts with `No route for` means the path or method is wrong.
```bash cURL theme={null}
# Read one limit order by ID.
# Needs openssl, curl and OLYMPEX_API_KEY_ID, OLYMPEX_SECRET_KEY, OLYMPEX_PASSPHRASE.
ORDER_ID='afc47108-d059-473c-b2e1-5f2ca7951466' # from POST /limit-order
METHOD=GET
ENDPOINT="/limit-order/$ORDER_ID"
QUERY=''
BODY='' # GET has no body: the signature covers the empty string
TS="${OLYMPEX_TIMESTAMP:-$(date +%s)}"
NONCE="${OLYMPEX_NONCE:-$(openssl rand -hex 12)}"
BODY_HASH="$(printf '%s' "$BODY" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')"
VALUE_INFO="$(printf '%s\n%s\n%s' "$TS" "$NONCE" "$BODY_HASH")"
MESSAGE="$(printf 'OLPX-HMAC-SHA256-V2\n%s\n%s\n%s\n%s\n%s\n%s' "$TS" "$NONCE" "$METHOD" "/api/v1$ENDPOINT" "$QUERY" "$BODY_HASH")"
curl -sS -X "$METHOD" "https://api-rest.olympex.io/api/v1$ENDPOINT${QUERY:+?$QUERY}" \
-H "content-type: application/json" \
-H "x-api-key-id: $OLYMPEX_API_KEY_ID" \
-H "x-value-info: $(printf '%s' "$VALUE_INFO" | openssl base64 -A)" \
-H "x-passphrase: $OLYMPEX_PASSPHRASE" \
-H "x-signature: $(printf '%s' "$MESSAGE" | openssl dgst -sha256 -hmac "$OLYMPEX_SECRET_KEY" -binary | od -An -v -tx1 | tr -d ' \n')"
```
```ts TypeScript theme={null}
import { olympexRequest } from "./sign-request.ts"; // /authentication/sign-requests
type LimitOrder = { id: string; status: string; expired: string; txHash: string; reasonFail: string[]; attemptNumber: number };
const FINAL = new Set(["completed", "failed", "cancelled"]);
const orderId = "afc47108-d059-473c-b2e1-5f2ca7951466"; // from POST /limit-order
let order = await olympexRequest("GET", `/limit-order/${orderId}`);
const stopAt = Number(order.expired) + 60 * 60_000; // the order's own expiry (Unix ms) plus an hour
while (!FINAL.has(order.status) && Date.now() < stopAt) { // any other status, known or not, isn't final
await new Promise((resolve) => setTimeout(resolve, 30_000)); // poll every 15 to 60 seconds
order = await olympexRequest("GET", `/limit-order/${orderId}`);
}
if (order.status === "completed") console.log(`Executed in ${order.txHash}`);
else if (order.status === "failed") console.log(`Failed after ${order.attemptNumber} attempts: ${order.reasonFail.join("; ")}`);
else if (order.status === "cancelled") console.log("Cancelled");
else console.log(`Still ${order.status} an hour after its expiry: check it again later, or cancel it`);
```
```python Python theme={null}
import time
from sign_request import olympex_request # /authentication/sign-requests
FINAL = {"completed", "failed", "cancelled"}
order_id = "afc47108-d059-473c-b2e1-5f2ca7951466" # from POST /limit-order
order = olympex_request("GET", f"/limit-order/{order_id}")
stop_at = int(order["expired"]) / 1000 + 60 * 60 # the order's own expiry (Unix ms) plus an hour, in seconds
while order["status"] not in FINAL and time.time() < stop_at: # any other status, known or not, isn't final
time.sleep(30) # poll every 15 to 60 seconds
order = olympex_request("GET", f"/limit-order/{order_id}")
if order["status"] == "completed":
print("Executed in", order["txHash"])
elif order["status"] == "failed":
print(f'Failed after {order["attemptNumber"]} attempts:', "; ".join(order["reasonFail"]))
elif order["status"] == "cancelled":
print("Cancelled")
else:
print(f'Still {order["status"]} an hour after its expiry: check it again later, or cancel it')
```
```json 200 Pending theme={null}
{
"success": true,
"data": {
"id": "afc47108-d059-473c-b2e1-5f2ca7951466",
"accountTo": "0x1E67cb01969D79B2B895179e4A07D24a839dBb52",
"chainId": 137,
"gasPrice": "35",
"inTokenAddress": "0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619",
"outTokenAddress": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
"slippage": "1",
"tokenASymbol": "ETH",
"tokenBSymbol": "USDC",
"amount": 0.5,
"price": 4200,
"priceTrigger": 4200,
"expired": "1791302400000",
"txHash": "",
"status": "pending",
"reasonFail": [],
"attemptNumber": 0,
"allowance": "",
"estimateGas": "",
"effectivePriceGas": "",
"createdAt": "2026-09-29T16:01:22.237Z",
"updatedAt": "2026-09-29T16:01:22.237Z",
"deletedAt": ""
},
"meta": {
"requestId": "EdkevjVXoAMEZIw=",
"version": "v1",
"accountType": "integrator",
"apiKeyId": "00000000-0000-4000-8000-000000000000"
}
}
```
```json 404 Not found theme={null}
{
"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"
}
}
```
```json 403 Gateway theme={null}
{
"message": "Forbidden"
}
```
## OpenAPI
````yaml api-reference/openapi.json GET /limit-order/{id}
openapi: 3.0.3
info:
title: Olympex REST API
version: 1.0.0
description: >-
Aggregated swap quotes and transactions, limit orders and DCA strategies on
EVM chains, plus the chain and token catalog. Every response uses the same
envelope, except the API gateway's own responses (`{"message": …}`): `401`
or `403` when the signed headers are missing or rejected, `429` when it
throttles requests, and `500` or `503` when it can't get a response from
Olympex in time. Chain IDs are integers on every endpoint. Signed endpoints
require four signed headers; see [Sign
requests](https://docs.olympex.io/authentication/sign-requests).
termsOfService: https://docs.olympex.io/legal/terms
contact:
name: Olympex partnerships
email: partners@olympex.io
url: https://docs.olympex.io
servers:
- url: https://api-rest.olympex.io/api/v1
description: Olympex REST API v1
security: []
tags:
- name: Accounts
description: Create API credentials.
- name: Quotes
description: Aggregated single-chain and cross-chain quotes.
- name: Swap
description: Unsigned transaction calldata for a quoted route.
- name: TxStatus
description: Track a cross-chain transfer after you broadcast it.
- name: Transactions
description: On-chain status of a transaction you broadcast.
- name: Chains and tokens
description: Enabled chains and the tokens listed on each.
- name: Limit orders
description: Orders that Olympex executes when the market reaches your price.
- name: DCA
description: Strategies that buy a token in equal orders over time.
- name: Docs
description: Machine-readable API description.
paths:
/limit-order/{id}:
get:
tags:
- Limit orders
summary: Get a limit order
description: >-
Returns one limit order created with your API key. Poll it to follow the
order's `status`. No request body: sign the empty string.
operationId: getLimitOrder
parameters:
- name: id
in: path
required: true
description: Limit order ID, as returned when it was created.
schema:
type: string
example: afc47108-d059-473c-b2e1-5f2ca7951466
responses:
'200':
description: The order.
content:
application/json:
schema:
$ref: '#/components/schemas/LimitOrderSuccessResponse'
example:
success: true
data:
id: afc47108-d059-473c-b2e1-5f2ca7951466
accountTo: '0x1E67cb01969D79B2B895179e4A07D24a839dBb52'
chainId: 137
gasPrice: '35'
inTokenAddress: '0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619'
outTokenAddress: '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359'
slippage: '1'
tokenASymbol: ETH
tokenBSymbol: USDC
amount: 0.5
price: 4200
priceTrigger: 4200
expired: '1791302400000'
txHash: ''
status: pending
reasonFail: []
attemptNumber: 0
allowance: ''
estimateGas: ''
effectivePriceGas: ''
createdAt: '2026-09-29T16:01:22.237Z'
updatedAt: '2026-09-29T16:01:22.237Z'
deletedAt: ''
meta:
requestId: EdkevjVXoAMEZIw=
version: v1
accountType: integrator
apiKeyId: 00000000-0000-4000-8000-000000000000
'401':
description: >-
A signing header is missing. The gateway answers with
`{"message":"Unauthorized"}` before your request reaches Olympex;
the handler answers with the `UNAUTHORIZED` envelope when the
authorizer context is missing.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/GatewayError'
- $ref: '#/components/schemas/ErrorResponse'
example:
message: Unauthorized
'403':
description: >-
Authentication failed: unknown key, wrong passphrase, invalid
signature, timestamp outside the ±300 s window, reused nonce, or
inactive account (gateway `{"message":"Forbidden"}`). The handler
answers with the `FORBIDDEN` envelope when the signed `bodyHash` is
not the hash of an empty body.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/GatewayError'
- $ref: '#/components/schemas/ErrorResponse'
examples:
gateway:
summary: Signature rejected by the gateway
value:
message: Forbidden
bodyHash:
summary: Body does not match the signed hash
value:
success: false
error:
code: FORBIDDEN
message: Invalid body hash
details: []
meta:
requestId: ENXGDhsXIAMEMEw=
version: v1
accountType: integrator
apiKeyId: 00000000-0000-4000-8000-000000000000
'404':
description: >-
No limit order with this ID belongs to your API key (`NOT_FOUND`).
IDs of other API keys return the same error. An unknown path or
method also returns `NOT_FOUND`, with a message that names the
method and path.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
notFound:
summary: Unknown limit order
value:
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
unknownRoute:
summary: Unknown path or method
value:
success: false
error:
code: NOT_FOUND
message: No route for GET /api/v1/quote
details: []
meta:
requestId: E7edogG4IAMEPYA=
version: v1
'500':
description: >-
Olympex could not complete the request (`INTERNAL_ERROR`), or the
gateway could not get a response (`{"message":"Internal Server
Error"}`), which also happens on the first request after a quiet
period. Retry with backoff.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ErrorResponse'
- $ref: '#/components/schemas/GatewayError'
example:
success: false
error:
code: INTERNAL_ERROR
message: Unexpected internal error
details: []
meta:
requestId: EdkevjVXoAMEZIw=
version: v1
accountType: integrator
apiKeyId: 00000000-0000-4000-8000-000000000000
'503':
description: >-
The gateway could not get a response in time (the integration
timeout is about 30 seconds) or the service is briefly unavailable.
Returned by the gateway. Retry with backoff.
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayError'
example:
message: Service Unavailable
security:
- ApiKeyId: []
ValueInfo: []
Passphrase: []
Signature: []
components:
schemas:
LimitOrderSuccessResponse:
type: object
required:
- success
- data
- meta
properties:
success:
type: boolean
enum:
- true
data:
$ref: '#/components/schemas/LimitOrder'
meta:
$ref: '#/components/schemas/Meta'
GatewayError:
type: object
required:
- message
description: >-
Returned by the API gateway itself: `401` or `403` when the signed
headers are missing or rejected, `429` when it throttles requests, and
`500` or `503` when it can't get a response from Olympex in time. It has
no `success`, `error` or `meta`.
properties:
message:
type: string
example: Forbidden
ErrorResponse:
type: object
required:
- success
- error
- meta
properties:
success:
type: boolean
enum:
- false
error:
$ref: '#/components/schemas/ErrorBody'
meta:
$ref: '#/components/schemas/Meta'
LimitOrder:
type: object
description: A limit order. Olympex can add fields; ignore the ones you don't use.
required:
- id
- accountTo
- chainId
- inTokenAddress
- outTokenAddress
- tokenASymbol
- tokenBSymbol
- amount
- price
- priceTrigger
- expired
- slippage
- gasPrice
- status
- txHash
- reasonFail
- attemptNumber
- createdAt
- updatedAt
- deletedAt
properties:
id:
type: string
format: uuid
description: Order ID.
accountTo:
type: string
description: Maker wallet, as sent when the order was created.
chainId:
type: integer
description: Chain ID.
inTokenAddress:
type: string
description: Token sold, as sent.
outTokenAddress:
type: string
description: Token bought, as sent.
tokenASymbol:
type: string
description: >-
Symbol of the token sold, possibly normalized (`WETH` becomes
`ETH`).
tokenBSymbol:
type: string
description: Symbol of the token bought, possibly normalized.
amount:
type: number
description: Amount of the token sold, human-readable.
price:
type: number
description: Copy of the limit price. `0` when it wasn't sent.
priceTrigger:
type: number
description: 'Limit price: units of the token bought per 1 token sold.'
expired:
type: string
description: 'Expiry as sent: a Unix timestamp in milliseconds.'
slippage:
type: string
description: Maximum slippage, in percent.
gasPrice:
type: string
description: >-
Gas price, in gwei, as sent. Olympex stores it with the order, but
execution uses the chain's gas price at that moment, so it isn't a
cap.
status:
type: string
enum:
- pending
- executing
- submitted
- completed
- cancelled
- failed
description: >-
`pending`: waiting for the price. `executing` and `submitted`:
Olympex is executing it. `completed`: executed, see `txHash`.
`cancelled`: cancelled. `failed`: execution failed, see
`reasonFail`. Treat any other value as not final.
txHash:
type: string
description: >-
Execution transaction hash on `chainId`. Empty until the order
executes.
reasonFail:
type: array
items:
type: string
description: Why execution failed, when it did. Empty otherwise.
attemptNumber:
type: integer
description: How many times Olympex has tried to execute the order.
allowance:
type: string
description: >-
Informational, reserved for Olympex: you can't set it. Usually an
empty string.
estimateGas:
type: string
description: >-
Informational, reserved for Olympex: you can't set it. Usually an
empty string.
effectivePriceGas:
type: string
description: >-
Informational, reserved for Olympex: you can't set it. Usually an
empty string.
createdAt:
type: string
format: date-time
description: When the order was created (ISO 8601, UTC).
updatedAt:
type: string
format: date-time
description: When the order last changed (ISO 8601, UTC).
deletedAt:
type: string
description: >-
When the order was cancelled with `DELETE` (ISO 8601, UTC). An empty
string until then.
Meta:
type: object
required:
- requestId
- version
properties:
requestId:
type: string
description: Unique ID for this request. Include it when you contact support.
version:
type: string
default: v1
description: API version that served the request.
accountType:
type: string
description: >-
Account type resolved by the signature check, for example
`integrator`. Present when the request was authenticated; absent on
the `404` for an unknown path or method.
apiKeyId:
type: string
format: uuid
description: >-
The API key ID that signed the request. Present when the request was
authenticated; absent on the `404` for an unknown path or method.
ErrorBody:
type: object
required:
- code
- message
- details
properties:
code:
type: string
description: >-
Machine-readable error code. `VALIDATION_ERROR` (400),
`UNAUTHORIZED` (401), `FORBIDDEN` (403), `NOT_FOUND` (404, also for
an unknown path or method), `CONFLICT` (409), `NO_ROUTE` (422), and
for 500: `QUOTE_ERROR`, `CROSS_CHAIN_QUOTE_ERROR`, `SWAP_ERROR`,
`CROSS_CHAIN_SWAP_ERROR`, `SUPPORT_CHAIN_ERROR`,
`ENABLED_CHAINS_ERROR`, `TOKEN_LIST_ERROR`, `TX_STATUS_ERROR`,
`INTERNAL_ERROR`. Olympex can add codes: handle an unknown code by
its HTTP status.
message:
type: string
description: Human-readable summary. Don't parse it.
details:
type: array
items:
$ref: '#/components/schemas/ErrorDetail'
ErrorDetail:
type: object
additionalProperties: true
description: >-
Validation errors carry `field` and `message`; other errors carry
`message` only.
properties:
field:
type: string
description: >-
Dot path of the invalid field, for example `params.chainId`. Empty
for the top level.
message:
type: string
securitySchemes:
ApiKeyId:
type: apiKey
in: header
name: x-api-key-id
description: >-
Your API key ID (UUID). See [Sign
requests](https://docs.olympex.io/authentication/sign-requests).
ValueInfo:
type: apiKey
in: header
name: x-value-info
description: >-
Base64 of `timestamp + "\n" + nonce + "\n" + bodyHash`, where
`timestamp` is Unix seconds, `nonce` is 24 new hexadecimal characters
and `bodyHash` is the unpadded base64url SHA-256 of the canonical body.
Passphrase:
type: apiKey
in: header
name: x-passphrase
description: Your account passphrase. Treat it like the secret key.
Signature:
type: apiKey
in: header
name: x-signature
description: >-
Lowercase hex HMAC-SHA256 (signature v2), keyed with your secret key
string (UTF-8, not decoded), of seven lines joined with `\n`, with no
trailing newline: `OLPX-HMAC-SHA256-V2`, `timestamp`, `nonce`, the
uppercase method, `path`, `canonicalQuery` and `bodyHash`. `path` is the
request path including `/api/v1`, without the query string, for example
`/api/v1/limit-order/`. `canonicalQuery` is the query parameters
decoded (`+` is a space), sorted by key and then by value, re-encoded
per RFC 3986 and joined with `&`, or the empty string when there is no
query. Headers signed for one request are rejected on any other. See
[Sign requests](https://docs.olympex.io/authentication/sign-requests).
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.