Find something... ⌘K

Swaps / Routes

Buy BTC

The whole buy with raw calls, from a price to the BTC arriving. Run these samples in order, in one shell or one file, and with a test key they run as they are.

Get a price

Ask while the user types. It needs your key but no wallet, and it reserves nothing.

curlTypeScriptPython
Copy
export BASE=https://whhxyutitykcsdpvdgcd.supabase.co/functions/v1/maxy-api curl -s "$BASE/price?from=USDC%20on%20base&to=BTC&amount=10"

amount is in whole coins; fromAmount takes the smallest unit. Name a coin as USDC on base, ETH on arbitrum, BNB, AVAX or SOL. Every amount in the answer is a string in the smallest unit, and formatted has the same amounts in words. The same question within 3 seconds is one read, so refresh as often as you like.

Get a quote

Ask when the user moves to confirm. A quote names who pays and who receives, needs your key, and holds for 60 seconds. This sample sets up the wallet the next steps use. Put your test key in place of mxk_test_…. Live, the wallet and the address are your user's.

curlTypeScriptPython
Copy
export MAXY_API_KEY=mxk_test_… export TEST_WALLET_KEY=$(cast wallet new --json | jq -r '.[0].private_key') # a throwaway wallet export WALLET=$(cast wallet address --private-key "$TEST_WALLET_KEY") export MY_BTC_ADDRESS=bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4 # where the BTC goes curl -s -G "$BASE/quote" -H "x-maxy-key: $MAXY_API_KEY" \ --data-urlencode "from=ETH on base" --data-urlencode "to=BTC" --data-urlencode "amount=0.004" \ --data-urlencode "fromAddress=$WALLET" --data-urlencode "toAddress=$MY_BTC_ADDRESS" > quote.json jq '{quoteId, toAmount, issues, steps: [.steps[]?.id]}' quote.json
  • quoteId becomes the order id.
  • toAmount is what arrives. It is executable, with every cost in. To ask for an exact BTC amount, send receive=0.0001 in place of amount.
  • steps is what the wallet does, in order. signing is the same in one shape on every route.
  • issues says what is short: balance, allowance, or orderCap.

Check the Bitcoin address first: GET /addresses/validate?chain=bitcoin&address=… answers payable and a reason. EVM buys pay native SegWit (bc1q…) only. Solana buys can also pay Taproot (bc1p…) live, though this check reads payable: false for it.

Always show the amounts and keep the button live. If a quote carries issues.orderCap or liquidityAvailable: false, show the refusal when the user clicks, and offer a smaller amount.

Sign

The wallet signs what the quote's steps ask for. Each signature step carries the typed data exactly as the wallet shows it, and its hash. Check the hash, then ask the wallet to sign. It costs no gas.

curlTypeScriptPython
Copy
INTENT_SIG=$(cast wallet sign --private-key "$TEST_WALLET_KEY" --data "$(jq -c '.steps[] | select(.id == "intent") | .typedData' quote.json)")

The signature binds the paying wallet, the coin, the sats, the price and its band, the solver's bond, the Bitcoin script that must receive the BTC, and the deadline. ETH, BNB and AVAX need no allowance: the escrow transaction carries the value. If the wallet declines (4001), nothing was signed: go back to the confirm screen.

Place the order

Send the quote's order unchanged, with the signatures keyed by step id. Then the wallet sends the escrow transaction, and you tell Maxy its hash so the solver starts at once. A sandbox transaction is never sent: its simulatedHash stands in for the hash, as below.

curlTypeScriptPython
Copy
curl -s -X POST "$BASE/orders" -H "x-maxy-key: $MAXY_API_KEY" -H "content-type: application/json" \ -d "$(jq -c --arg sig "$INTENT_SIG" '{order: .order, signatures: {intent: $sig}}' quote.json)" > placed.json jq '{orderId, simulation}' placed.json TX_HASH=$(jq -r .transaction.simulatedHash placed.json) # live: send .transaction from the wallet, use its hash curl -s -X POST "$BASE/orders/submit" -H "x-maxy-key: $MAXY_API_KEY" -H "content-type: application/json" \ -d "$(jq -c --arg tx "$TX_HASH" '.next.body + {txHash: $tx}' placed.json)"

If simulation.ok is false, do not send the transaction. USDC orders answer submitted: true and send nothing: see Pay with USDC. Retries are safe: the same signed order returns the same orderId. A solver fills only at the price the user signed, within 2 hours of signing. To tag an order for your records, add externalId to the body.

CodeHTTPCauseFix
quote_expired409Over 60 seconds since the quoteNew quote, sign again
wallet_mismatch400The signature is from another walletSign with the paying wallet
order_cap_exceeded422Above your key's capOrder less
insufficient_liquidity422Maxy cannot fill this size nowLess, or later

Track the order

Show the user where the order is. Poll every 2 seconds while they watch, and use webhooks for your records. No key is needed.

curlTypeScriptPython
Copy
ORDER_ID=$(jq -r .orderId placed.json) while :; do STATUS=$(curl -s "$BASE/status?orderId=$ORDER_ID&chainId=8453") echo "$STATUS" | jq -c '{state, btcTxId}' [ "$(echo "$STATUS" | jq -r '.isComplete or .state == "refundable"')" = true ] && break sleep 2 done

pending lasts one block, until the solver commits. in_progress lasts seconds, while the solver pays. completed means btcTxId is set: link it on any Bitcoin explorer. The user's wallet shows the BTC after its first confirmation, about 10 minutes. A receipt shows what was paid, what arrived, the receiving address, btcTxId, the escrow transaction and orderId.

GET /orders/{id}/events/stream sends the same changes as a stream. If the order reads refundable, go to When it fails. A brand-new order id reads pending, never 404.