> ## Documentation Index > Fetch the complete documentation index at: https://docs.0xmonaco.com/llms.txt > Use this file to discover all available pages before exploring further. # Get user orders > Get user orders. Get orders for the authenticated user with pagination and optional filtering by status and trading pair. A TWAP order's slices are not listed here; read them from ListTwapOrderSlices. ## OpenAPI ````yaml /proto-openapi/api/openapi.yaml get /api/v1/orders openapi: 3.0.3 info: title: Monaco Protocol API description: REST API for the Monaco Protocol hybrid CLOB exchange. version: 1.0.0 servers: - url: https://staging.apimonaco.xyz description: Staging server (Testnet) security: [] tags: - name: AccountsService - name: ApplicationsService - name: AuthService - name: BuildercodeRewardsService - name: CopyTradingService - name: DelegatedAgentsService - name: FaucetService - name: FeesService - name: HealthService - name: ManagedMarketsService description: |- Wallet-authenticated maker assignments. The signed session must match both configured maker user and application. Owner IDs are process fences, never auth. Only wallet sessions are supported; delegated-agent sessions receive 403. - name: MarginAccountsService description: |- Current public isolated-margin semantics: - a user has one parent margin account per application scope - opening orders create or reuse isolated position buckets under that parent - parent account creation is handled internally by margin workflows - name: MarketService - name: OrderbookService - name: OrdersService - name: PositionsService description: |- Current public isolated-margin semantics: - positions link to a parent margin account and, when applicable, a bucket id - opening orders create or reuse isolated position buckets under the parent - users can open another isolated position by reusing the parent account with a different market bucket - name: PulseService - name: SweeperService - name: TraderCodeService - name: TradesService - name: WhitelistService - name: WithdrawalsService paths: /api/v1/orders: get: tags: - OrdersService - Orders summary: Get user orders description: |- Get user orders. Get orders for the authenticated user with pagination and optional filtering by status and trading pair. A TWAP order's slices are not listed here; read them from ListTwapOrderSlices. operationId: get_orders parameters: - name: pageSize in: query schema: type: integer format: uint32 minimum: 1 maximum: 1000 default: 20 description: >- Items per page (max 100 in page-number mode; up to 1000 when pageToken is present) - name: status in: query schema: type: string minLength: 1 description: Order status (single value or comma-separated list) - name: tradingPairId in: query schema: type: string minLength: 1 format: uuid description: Trading pair identifier (UUID) - name: tradingMode in: query schema: type: string enum: - SPOT - MARGIN minLength: 1 description: Trading mode - name: marginAccountId in: query schema: type: string - name: orderBy in: query schema: type: string default: DESC enum: - ASC - DESC minLength: 1 description: Sort direction for createdAt - name: pageToken in: query description: |- Pagination cursor with two states: - Omitted or empty string (""): start a cursor walk with no prior position, from the newest row (or the oldest, when `orderBy` is ASC). - Non-empty: an opaque cursor from a previous response's `next_page_token`; results resume immediately after that position. `total` and `total_pages` are populated — bounded by the server count ceiling, see `total_capped`. Every walk covers full order history — hot and archived rows merged. Filters and orderBy must match the request that produced the token. schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ListOrdersResponse' '400': description: Invalid query parameters '401': description: Authentication required '403': description: User does not belong to application '404': description: User not found '429': description: >- Read rate limit exceeded — every authenticated read draws one request from the account's read budget; retry after the interval in details.retryAfter '500': description: Internal server error security: - monacoSignature: [] - monacoHttpSignature: [] components: schemas: ListOrdersResponse: type: object properties: orders: type: array items: $ref: '#/components/schemas/GetOrderResponse' nullable: true total: example: 150 type: integer description: >- Total number of orders matching the filter, populated in both pagination modes; bounded by the server ceiling — a lower bound when totalCapped is true. format: uint32 nullable: true pageSize: example: 20 type: integer description: Items per page format: uint32 nullable: true totalPages: example: 8 type: integer description: >- Total number of pages at this pageSize, populated in both pagination modes; bounded by the server ceiling — a lower bound when totalCapped is true. format: uint32 nullable: true nextPageToken: type: string description: >- Cursor for the next page. Present whenever that page returned any rows (AIP-158 "maybe more" semantics), not only when the page is exactly full. Empty only when a page returned zero rows, which is the sole proof the walk is exhausted; a non-empty token does not guarantee further results, so keep following it until a response returns zero rows and an empty token. nullable: true totalCapped: example: false type: boolean description: >- True when more than the server ceiling of orders matched, so the count stopped at the ceiling and total/totalPages are a lower bound (more than total exist). False when total is the exact count, including exactly the ceiling. nullable: true GetOrderResponse: type: object properties: id: example: 123e4567-e89b-12d3-a456-426614174000 type: string description: Order UUID format: uuid nullable: true tradingPairId: example: 456e7890-e12b-12d3-a456-426614174000 type: string description: Trading pair UUID format: uuid nullable: true orderType: example: LIMIT type: string description: 'Order type: LIMIT or MARKET' nullable: true side: example: BUY type: string description: 'Order side: BUY or SELL' nullable: true price: example: '35000.00' type: string description: Limit price (null for market orders) nullable: true quantity: example: '0.5' type: string description: Original order quantity nullable: true filledQuantity: example: '0.2' type: string description: Quantity filled so far nullable: true averageFillPrice: example: '35050.00' type: string description: Volume-weighted average fill price nullable: true status: example: PARTIALLY_FILLED type: string description: >- Order status: SUBMITTED, PARTIALLY_FILLED, FILLED, CANCELLED, REJECTED, or EXPIRED nullable: true tradingMode: example: SPOT type: string description: 'Trading mode: SPOT or MARGIN' nullable: true timeInForce: example: GTC type: string description: >- Time in force: GTC, IOC, or FOK. Absent on MARKET orders, which have none. nullable: true createdAt: example: '2023-11-13T10:30:00Z' type: string description: Order creation timestamp (ISO 8601) nullable: true updatedAt: example: '2023-11-13T10:35:00Z' type: string description: Last update timestamp (ISO 8601) nullable: true expirationDate: example: '2023-11-13T10:35:00Z' type: string description: Order expiration date (ISO 8601) nullable: true applicationTakerFee: example: '0.88' type: string description: >- Application (builder) taker fee this order paid, in quote token units, summed over the fills where it was the taker: each fill's fee as charged, rounded down to the quote token's smallest unit. A replacement order also includes the fills of the order it replaced. 0 on a liquidation order. An amount, not a rate. nullable: true monacoTakerFee: example: '1.75' type: string description: >- Monaco protocol taker fee this order paid, in quote token units, summed over the fills where it was the taker: each fill's fee as charged, rounded down to the quote token's smallest unit. A replacement order also includes the fills of the order it replaced. A liquidation order carries the liquidation fee it was charged instead. An amount, not a rate. nullable: true monacoMakerRebate: example: '-0.35' type: string description: >- Monaco maker fee on this order, in quote token units, summed over the fills where it was the maker; negative is a rebate credited to the maker. A replacement order also includes the fills of the order it replaced. An amount, not a rate. nullable: true totalTakerFees: example: '2.63' type: string description: >- Total taker fees charged in quote token (monaco_taker_fee + application_taker_fee) nullable: true takerTotalPayment: example: '17502.63' type: string description: >- Total amount paid by taker, in quote token units: the filled notional as the ledger booked it (each fill's price * qty, rounded down to the quote token's smallest unit) plus total_taker_fees. A replacement order also includes the fills of the order it replaced. nullable: true makerTotalReceipt: example: '17500.35' type: string description: >- Total amount received by maker, in quote token units: the notional of its maker fills as the ledger booked it (each fill's price * qty, rounded down to the quote token's smallest unit) minus monaco_maker_rebate, so a rebate adds. A replacement order also includes the fills of the order it replaced. nullable: true marginAccountId: example: 123e4567-e89b-12d3-a456-426614174000 type: string description: Margin account UUID for margin orders format: uuid nullable: true positionSide: example: LONG deprecated: true type: string description: DEPRECATED derived compatibility value. Order side is authoritative. nullable: true leverage: example: '5' type: string description: Leverage for margin orders nullable: true reduceOnly: example: false type: boolean description: Whether the order is reduce-only nullable: true positionId: example: 123e4567-e89b-12d3-a456-426614174000 type: string description: Associated margin position UUID format: uuid nullable: true quantityRaw: example: '500000000' type: string description: Original order quantity in raw format (for precision) nullable: true filledQuantityRaw: example: '200000000' type: string description: Filled quantity in raw format (for precision) nullable: true remainingQuantity: example: '0.3' type: string description: Remaining unfilled quantity (normalized for display) nullable: true remainingQuantityRaw: example: '300000000' type: string description: Remaining unfilled quantity in raw format (for precision) nullable: true clientOrderId: example: quote-btc-1130-a type: string description: >- Client-assigned correlation handle as stored: the value supplied on create or replace, with surrounding whitespace trimmed. Absent when the order carried none, including every order placed before the field was accepted on write. Uniqueness is enforced only among your orders that are RESTING on the book, so several of your orders may share one value over time and a lookup by it can be ambiguous: an order that never rests never takes the handle, and the value is released the moment any order reaches a terminal state. It is a correlation handle, not an idempotency key. nullable: true cancelledAt: example: '2023-11-13T10:35:00Z' type: string description: Timestamp when the order was cancelled (ISO 8601) nullable: true filledAt: example: '2023-11-13T10:35:00Z' type: string description: Timestamp when the order was fully filled (ISO 8601) nullable: true expiredAt: example: '2023-11-13T10:35:00Z' type: string description: Timestamp when the order expired (ISO 8601) nullable: true submittedAt: example: '2023-11-13T10:35:00Z' type: string description: Timestamp when the order was submitted (ISO 8601) nullable: true acknowledgedAt: example: '2023-11-13T10:35:00Z' type: string description: Timestamp when the order was acknowledged (ISO 8601) nullable: true triggerPrice: example: '34000.00' type: string description: Trigger price for stop/conditional orders nullable: true quoteVolume: example: '17500.00' type: string description: Quote volume of the order nullable: true applicationId: type: string description: Application UUID that created the order format: uuid nullable: true parentOrderId: type: string description: Parent order UUID for linked orders format: uuid nullable: true batchId: type: string description: Batch UUID for batch orders format: uuid nullable: true terminalReason: example: REDUCE_ONLY_EXHAUSTED type: string description: >- Stable terminal cause for a cancelled order: USER_REQUESTED, REPLACED, LIQUIDATION, INSUFFICIENT_MARGIN, REDUCE_ONLY_EXHAUSTED, POSITION_CLOSED, OCO_SIBLING_TRIGGERED, SELF_TRADE_PREVENTION, AUTO_DELEVERAGING, PRICE_BAND, SLIPPAGE_TOLERANCE, or SYSTEM. AUTO_DELEVERAGING means auto-deleveraging closed the position your risk bucket held and this resting order was cancelled with it; you were deleveraged as a counterparty, not liquidated. PRICE_BAND means the exchange's protective price band stopped the order and its remainder was cancelled, or, on a resting perp order, that the mark moved the order past the band, where no taker may trade with it; SLIPPAGE_TOLERANCE means your own slippageToleranceBps did. nullable: true postOnly: example: false type: boolean description: >- Whether the order was placed post-only (maker-only). Absent for orders placed before the flag was persisted. nullable: true version: example: 918342 type: integer description: >- Opaque, compare-only revision counter for this order's state: the sequencer step that wrote it. A strictly higher value is strictly newer state for that order. The SAME counter is carried on every order WebSocket event and on the `orders` snapshot frame, so a reconnecting client reconciles on `(id, version)` — take the REST row when `snapshot.version >= local.version`, else keep local state. Note `>=`, not `>`: on the stream, equal versions mean the SAME STEP rather than identical state, because one step emits several events for one order (an `OrderPlaced` and then its fills) and a batch shares one step across every item. A REST row is that step's FINAL state, so it wins a tie. Between two REST reads the comparison is simpler — equal there does mean identical state. Do not read anything else into the number: it is not a count of updates, consecutive values are not expected (it is drawn from a global sequence shared by every order, so per-order values are sparse and gaps are normal), and it is not comparable across different orders. Absent means unknown: an order last written before this field existed. Fall back to a full field comparison for those rather than treating absent as version zero — and note that a comparison against an absent value is false in both directions, so an order held locally without one is never refreshed by the merge above; take the REST row unconditionally for those. Reconciling on this counter does NOT on its own close a reconnect gap: an order that filled or was cancelled while the socket was down appears in neither the resting snapshot nor the stream, so recover fills from `listUserTrades` (ordered by execution time) and resolve anything your local state believes is resting that the snapshot no longer lists with a targeted `getOrder`. Unlike `updatedAt`, this value is identical on every REST endpoint that serves the same order state, and never advances without a state change. format: int64 nullable: true selfTradePreventionMode: example: CANCEL_TAKER enum: - CANCEL_MAKER - CANCEL_TAKER - CANCEL_BOTH - SKIP type: string description: >- The per-order self-trade-prevention override REQUESTED when this order was placed or replaced: CANCEL_MAKER, CANCEL_TAKER, CANCEL_BOTH, or SKIP. Absent when the order carried no override — including every order placed before the field was accepted on write — even though a wallet or platform default still governed its matching. This echoes the request, not the resolved default. nullable: true conditionalOrderId: example: 019aefab-f665-854c-99dc-ced6db9014aa type: string description: >- Present only on an order the engine placed for a take-profit or stop-loss trigger: the conditional order (GET /api/v1/orders/conditional/{conditionalOrderId}) that fired it. The reverse of ConditionalOrder.triggeredOrderId, so a close in order history can be attributed to the TP/SL that produced it without scanning the conditional list. Absent on every order a client placed itself, on TWAP slice children (those carry parentOrderId), and on triggered closes written before the field existed — there is no backfill, so a missing key on an older close means unknown, not placed by hand. nullable: true origin: example: LIQUIDATION type: string description: >- What placed the order: USER (the account itself, including its TP/SL triggers and TWAP slices), LIQUIDATION (the liquidation engine closing the account's position), ADL (an auto-deleveraging close), COPY (the copy trading engine mirroring a leader for one of the account's follows), or SYSTEM. Use it to label a row in order history: a liquidation is a reduce-only IOC limit order, so orderType, timeInForce and reduceOnly alone read the same as an order the user placed. The same labels as the origin key on the order WebSocket events. Present on every book order. Absent on a TWAP parent row and a conditional order row, which are the account's own instructions, not orders an engine placed. A plain string, not a closed set: a value added later must read as an origin this client does not know yet, not fail the response. nullable: true securitySchemes: monacoSignature: type: apiKey description: >- Ed25519 session-key request signing. Every authenticated request carries three headers: `X-Monaco-PublicKey` (64-char lowercase-hex session public key), `X-Monaco-Timestamp` (Unix milliseconds, within 30s of server time), and `X-Monaco-Signature` (hex ed25519 signature). The signature is over `METHOD\npath?query\ntimestamp_ms\nSHA256_hex(body)`, where the body hash is the SHA-256 of the empty byte string when there is no body. Obtain the session keypair from `POST /api/v1/auth/challenge` followed by `POST /api/v1/auth/verify`. name: X-Monaco-Signature in: header monacoHttpSignature: type: apiKey description: >- RFC 9421 Ed25519 session-key request signatures. Send Signature-Input, Signature, and Content-Digest together; never combine them with X-Monaco-* credentials. The monaco signature covers @method, @path, @query, and content-digest in that order, with created (Unix seconds within 30s of server time), keyid (registered lowercase-hex session public key), and alg=ed25519 parameters. Content-Digest uses RFC 9530 sha-256 over the exact body bytes, including the empty body. Query coverage retains ordering and percent encoding. Timestamp freshness does not reject repeated identical requests; use endpoint idempotency where supported. Existing legacy signing remains supported during server-first migration; SDK RFC 9421 signing is opt-in. See https://docs.0xmonaco.com/reference/http-message-signatures for the complete profile and trust model. name: Signature in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.