Reference / HTTP API
API reference
The routes an integration uses, each with its parameters, a sample in curl, TypeScript and Python, and a real sandbox answer. The samples use BASE and MAXY_API_KEY from First order; KEY in the TypeScript and Python samples is the same key. Every route is listed on API routes, and all of them are in GET /openapi.json and the integration guide PDF.
POST /sandbox/keys
A test key and a test publishable key, with no sign-up. No key needed.
curl -s -X POST "$BASE/sandbox/keys" -H "content-type: application/json" \ -d '{ "name": "my project", "origins": ["http://localhost:3000"] }'
{ "secretKey": "mxk_test_fBFzTP…", "publishableKey": "mxk_pk_test_ZnoGp6…", "origins": [ "http://localhost:3000" ], "orderCapUsd": 100, "note": "Test keys: the sandbox only, nothing real moves. Shown once; Maxy keeps only a hash. Unused for 30 days, they are revoked." }
POST /sandbox/keys (HTTP 201): a real sandbox answer, 5 November 2026 (x-request-id ee2e78cb-478b-4d65-8f53-8dcb63f4c103).
Fields: secretKey, publishableKey, origins, orderCapUsd, note.
Errors: 400: invalid_input; 401: auth_required, invalid_api_key; 403: key_revoked; 422: amount_out_of_range, order_cap_exceeded, insufficient_funds, insufficient_liquidity, tx_reverted; 429: rate_limited. See error codes.
GET /key
Your key, its class and its order size cap. Needs your key.
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/key"
{ "key": "mxk_test_8GOVco…", "kind": "secret", "scopes": [ "read", "quote", "place", "orders", "webhooks", "account" ], "origins": [], "orderCapUsd": 100, "sandbox": true }
GET /key: a real sandbox answer, 13 November 2026 (x-request-id 104dbd34-c9fd-41e7-99ff-daa1f12c9c3b).
Fields: key, kind, scopes, origins, orderCapUsd.
Errors: none of its own beyond rate_limited. See error codes.
GET /limits
Your key's class and order size cap, the smallest order per route, how long a quote lasts, and your rate limits. Needs your key.
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/limits"
{ "kind": "secret", "scopes": [ "read", "quote", "place", "orders", "webhooks", "account" ], "origins": [], "orderCapUsd": 100, "minOrderSats": 546, "routes": { "evm-btc-escrow": { "minSats": 546 }, "evm-btc-gasless": { "minSats": 546 }, "btc-evm": { "minUsd": 10 }, "sol-btc": { "minUsd": 2 }, "btc-sol": { "minUsd": 2 } }, "quoteTtlSeconds": 60, "batchMax": 20, "rateLimit": { "limit": 120, "remaining": 118, "resetSeconds": 60, "per": "key", "priceLimit": 1200 }, "sandbox": true }
GET /limits: a real sandbox answer, 13 November 2026 (x-request-id 2a9d335f-ceff-43fc-9c3d-5b741f61a402).
Fields: kind, scopes, origins, orderCapUsd, minOrderSats, routes, quoteTtlSeconds, batchMax, rateLimit.
Errors: 400: invalid_input; 401: auth_required, invalid_api_key; 403: key_revoked; 422: amount_out_of_range, order_cap_exceeded, insufficient_funds, insufficient_liquidity, tx_reverted; 429: rate_limited. See error codes.
GET /pairs
Every pair, with its route, settler, smallest order and confirmations. Needs your key.
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/pairs"
{ "pairs": [ { "from": { "chain": 8453, "token": "0x0000000000000000000000000000000000000000", "symbol": "ETH", "decimals": 18, "chainName": "Base" }, "to": { "chain": "bitcoin", "token": "BTC", "symbol": "BTC", "decimals": 8, "chainName": "Bitcoin" }, "label": "ETH on Base → BTC", "fromAssetId": "eip155:8453/slip44:60", "toAssetId": "bip122:000000000019d6689c085ae165831e93/slip44:0", "route": "evm-btc-escrow", "settler": "0xeC5a05b28dd848F628e19CB26Df32f053e64ab86", "minSats": 546, "requiredConfirmations": 1, "confirmationsBySize": false }, { "from": { "chain": 8453, "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "symbol": "USDC", "decimals": 6, "chainName": "Base" }, "to": { "chain": "bitcoin", "token": "BTC", "symbol": "BTC", "decimals": 8, "chainName": "Bitcoin" }, "label": "USDC on Base → BTC", "fromAssetId": "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "toAssetId": "bip122:000000000019d6689c085ae165831e93/slip44:0", "route": "evm-btc-gasless", "settler": "0xeC5a05b28dd848F628e19CB26Df32f053e64ab86", "minSats": 546, "requiredConfirmations": 1, "confirmationsBySize": false }, "…" ], "sandbox": true }
GET /pairs: a real sandbox answer, 13 November 2026 (x-request-id 0a46da56-61c4-4911-8f16-de025ca1482c), with long fields folded.
Fields: pairs.
Errors: none of its own beyond rate_limited. See error codes.
GET /chains
Chains Maxy swaps on. Needs your key.
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/chains"
{ "chains": [ { "chain": "bitcoin", "name": "Bitcoin", "type": "bitcoin", "nativeSymbol": "BTC", "settler": null, "explorer": "https://mempool.space", "caip2": "bip122:000000000019d6689c085ae165831e93" }, { "chain": 8453, "name": "Base", "type": "evm", "nativeSymbol": "ETH", "settler": "0xeC5a05b28dd848F628e19CB26Df32f053e64ab86", "explorer": "https://basescan.org", "caip2": "eip155:8453" }, "…" ], "sandbox": true }
GET /chains: a real sandbox answer, 13 November 2026 (x-request-id a91d0dd7-3986-4030-b99b-522a86ea8d4a), with long fields folded.
Fields: chains.
Errors: none of its own beyond rate_limited. See error codes.
GET /tokens
Tokens per chain. Needs your key.
| Parameter | Required | Meaning |
|---|---|---|
chain | no | A chain name, id or CAIP-2 id: base, 8453, eip155:8453, bitcoin, bip122:000000000019d6689c085ae165831e93, solana, solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp. |
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/tokens?chain=base"
{ "tokens": [ { "chain": 8453, "chainName": "Base", "symbol": "ETH", "address": "0x0000000000000000000000000000000000000000", "decimals": 18, "assetId": "eip155:8453/slip44:60" }, { "chain": 8453, "chainName": "Base", "symbol": "USDC", "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "decimals": 6, "assetId": "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "…" ], "sandbox": true }
GET /tokens: a real sandbox answer, 13 November 2026 (x-request-id b31d8fb7-6c7f-452c-a327-52658715851f), with long fields folded.
Fields: tokens.
Errors: none of its own beyond rate_limited. See error codes.
GET /addresses/validate
Is an address valid for a chain, and would an order pay it. Needs your key.
| Parameter | Required | Meaning |
|---|---|---|
chain | yes | A chain name, id or CAIP-2 id: base, 8453, eip155:8453, bitcoin, bip122:000000000019d6689c085ae165831e93, solana, solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp. |
address | yes |
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/addresses/validate?chain=bitcoin&address=bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq"
{ "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq", "chain": "bitcoin", "valid": true, "type": "p2wpkh", "network": "mainnet", "payable": true, "reason": null, "sandbox": true }
GET /addresses/validate: a real sandbox answer, 13 November 2026 (x-request-id 21ef731c-42d2-446c-9ff7-28a25f97f02a).
Fields: address, chain, valid, type, network, payable, reason.
Errors: 400: invalid_input; 401: auth_required, invalid_api_key; 403: key_revoked; 422: amount_out_of_range, order_cap_exceeded, insufficient_funds, insufficient_liquidity, tx_reverted; 429: rate_limited. See error codes.
GET /price
Check prices: what an amount gets right now. No wallet. Needs your key.
| Parameter | Required | Meaning |
|---|---|---|
from | no | What you sell, in words: "ETH", "USDC on arbitrum", "BASE.ETH", "BTC", "SOL", "USDC on eip155:8453". Or use fromChain + fromToken. |
to | no | What you buy, in words. A CAIP-2 id alone is its chain's own coin (bip122:000000000019d6689c085ae165831e93 is BTC). Or use toChain + toToken. |
amount | no | How much you sell, in whole coins. Or use fromAmount. |
fromChain | no | Chain id, name or CAIP-2 id (8453, base, eip155:8453, bitcoin, solana). Alias: chainId. |
fromToken | no | Token address or symbol. Alias: sellToken. |
toChain | no | Chain id, name or CAIP-2 id; defaults to bitcoin when toToken is BTC. |
toToken | no | Token address or symbol. Alias: buyToken. |
fromAmount | no | How much you sell, in the smallest unit. Alias: sellAmount. |
scenario | no | Sandbox only: forces an outcome with a test key (GET /sandbox/scenarios lists them). A live key ignores it. |
simulate | no | Sandbox only: the same as scenario, also by other names: quote_expired, fill_timeout, underpaid, refund. |
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/price?from=USDC%20on%20base&to=BTC&amount=10"
{ "route": "evm-btc-gasless", "liquidityAvailable": true, "from": { "chain": 8453, "chainName": "Base", "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "symbol": "USDC", "decimals": 6, "caip2": "eip155:8453", "assetId": "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "to": { "chain": "bitcoin", "chainName": "Bitcoin", "token": "BTC", "symbol": "BTC", "decimals": 8, "caip2": "bip122:000000000019d6689c085ae165831e93", "assetId": "bip122:000000000019d6689c085ae165831e93/slip44:0" }, "fromAmount": "10000000", "toAmount": "13667", "toAmountMin": "13667", "formatted": { "send": "10.00 USDC on Base", "receive": "0.00013667 BTC", "pair": "USDC on Base → BTC" }, "expiresAt": 1794535530, "expiresAtIso": "2026-11-13T02:05:30.000Z", "limits": { "minSats": 546 }, "sandbox": true }
GET /price: a real sandbox answer, 13 November 2026 (x-request-id a4e23a42-1909-467e-acc7-5a24f4d66c99).
Fields: route, liquidityAvailable, from, to, fromAmount, toAmount, toAmountMin, formatted, limits, expiresAt, expiresAtIso, message.
Errors: 400: invalid_input; 401: auth_required, invalid_api_key; 403: key_revoked; 422: amount_out_of_range, order_cap_exceeded, insufficient_funds, insufficient_liquidity, tx_reverted; 429: rate_limited. See error codes.
GET /quote
The quote for an order about to be placed: id, expiry and the steps to execute it. Needs your key.
| Parameter | Required | Meaning |
|---|---|---|
from | no | What you sell, in words: "ETH", "USDC on arbitrum", "BASE.ETH", "BTC", "SOL", "USDC on eip155:8453". Or use fromChain + fromToken. |
to | no | What you buy, in words. A CAIP-2 id alone is its chain's own coin (bip122:000000000019d6689c085ae165831e93 is BTC). Or use toChain + toToken. |
amount | no | How much you sell, in whole coins. Or use fromAmount. |
fromChain | no | Chain id, name or CAIP-2 id (8453, base, eip155:8453, bitcoin, solana). Alias: chainId. |
fromToken | no | Token address or symbol. Alias: sellToken. |
toChain | no | Chain id, name or CAIP-2 id; defaults to bitcoin when toToken is BTC. |
toToken | no | Token address or symbol. Alias: buyToken. |
fromAmount | no | How much you sell, in the smallest unit. Alias: sellAmount. |
scenario | no | Sandbox only: forces an outcome with a test key (GET /sandbox/scenarios lists them). A live key ignores it. |
simulate | no | Sandbox only: the same as scenario, also by other names: quote_expired, fill_timeout, underpaid, refund. |
fromAddress | yes | The paying wallet. Alias: taker. |
toAddress | yes | Where the coins go (a bc1q… address when buying BTC). Alias: recipient. |
slippageBps | no | |
receive | no | Buying BTC: the BTC wanted, in whole BTC, instead of amount. |
toAmount | no | Buying BTC: the sats wanted, instead of amount. Alias: buyAmount. |
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/quote?from=ETH%20on%20base&to=BTC&amount=0.004&fromAddress=$WALLET&toAddress=$MY_BTC_ADDRESS"
{ "route": "evm-btc-escrow", "liquidityAvailable": true, "from": "…", "to": "…", "fromAmount": "4000000000000000", "toAmount": "10887", "toAmountMin": "10887", "formatted": { "send": "0.004 ETH on Base", "receive": "0.00010887 BTC", "pair": "ETH on Base → BTC" }, "expiresAt": 1794535550, "expiresAtIso": "2026-11-13T02:05:50.000Z", "limits": { "minSats": 546 }, "quoteId": "0x53414e44424f589aa64a8c0ee6e1cc6c96f4549a46f8dbcbaef270a82a2333c3", "order": { "route": "evm-btc-escrow", "orderId": "0x53414e44424f589aa64a8c0ee6e1cc6c96f4549a46f8dbcbaef270a82a2333c3", "chainId": 8453, "btcAddress": "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4", "intent": "…", "status": "/status?orderId=0x53414e44424f589aa64a8c0ee6e1cc6c96f4549a46f8dbcbaef270a82a2333c3&chainId=8453&route=evm-btc-escrow", "sandbox": "…", "quote": { "expiresAt": 1794535550, "id": "0x53414e44424f589aa64a8c0ee6e1cc6c96f4549a46f8dbcbaef270a82a2333c3", "token": "e2860bd87c250703d6079b481f847a2ae01f097e7fca558b97b51a7aced769a3", "ask": "from=ETH+on+base&to=BTC&amount=0.004&fromAddress=0xdd0d268Abc55f328F88f1Ee2e2f0850bFf43686b&toAddress=bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4" } }, "issues": { "balance": null, "allowance": null, "orderCap": null }, "steps": [ { "id": "intent", "kind": "signature", "description": "Sign the order (EIP-712). No gas. Sandbox: this signature authorizes nothing.", "signatureKind": "eip712", "typedData": { "domain": { "name": "Maxy Sandbox", "version": "1", "chainId": 8453, "verifyingContract": "0x0000000000000000000000000000000000000000" }, "types": "…", "primaryType": "MaxySandboxOrder", "message": { "orderId": "0x53414e44424f589aa64a8c0ee6e1cc6c96f4549a46f8dbcbaef270a82a2333c3", "step": "intent", "notice": "Maxy sandbox. This moves nothing and cannot be spent." } }, "hash": "0x25b9b9f55bfdf01ce7a847c7342f934e59e5c02d58ab9d8af87a17f1cba4773c" }, { "id": "order", "kind": "post", "description": "Send the order and its signature; you get back the transaction to send.", "method": "POST", "path": "/orders", "body": "…" }, { "id": "escrow", "kind": "transaction", "description": "Sandbox: do not send the transaction. POST /orders/submit with its simulatedHash.", "chainId": 8453, "transaction": null } ], "signing": { "kind": "eip712", "payloads": [ { "id": "intent", "typedData": { "domain": { "name": "Maxy Sandbox", "version": "1", "chainId": 8453, "verifyingContract": "0x0000000000000000000000000000000000000000" }, "types": { "MaxySandboxOrder": [ { "name": "orderId", "type": "string" }, { "name": "step", "type": "string" }, { "name": "notice", "type": "string" } ] }, "primaryType": "MaxySandboxOrder", "message": { "orderId": "0x53414e44424f589aa64a8c0ee6e1cc6c96f4549a46f8dbcbaef270a82a2333c3", "step": "intent", "notice": "Maxy sandbox. This moves nothing and cannot be spent." } }, "hash": "0x25b9b9f55bfdf01ce7a847c7342f934e59e5c02d58ab9d8af87a17f1cba4773c" } ], "approval": null, "after": { "method": "POST", "path": "/orders" } }, "sandbox": true }
GET /quote: a real sandbox answer, 13 November 2026 (x-request-id 6503b124-ab52-4f9b-a6dd-3bcac3d29a36), with long fields folded.
Fields: route, liquidityAvailable, from, to, fromAmount, toAmount, toAmountMin, formatted, limits, expiresAt, expiresAtIso, message, quoteId, order, issues, steps, signing.
Errors: 400: invalid_input; 401: auth_required, invalid_api_key; 403: key_revoked; 422: amount_out_of_range, order_cap_exceeded, insufficient_funds, insufficient_liquidity, tx_reverted; 429: rate_limited. See error codes.
POST /quotes/batch
Up to 20 prices or quotes in one call, with an answer or an error for each. Needs your key.
curl -s -X POST -H "x-maxy-key: $MAXY_API_KEY" "$BASE/quotes/batch" -H "content-type: application/json" \ -d '{ "requests": [{ "from": "ETH on base", "to": "BTC", "amount": "0.004" }] }'
{ "results": [ { "index": 0, "status": 200, "requestId": "0cf5d4fd-1d71-461e-ac64-9bbba4d323d8", "quote": "…" }, { "index": 1, "status": 200, "requestId": "ac3faae4-3d5c-42f1-9a43-12305c32c7df", "quote": "…" }, { "index": 2, "status": 400, "requestId": "73b1d8bf-c950-4f78-ab64-38397ffc7e85", "error": { "code": "invalid_input", "message": "PEPE is not a coin Maxy knows on Base (it knows ETH, USDC, USDT, WBTC, cbBTC, MORPHO, USDe). Pass its contract address instead.", "retryable": false, "docs": "https://maxy.co/docs/sdk-errors#invalid_input" } } ] }
POST /quotes/batch: a real sandbox answer, 13 November 2026 (x-request-id b2cf35b7-32eb-4af2-9a91-95355871ece8), with long fields folded.
Fields: results.
Errors: 400: invalid_input; 401: auth_required, invalid_api_key; 403: key_revoked; 422: amount_out_of_range, order_cap_exceeded, insufficient_funds, insufficient_liquidity, tx_reverted; 429: rate_limited. See error codes.
POST /prices/stream-ticket
A ticket for GET /prices/stream from a browser, for this pair. Needs your key.
| Parameter | Required | Meaning |
|---|---|---|
from | no | What you sell, in words: "ETH", "USDC on arbitrum", "BASE.ETH", "BTC", "SOL", "USDC on eip155:8453". Or use fromChain + fromToken. |
to | no | What you buy, in words. A CAIP-2 id alone is its chain's own coin (bip122:000000000019d6689c085ae165831e93 is BTC). Or use toChain + toToken. |
amount | no | How much you sell, in whole coins. Or use fromAmount. |
fromChain | no | Chain id, name or CAIP-2 id (8453, base, eip155:8453, bitcoin, solana). Alias: chainId. |
fromToken | no | Token address or symbol. Alias: sellToken. |
toChain | no | Chain id, name or CAIP-2 id; defaults to bitcoin when toToken is BTC. |
toToken | no | Token address or symbol. Alias: buyToken. |
fromAmount | no | How much you sell, in the smallest unit. Alias: sellAmount. |
scenario | no | Sandbox only: forces an outcome with a test key (GET /sandbox/scenarios lists them). A live key ignores it. |
simulate | no | Sandbox only: the same as scenario, also by other names: quote_expired, fill_timeout, underpaid, refund. |
curl -s -X POST -H "x-maxy-key: $MAXY_API_KEY" "$BASE/prices/stream-ticket?from=ETH%20on%20base&to=BTC"
{ "ticket": "mst1.eyJrIjoicCIsInQiOiJmcm9tPWV0aCBvbiBiYXNlJmZyb21DaGFpbj0mZnJvbVRva2VuPSZ0bz1idGMmdG9DaGFpbj0mdG9Ub2tlbj0iLCJhIjoiODcwNWU2NTMtMWUzMy00MDFhLWFlZTYtOTQ2MTc2YzNlMmU5IiwicyI6MSwiZSI6MTc5NDUzNjA5NH0.74dc0ab55da9eabcb8fbd84dc88315c698f333b6966aced465129a7d8f81d322", "expiresAt": 1794536094, "expiresAtIso": "2026-11-13T02:14:54.000Z", "stream": "https://whhxyutitykcsdpvdgcd.supabase.co/functions/v1/maxy-api/prices/stream?from=ETH+on+base&to=BTC&ticket=mst1.eyJrIjoicCIsInQiOiJmcm9tPWV0aCBvbiBiYXNlJmZyb21DaGFpbj0mZnJvbVRva2VuPSZ0bz1idGMmdG9DaGFpbj0mdG9Ub2tlbj0iLCJhIjoiODcwNWU2NTMtMWUzMy00MDFhLWFlZTYtOTQ2MTc2YzNlMmU5IiwicyI6MSwiZSI6MTc5NDUzNjA5NH0.74dc0ab55da9eabcb8fbd84dc88315c698f333b6966aced465129a7d8f81d322", "sandbox": true }
POST /prices/stream-ticket (HTTP 201): a real sandbox answer, 13 November 2026 (x-request-id 9b12e15b-b00e-4e5b-8cc2-68cc141f87d2).
Fields: ticket, expiresAt, expiresAtIso, stream.
Errors: 400: invalid_input; 401: auth_required, invalid_api_key; 403: key_revoked; 422: amount_out_of_range, order_cap_exceeded, insufficient_funds, insufficient_liquidity, tx_reverted; 429: rate_limited. See error codes.
POST /orders
Send the signed order. Needs your key.
curl -s -X POST -H "x-maxy-key: $MAXY_API_KEY" "$BASE/orders" -H "content-type: application/json" \ -d "$(jq -c --arg sig "$SIG" '{order: .order, signatures: {intent: $sig}}' quote.json)"
{ "orderId": "0x53414e44424f589aa64a8c0ee6e1cc6c96f4549a46f8dbcbaef270a82a2333c3", "route": "evm-btc-escrow", "expiresAt": 1794542691, "transaction": { "chainId": 8453, "from": "0xdd0d268Abc55f328F88f1Ee2e2f0850bFf43686b", "to": "0x0000000000000000000000000000000000000000", "data": "0x4d4158592053414e44424f583a204e4f542041205245414c205452414e53414354494f4e", "value": "0", "gas": "1", "simulatedHash": "0x53414e44424f587275400aa546ca2ac2b84bcc59cfd39e276e393980b96bdb13", "simulated": true, "sandbox": true, "notice": "Sandbox transaction: do not broadcast. It goes to the zero address, moves nothing and cannot do anything." }, "simulation": { "ok": true }, "next": { "method": "POST", "path": "/orders/submit", "body": { "order": "…", "signatures": "…", "txHash": "<transaction.simulatedHash>" } }, "expiresAtIso": "2026-11-13T04:04:51.000Z", "refundAt": 1794542691, "sandbox": true }
POST /orders: a real sandbox answer, 13 November 2026 (x-request-id e6836a36-5e96-48f0-a94d-36486fe8db98), with long fields folded.
Fields: orderId, route, submitted, expiresAt, expiresAtIso, refundAt, transaction, simulation, next, status, steps.
Errors: 400: invalid_input; 401: auth_required, invalid_api_key; 403: key_revoked; 409: quote_expired, quote_mismatch, conflict; 422: amount_out_of_range, order_cap_exceeded, insufficient_funds, insufficient_liquidity, tx_reverted; 429: rate_limited. See error codes.
POST /orders/submit
Tell Maxy the escrow or bridge transaction is sent (the solver also watches the chain). Needs your key.
curl -s -X POST -H "x-maxy-key: $MAXY_API_KEY" "$BASE/orders/submit" -H "content-type: application/json" \ -d "$(jq -c --arg sig "$SIG" --arg h "$TX_HASH" '{order: .order, signatures: {intent: $sig}, txHash: $h}' quote.json)"
{ "orderId": "0x53414e44424f589aa64a8c0ee6e1cc6c96f4549a46f8dbcbaef270a82a2333c3", "route": "evm-btc-escrow", "notified": true, "status": "/status?orderId=0x53414e44424f589aa64a8c0ee6e1cc6c96f4549a46f8dbcbaef270a82a2333c3&chainId=8453&route=evm-btc-escrow", "sandbox": true }
POST /orders/submit: a real sandbox answer, 13 November 2026 (x-request-id 2e7f1e4c-d9f9-4350-9ad5-13c93f7acf8a).
Fields: orderId, route, notified, onChain, status.
Errors: 400: invalid_input; 401: auth_required, invalid_api_key; 403: key_revoked; 422: amount_out_of_range, order_cap_exceeded, insufficient_funds, insufficient_liquidity, tx_reverted; 429: rate_limited. See error codes.
GET /status
Where an order is. Needs your key.
| Parameter | Required | Meaning |
|---|---|---|
orderId | no | The order id; or give txHash. |
txHash | no | Any transaction of the order: the escrow or settlement transaction, or the Bitcoin payment. |
chainId | no | |
route | no | |
toChainId | no | cross-evm only. |
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/status?orderId=$ORDER_ID&chainId=8453"
{ "orderId": "0x53414e44424f589aa64a8c0ee6e1cc6c96f4549a46f8dbcbaef270a82a2333c3", "route": "evm-btc-escrow", "state": "completed", "rawStatus": "SANDBOX_COMPLETED", "isComplete": true, "btcTxId": "53414e44424f58180157a60e949ed223ebb533d0b5e3062f5b8138765c962bb9", "txs": [ { "label": "escrow", "hash": "0x53414e44424f587275400aa546ca2ac2b84bcc59cfd39e276e393980b96bdb13" }, { "label": "btc_payout", "hash": "53414e44424f58180157a60e949ed223ebb533d0b5e3062f5b8138765c962bb9" } ], "failureReason": null, "sandbox": true, "scenario": "success" }
GET /status: a real sandbox answer, 13 November 2026 (x-request-id e828f87c-73d8-4eee-8ff3-ea5539d44411).
Fields: orderId, route, state, rawStatus, isComplete, btcTxId, txs, refundAt, refundAtIso, refundAfterBlock, externalId, externalCustomerId, failureReason, scenario.
Errors: 400: invalid_input; 401: auth_required, invalid_api_key; 403: key_revoked; 422: amount_out_of_range, order_cap_exceeded, insufficient_funds, insufficient_liquidity, tx_reverted; 429: rate_limited. See error codes.
GET /orders/{id}
Where an order is (the same object as /status). Needs your key.
| Parameter | Required | Meaning |
|---|---|---|
chainId | no | |
route | no |
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/orders/$ORDER_ID"
{ "orderId": "0x53414e44424f589aa64a8c0ee6e1cc6c96f4549a46f8dbcbaef270a82a2333c3", "route": "evm-btc-escrow", "state": "completed", "rawStatus": "SANDBOX_COMPLETED", "isComplete": true, "btcTxId": "53414e44424f58180157a60e949ed223ebb533d0b5e3062f5b8138765c962bb9", "txs": [ { "label": "escrow", "hash": "0x53414e44424f587275400aa546ca2ac2b84bcc59cfd39e276e393980b96bdb13" }, { "label": "btc_payout", "hash": "53414e44424f58180157a60e949ed223ebb533d0b5e3062f5b8138765c962bb9" } ], "failureReason": null, "sandbox": true, "scenario": "success", "externalId": null, "externalCustomerId": null }
GET /orders/{id}: a real sandbox answer, 13 November 2026 (x-request-id 93bd9560-1299-4260-bc3b-351e9c871a10).
Fields: orderId, route, state, rawStatus, isComplete, btcTxId, txs, refundAt, refundAtIso, refundAfterBlock, externalId, externalCustomerId, failureReason, scenario.
Errors: 400: invalid_input; 401: auth_required, invalid_api_key; 403: key_revoked; 422: amount_out_of_range, order_cap_exceeded, insufficient_funds, insufficient_liquidity, tx_reverted; 429: rate_limited. See error codes.
GET /orders/{id}/events
The order's states so far, with times. Needs your key.
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/orders/$ORDER_ID/events"
{ "orderId": "0x53414e44424f5823936eadc65c68429f1fc465d671b4382365c5ff83ffbf13ae", "events": [ { "state": "pending", "previousState": null, "rawStatus": "SANDBOX_PENDING", "btcTxId": null, "txs": [], "at": "2026-11-13T02:09:03.000Z" }, { "state": "in_progress", "previousState": "pending", "rawStatus": "SANDBOX_FILLING", "btcTxId": null, "txs": [], "at": "2026-11-13T02:08:54.000Z" }, { "state": "completed", "previousState": "in_progress", "rawStatus": "SANDBOX_COMPLETED", "btcTxId": "53414e44424f584ae8dec8623d0c26e0d71d5d285965afaaa487298533b1cdf7", "txs": [ { "label": "btc_payout", "hash": "53414e44424f584ae8dec8623d0c26e0d71d5d285965afaaa487298533b1cdf7" } ], "at": "2026-11-13T02:09:06.000Z" } ], "nextCursor": null, "sandbox": true }
GET /orders/{id}/events: a real sandbox answer, 13 November 2026 (x-request-id 38d7829b-fba3-4d13-9e17-26e684d7594d).
Fields: orderId, events, nextCursor.
Errors: 400: invalid_input; 401: auth_required, invalid_api_key; 403: key_revoked; 422: amount_out_of_range, order_cap_exceeded, insufficient_funds, insufficient_liquidity, tx_reverted; 429: rate_limited. See error codes.
POST /orders/{id}/stream-ticket
A ticket for GET /orders/{id}/events/stream from a browser, for this order. Needs your key.
| Parameter | Required | Meaning |
|---|---|---|
chainId | no | |
route | no |
curl -s -X POST -H "x-maxy-key: $MAXY_API_KEY" "$BASE/orders/$ORDER_ID/stream-ticket?chainId=8453"
{ "ticket": "mst1.eyJrIjoibyIsInQiOiIweDUzNDE0ZTQ0NDI0ZjU4OWFhNjRhOGMwZWU2ZTFjYzZjOTZmNDU0OWE0NmY4ZGJjYmFlZjI3MGE4MmEyMzMzYzMiLCJhIjoiODcwNWU2NTMtMWUzMy00MDFhLWFlZTYtOTQ2MTc2YzNlMmU5IiwicyI6MSwiZSI6MTc5NDUzNjA5NH0.1b4bd2441c864515bf147e47a09dc6da896f4b78437a70d85ff42d42c64d52fc", "expiresAt": 1794536094, "expiresAtIso": "2026-11-13T02:14:54.000Z", "stream": "https://whhxyutitykcsdpvdgcd.supabase.co/functions/v1/maxy-api/orders/0x53414e44424f589aa64a8c0ee6e1cc6c96f4549a46f8dbcbaef270a82a2333c3/events/stream?chainId=8453&ticket=mst1.eyJrIjoibyIsInQiOiIweDUzNDE0ZTQ0NDI0ZjU4OWFhNjRhOGMwZWU2ZTFjYzZjOTZmNDU0OWE0NmY4ZGJjYmFlZjI3MGE4MmEyMzMzYzMiLCJhIjoiODcwNWU2NTMtMWUzMy00MDFhLWFlZTYtOTQ2MTc2YzNlMmU5IiwicyI6MSwiZSI6MTc5NDUzNjA5NH0.1b4bd2441c864515bf147e47a09dc6da896f4b78437a70d85ff42d42c64d52fc", "sandbox": true }
POST /orders/{id}/stream-ticket (HTTP 201): a real sandbox answer, 13 November 2026 (x-request-id b7e4e48b-4d58-4258-b02e-1c4a24b02995).
Fields: ticket, expiresAt, expiresAtIso, stream.
Errors: 400: invalid_input; 401: auth_required, invalid_api_key; 403: key_revoked; 422: amount_out_of_range, order_cap_exceeded, insufficient_funds, insufficient_liquidity, tx_reverted; 429: rate_limited. See error codes.
GET /orders
Your orders, newest first: placed through this API or the SDK with your key, or followed with /orders/watch. Needs your key.
| Parameter | Required | Meaning |
|---|---|---|
from | no | |
to | no | |
format | no | |
limit | no | A page, newest first. A CSV export takes up to 1,000. |
cursor | no | nextCursor of the page before. |
state | no | |
wallet | no | The paying wallet. |
externalId | no | |
externalCustomerId | no |
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/orders?from=2026-11-01&to=2026-12-01"
{ "orders": [ { "orderId": "0x53414e44424f58bd874a9c3b8b3e2b671f7f15d92a42a9c9c34bd5d8079ca56b", "route": "evm-btc-gasless", "chainId": 8453, "state": "completed", "btcTxId": "53414e44424f58ce5c8ed9d6d714d8b1008a4797d5744581ac6f2d6193f13dfc", "createdAt": "2026-11-13T02:08:08.725062+00:00", "doneAt": "2026-11-13T02:09:01.000Z", "externalId": null, "externalCustomerId": null, "wallet": "0x174EeB02AC30add92d28f86401E5141cf3f9e480" }, { "orderId": "0x53414e44424f5861c0d4304e38a2ea470fa92d4b3e57d4190e3d938018b72480", "route": "cross-evm", "chainId": 8453, "state": "completed", "btcTxId": null, "createdAt": "2026-11-13T02:08:03.886737+00:00", "doneAt": "2026-11-13T02:09:01.000Z", "externalId": null, "externalCustomerId": null, "wallet": "0x9b37eeb80632945471951d20610C45355Cdba69e" }, "…" ], "nextCursor": null, "sandbox": true }
GET /orders: a real sandbox answer, 13 November 2026 (x-request-id 31abf078-0414-42ac-9ba3-a91ca2d80f13), with long fields folded.
Fields: orders, nextCursor.
Errors: 400: invalid_input; 401: auth_required, invalid_api_key; 403: key_revoked; 422: amount_out_of_range, order_cap_exceeded, insufficient_funds, insufficient_liquidity, tx_reverted; 429: rate_limited. See error codes.
POST /orders/{id}/cancel
The transaction that takes back an escrow no solver committed to. Needs your key.
| Parameter | Required | Meaning |
|---|---|---|
chainId | yes | |
from | no | The wallet that will send it; defaults to the escrow's maker. |
curl -s -X POST -H "x-maxy-key: $MAXY_API_KEY" "$BASE/orders/$ORDER_ID/cancel?chainId=8453"
{ "orderId": "0x53414e44424f58d83c861d140370c484eb094547ddc05b8e7ac093b585326213", "state": "pending", "cancellable": true, "function": "cancelBuyEscrow", "allowedStates": [ "pending" ], "explanation": "Takes back the escrow: no solver has committed yet. Sandbox: nothing to send; the order now reads cancelled.", "transaction": "…", "sandbox": true }
POST /orders/{id}/cancel: a real sandbox answer, 13 November 2026 (x-request-id 3b4d6287-ca5d-4059-a2cc-e952d9efaf20), with long fields folded.
Fields: orderId, cancellable, function, explanation, reason, transaction, simulation, state, allowedStates.
Errors: 400: invalid_input; 401: auth_required, invalid_api_key; 403: key_revoked; 409: quote_expired, quote_mismatch, conflict; 422: amount_out_of_range, order_cap_exceeded, insufficient_funds, insufficient_liquidity, tx_reverted; 429: rate_limited. See error codes.
GET /orders/{id}/refund
The transaction that takes an expired escrow back to the user. Needs your key.
| Parameter | Required | Meaning |
|---|---|---|
chainId | yes | |
from | no | Simulate from this sender. Default: the paying wallet. |
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/orders/$ORDER_ID/refund?chainId=8453"
{ "orderId": "0x53414e44424f58ec837ff3f2e3b5ff0db94324f8ff30f5e2d799de1f997273cd", "refundable": true, "function": "cancelBuyEscrow", "explanation": "No solver committed before the escrow deadline: the escrow goes back to the user. Sandbox: nothing to send; the order reads refunded shortly.", "transaction": { "chainId": 8453, "from": "0x30A7cba29a6f3C34c812fc64586f61A5872251A4", "to": "0x0000000000000000000000000000000000000000", "data": "0x4d4158592053414e44424f583a204e4f542041205245414c205452414e53414354494f4e", "value": "0", "gas": "1", "simulatedHash": "0x53414e44424f58ab2ab7c49ce88c7bddd2bb3fc3d3900a32641cf1bd7a1372be", "simulated": true, "sandbox": true, "notice": "Sandbox transaction: do not broadcast. It goes to the zero address, moves nothing and cannot do anything." }, "simulation": { "ok": true }, "sandbox": true }
GET /orders/{id}/refund: a real sandbox answer, 13 November 2026 (x-request-id a84971e0-80f7-4991-8f4d-01d03dcf56d9).
Fields: orderId, refundable, function, explanation, reason, unlocksAt, transaction, simulation.
Errors: 400: invalid_input; 401: auth_required, invalid_api_key; 403: key_revoked; 422: amount_out_of_range, order_cap_exceeded, insufficient_funds, insufficient_liquidity, tx_reverted; 429: rate_limited. See error codes.
GET /orders/{id}/deposit
Selling BTC: where and how much to pay, read from the settler. Needs your key.
| Parameter | Required | Meaning |
|---|---|---|
chainId | yes | |
maker | no | |
token | no | |
sats | no | |
minPayout | no | |
lockBy | no |
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/orders/$ORDER_ID/deposit?chainId=8453&sats=50000"
{ "orderId": "0x53414e44424f58ce8483f271a52bb64d58d6c8b34209d34c0733d5d2556ef926", "route": "btc-evm", "chainId": 8453, "settler": "0x0000000000000000000000000000000000000000", "state": "COMMITTED", "ready": true, "address": "tb1qwrdwhtmx7snnesh4k9vt82ggn9xmyg8zwetx06", "sats": 50000, "amountBtc": "0.0005", "bitcoinUri": "bitcoin:tb1qwrdwhtmx7snnesh4k9vt82ggn9xmyg8zwetx06?amount=0.0005", "scriptPubKey": "0x001470daebaf66f4273cc2f5b158b3a908994db220e2", "payout": { "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "35320482", "to": "0x11B172F50AaD19f0372c3de1d2850cA1Cd180064" }, "expiresAt": 1794539231, "btcDeadline": 0, "blocksLeft": 6, "verifierHeight": 0, "requiredConfirmations": 1, "intentHash": "0x53414e44424f58ce8483f271a52bb64d58d6c8b34209d34c0733d5d2556ef926", "checked": "order", "simulated": true, "instructions": "Sandbox: do not pay. This is a testnet address, and the order moves on by itself.", "verify": "…", "claim": "/orders/0x53414e44424f58ce8483f271a52bb64d58d6c8b34209d34c0733d5d2556ef926/claim?chainId=8453", "status": "/status?orderId=0x53414e44424f58ce8483f271a52bb64d58d6c8b34209d34c0733d5d2556ef926&chainId=8453&route=btc-evm", "sandbox": true }
GET /orders/{id}/deposit: a real sandbox answer, 13 November 2026 (x-request-id 58d489ce-b64a-4f0c-9220-6e350066ada1), with long fields folded.
Fields: orderId, route, chainId, settler, state, ready, reason, address, satAmount, amountBtc, bitcoinUri, btcDeadline, retryAfterSeconds, lockBy, sats, scriptPubKey, payout, expiresAt, blocksLeft, verifierHeight, requiredConfirmations, intentHash, checked, simulated, instructions, verify, claim, status.
Errors: 400: invalid_input; 401: auth_required, invalid_api_key; 403: key_revoked; 409: quote_expired, quote_mismatch, conflict; 422: amount_out_of_range, order_cap_exceeded, insufficient_funds, insufficient_liquidity, tx_reverted; 429: rate_limited. See error codes.
GET /orders/{id}/claim
Selling BTC: the transaction that proves the payment and releases the payout to the user. Needs your key.
| Parameter | Required | Meaning |
|---|---|---|
chainId | yes | |
btcTxid | no | |
from | no | Simulate from this sender. Default: the wallet being paid. |
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/orders/$ORDER_ID/claim?chainId=8453"
{ "orderId": "0x53414e44424f58ce8483f271a52bb64d58d6c8b34209d34c0733d5d2556ef926", "route": "btc-evm", "chainId": 8453, "claimable": true, "function": "fillIntentWithFeeToken", "explanation": "Proves the BTC payment to the settler, which releases the payout to the maker. Sandbox: nothing to send; the order completes by itself.", "btcTxid": "53414e44424f58f9ac0e49ea608e743552bca7a46625f415623b2b7c2144d436", "btcBlockHeight": 0, "payout": { "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "35320482", "to": "0x11B172F50AaD19f0372c3de1d2850cA1Cd180064" }, "transaction": { "chainId": 8453, "from": "0x11B172F50AaD19f0372c3de1d2850cA1Cd180064", "to": "0x0000000000000000000000000000000000000000", "data": "0x4d4158592053414e44424f583a204e4f542041205245414c205452414e53414354494f4e", "value": "0", "gas": "1", "simulatedHash": "0x53414e44424f58282aa26e0d84fb2cf2505b5e6edeafa1f43680b552e1e2ed45", "simulated": true, "sandbox": true, "notice": "Sandbox transaction: do not broadcast. It goes to the zero address, moves nothing and cannot do anything." }, "simulation": { "ok": true }, "sandbox": true }
GET /orders/{id}/claim: a real sandbox answer, 13 November 2026 (x-request-id a7477538-3026-40e7-a475-3f633477e530).
Fields: orderId, claimable, reason, transaction, retryAfterSeconds, route, chainId, function, explanation, btcTxid, btcBlockHeight, payout, simulation.
Errors: 400: invalid_input; 401: auth_required, invalid_api_key; 403: key_revoked; 422: amount_out_of_range, order_cap_exceeded, insufficient_funds, insufficient_liquidity, tx_reverted; 429: rate_limited. See error codes.
POST /webhooks
Register an HTTPS endpoint for signed order.updated events. Needs your key.
curl -s -X POST -H "x-maxy-key: $MAXY_API_KEY" "$BASE/webhooks" -H "content-type: application/json" \ -d '{ "url": "https://your.app/maxy/webhooks" }'
{ "id": "7d320755-9eac-435b-9b4b-d8151856cdde", "url": "https://postman-echo.com/post", "events": [ "order.updated" ], "secret": "whsec_… (shown once: store it)", "createdAt": "2026-11-13T02:08:05.553716+00:00", "sandbox": true }
POST /webhooks (HTTP 201): a real sandbox answer, 13 November 2026 (x-request-id c93801d0-4315-40ac-8f99-cac312d79550).
Fields: id, url, secret, events, createdAt.
Errors: 400: invalid_input; 401: auth_required, invalid_api_key; 403: key_revoked; 409: quote_expired, quote_mismatch, conflict; 422: amount_out_of_range, order_cap_exceeded, insufficient_funds, insufficient_liquidity, tx_reverted; 429: rate_limited. See error codes.
POST /webhooks/{id}/test
Send a signed webhook.test event now. Needs your key.
curl -s -X POST -H "x-maxy-key: $MAXY_API_KEY" "$BASE/webhooks/$WEBHOOK_ID/test"
{ "eventId": "evt_04417bf111cda494f5b148a3", "delivered": true, "status": 200, "error": null, "sandbox": true }
POST /webhooks/{id}/test: a real sandbox answer, 13 November 2026 (x-request-id 7e45d64f-46cc-4eaf-b4a9-d07f7c5d371b).
Fields: delivered, status, eventId, error.
Errors: none of its own beyond rate_limited. See error codes.
POST /sandbox/orders/{id}/advance
Test keys only: move a sandbox order to its next state now, or to the state you name. Needs your key.
curl -s -X POST -H "x-maxy-key: $MAXY_API_KEY" "$BASE/sandbox/orders/$ORDER_ID/advance" -H "content-type: application/json" \ -d '{ "to": "completed" }'
{ "orderId": "0x53414e44424f5823936eadc65c68429f1fc465d671b4382365c5ff83ffbf13ae", "route": "evm-btc-escrow", "state": "completed", "rawStatus": "SANDBOX_COMPLETED", "isComplete": true, "btcTxId": "53414e44424f584ae8dec8623d0c26e0d71d5d285965afaaa487298533b1cdf7", "txs": [ { "label": "btc_payout", "hash": "53414e44424f584ae8dec8623d0c26e0d71d5d285965afaaa487298533b1cdf7" } ], "failureReason": null, "sandbox": true, "scenario": "success", "advanced": true }
POST /sandbox/orders/{id}/advance: a real sandbox answer, 13 November 2026 (x-request-id 172f8ed3-4ac3-4e7f-a061-e290c75044a6).
Fields: orderId, route, state, rawStatus, isComplete, btcTxId, txs, refundAt, refundAtIso, refundAfterBlock, externalId, externalCustomerId, failureReason, scenario, advanced.
Errors: 400: invalid_input; 401: auth_required, invalid_api_key; 403: key_revoked; 409: quote_expired, quote_mismatch, conflict; 422: amount_out_of_range, order_cap_exceeded, insufficient_funds, insufficient_liquidity, tx_reverted; 429: rate_limited. See error codes.
GET /health
The solver, Bitcoin and each chain's verifier, with a degraded flag. No key needed.
curl -s "$BASE/health"
{ "status": "ok", "degraded": false, "checkedAt": "2026-11-13T02:04:27.415Z", "components": { "api": { "status": "ok" }, "quotes": { "status": "ok", "latencyMs": 158 }, "solver": { "status": "ok", "latencyMs": 158, "priceAgeSeconds": 8 }, "bitcoin": { "status": "ok", "tipHeight": 975617 }, "verifiers": [ { "chainId": 8453, "chain": "Base", "status": "ok", "height": 975617, "lagBlocks": 0 }, { "chainId": 56, "chain": "BNB Chain", "status": "ok", "height": 975617, "lagBlocks": 0 }, { "chainId": 42161, "chain": "Arbitrum", "status": "ok", "height": 975617, "lagBlocks": 0 }, { "chainId": 43114, "chain": "Avalanche", "status": "ok", "height": 975617, "lagBlocks": 0 }, { "chainId": 4663, "chain": "Robinhood", "status": "ok", "height": 975617, "lagBlocks": 0 } ] } }
GET /health: a real sandbox answer, 13 November 2026 (x-request-id f37adee8-d4df-48d6-a6e2-2023eeecac80).
Fields: status, degraded, checkedAt, components.
Errors: none of its own beyond rate_limited. See error codes.