Test mode & tour

You can try everything OpenSwap does without risking a cent. There are two ways in: a guided tour, and a full sandbox.

The two-minute tour

openswap tour

The tour walks you through a complete swap with real live prices and a clearly simulated payment. No deposit address is created, nothing is saved, and no funds can move. If it's your first run, the menu puts the tour right at the top.

The sandbox: test mode

openswap test on     # everything now runs simulated — you'll see a TEST badge
openswap swap        # do a full swap; the deposit "pays itself" after a few seconds
openswap test off    # back to the real world

Test mode runs the entire CLI against a simulated exchange: streaming quotes, deposit addresses, receipts, tracking — all of it, with pretend wallets and balances. It exists so you can learn the tool risk-free, and so bots and CI pipelines can rehearse thousands of swaps before touching real money.

How realistic is it?

Very — that's the point. The production code paths run unmodified; only the outside world is simulated. Quotes stream the same way, amounts use the same precision, and addresses go through the same validation. Prices are a snapshot with a little noise, not live.

Three things keep it safely separate from your real swaps:

Simulated receipts are prefixed ost_ and marked simulated, and all

test data lives in its own folder — your real receipts can't be touched.

Every screen shows a TEST badge, and the payment screen deliberately

shows no QR code (a scannable code for a fake address is the one thing someone might actually pay).

Test mode never contacts the real API at all.

Choosing how a practice swap ends

Deposits auto-pay after about 8 seconds, or trigger payment yourself:

openswap test pay

Want a specific outcome? End the amount with a magic value:

| Amount ends in | What happens | | --- | --- | | .13 | The swap fails after payment | | .19 | The swap refunds back to the sender | | .07 | The deposit window is only 15 seconds | | .23 | Confirmations come in slowly |

Or set a default story for every practice swap: openswap test scenario refund (choices: happy, refund, fail, expire, slow).

The rest of the toolbox

openswap test status               # current scenario, seed, balances, cheatsheet
openswap test fund BASE:USDC 500   # give yourself a pretend balance
openswap test reset                # brand-new simulated world

For CI: OPENSWAP_TEST_TIMESCALE=50 runs the simulation 50× faster (a full swap story finishes in under a second), and OPENSWAP_TEST_SEED makes outcomes reproducible run after run.

For AI agents

Everything works identically in machine mode (--json --yes), every JSON response is marked simulated, and magic amounts make outcomes deterministic — which means an agent can prove a change works end to end before claiming it's done:

OPENSWAP_TEST_MODE=1 OPENSWAP_TEST_TIMESCALE=100 openswap swap \
  --from eth:usdc --to base:usdc --amount 25 \
  --to-address 0x1111111111111111111111111111111111111111 \
  --refund-address 0x2222222222222222222222222222222222222222 --yes --json