Get Orders History

Retrieve orders history for the authenticated subaccount with comprehensive filtering, sorting, and pagination capabilities, providing access to orders in any status with flexible query options.

Endpoint

POST https://papi.synthetix.io/v1/trade

Request

Request Format

{
  "params": {
    "action": "getOrderHistory",
    "subAccountId": "1867542890123456789",
    "status": ["placed", "filled"],
    "fromTime": 1730160000000,
    "toTime": 1730764800000,
    "limit": 100
  },
  "expiresAfter": 1704067500,
  "signature": {
    "v": 28,
    "r": "0x19480589384695193600abcdef19480589384695193600abcdef19480589384695193600abcdef19480589384695193600abcdef",
    "s": "0xabcdef19480589384695193600abcdef19480589384695193600abcdef19480589384695193600abcdef19480589384695193600"
  }
}

Request Parameters

Parameter	Type	Required	Description
`params`	object	Yes	Request parameters wrapper
`params.action`	string	Yes	Must be `"getOrderHistory"`
`params.subAccountId`	string	Yes	SubAccount ID to retrieve orders for
`params.status`	string[]	No	Filter by order status: `["started", "placed", "partially filled", "filled", "cancelling", "cancelled", "rejected", "modifying", "modified", "unknown"]`
`params.symbol`	string	No	Filter by specific trading pair symbol (e.g., "BTC-USDT")
`params.side`	string	No	Filter by order side: `"buy"` or `"sell"`
`params.type`	string	No	Filter by order type (e.g., `"LIMIT"`, `"MARKET"`)
`params.fromTime`	integer	No	Start timestamp in milliseconds (inclusive). Max 7-day range
`params.toTime`	integer	No	End timestamp in milliseconds (inclusive). Max 7-day range
`params.limit`	integer	No	Maximum number of orders to return (no default specified, max: 1000)

Parameter	Type	Required	Description
`nonce`	uint64	Yes*	Unix milliseconds timestamp (must be monotonically increasing)
`signature`	object	Yes	EIP-712 signature object
`expiresAfter`	uint64	No	Unix seconds expiration timestamp (5x rate limit on stale cancels)

