Sandbox Mode

Paper-trade against the live order book without risking real money. Sandbox uses the same SOR, the same venue edges, the same fill router, and the same positions_v2 table as live — only the source of initial portfolio state and the execution destination differ.

There is no "sandbox build" of the engine. Live and sandbox run inside the same edge processes; per-order dispatch is decided by the is_sandbox flag on the order intent.

Architecture at a glance

code

┌────────────────┐         ┌────────────────┐
│  seq_test_*    │   POST  │   /v1/orders   │
│   API key      ├────────►│   (same path)  │
└────────────────┘         └───────┬────────┘
                                   │ is_sandbox = true
                                   ▼
                           ┌────────────────┐
                           │      SOR       │
                           │ (real routing) │
                           └───────┬────────┘
                                   │ Allocate frame, is_sandbox=true
                                   ▼
                  ┌─────────────────────────────────┐
                  │   Venue Edge (same process)     │
                  │  ┌───────────────────────────┐  │
                  │  │  DualAdaptor              │  │
                  │  │  ─ live OMS  ◄─is_sandbox=false─
                  │  │  ─ AdversarialSimAdapter ◄─is_sandbox=true
                  │  └───────────────────────────┘  │
                  └────────────────┬────────────────┘
                                   │ Fill / Reject
                                   ▼
                           ┌────────────────┐
                           │ FillRouter →   │
                           │ positions_v2   │ (is_sandbox column)
                           └────────────────┘

The adversarial sim adapter is queue-aware and book-impact-aware — limit orders rest in the queue and can be picked off by adverse trades; market orders cross the spread and pay realistic fees. The sandbox path never falls back to naive mid-fill simulation.

Two ways to use sandbox

Sandbox API key (recommended)

A seq_test_* key forces every order through sandbox. Mint one via:

bash

curl -X POST https://api.sequencemkts.com/v1/api_keys \
  -H "Authorization: Bearer $LIVE_KEY" \
  -d '{"label":"my-paper-trading","sandbox":true}'

bash

export SEQ_API_KEY="seq_test_a1b2c3d4..."
sequence buy ETH-USD 50  # routes through sandbox automatically

Per-order sandbox flag

With a live key, set sandbox: true on individual order bodies. (Sandbox keys force the flag regardless of body content.)

python

seq.buy("BTC-USD", 0.001, sandbox=True)

Configuring your paper portfolio

Sandbox positions are configurable, persistent, and read-identical to live. You can seed the paper portfolio with explicit per-venue/per-asset positions:

bash

curl -X POST https://api.sequencemkts.com/v1/sandbox/positions \
  -H "Authorization: Bearer $SEQ_TEST_KEY" \
  -d '{
    "positions": [
      {"venue":"polymarket","kind":"crypto","symbol":"USDC","qty":10000.0},
      {"venue":"kalshi","kind":"fiat","symbol":"USD","qty":5000.0}
    ],
    "replace": true
  }'

GET /v1/positions then returns those rows the same way it returns live positions:

bash

curl https://api.sequencemkts.com/v1/positions \
  -H "Authorization: Bearer $SEQ_TEST_KEY"

For full reference see API → Sandbox.

What's real vs simulated

Aspect	Sandbox	Live
Market data (quotes, book, trades)	Real	Real
Order routing (SOR venue selection)	Real	Real
Edge connectivity / preflight guards	Real	Real
Fill prices	Adversarial sim against real book	Real exchange fills
Fees	Modeled (taker/maker bps)	Actual venue fees
Positions table	`positions_v2` (`is_sandbox=true`)	`positions_v2` (`is_sandbox=false`)
Position read API	`GET /v1/positions`	`GET /v1/positions` (same handler)
Exchange API keys	Not required	Required
TCA reports	Generated	Generated

Failure-mode parity

Sandbox mirrors the live edge's safety preflights. For example, a market buy on a venue with no live ask and no explicit price cap will be rejected by the sandbox path with Execution-class error "sandbox market buy requires a live ask or explicit price cap" — the same condition that triggers the live edge's "polymarket market buy requires a live ask or explicit price cap" rejection.

This means sandbox can be trusted as a faithful indicator of whether a strategy will encounter venue-side surface errors in production.

Resetting sandbox state

bash

curl -X POST https://api.sequencemkts.com/v1/sandbox/reset \
  -H "Authorization: Bearer $SEQ_TEST_KEY"

Wipes all sandbox positions (positions_v2 rows with is_sandbox=true), clears the SOR's in-memory paper balance cache, and re-seeds default balances ($1B per quote asset across all venues, including Kalshi, Polymarket, and DEX). To customize the default balance, use PUT /v1/sandbox/settings first.