# Sandbox

The sandbox is the same API with nothing real behind it. To use it, change the key, in the API, the SDK and the CLI. The base URL, routes and JSON stay the same. Every answer carries `"sandbox": true` and the header `X-Maxy-Sandbox: true`. There is no testnet.

Put your test key in place of `mxk_test_…`.

```sh
export BASE=https://whhxyutitykcsdpvdgcd.supabase.co/functions/v1/maxy-api
export MAXY_API_KEY=mxk_test_…
curl -s -H "x-maxy-key: $MAXY_API_KEY" "$BASE/key"
```

```ts
import { createMaxyClient } from '@maxy-labs/sdk';

const maxy = createMaxyClient(); // reads MAXY_API_KEY
maxy.sandbox; // true with a test key, false with a live one
```

```python
import os, requests
BASE = "https://whhxyutitykcsdpvdgcd.supabase.co/functions/v1/maxy-api"
r = requests.get(f"{BASE}/key", headers={"x-maxy-key": os.environ["MAXY_API_KEY"]})
print(r.json()["sandbox"])  # True
```

| Real | Not real |
| --- | --- |
| Prices and quote amounts, routes, JSON, error codes, the 60-second quote, your cap, signed webhooks, signature checks | Orders, balances and allowances, transactions, deposit addresses, Bitcoin txids |

**Nothing can be broadcast.** A signature authorizes nothing, a transaction goes to the zero address with `gas` `"1"`, and a deposit address is a testnet one. Ids start with `53414e44424f58`, "SANDBOX" in hex.

**Limits.** 120 calls a minute, 50 open orders, swaps only. Orders are kept for 7 days. The SDK answers `sandbox_refused` for a loan, mint or sign-in call, and any other Maxy function answers `invalid_api_key` for a test key. A real order id read with a test key answers `not_found`. The sandbox does not enforce the $10 sell minimum, so a smaller sell walks to `completed` there. Live, `POST /orders` refuses it.

## Test scenarios

Force every outcome your product must handle. Name a `scenario` on the quote, place the order as usual, and it walks there by itself. A live key ignores it. Name `expired_quote` to simulate expired quote handling, and so on for each outcome. An order starts when you submit it, or by itself 30 seconds after you place it. The samples use the setup from [Get a quote](https://maxy.co/docs/buy-btc#get-a-quote).

```sh
curl -sG -H "x-maxy-key: $MAXY_API_KEY" "$BASE/quote" \
  --data-urlencode "from=ETH on base" -d to=BTC -d amount=0.01 \
  -d fromAddress="$WALLET" -d toAddress="$MY_BTC_ADDRESS" -d scenario=refund_available > quote.json
```

```ts
import { createMaxyClient, evmSignerFromWalletClient } from '@maxy-labs/sdk';

const maxy = createMaxyClient(); // reads MAXY_API_KEY
const evm = evmSignerFromWalletClient(walletClient);
const { status } = await maxy.swap.execute({
  from: 'ETH on base', to: 'BTC', amount: '0.01',
  evm, btcAddress, scenario: 'refund_available',
});
console.log(status.state); // refundable
const { txHash } = await maxy.swap.refund({ chainId: 8453, intentHash: status.orderId as `0x${string}`, evm });
```

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

| `scenario` | What happens |
| --- | --- |
| `refund_available` | Reaches `refundable`, then `refunded` 15 seconds after you ask |
| `order_expired`, `order_failed`, `order_cancelled` | Ends in that state |
| `expired_quote` | `409 quote_expired` |
| `over_cap` | `issues.orderCap`, then `422` |
| `too_small` | `422 amount_out_of_range` |
| `unfillable` | `liquidityAvailable: false` |
| `price_moved` | `409 quote_mismatch` |
| `rate_limited` | `429` with `Retry-After` |
| `insufficient_funds`, `needs_approval` | `issues.balance`, `issues.allowance` |
| `simulation_fails` | `simulation.ok: false` |
| `underpaid` | A sell ends `expired` |
| `webhook_replay` | Each event arrives twice |

`POST /sandbox/orders/{id}/advance` skips the wait, with `{ "to": "completed" }` or an empty body for the next state. `GET /health?scenario=degraded` tests your code that skips Maxy when it is degraded.

Then, on mainnet: one buy with $5 of USDC and one with 0.002 ETH. Do not load-test production. To go live, change to `mxk_live_…`, and work through the [launch checklist](https://maxy.co/docs/launch-checklist).

---
Source: https://maxy.co/docs/sandbox (Maxy Docs › Launch › Test)
