Orders / Follow an order
Order states and records
Every route reports one state, from nine values. Branch on state; rawStatus is for support. Then match what happened against your own books.
state | Meaning | Who acts | Final |
|---|---|---|---|
pending | Placed; no solver has committed | solver | no |
awaiting_deposit | Selling: payout locked, user sends BTC | user | no |
in_progress | The solver is filling | solver | no |
completed | Buying: BTC sent. Selling: payout released | nobody | yes |
refundable | Buying: no solver filled in time | user | no |
refunded | The coins went back | nobody | yes |
cancelled | Cancelled before anything moved | nobody | yes |
expired | Selling and Solana: window closed | nobody | yes |
failed | Selling, Solana and coin to coin: see rawStatus | Maxy support | yes |
An order is done for the user when their funds arrive. A buy, EVM or Solana, reads completed the moment btcTxId is set. A settlement is Maxy getting its own money back: nothing waits for it, and if it fails the swap still reads completed. Before the payment confirms, the solver may speed it up: same amount and address, a new btcTxId. Show the latest.
To cancel while pending: POST /orders/{id}/cancel?chainId=8453 answers the call for the wallet to send. After a solver commits, it answers 409 order_state.
Reconcile
GET /orders lists the orders placed with your key, newest first. format=csv gives a spreadsheet.
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/orders?from=2026-11-01&to=2026-12-01"
- Up to 100 a page, or 1,000 in a CSV. Follow
nextCursorwithcursor=. - Filter by
state,wallet,externalIdorexternalCustomerId. - Send your own ids on
POST /orders. Maxy stores them as given. - An order stays listed for 30 days after it ends, so export monthly.
A month as a statement, in JSON, CSV or PDF: GET /statements?month=2026-11.
At month-end, export the month and join on orderId:
- 01
completed:btcTxIdis the payment. Match the amount you showed. - 02
refunded,refundable,failed: no BTC was paid. - 03 In your books but not the export: look it up with
GET /status?txHash=. That finds any Maxy order. If it answers404, Maxy has no such order.
To add an order placed another way: POST /orders/watch.