Swaps / Recovery
When it fails
Where the money is when an order goes wrong, and who acts next. Every exit but a proven BTC payment sends a buyer's coins back, and no Maxy server can change that.
Refunds
Use this when a buy reads refundable. The refund is a contract call, sent from the user's wallet. GET /orders/{id}/refund builds it and simulates it, with no key. To try it, quote with scenario=refund_available; the sandbox transaction is never sent.
curl -s "$BASE/orders/$ORDER_ID/refund?chainId=8453"
| What happened | Where the money is | Who acts, when |
|---|---|---|
| Rejected a signature | the wallet | nobody |
| Gasless, escrow never opened | the wallet | nobody: the signature lapses after 2 hours |
| Escrow open, no solver | the settler | the user any time; anyone after 2 hours |
| Solver committed, did not pay | the settler, plus the bond | anyone, after 144 Bitcoin blocks, about a day |
| Refund sent | the wallet, with the bond if there was one | nobody |
The bond goes half to whoever sends the refund, half to the user, so a user who sends it gets it all. Pausing the settler never blocks a refund. While no solver has committed, the user can also cancel: POST /orders/{id}/cancel?chainId=8453 answers the call to send.
If the answer is refundable: false, it is before the deadline or there is nothing to refund: read reason, and wait for unlocksAt. The SDK says the same with not_refundable. tx_reverted means it was already refunded or settled.
Failed sells
A sell goes wrong when the payment is the wrong amount or too late. The contract proves only an output of exactly the amount in sats, inside the window.
| What happened | state | Result | Do |
|---|---|---|---|
| Exact, in time | in_progress, completed | Payout released | Nothing |
| Exact, one block after the deadline | in_progress | Still the user's | GET /orders/{id}/claim |
| Different amount | awaiting_deposit, expired | The contract cannot pay | Contact Maxy with the txid |
| Later than that | expired | Escrow returns to the solver | Contact Maxy with the txid |
| Never paid | expired | Nothing was sent | New order |
The solver sends the proof itself. If a paid order sits unproven, GET /orders/{id}/claim answers the proof as a transaction any wallet may send. The payout still goes only to the user. Prevent support cases: show the exact amount, ask for one payment, and show the time left from expiresAt.
Support script
For any order a user asks about.
- 01 Look up the order:
GET /status?txHash=, with any transaction of the order. - 02
completed: send thebtcTxIdlink. - 03
pendingorin_progressunder an hour: it is in flight. - 04
refundable: the user takes the coins back, as above. - 05 Anything else: send Maxy the order id, the hashes and the time.