# 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](https://maxy.co/docs/first-order); `KEY` in the TypeScript and Python samples is the same key. Every route is listed on [API routes](https://maxy.co/docs/api-routes), and all of them are in `GET /openapi.json` and the [integration guide PDF](https://maxy.co/guides/maxy-integration-guide.pdf).

## POST /sandbox/keys

A test key and a test publishable key, with no sign-up. No key needed.

```sh
curl -s -X POST "$BASE/sandbox/keys" -H "content-type: application/json" \
  -d '{ "name": "my project", "origins": ["http://localhost:3000"] }'
```

```ts
const res = await fetch(`${BASE}/sandbox/keys`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ name: 'my project', origins: ['http://localhost:3000'] }) });
const answer = await res.json();
```

```python
answer = requests.post(f"{BASE}/sandbox/keys", json={"name": "my project", "origins": ["http://localhost:3000"]}).json()
```

```json
{
  "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.

```sh
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/key"
```

```ts
const res = await fetch(`${BASE}/key`, { headers: { 'x-maxy-key': KEY } });
const answer = await res.json();
```

```python
answer = requests.get(f"{BASE}/key", headers={"x-maxy-key": KEY}).json()
```

```json
{
  "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.

```sh
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/limits"
```

```ts
const res = await fetch(`${BASE}/limits`, { headers: { 'x-maxy-key': KEY } });
const answer = await res.json();
```

```python
answer = requests.get(f"{BASE}/limits", headers={"x-maxy-key": KEY}).json()
```

```json
{
  "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.

```sh
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/pairs"
```

```ts
const res = await fetch(`${BASE}/pairs`, { headers: { 'x-maxy-key': KEY } });
const answer = await res.json();
```

```python
answer = requests.get(f"{BASE}/pairs", headers={"x-maxy-key": KEY}).json()
```

```json
{
  "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.

```sh
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/chains"
```

```ts
const res = await fetch(`${BASE}/chains`, { headers: { 'x-maxy-key': KEY } });
const answer = await res.json();
```

```python
answer = requests.get(f"{BASE}/chains", headers={"x-maxy-key": KEY}).json()
```

```json
{
  "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. |

```sh
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/tokens?chain=base"
```

```ts
const res = await fetch(`${BASE}/tokens?${new URLSearchParams({ chain: 'base' })}`, { headers: { 'x-maxy-key': KEY } });
const answer = await res.json();
```

```python
answer = requests.get(f"{BASE}/tokens", headers={"x-maxy-key": KEY}, params={"chain": "base"}).json()
```

```json
{
  "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 |  |

```sh
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/addresses/validate?chain=bitcoin&address=bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq"
```

```ts
const res = await fetch(`${BASE}/addresses/validate?${new URLSearchParams({ chain: 'bitcoin', address: 'bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq' })}`, { headers: { 'x-maxy-key': KEY } });
const answer = await res.json();
```

```python
answer = requests.get(f"{BASE}/addresses/validate", headers={"x-maxy-key": KEY}, params={"chain": "bitcoin", "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq"}).json()
```

```json
{
  "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. |

```sh
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/price?from=USDC%20on%20base&to=BTC&amount=10"
```

```ts
const res = await fetch(`${BASE}/price?${new URLSearchParams({ from: 'USDC on base', to: 'BTC', amount: '10' })}`, { headers: { 'x-maxy-key': KEY } });
const answer = await res.json();
```

```python
answer = requests.get(f"{BASE}/price", headers={"x-maxy-key": KEY}, params={"from": "USDC on base", "to": "BTC", "amount": "10"}).json()
```

```json
{
  "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. |

```sh
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"
```

```ts
const res = await fetch(`${BASE}/quote?${new URLSearchParams({ from: 'ETH on base', to: 'BTC', amount: '0.004', fromAddress: account.address, toAddress: btcAddress })}`, { headers: { 'x-maxy-key': KEY } });
const answer = await res.json();
```

```python
answer = requests.get(f"{BASE}/quote", headers={"x-maxy-key": KEY}, params={"from": "ETH on base", "to": "BTC", "amount": "0.004", "fromAddress": account.address, "toAddress": btc_address}).json()
```

```json
{
  "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.

```sh
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" }] }'
```

```ts
const res = await fetch(`${BASE}/quotes/batch`, { method: 'POST', headers: { 'x-maxy-key': KEY, 'content-type': 'application/json' }, body: JSON.stringify({ requests: [{ from: 'ETH on base', to: 'BTC', amount: '0.004' }] }) });
const answer = await res.json();
```

```python
answer = requests.post(f"{BASE}/quotes/batch", headers={"x-maxy-key": KEY}, json={"requests": [{"from": "ETH on base", "to": "BTC", "amount": "0.004"}]}).json()
```

```json
{
  "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. |

```sh
curl -s -X POST -H "x-maxy-key: $MAXY_API_KEY" "$BASE/prices/stream-ticket?from=ETH%20on%20base&to=BTC"
```

```ts
const res = await fetch(`${BASE}/prices/stream-ticket?${new URLSearchParams({ from: 'ETH on base', to: 'BTC' })}`, { method: 'POST', headers: { 'x-maxy-key': KEY } });
const answer = await res.json();
```

```python
answer = requests.post(f"{BASE}/prices/stream-ticket", headers={"x-maxy-key": KEY}, params={"from": "ETH on base", "to": "BTC"}).json()
```

```json
{
  "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.

```sh
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)"
```

```ts
const res = await fetch(`${BASE}/orders`, { method: 'POST', headers: { 'x-maxy-key': KEY, 'content-type': 'application/json' }, body: JSON.stringify({ order: quote.order, signatures }) });
const answer = await res.json();
```

```python
answer = requests.post(f"{BASE}/orders", headers={"x-maxy-key": KEY}, json={"order": quote["order"], "signatures": signatures}).json()
```

```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.

```sh
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)"
```

```ts
const res = await fetch(`${BASE}/orders/submit`, { method: 'POST', headers: { 'x-maxy-key': KEY, 'content-type': 'application/json' }, body: JSON.stringify({ ...placed.next.body, txHash }) });
const answer = await res.json();
```

```python
answer = requests.post(f"{BASE}/orders/submit", headers={"x-maxy-key": KEY}, json={**placed["next"]["body"], "txHash": tx_hash}).json()
```

```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. |

```sh
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/status?orderId=$ORDER_ID&chainId=8453"
```

```ts
const res = await fetch(`${BASE}/status?${new URLSearchParams({ orderId: orderId, chainId: '8453' })}`, { headers: { 'x-maxy-key': KEY } });
const answer = await res.json();
```

```python
answer = requests.get(f"{BASE}/status", headers={"x-maxy-key": KEY}, params={"orderId": order_id, "chainId": "8453"}).json()
```

```json
{
  "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 |  |

```sh
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/orders/$ORDER_ID"
```

```ts
const res = await fetch(`${BASE}/orders/${orderId}`, { headers: { 'x-maxy-key': KEY } });
const answer = await res.json();
```

```python
answer = requests.get(f"{BASE}/orders/{order_id}", headers={"x-maxy-key": KEY}).json()
```

```json
{
  "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.

```sh
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/orders/$ORDER_ID/events"
```

```ts
const res = await fetch(`${BASE}/orders/${orderId}/events`, { headers: { 'x-maxy-key': KEY } });
const answer = await res.json();
```

```python
answer = requests.get(f"{BASE}/orders/{order_id}/events", headers={"x-maxy-key": KEY}).json()
```

```json
{
  "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 |  |

```sh
curl -s -X POST -H "x-maxy-key: $MAXY_API_KEY" "$BASE/orders/$ORDER_ID/stream-ticket?chainId=8453"
```

```ts
const res = await fetch(`${BASE}/orders/${orderId}/stream-ticket?${new URLSearchParams({ chainId: '8453' })}`, { method: 'POST', headers: { 'x-maxy-key': KEY } });
const answer = await res.json();
```

```python
answer = requests.post(f"{BASE}/orders/{order_id}/stream-ticket", headers={"x-maxy-key": KEY}, params={"chainId": "8453"}).json()
```

```json
{
  "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 |  |

```sh
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/orders?from=2026-11-01&to=2026-12-01"
```

```ts
const res = await fetch(`${BASE}/orders?${new URLSearchParams({ from: '2026-11-01', to: '2026-12-01' })}`, { headers: { 'x-maxy-key': KEY } });
const answer = await res.json();
```

```python
answer = requests.get(f"{BASE}/orders", headers={"x-maxy-key": KEY}, params={"from": "2026-11-01", "to": "2026-12-01"}).json()
```

```json
{
  "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. |

```sh
curl -s -X POST -H "x-maxy-key: $MAXY_API_KEY" "$BASE/orders/$ORDER_ID/cancel?chainId=8453"
```

```ts
const res = await fetch(`${BASE}/orders/${orderId}/cancel?${new URLSearchParams({ chainId: '8453' })}`, { method: 'POST', headers: { 'x-maxy-key': KEY } });
const answer = await res.json();
```

```python
answer = requests.post(f"{BASE}/orders/{order_id}/cancel", headers={"x-maxy-key": KEY}, params={"chainId": "8453"}).json()
```

```json
{
  "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. |

```sh
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/orders/$ORDER_ID/refund?chainId=8453"
```

```ts
const res = await fetch(`${BASE}/orders/${orderId}/refund?${new URLSearchParams({ chainId: '8453' })}`, { headers: { 'x-maxy-key': KEY } });
const answer = await res.json();
```

```python
answer = requests.get(f"{BASE}/orders/{order_id}/refund", headers={"x-maxy-key": KEY}, params={"chainId": "8453"}).json()
```

```json
{
  "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 |  |

```sh
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/orders/$ORDER_ID/deposit?chainId=8453&sats=50000"
```

```ts
const res = await fetch(`${BASE}/orders/${orderId}/deposit?${new URLSearchParams({ chainId: '8453', sats: '50000' })}`, { headers: { 'x-maxy-key': KEY } });
const answer = await res.json();
```

```python
answer = requests.get(f"{BASE}/orders/{order_id}/deposit", headers={"x-maxy-key": KEY}, params={"chainId": "8453", "sats": "50000"}).json()
```

```json
{
  "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. |

```sh
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/orders/$ORDER_ID/claim?chainId=8453"
```

```ts
const res = await fetch(`${BASE}/orders/${orderId}/claim?${new URLSearchParams({ chainId: '8453' })}`, { headers: { 'x-maxy-key': KEY } });
const answer = await res.json();
```

```python
answer = requests.get(f"{BASE}/orders/{order_id}/claim", headers={"x-maxy-key": KEY}, params={"chainId": "8453"}).json()
```

```json
{
  "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.

```sh
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" }'
```

```ts
const res = await fetch(`${BASE}/webhooks`, { method: 'POST', headers: { 'x-maxy-key': KEY, 'content-type': 'application/json' }, body: JSON.stringify({ url: 'https://your.app/maxy/webhooks' }) });
const answer = await res.json();
```

```python
answer = requests.post(f"{BASE}/webhooks", headers={"x-maxy-key": KEY}, json={"url": "https://your.app/maxy/webhooks"}).json()
```

```json
{
  "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.

```sh
curl -s -X POST -H "x-maxy-key: $MAXY_API_KEY" "$BASE/webhooks/$WEBHOOK_ID/test"
```

```ts
const res = await fetch(`${BASE}/webhooks/${webhookId}/test`, { method: 'POST', headers: { 'x-maxy-key': KEY } });
const answer = await res.json();
```

```python
answer = requests.post(f"{BASE}/webhooks/{webhook_id}/test", headers={"x-maxy-key": KEY}).json()
```

```json
{
  "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.

```sh
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" }'
```

```ts
const res = await fetch(`${BASE}/sandbox/orders/${orderId}/advance`, { method: 'POST', headers: { 'x-maxy-key': KEY, 'content-type': 'application/json' }, body: JSON.stringify({ to: 'completed' }) });
const answer = await res.json();
```

```python
answer = requests.post(f"{BASE}/sandbox/orders/{order_id}/advance", headers={"x-maxy-key": KEY}, json={"to": "completed"}).json()
```

```json
{
  "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.

```sh
curl -s "$BASE/health"
```

```ts
const res = await fetch(`${BASE}/health`);
const answer = await res.json();
```

```python
answer = requests.get(f"{BASE}/health").json()
```

```json
{
  "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.

---
Source: https://maxy.co/docs/api-reference (Maxy Docs › Reference › HTTP API)
