Sandbox#
Practice trading before you risk money. Orders fill against Polymarket US's and Kalshi's live order books with each venue's real fees, and nothing is sent to either venue. Each account starts with $10,000 of simulated cash.
Use it three ways:
- On the web: uselayer.sh/sandbox. Watch what your bot or AI agent did: account value, profit over time, every order (with its
why) and payout, open positions and results. Click an order to see what its side backs (a team, Over or Under), the price it asked for against what it got, each fill, why it didn't fill if it didn't, and everything in that market with the result after fees. The page doesn't place orders. - Over the API: the endpoints below, with your API key. Kalshi and pairs are API only. The web page and the API share one account.
- From your AI assistant: connect the MCP server and it hands your agent these endpoints; the agent then trades over the API, on the same account. Ask it to paper-trade a game and it finds the market, previews the order and places it.
- On your own machine: the Python SDK's paper mode, with nothing sent to Layer.
The Python SDK's mode="sandbox" sends Polymarket US orders only; use the API for Kalshi and pairs.
On your own machine#
The Python SDK's paper mode runs the same kind of practice trading locally: it reads the venue's live order book, fills your orders against it with the venue's real fees, and sends nothing to the venue or to Layer.
from uselayer import Client
client = Client() # paper mode is the default- Paper trade: the full example.
- One strategy, every mode: the same code in backtest, paper and live.
- What paper mode can't tell you: where simulated fills and real ones differ.
- Spread on GitHub: an example bot that runs in paper mode. Clone it and run it (how it works).
How orders fill#
- Every order has a limit price. A buy takes the cheapest offers up to your price, level by level; a sell takes the highest bids down to your price. You never pay more, or sell for less, than your limit.
- Each level is charged the venue's taker fee on its own, the same way
POST /v0/sizeprices fills: Polymarket US'sfeeCoefficient× C × p × (1 − p) to the cent, or Kalshi's 0.07 × the series'fee_multiplier× C × P × (1 − P), rounded up to the cent. tif: "ioc"(the default) fills what it can now and cancels the rest;tif: "fok"fills all of it now or nothing.tif: "gtc"fills what it can now and the rest waits in the book.- No: buying NO at 60¢ fills against YES bids at 40¢, as on the venue.
- Kalshi lists only bids, YES bids and NO bids, so a YES offer is a NO bid turned round: a NO bid at 60¢ is a YES offer at 40¢. Kalshi takes fractional contracts in steps of 0.01.
- Positions are valued at the best bid: what you could sell them for now. When the venue settles a market, each contract pays what the venue paid ($1 if it won, $0 if it lost, or Kalshi's fair price if a game is canceled) and the position closes.
- Orders take time to arrive: an order waits half a second, about how long a real one takes to reach the venue, then fills against the book as it is then. If the price moves in that time, you get the new price, or nothing past your limit.
- What you take stays taken: a paper fill doesn't change the venue's book, so the sandbox keeps the contracts your own orders just took off the book your next order sees. They come back as other traders refill the level: about half within a second and four fifths by 30 seconds (measured on Polymarket's books), and the sandbox counts the rest back over the next few minutes. So you can't buy the same 100 contracts at 42¢ twice.
Orders that wait in the book#
Send tif: "gtc" to leave a limit order: a take-profit, or a bid below the market. What crosses the book now fills at once, as above. The rest waits, with status: "open", behind everyone already at its price, and fills at your limit price as the line ahead of it clears:
- Trades at your price use up the line ahead of you first; once it's gone, the rest of each trade fills your order. 50 bid at 40¢ before yours means 50 must trade at 40¢ before you get anything.
- A trade through your price (a sale below your buy's limit) means nobody was left at it, so your order fills up to that trade's size.
- The other side reaching your price (an offer at or below your buy's limit) fills it from what's offered there, and the same contracts never fill it twice.
- Cancels at your price that no trade explains are spread through the line, so the part ahead of you shrinks by its share.
Layer follows each venue's live book and every trade for the markets you have open orders on, as they happen. The rules are SDK paper mode's, so an order fills the same here as on your own machine.
- Fees: a waiting order's fills are maker fills. Kalshi charges makers 0.0175 × the series'
fee_multiplier× C × P × (1 − P), rounded up to the cent, only on series with maker fees, and nothing on the rest. Polymarket US charges makers nothing. - Cash and contracts are held: an open buy holds its cost at the limit plus the taker fee on it, so
cash_freeonGET /v0/sandboxis what new orders can spend. An open sell holds the contracts it would sell, so you can't promise the same contracts twice. - How it ends: it fills;
expires_atpasses (status: "expired"); you cancel it withDELETE /v0/sandbox/orders/{id}(canceled); or its market closes (canceled, with anote). What filled before it ended stays. post_only: true: the order only ever waits. If it would trade now, it's refused (422would_cross) and nothing happens.- Seeing fills: poll
GET /v0/sandbox/orders/{id}(or the order list). Fills are saved as they happen; reading also checks the book again, at most every 2 seconds. - What it can't know: venues show the total size at each price, not single orders, so your place in line is an estimate. It assumes nobody jumps the queue and that cancels come evenly from the whole line.
curl -X POST -H "authorization: Bearer $LAYER_API_KEY" -H "content-type: application/json" \
"https://uselayer.sh/v0/sandbox/orders" \
-d '{"venue":"polymarket_us","market":"aec-nfl-buf-pit-2026-10-04","side":"yes","action":"sell","price":0.60,"size":150,"tif":"gtc","expires_at":"2026-10-04T20:00:00Z","client_id":"tp-1"}'The answer is the order with status: "open", filled so far and note: null. Poll GET /v0/sandbox/orders/tp-1 to see it fill.
Safety checks#
The sandbox runs the same always-on checks as the SDK, so an order it accepts is one the SDK would send:
| Check | Rejects |
|---|---|
| Price collar | A limit more than 5¢ past the best price (above the best offer for a buy, below the best bid for a sell) |
| Tick size | A price that isn't a multiple of the market's tick (often $0.01, sometimes $0.001) |
| Minimum size | Fewer contracts than the market's minimum |
| Size step | Kalshi: a size that isn't a multiple of 0.01 contracts |
| Holdings | Selling more than you hold, less what open sells already promise. To bet the other way, buy the other side |
| Cash | A buy that costs more, with fees, than your cash not held for open buys. For gtc, the part that waits counts at its limit plus the taker fee |
| Open market | Buying in a market that isn't open. You can still sell |
| Post only | A post_only order that would trade now |
POST/v0/sandbox/orders#
Places an order. The body is the Python SDK's order shape (the fields below), so the SDK can send its own orders as they are.
curl -X POST -H "authorization: Bearer $LAYER_API_KEY" -H "content-type: application/json" \
"https://uselayer.sh/v0/sandbox/orders" \
-d '{"venue":"polymarket_us","market":"aec-nfl-buf-pit-2026-10-04","side":"yes","action":"buy","price":0.43,"size":150}'| Field | |
|---|---|
venue |
"polymarket_us" or "kalshi" |
market |
Polymarket US: the slug, as in the market's URL, or <slug>:long / <slug>:short for a market with two named sides. Kalshi: the ticker, e.g. KXMLBGAME-26OCT062130MILSD-SD |
side |
"yes" or "no" |
action |
"buy" (default) or "sell" |
price |
Your limit in dollars per contract, above 0 and below 1 |
size |
Contracts |
tif |
"ioc" (default), "fok" or "gtc" (waits in the book) |
expires_at |
Optional, gtc only. When the order stops waiting, as an ISO 8601 time. Leave it out to wait until you cancel |
post_only |
Optional, gtc only. true refuses the order if it would trade now |
client_id |
Optional. Send the same order again with the same one (after a timeout, say) and you get the first order back (repeated: true) instead of a second fill. The same client_id with a different order answers 409 client_id_reused. Defaults you spell out, key order and the SDK's result fields (id, status, filled, …) don't make it a different order |
why |
Optional. Your reason for the order, up to 500 characters, e.g. "Rangers at 50¢, my model says 56%". It's saved with the order, comes back as why on it, and shows under the market in your orders. It doesn't change how the order fills, or make a repeated client_id a different order |
The answer (201, or 200 with repeated: true for a repeated client_id) is the order, each fill and your cash after it. On a book with 100 offered at 42¢ and 300 at 43¢:
{
"order": {
"id": "sbx_4f0c…", "client_id": "…", "venue": "polymarket_us", "market": "aec-nfl-buf-pit-2026-10-04",
"side": "yes", "action": "buy", "price": 0.43, "size": 150, "tif": "ioc", "mode": "sandbox",
"status": "filled", "filled": 150, "avg_price": 0.423333, "fees": 2.54, "fee_estimate": 2.56,
"book_as_of": "2026-10-01T18:30:02.000Z", "created_at": "2026-10-01T18:30:02.410Z"
},
"fills": [
{ "price": 0.42, "contracts": 100, "cost": 42, "fee": 1.69 },
{ "price": 0.43, "contracts": 50, "cost": 21.5, "fee": 0.85 }
],
"cash": 9933.96,
"note": null,
"repeated": false
}status is filled; canceled when some or all of it couldn't fill (filled says how much did, and note why); or, for gtc, open while the rest waits in the book (later expired or canceled if it ends before filling). fee_estimate is the taker fee on the whole order at its limit price; fees is what the fills actually cost. The order's own note says why it ended when you didn't cancel it, e.g. "the market closed".
POST/v0/sandbox/pairs#
Buys both sides of a match between Kalshi and Polymarket US: YES on one venue and NO on the other, which pays $1 a contract however the event settles. If one side fills and the other doesn't, the sandbox does what the SDK's leg-risk guard does, and tells you which of four things happened.
curl -X POST -H "authorization: Bearer $LAYER_API_KEY" -H "content-type: application/json" \
"https://uselayer.sh/v0/sandbox/pairs" \
-d '{"kalshi":"KXMLBGAME-26OCT062130MILSD-SD","max_cost_per_leg":50,"min_edge":0.01}'| Field | |
|---|---|
kalshi |
The Kalshi ticker of a live match: kalshi.market_id in GET /v0/matches?venue=polymarket_us |
polymarket_us |
Optional. The matched Polymarket US market id, checked against Layer's match. Leave it out and Layer uses the match |
size |
Contracts wanted, a whole number |
max_cost_per_leg |
The most either leg may cost, with fees, in dollars. Send size, this, or both |
min_edge |
The smallest profit per contract after both fees you'll take, in dollars. Default 0.01 (1¢) |
max_position |
Optional. The most contracts you may hold on each leg's market and side after the pair, counting what you hold already |
on_miss |
"unwind" (default): sell an unmatched first leg back. "hold": keep it |
max_unwind_loss |
How far below its entry price an unmatched leg may be sold back, in dollars per contract. Default 0.05 |
first |
Optional. "kalshi" or "polymarket_us": the leg to send first. By default the thinner book goes first |
client_id |
Optional. Send the same pair again with the same one and you get the first pair back (repeated: true) instead of a second trade. The same client_id with a different pair answers 409 client_id_reused |
what_if |
Optional. Books you build, to see what happens when a side doesn't fill (below) |
How it runs:
- Layer reads both books and sizes the pair both ways round (Kalshi YES with Polymarket US NO, and the reverse) with the same walk as
POST /v0/size, keeping the better. It stops atsize, at each leg'smax_cost_per_legandmax_position, and never goes more than 5¢ past either best offer. Both legs are checked together; if either fails a safety check, nothing is sent (422). - If no contract clears
min_edgeafter both fees, nothing is sent. - The thinner leg goes first, fill-what-you-can. If none of it fills, the second isn't sent.
- The second leg goes for what the first filled, up to its break-even: the highest price at which the pair still clears
min_edgeafter its fee, within the collar andmax_cost_per_leg. - If the second leg falls short, the extra first-leg contracts are sold back, never below their entry price minus
max_unwind_loss.
The answer's outcome:
outcome |
What happened | Look at |
|---|---|---|
hedged |
Both legs filled | hedged (contracts) and locked_in: what they pay at settlement after their cost and fees |
missed |
Nothing was traded: the edge didn't clear min_edge, a cap left no room, or the first leg found nothing |
quote.edge_at_best and explanation |
unwound |
One leg filled and the other didn't, so the first was sold back | unwind_cost: what that cost with fees |
one_sided |
The first leg couldn't all be sold back (no bid above the floor, or on_miss: "hold") |
exposure: the contracts you hold on one side, what they cost and are worth now. cost_with_fees is what you lose if it settles against you |
Every answer has an explanation in plain English you can show as it is, the quote it was sized on (with the match's best_trade at the top of both books, as GET /v0/match shows it), every order sent (group_id is the pair's id), and notes. The orders show in GET /v0/sandbox/orders too.
Worked example#
On books like these: Kalshi has YES offered at 40¢ (its best NO bid is 60¢) and Polymarket US has NO offered at 54¢ (its best YES bid is 46¢). That's 6¢ before fees, a contract:
- Kalshi's fee: 0.07 × 0.40 × 0.60 = 1.68¢
- Polymarket US's fee: 0.095 × 0.54 × 0.46 = 2.36¢ (its markets'
feeCoefficient, the Tier 1 rate) - Edge after fees: 6 − 1.68 − 2.36 = 1.96¢, which clears a 1¢
min_edge
{"kalshi": "…", "size": 10} buys 10 YES on Kalshi for $4.00 plus a $0.17 fee (0.168 rounded up), then 10 NO on Polymarket US for $5.40 plus $0.24 (0.236, half to even). The pair pays $10 whichever side wins, so it's hedged, and locked_in is $10 − $9.81 = $0.19:
{
"pair": {
"id": "pair_9b2…", "client_id": "…", "outcome": "hedged",
"explanation": "Both legs filled: 10 contracts hedged (Kalshi YES + Polymarket US NO), locking in $0.19 after fees, paid when the match settles.",
"what_if": false, "kalshi": "KX…", "polymarket_us": "aec-…", "first_leg": "kalshi",
"hedged": 10, "locked_in": 0.19, "unwind_cost": 0, "exposure": null,
"quote": { "contracts": 10, "limited_by": "size", "min_edge": 0.01, "edge_at_best": 0.019602, "net_profit": 0.19, "kalshi": { "side": "yes", "best_price": 0.4, "limit_price": 0.4, "…": "…" }, "polymarket_us": { "side": "no", "best_price": 0.54, "…": "…" }, "best_trade": { "…": "…" } },
"orders": [ { "venue": "kalshi", "side": "yes", "filled": 10, "avg_price": 0.4, "fees": 0.17, "…": "…" }, { "venue": "polymarket_us", "side": "no", "filled": 10, "avg_price": 0.54, "fees": 0.24, "…": "…" } ],
"notes": [], "books": { "kalshi": "live", "polymarket_us": "live" }
},
"cash": 9990.19,
"repeated": false
}Now say Polymarket US's offers vanish before the second leg arrives. Kalshi's best YES bid is 38¢, and the floor is the higher of 40¢ − max_unwind_loss (35¢) and 38¢ − the 5¢ collar (33¢), so the 10 are sold back at 38¢ with a $0.17 fee (0.07 × 10 × 0.38 × 0.62 = 0.165, rounded up). The outcome is unwound, and unwind_cost is 10 × 2¢ + $0.17 + the first leg's $0.17 = $0.54. If Kalshi's best bid had been 30¢, under the floor, they'd stay unsold: one_sided, with exposure showing 10 YES costing $4.17 with fees.
What if a side doesn't fill?#
Live books rarely leave a pair half done, so what_if lets you build the books yourself and watch what the pair does. Each book is for the market's YES side, as its id names it: {"bids": [{"price": 0.38, "size": 100}], "asks": [{"price": 0.40, "size": 100}]}.
what_if.books.kalshi/.polymarket_us: the book used for the quote and the first leg, instead of the live one.what_if.then.kalshi/.polymarket_us: the book an order meets after the first leg (the second leg, or the sell-back). Without it, Layer useswhat_if.books, else reads the live book again.
{ "kalshi": "KX…", "size": 10, "what_if": { "then": { "polymarket_us": { "asks": [] }, "kalshi": { "bids": [{ "price": 0.30, "size": 100 }] } } } }Here Polymarket US has nothing to sell when the second leg arrives, and Kalshi's only bid is below the floor, so the answer is one_sided. A what-if pair is answered like any other ("what_if": true) but never changes your account.
GET /v0/sandbox/pairs#
Your pairs, newest first, each as POST answered it. limit is 1–200 (default 50).
POST/v0/sandbox/preview#
The same body as an order. Says what the order would fill now, its fees, and every check it would fail, and changes nothing.
{ "allowed": false, "problems": [{ "code": "price_collar", "detail": "Limit 0.48 is more than 0.05 above the best ask 0.42.", "hint": "Use a limit of at most 0.47." }], "estimate": { "filled": 10, "avg_price": 0.42, "cost": 4.2, "fees": 0.17, "fills": [{ "price": 0.42, "contracts": 10, "cost": 4.2, "fee": 0.17 }], "note": null }, "fee_estimate": 0.17, "best_bid": 0.41, "best_ask": 0.42, "book_as_of": "…", "cash": 10000 }best_bid and best_ask are the best prices now on the order's side (for "no", the NO prices), or null when that side of the book is empty. Not sure what limit to send? Preview with a guess and read them.
GET/v0/sandbox#
Your account: cash, each position valued at the best bid now, and profit or loss since you started. Positions whose market has settled are paid out first.
{
"mode": "sandbox", "cash": 9933.96, "cash_on_hold": 0, "cash_free": 9933.96, "open_orders": 0,
"positions_value": 60, "total": 9993.96, "starting_cash": 10000, "pnl": -6.04,
"started_at": "2026-10-01T18:29:00.000Z",
"positions": [
{ "venue": "polymarket_us", "market": "aec-nfl-buf-pit-2026-10-04", "side": "yes", "question": "Bills vs. Steelers", "contracts": 150,
"avg_price": 0.423333, "cost": 63.5, "fees": 2.54, "price_now": 0.4, "value": 60, "pnl": -6.04, "opened_at": "…" }
]
}A position's pnl is value − cost − fees. When its book can't be read, price_now, value and pnl are null and total counts it at cost. cash includes what open buys hold (cash_on_hold); cash_free is what new orders can spend, and open_orders how many orders are waiting in the book.
GET/v0/sandbox/orders#
Your orders, newest first. limit is 1–200 (default 50). status=open lists only the orders waiting in the book (also filled, canceled, expired).
Each order has key: the name and first characters of the API key that placed it, e.g. {"name": "muse", "prefix": "lyr_ab12"}, so an account with a key per agent can tell their orders apart. It's null for orders placed before November 17, 2026. All your keys share one sandbox account.
GET/v0/sandbox/orders/{id}#
One order, by its id (sbx_…) or the client_id you sent, with every fill: {"order": {…}, "fills": [{"price", "contracts", "cost", "fee"}]}. An open order is checked against the live book first, so poll this to watch a gtc order fill. 404 order_not_found if there's no such order in your account.
DELETE/v0/sandbox/orders/{id}#
Cancels an open order. What it already filled stays; the rest stops waiting, and its held cash or contracts are free again. Answers like GET, with status: "canceled". Canceling an order that already ended returns it as it is, so a retry is safe, except a filled one: 409 order_filled.
DELETE/v0/sandbox/orders#
Cancels every open order, or only those on one market with venue and market. Answers {"canceled": [orders]}.
GET/v0/sandbox/history#
Your money over time, for a profit chart: every buy, sell and payout since you started (or last reset), oldest first. An order's fills are one point, and each point has your cash and the profit you'd booked after it. Settled markets are paid out first, as on GET /v0/sandbox. limit is 1–5000 (default 500) and keeps the newest; count is how many there are in all.
{
"mode": "sandbox", "starting_cash": 10000, "started_at": "2026-10-01T18:29:00.000Z", "cash": 10083.96, "count": 2,
"points": [
{ "at": "2026-10-01T18:30:02.410Z", "kind": "buy", "order_id": "sbx_4f0c…", "venue": "polymarket_us", "market": "aec-nfl-buf-pit-2026-10-04",
"question": "Bills vs. Steelers", "side": "yes", "contracts": 150, "price": 0.423333, "cash_change": -66.04, "fees": 2.54, "cash": 9933.96, "realized_pnl": 0 },
{ "at": "2026-10-04T20:31:40.000Z", "kind": "payout", "order_id": null, "venue": "polymarket_us", "market": "aec-nfl-buf-pit-2026-10-04",
"question": "Bills vs. Steelers", "side": "yes", "contracts": 150, "price": 1, "cash_change": 150, "fees": 0, "cash": 10083.96, "realized_pnl": 83.96 }
]
}kindisbuy,sellorpayout(the market settled;priceis what one contract paid). Agtcorder's later fills are points of their own, at the time they filled.cash_changeis after fees: a buy spends its cost plus fees, a sell brings in its proceeds minus fees.realized_pnlis the profit booked so far: it moves when contracts are sold or paid out, since open positions count at what they cost.GET /v0/sandbox'spnlis this plus what open positions are worth now.- Orders that filled nothing aren't here; they're in
GET /v0/sandbox/orders.
GET/v0/sandbox/markets#
Open markets to trade: Polymarket US, or Kalshi with venue=kalshi. q searches events, questions and outcomes, including the event's other outcomes, so canadiens rangers finds a game listed as "Montreal vs New York R" (every word must match). limit is 1–50 (default 20).
Game winners come first, then full-game spreads and totals (one line from each in turn), then markets that aren't sports lines (prices, politics, futures), then every other line and player prop. Within each, the soonest event comes first. So q=nhl lists the upcoming games' winners, and a search for one game shows its winner, spreads and totals before its props. Kalshi's 15-minute markets (crypto, currencies, commodities) are listed within about a minute of each window opening.
{ "markets": [{ "venue": "polymarket_us", "market": "aec-nfl-buf-pit-2026-10-04", "event": "Bills vs. Steelers", "outcome": "Bills", "event_time": "2026-10-04T17:00:00.000Z", "close_time": "…" }] }POST/v0/sandbox/reset#
Starts again: every order, fill, pair and position goes, and cash is back to $10,000. Answers with the account.
Errors#
As everywhere in the API, each error has a detail, and a hint except on 503s.
| Status | error |
When |
|---|---|---|
| 400 | bad_request |
The body isn't a valid order or pair |
| 400 | gtc_only |
post_only or expires_at without tif: "gtc" |
| 400 | expires_at_passed |
expires_at is already in the past |
| 404 | order_not_found |
No order with that id or client_id in your account |
| 409 | order_filled |
Canceling an order that already filled |
| 400 | venue_not_in_sandbox |
venue: "polymarket" (polymarket.com isn't in the sandbox) |
| 403 | sandbox_not_enabled |
Layer has turned the sandbox off for your account |
| 404 | market_not_found |
The venue has no such market |
| 404 | not_a_match |
Pairs: Layer has no live Polymarket US match for that Kalshi ticker |
| 409 | client_id_reused |
The client_id was already used for a different order or pair (detail names it). Nothing was traded. Send a new client_id, or the exact same request to get the first one back |
| 422 | not_a_match |
Pairs: the polymarket_us you sent isn't the Kalshi market's match (hint names it) |
| 422 | match_settled |
Pairs: the match has settled |
| 422 | price_collar, off_tick, below_min_size, off_size_step, sell_more_than_held, not_enough_cash, market_closed, would_cross |
A safety check failed (see above). For a pair, nothing was sent |
| 503 | venue_unavailable |
A venue didn't answer, or Layer has paused it (venues says which); try again in a few seconds |