:::info Common Parameters These are top-level request parameters. The subAccountId parameter is specified within the params object (see each endpoint's parameter table). :::

:::info SubAccountAction Endpoints Endpoints using SubAccountAction signing (getPositions, getOpenOrders, getOrdersHistory, getTrades, getFundingPayments, getSubAccount, getDelegatedSigners, getBalanceUpdates) do not require the nonce parameter. Only signature and optional expiresAfter are needed. :::

Filter Combinations

The endpoint supports powerful filter combinations:

All Orders: Omit status to get orders in any status
Historical Orders: "status": ["filled", "cancelled"] with time range
Recent Activity: Use fromTime without toTime for orders since a specific time
Symbol-Specific: Combine symbol with any other filters

Response

Response Structure

Field	Type	Description
`status`	string	Always `"ok"` for successful requests or `"error"` for failures
`response`	array	Array of order objects matching filter criteria (omitted when `status` is `"error"`)
`error`	object	Error details (only present when `status` is `"error"`)
`request_id`	string	Request tracking identifier

Success Response Examples

Multiple Orders with Various Statuses

{
  "status": "ok",
  "response": [
    {
      "orderId": "1958787130134106112",
      "symbol": "BTC-USDT",
      "side": "buy",
      "type": "LIMIT",
      "status": "FILLED",
      "quantity": "0.1",
      "price": "45000.00",
      "timeInForce": "GTC",
      "createdTime": 1755846234000,
      "filledQuantity": "0.1",
      "filledPrice": "44998.50",
      "triggeredByLiquidation": false,
      "reduceOnly": false,
      "postOnly": false
    },
    {
      "orderId": "1958787130134106113",
      "symbol": "ETH-USDT",
      "side": "sell",
      "type": "LIMIT",
      "status": "PARTIALLY_FILLED",
      "quantity": "2.0",
      "price": "2800.00",
      "timeInForce": "GTC",
      "reduceOnly": false,
      "postOnly": false,
      "createdTime": 1755846235000,
      "filledQuantity": "0.5",
      "filledPrice": "2801.25",
      "triggeredByLiquidation": false
    },
    {
      "orderId": "1958787130134106114",
      "symbol": "BTC-USDT",
      "side": "buy",
      "type": "LIMIT",
      "status": "NEW",
      "timeInForce": "GTC",
      "quantity": "0.05",
      "price": "44000.00",
      "reduceOnly": false,
      "postOnly": false,
      "createdTime": 1755846236000,
      "filledQuantity": "0.0",
      "filledPrice": "0.0",
      "triggeredByLiquidation": false
    }
  ],
  "request_id": "5ccf215d37e3ae6d"
}

Empty Result Set

{
  "status": "ok",
  "response": [],
  "request_id": "5ccf215d37e3ae6f"
}

Order Object

Field	Type	Description
`orderId`	string	Unique order identifier (64-bit unsigned integer as string)
`symbol`	string	Trading pair symbol (e.g., "BTC-USDT")
`side`	string	Order side: "buy" or "sell"
`type`	string	Order type: "LIMIT", "MARKET", "STOP_LOSS", "TAKE_PROFIT"
`status`	string	Order status: "open", "filled", "partially_filled", "cancelled", "rejected"
`quantity`	string	Original order quantity
`price`	string	Order price (empty for market orders)
`filledPrice`	string	Average fill price (empty if not filled)
`triggerPrice`	string	Trigger price for conditional orders
`triggerPriceType`	string	Trigger price type: "mark", "last", or "index"
`timeInForce`	string	Time in force: "GTC", "IOC", or "FOK"
`reduceOnly`	boolean	Whether order only reduces existing position
`postOnly`	boolean	Whether order must be maker (no immediate match)
`triggeredByLiquidation`	boolean	Whether order was triggered by a liquidation
`createdTime`	integer	Order creation timestamp (Unix milliseconds)
`updatedTime`	integer	Last update timestamp (Unix milliseconds)
`filledQuantity`	string	Quantity that has been filled
`takeProfitOrderId`	string	ID of linked take-profit order (if exists)
`stopLossOrderId`	string	ID of linked stop-loss order (if exists)
`closePosition`	boolean	Whether order closes entire position

Error Response

{
  "status": "error",
  "error": {
    "message": "Invalid time range: fromTime must be less than or equal to toTime",
    "code": "VALIDATION_ERROR"
  },
  "request_id": "5ccf215d37e3ae6d"
}

Advanced Filtering

Time-based Queries

// Orders from last 24 hours
"fromTime": Date.now() - 86400000
 
// Orders in specific date range
"fromTime": 1704067200000,
"toTime": 1704153600000
 
// Orders since specific time (no end)
"fromTime": 1704067200000

EIP-712 Signature

const domain = {
  name: "Synthetix",
  version: "1",
  chainId: 1,
  verifyingContract: "0x0000000000000000000000000000000000000000"
};
 
const types = {
  SubAccountAction: [
    { name: "subAccountId", type: "uint256" },
    { name: "action", type: "string" },
    { name: "expiresAfter", type: "uint256" }
  ]
};
 
const message = {
  subAccountId: "1867542890123456789",
  action: "getOrderHistory",
  expiresAfter: 0
};
 
const signature = await signer._signTypedData(domain, types, message);

Implementation Notes

Authentication requires signature by account owner or authorized delegate
Time range cannot exceed 7 days (604,800,000 milliseconds)
Time range filtering supports inclusive bounds with fromTime ≤ toTime validation
Pagination: Use limit parameter (no default specified, max: 1000)
Status filtering accepts multiple values

Signing

All trading methods are signed using EIP-712. Each successful trading request will contain:

A piece of structured data that includes the sender address
A signature of the hash of that structured data, signed by the sender

For detailed information on EIP-712 signing, see EIP-712 Signing.

Nonce Management

The nonce system prevents replay attacks and ensures order uniqueness:

Use current timestamp in milliseconds as nonce
Each nonce must be greater than the previous one
Recommended: Use Date.now() or equivalent
If nonce conflicts occur, increment by 1 and retry

:::note SubAccountAction Exception SubAccountAction endpoints (getPositions, getOpenOrders, getOrdersHistory, getTrades, getFundingPayments, getSubAccount, getDelegatedSigners, getBalanceUpdates) do not require a nonce. Only the signature and optional expiresAfter parameters are needed. :::

Error Handling

Common error scenarios:

Error	Description
Invalid signature	EIP-712 signature validation failed
Invalid market symbol	Market symbol not recognized
Nonce already used	Nonce must be greater than previous value
Rate limit exceeded	Too many requests in time window
Request expired	`expiresAfter` timestamp has passed

Error	Description
Invalid request format	Request payload could not be parsed
Internal error	Failed to retrieve orders
Invalid time range	fromTime is greater than toTime, or time range exceeds 7 days
Invalid status	Specified status is not recognized
Invalid symbol	Specified symbol is not recognized
Invalid sort field	Specified sortBy field is invalid
Invalid pagination	Limit or offset out of valid range
Subaccount not found	Specified subaccount does not exist