Get order status

curl

ADDR=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
ORDER_ID=a1b2c3d4e5f6g7h8
curl "https://api.arcus.xyz/v1/order/${ORDER_ID}?address=${ADDR}"

const orderId = "a1b2c3d4e5f6g7h8";
const url = new URL(`https://api.arcus.xyz/v1/order/${orderId}`);
url.searchParams.set("address", "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb");
const res = await fetch(url);
console.log(await res.json());

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.arcus.xyz/v1/order/{orderId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.arcus.xyz/v1/order/{orderId}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.arcus.xyz/v1/order/{orderId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "orderId": "<string>",
  "marketId": 32767,
  "marketDisplayName": "BTC-USD",
  "side": "BUY",
  "status": "PENDING",
  "price": "<string>",
  "originalSize": "<string>",
  "remainingSize": "<string>",
  "updatedAt": 123,
  "clientId": "<string>",
  "type": "LIMIT",
  "filledSize": "<string>",
  "avgFillPrice": "<string>",
  "timeInForce": "GTC",
  "goodTilTime": "<string>",
  "reduceOnly": true,
  "triggerPrice": "<string>",
  "tpslType": "STOP_LOSS",
  "isPositionTPSL": true,
  "parentOrderId": "<string>",
  "rejectionReason": "POST_ONLY_WOULD_CROSS",
  "cancelReason": "MODIFY_CANCELED",
  "state": "OPEN",
  "positionEffect": "OPEN_LONG",
  "createdAt": 123,
  "sequenceNumber": 123
}

{
  "error": "Invalid request body",
  "code": "GEO_RESTRICTED",
  "errorSource": "Order",
  "errorType": "Tick",
  "rejectionReason": "POST_ONLY_WOULD_CROSS"
}

{
  "error": "Invalid request body",
  "code": "GEO_RESTRICTED",
  "errorSource": "Order",
  "errorType": "Tick",
  "rejectionReason": "POST_ONLY_WOULD_CROSS"
}

{
  "error": "rate limited",
  "reason": "account_empty",
  "retryAfterMs": 850,
  "clientId": "my-order-42"
}

GET

order

{orderId}

curl

ADDR=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
ORDER_ID=a1b2c3d4e5f6g7h8
curl "https://api.arcus.xyz/v1/order/${ORDER_ID}?address=${ADDR}"

const orderId = "a1b2c3d4e5f6g7h8";
const url = new URL(`https://api.arcus.xyz/v1/order/${orderId}`);
url.searchParams.set("address", "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb");
const res = await fetch(url);
console.log(await res.json());

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.arcus.xyz/v1/order/{orderId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.arcus.xyz/v1/order/{orderId}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.arcus.xyz/v1/order/{orderId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "orderId": "<string>",
  "marketId": 32767,
  "marketDisplayName": "BTC-USD",
  "side": "BUY",
  "status": "PENDING",
  "price": "<string>",
  "originalSize": "<string>",
  "remainingSize": "<string>",
  "updatedAt": 123,
  "clientId": "<string>",
  "type": "LIMIT",
  "filledSize": "<string>",
  "avgFillPrice": "<string>",
  "timeInForce": "GTC",
  "goodTilTime": "<string>",
  "reduceOnly": true,
  "triggerPrice": "<string>",
  "tpslType": "STOP_LOSS",
  "isPositionTPSL": true,
  "parentOrderId": "<string>",
  "rejectionReason": "POST_ONLY_WOULD_CROSS",
  "cancelReason": "MODIFY_CANCELED",
  "state": "OPEN",
  "positionEffect": "OPEN_LONG",
  "createdAt": 123,
  "sequenceNumber": 123
}

{
  "error": "Invalid request body",
  "code": "GEO_RESTRICTED",
  "errorSource": "Order",
  "errorType": "Tick",
  "rejectionReason": "POST_ONLY_WOULD_CROSS"
}

{
  "error": "Invalid request body",
  "code": "GEO_RESTRICTED",
  "errorSource": "Order",
  "errorType": "Tick",
  "rejectionReason": "POST_ONLY_WOULD_CROSS"
}

{
  "error": "rate limited",
  "reason": "account_empty",
  "retryAfterMs": 850,
  "clientId": "my-order-42"
}

The response body shown here is a static example, not live data. After you click Send, your live result appears in a separate panel headed 200 OK. The panel under the status-code tabs is a fixed sample from the spec — its field values (fees, prices, sizes, IDs, timestamps) are placeholders. Use Send, or call the endpoint, for current values.

Returns the status of a specific order by order ID. Requires address query parameter for the owning account because order data is partitioned by account, so the lookup needs the owning account.

Path Parameters

orderId

string

required

System-generated order ID (hex string).

Query Parameters

address

string

required

Master Ethereum address for this API key (must match address from POST /createApiKey for the same key). Required on REST for account-scoped reads and for place/cancel. Invalid hex → 400; mismatch with key → 403.

20-byte EVM address as hex: optional 0x or 0X prefix and exactly 40 hexadecimal digits. API responses normalize to lowercase a–f after 0x.

Pattern: ^(0x|0X)?[0-9a-fA-F]{40}$

accountIndex

integer

default:0

Subaccount index (0–9) to scope the request to. Defaults to 0 (the primary account). Values above 9 → 400.

Required range: 0 <= x <= 9

Response

Order status details.

Unified order shape used across REST responses, WebSocket snapshots, and streaming updates. Fields only available from the store are optional and may be absent in streaming updates.

orderId

string

required

System-generated order ID.

marketId

integer

required

Perpetual market identifier (uint16). Map to display name via GET /markets. Used for orders, positions, funding, and market metadata.

Required range: 0 <= x <= 65535

marketDisplayName

string

required

Market symbol (e.g. BTC-USD).

Example:

"BTC-USD"

side

enum<string>

required

Order side.

Available options:

BUY,

SELL

status

enum<string>

required

Current status of an order.

Available options:

PENDING,

OPEN,

PARTIALLY_FILLED,

FILLED,

CANCELED,

MARGIN_CANCELED,

REJECTED,

UNTRIGGERED,

TPSL_PLACED,

TPSL_TRIGGERED,

TPSL_CANCELED,

LIQUIDATED,

ADL,

ACK,

CANCEL_ACKNOWLEDGED,

CANCEL_ALL_ACKNOWLEDGED,

CANCEL_PENDING,

ERROR

price

string

required

Limit price in human-readable units (decimal string).

originalSize

string

required

Original order size in human-readable units (decimal string).

remainingSize

string

required

Remaining unfilled size in human-readable units. "0" when fully filled.

updatedAt

integer<int64>

required

Last update timestamp (epoch microseconds).

clientId

string

Client-provided order identifier. Optional; max 36 characters. An account may have at most 10,000 live clientIds simultaneously — placing an order with a new clientId while at this limit is rejected with TOO_MANY_CLIENT_IDS. A clientId slot is freed when the order reaches a terminal state (FILLED, CANCELED, or REJECTED). Reusing an already-active clientId is rejected with DUPLICATE_CLIENT_ID.

Maximum string length: 36

type

enum<string>

Execution style of the order. Use tpslType to mark an order as stop-loss or take-profit. Absent on forced closures (status LIQUIDATED or ADL): those have no originating user order, so no execution style exists — key off status instead.

Available options:

LIMIT,

MARKET

filledSize

string

Filled size in human-readable units (decimal string). Computed as originalSize − remainingSize.

avgFillPrice

string

Cumulative average fill price (decimal string), computed as filledNotional / filledSize. Present on REST, snapshot, and streaming responses whenever the order has any filled quantity; absent when nothing has filled.

timeInForce

enum<string>

Time-in-force policy for the order. Resting orders (submitted as GTT) are currently reported as GTC for backward compatibility with consumers that predate the GTT rename; treat GTC and GTT as equivalent when reading.

Available options:

GTC,

GTT,

IOC,

FOK,

ALO

goodTilTime

string

Expiration timestamp in epoch microseconds (as string), the API's user-facing timestamp resolution. Present when the order carries a good-till-time expiry.

reduceOnly

boolean

True when the order can only reduce an existing position (echoed from the placing request). Present only when true; absent for regular orders.

triggerPrice

string

Trigger price for stop/TPSL orders (decimal string).

tpslType

enum<string>

Trigger purpose of the order, orthogonal to type (execution style). Absent for plain orders.

Available options:

STOP_LOSS,

TAKE_PROFIT

isPositionTPSL

boolean

True when the TPSL closes the user's full open position at trigger time (resized against the live position) rather than a sized leg (partialTpsl) or an entryTpsl child. Only present on TPSL orders; absent on plain orders. At most one position-level TPSL of each trigger class (TP, SL) may be active per account+market — a second placement is rejected with POSITION_TPSL_ALREADY_EXISTS.

parentOrderId

string

Entry order id this TPSL leg is bound to (entryTpsl bundles). Cancelling the entry cancels every TPSL leg pointing at it. Only present on TPSL orders that were placed alongside an entry; absent on standalone TPSLs (partialTpsl, positionTpsl) and on plain orders.

rejectionReason

enum<string>

Machine-readable reason emitted by the matching engine when an order is rejected. See the canonical RejectionReason schema for the full enum and per-value descriptions.

Available options:

POST_ONLY_WOULD_CROSS,

SELF_TRADE,

UNDERCOLLATERALIZED,

COULD_NOT_FILL,

IOC_CANCELED,

FOK_FAILED,

REDUCE_ONLY_WOULD_INCREASE,

TOO_MANY_CLIENT_IDS,

DUPLICATE_CLIENT_ID,

POSITION_TPSL_ALREADY_EXISTS,

ENTRY_TPSL_CANNOT_BE_POSITION_TPSL,

ORDER_WILL_TAKE_LIQUIDITY_DURING_MARKET_HALT,

ORDER_NOT_FOUND_FOR_MODIFY,

MODIFY_CHANGED_IMMUTABLE_FIELD,

MODIFY_ZERO_SIZE,

PRICE_WILL_EXCEED_MAXIMUM_OUTSIDE_RTH_TRADING_BOUND,

MODIFY_WOULD_CROSS_OUTSIDE_RTH_TRADING_BOUNDARY,

FILL_WILL_EXCEED_TRADING_BOUND,

OPEN_INTEREST_CAP_EXCEEDED,

POSITION_SIZE_CAP_EXCEEDED,

MODIFY_TPSL_NOT_SUPPORTED,

MODIFY_SUPERSEDED_BY_CANCEL,

MODIFY_SIZE_ALREADY_FILLED

cancelReason

enum<string>

Qualifies a CANCELED update when the matching engine stamped a reason. Currently the only value is MODIFY_CANCELED: this cancel is the first leg of a modify — the SAME order id is re-placed by the account's very next update (PLACED / FILL / REJECTED), so the order is not terminally gone unless that follow-up says so. Absent on all other cancels, which are genuinely terminal.

Available options:

MODIFY_CANCELED

state

enum<string>

Engine-authoritative lifecycle position after this event. Sourced directly from the matching engine and stamped on every streaming update — clients can drive an order state machine off this alone without parsing event types or comparing sizes:

Partial fill of a resting order: state=PARTIALLY_FILLED (status is "OPEN").
IOC partial: state=PARTIALLY_FILLED is terminal; the implicit cancel of the IOC remainder is conveyed by timeInForce == IOC with no follow-up event (status is "CANCELED" instead).
Explicit cancel after prior partial fills: state=CANCELED. status carries broader signals (ACK, CANCEL_PENDING, MARGIN_CANCELED, TPSL_*, etc.) that have no equivalent here.

Available options:

OPEN,

PARTIALLY_FILLED,

FILLED,

CANCELED,

REJECTED

positionEffect

enum<string>

How a fill on this order changed the account's position in marketId. Only set on fill events; absent on placements / cancels / rejects. For taker fills the value is the net effect across all fills in the same aggregated update (FLIP_* covers a position that closed and reopened on the opposite side within one user order).

Available options:

OPEN_LONG,

OPEN_SHORT,

ADD_LONG,

ADD_SHORT,

CLOSE_LONG,

CLOSE_SHORT,

FLIP_LONG_TO_SHORT,

FLIP_SHORT_TO_LONG

createdAt

integer<int64>

Order creation timestamp (epoch microseconds). Only present on REST and snapshot responses.

sequenceNumber

integer<uint64>

Per-account sequence of the engine event that last wrote this order (same counter as AccountUpdate.sequenceNumber). Present on streaming orders channel updates and on WebSocket OrdersSnapshot rows; omitted on REST when unset.

API documentation

Endpoints

WebSocket

Changelog

Path Parameters

Query Parameters

Response