Querying Executions

Three read surfaces, with different audiences:

Query	Scope	Use
getOrderExecution	One fill, parties only	Everything about one trade, settlement artifacts included
listOrderExecutions	Your fills, either side	Activity history, reconciliation, per-submission fill tracking
recentOrderExecutions	Public, anonymized	The recent-trades tape for a product

Fills are visible only to the trade's two parties. A non-party querying an execution id gets ORDER_EXECUTION_NOT_FOUND — the same answer as for an id that doesn't exist, so nothing leaks about whether a trade happened.

Fetching one fill

Look up by orderExecutionId — the id from a list, a fill push, or the public tape. Each include flag folds in more of the settlement picture:

Flag	Adds
includeTransfers	Shipment/transfer records sourced off this fill
includeMoneyMovements	The fill's ledger lines
includeDisputes	Disputes raised against this fill
includeReturns	Return legs unwinding this fill
includeLineItemEvents	The durable record of which inventory units the fill moved — the only way to recover the traded units after settlement clears the execution link off the line items
includeProductData	The traded product: asset configuration + parent asset + key
includeMarket	The venue the fill cleared in
includePnl	The fill's economics: outcome quantities, effective per-unit prices, the seller's cost basis and realized P&L — see ExecutionPnl
includeHandChanges	Your own prior acquisitions and disposals of the same product and grade, newest first. Always scoped to you; single fetch only

query {
  getOrderExecution(input: {
    orderExecutionId: "2cd3835c-cc3b-44df-a301-03f71bdb47f8"
    includeTransfers: true
    includeMoneyMovements: true
    includeProductData: true
    includeMarket: true
  }) {
    orderExecution {
      id orderNumber takerSide quantity executionPriceCents grossAmountCents
      status executedAt settledAt
      buySideOrderId sellSideOrderId buyerAccountId sellerAccountId
      assetConfiguration { name }
      asset { name }
      key { name }
      market { id isVaulted }
      transfers { id status }
      moneyMovements { id movementType amountCents status }
    }
    error { message code }
  }
}

A fill mid-settlement:

{
  "orderExecution": {
    "id": "2cd3835c-cc3b-44df-a301-03f71bdb47f8",
    "orderNumber": "TPST-QP220BSZ",
    "takerSide": "SELL",
    "quantity": 1,
    "executionPriceCents": 878,
    "grossAmountCents": 878,
    "status": "SETTLING",
    "executedAt": "2026-08-11T02:43:02.576982Z",
    "settledAt": null,
    "buySideOrderId": "cba02330-fb94-47a7-984b-9a2024268e77",
    "sellSideOrderId": "c3c022bd-21e5-4a9f-b0ef-5e4a7280ef3b",
    "assetConfiguration": { "name": "Ascended Heroes Booster Pack" },
    "asset": { "name": "ME: Ascended Heroes" },
    "key": { "name": "MINT" },
    "market": { "id": "2406c582-64f0-4192-a7f2-f2cb70e5d652", "isVaulted": false },
    "transfers": [
      { "id": "c934c968-0bc2-46ec-83d3-2ab132f2c513", "status": "PENDING_LABEL_GENERATION" }
    ],
    "moneyMovements": [
      { "id": "77540239-38e3-41d7-b9bd-0d3594d92e7e", "movementType": "PURCHASE", "amountCents": 899, "status": "PENDING" },
      { "id": "052dfb54-50cf-4237-8714-814844f984fa", "movementType": "PLATFORM_FEE", "amountCents": 21, "status": "PENDING" },
      { "id": "ce904d4e-5f07-4d5a-913b-fc666e367dad", "movementType": "SALE", "amountCents": -878, "status": "PENDING" }
    ]
  },
  "error": null
}

Reading it: the trade crossed at 878¢. The buyer's PURCHASE charge is 899¢ — execution price plus the 21¢ PLATFORM_FEE — and the seller's SALE line credits the 878¢ net. All three sit PENDING alongside a transfer awaiting label generation; when settlement completes, the fill flips SETTLED and settledAt stamps.

Listing your fills

Newest first, both sides of every trade you were party to. Filters compose:

Filter	Matches
side	Your buys only, or your sells only
orderSubmissionId	All fills for one of your submissions, whichever side it took
buySideOrderId / sellSideOrderId	Fills for a specific resting order
inventoryItemId	Fills that moved a specific inventory item
assetConfigurationId	Fills in one product
assetTypeIds	Fills whose product belongs to these asset classes
marketId	Fills cleared in one venue
status	One settlement status
executedAfter / executedBefore	Execution-time window
search	Order number, product name, or tracking code, case-insensitive. A UUID matches the fill id exactly
trackingCode	Exact tracking code
transferStatus	Fills whose shipment is in this TransferStatus
paymentStatus	Fills whose buyer-side PURCHASE movement is in this MoneyMovementStatus
disputeStatus	Fills carrying a dispute in this DisputeStatus
recipientAddressId	Fills shipping to this address (read off the buy-side submission)
minQuantity / maxQuantity	Quantity range
filterPresets	Action-needed shortcuts, unioned and side-aware: REQUIRES_TRANSFER (you still need to ship), FAILED_PAYMENT (your charge failed), OPEN_DISPUTE, RETURN_IN_PROGRESS

The same include flags as the single fetch apply per page (except includeHandChanges), plus includeTotals:

query {
  listOrderExecutions(input: {
    status: SETTLED
    executedAfter: "2026-08-01T00:00:00Z"
    includeTotals: true
    pagination: { first: 2 }
  }) {
    orderExecutions { id orderNumber status executedAt settledAt quantity executionPriceCents }
    pageInfo { hasNextPage endCursor }
    totals { totalCount pendingValueCents completedValueCents }
  }
}

{
  "orderExecutions": [
    { "id": "79c60643-e4c7-46f3-9f05-ba550830cf3f", "orderNumber": "TPST-3GD7CVRQ", "status": "SETTLED", "executedAt": "2026-08-08T04:09:19.283779Z", "settledAt": "2026-08-08T04:09:33.891455Z", "quantity": 1, "executionPriceCents": 1457 },
    { "id": "25059ffa-3234-4fda-b5d7-075157c5d380", "orderNumber": "TPST-MC5KE7QS", "status": "SETTLED", "executedAt": "2026-08-08T04:07:20.278196Z", "settledAt": "2026-08-08T04:07:36.427486Z", "quantity": 4, "executionPriceCents": 1006 }
  ],
  "pageInfo": { "hasNextPage": true, "endCursor": "eyJ0cyI6..." },
  "totals": { "totalCount": 241, "pendingValueCents": "379923", "completedValueCents": "1511761" }
}

Totals cover the full filtered set, independent of the page: pendingValueCents is gross value still PENDING, completedValueCents is gross value of SETTLING + SETTLED fills. Both are BigInt, serialized as strings — parse them.

Pagination is the same keyset cursor as listing submissions: pass pageInfo.endCursor back as pagination.after until hasNextPage is false. A submission that never matched returns an empty list, not an error.

The public tape

recentOrderExecutions is the anonymized recent-trades feed for a product: SETTLED fills only, no party or account fields, filterable by assetId, assetConfigurationId, marketId, or keyId. Each row carries the execution id and takerSide so a client can dedupe against the live trade stream and render buy/sell styling.

Not yet available with API keys

recentOrderExecutions currently authenticates against Tradepost-issued session tokens (the consumer apps), not partner API keys — an API-key call returns Authentication required. The same feed is open to API keys as getRecentTrades, and live with execution ids on the trades channel.