Documentation

How The Pit works

The rules of a pit, how the room trades its own odds on a Panta market, where your USDC goes and how the escrow protects it. Written for players, hosts, streamers and integrators.

Overview#

The Pit turns any prediction market into a trading game on Solana. A host opens a pit on a market — tonight's game, an election, a launch, or BTC, ETH and SOL — and everyone who joins pays the same seat. Inside the pit the room trades its own odds: every buy and sell moves the price for everyone, starting from Panta's line. Players are ranked by vault value; a single round pays the pool to the top finishers, and a royale cuts the bottom half each round until the finalists split it.

  • Host a pit on any market — pick an open Panta market, or create a new one on Panta for a game or event (see Pits on Panta markets).
  • The pit is the terminal — a live price tape, where the room's money sits, and Panta's line for reference.
  • The Oracle read — a running read of the pit's own market data, phrased by Claude (see The Oracle read).
  • Creator mode — a join code, QR and a stream overlay so an audience can play along (see Hosting & streaming).

Two call-contest formats need no trading at all: Predictions (five hidden picks on BTC, ETH and SOL) and Streak (a chain of quick calls, one miss and you're out).

  1. Pit engine — server-side rounds (enrolling → live → settling → advancing/complete) persisted in Postgres.
  2. USDC escrow — a non-custodial Solana program holds every seat deposit until players withdraw.
  3. Panta — the markets: their questions, Panta's price as the opening line, resolution, and market creation.
  4. Price oracle — live BTC, ETH and SOL spot prices for crypto pits.
Devnet. Everything runs on Solana devnet with Circle's devnet USDC. Test tokens have no monetary value.

Game rules#

FormatRoundsHow it ends
Single1One trading window. Players are ranked by final vault value and the pool is paid out.
Royale2–4After each round the bottom half is eliminated. Survivors carry their vault into the next round until one player remains or the round limit is reached. On a Panta market every round trades the same market.
Predictions1Crypto only. No trading. Every player answers the same five questions before the start; at the close each right answer is a point and the top scores are paid. See Predictions pits.
StreakUp to 6 legsCrypto only. No trading. One quick call per leg; a wrong pick knocks you out. Last caller standing takes the pool. See Streak pits.
01Enrolling
02Live
03Settling
04Advancing / Complete
  • Enrolling — seats are open. The clock starts once the host's own seat is confirmed: Quick pits stay open for 2 minutes, Scheduled pits for the chosen window (5 minutes to 3 hours). Enrollment locks early when every seat is filled. A host who ends up alone gets one practice opponent so the round can run.
  • Live — opening calls fill (at Panta's line on a Panta market, at 50¢ on a crypto pit), then everyone trades with the same starting vault. The pit shows in real time who is in the money (single round) or above and below the cut (royale). The round lasts its trading window: 5 minutes, 15 minutes or an hour.
  • Settling — on a Panta market, YES settles at the room's average price over the closing window, or at $1/$0 if Panta has resolved the market (see The room book). On a crypto pit the close is compared with the open: UP pays $1 if it closed higher, DOWN if lower (50¢ each if exactly flat). Players are ranked by vault value; ties go to whoever joined first.
  • Cut (royale) — the top ceil(alive / 2) players survive. Everyone else is eliminated and their vault is frozen at its final value until the end, when all players are paid out together.
  • Complete — the pit settles on-chain and every player can withdraw.

Pits on Panta markets#

When hosting, choose the market the pit trades: Crypto (BTC, ETH or SOL up or down), a Panta market already open on Panta, or a New market you create on Panta for the pit. Panta pits play as a single round or a royale.

  • Existing markets — the host list shows Panta's open, unresolved markets, busiest first, with Panta's current YES price and when each closes.
  • Creating a market — write a yes/no question (10–200 characters, ending in “?”), pick a category (sports, crypto, politics, entertainment, finance, science, world or other), a resolution rule (20–2,048 characters) and one to five http(s) sources of truth, and when trading ends. Trading must run at least 10 minutes and at most a year; a question that duplicates an existing Panta market is refused (host a pit on that market instead). Mark it happening now for an event already under way (a game in progress) so it opens immediately; otherwise Panta opens it about an hour after creation.
  • The fee is shown first — the first press asks Panta for a quote and shows the creation fee and starting liquidity; nothing is signed until you press again. Your X wallet then signs Panta's create transaction and the market is registered on Panta. Once a market is created the form locks it in, so if opening the pit fails you can retry without paying Panta again. Only the wallet that created a market can host a pit on it through this flow.
  • Opening line — when enrollment locks, Panta's YES price becomes the pit's opening line. Every seat call (YES or NO) fills at that line.
  • Resolution — if Panta resolves the market while the pit is running, the pit settles on the real outcome ($1 for the winning side) and a royale ends there.
Sandbox. A deployment on Panta's sandbox key has one test market, and its market-creation quotes show a fee but build an empty transaction, so nothing is charged. With a live key every open Panta market is listed and the creation fee is charged on-chain.

The room book#

On a Panta market the pit doesn't copy Panta's price — the room makes its own. The pit runs an automated market maker (a logarithmic market scoring rule) seeded at Panta's line. Buying YES pushes the room's YES price up for everyone; selling or buying NO pushes it down.

YES price  = 1 / (1 + e^((NO shares − YES shares) / b))
b (depth)  = total of all vaults, between 20 and 5,000
opening    = every seat call fills at Panta's line,
             then the book takes on the room's net position
  • Depth — a bigger room makes a deeper book, so the same trade moves the price less.
  • Your ticket — before you trade, the panel shows your average fill, the shares you get and where the room's price will be after your trade.
  • Practice traders — when a pit has practice bots, they trade against the book and lean back toward Panta's line.
  • Settlement on the average — YES settles at the room's time-weighted average price over the closing window (the last 20% of the round, between 30 seconds and 10 minutes), shaded on the chart. A last-second trade can't mark the close.
  • Royale — each new round re-opens the book at the previous round's settlement price.

The Oracle read#

Every trading pit shows a running read of its own market: a headline, a lean (YES, NO or neutral), a confidence and the signals behind it — the room against Panta's line, the one-minute move, where the room's money sits and the time to the bell.

  • Data first — the lean and confidence are computed from the pit's data. When the server has an Anthropic API key, Claude writes the headline from those numbers while the round is live; otherwise a plain read from the data is shown. The badge says which.
  • Shared — one read per pit, refreshed about every 20 seconds and shared by every viewer.
  • No leaks — while seats are open the read never uses seat calls, which stay hidden until the lock.
  • Not advice — it describes the pit's own numbers and never tells anyone what to buy.

Hosting & streaming#

Host from the Host tab, signed in with X. The host sets the market, format, seat, capacity, timing and an optional host fee, then pays seat #1 like everyone else — every pit gets a fresh code. Creating a new market is two presses: the first checks it with Panta and shows the creation fee; the second creates it and opens the pit. Once created, the market is locked in the form, so if opening the pit fails you can retry without paying again. While the pit is open the host's page shows a creator kit:

  • Join code and QR — large enough to put on stream; scanning it opens the pit.
  • Invite link — /a/CODE, ready to post.
  • Stream overlay — /a/CODE/overlay as a Browser Source in OBS or Streamlabs (1280×720). It shows the market, the live odds and tape, Panta's line, the top of the pit, the pool and the clock, and the QR while seats are open. The background is transparent; add ?bg=solid for a solid one. It reads only public pit state.

Every host setting, with the range the server enforces:

SettingOptions / rangeNotes
MarketCrypto · Panta market · New marketPanta markets run Single or Royale only; Predictions and Streak are crypto-only.
EnrollmentQuick (2 min) · Scheduled (5 min – 3 hours)Counted from your confirmed seat; locks early when every seat fills.
GameSingle · Royale · Predictions · StreakRoyale runs 2–4 rounds; Streak up to 6 legs.
Trading windowPanta: 5 / 15 / 60 min · Crypto: 5 / 15 min or 1 hourStreak legs are 1, 2 or 5 minutes each.
Players2 – 162 players is a duel (winner takes all).
Entry (USDC)$1 – $100 (whole dollars)Into the shared prize pool.
Vault (USDC)$5 – $500 (whole dollars)Your trading bankroll. Predictions and Streak have none.
Host fee0 – 5%Your cut of the pool, shown to players before they join.

Predictions pits#

A call contest with nothing to trade. Before the round starts, every player answers the same five questions about how the three coins move over it:

#QuestionRight answer
1–3BTC, ETH, SOL: up or down?Up if the coin closes above its price at the lock, down if below.
4Which does best?The coin with the biggest % change — the biggest gain, or the smallest drop if all three fall.
5A head-to-head, e.g. SOL or ETHWhichever of the two has the better % change. The pair varies by pit.
  • Why relative questions — BTC, ETH and SOL usually move together, so the three up/down calls often land or miss as one. “Which does best” and the head-to-head reward reading the market rather than calling everything the same way, and make ties much rarer.
  • Hidden picks — nobody else can see your picks while enrollment is open (the server shows other players only how many questions they have answered, and the deposit memo never contains picks). You can change them until the round locks; then everyone's picks are revealed.
  • Judged on the lock price — when enrollment locks, the live BTC, ETH and SOL prices are recorded. At the close (the timeframe: 5 minutes, 15 minutes or an hour) each coin is compared with its own opening price. While the round runs, the pit shows which answers are winning and everyone's live score.
  • Scoring — one point per right answer. A question with an exact dead heat (or a missing price) scores for nobody. An unanswered question scores nothing.
  • Lock — optionally lock 2 or 3 of your picks together, a parlay inside your card. If every locked pick is right, the lock lands and adds a bonus point per locked pick (they count double). If any locked pick is wrong, every locked pick scores 0. A locked question that ends level drops out and the rest decide the lock. Locks are hidden with your picks until the start. Because the coins usually move together, a lock on same-direction calls lands more often — and when the market turns, it all goes at once.
  • Prizes — the usual split of the pool: winner takes all in a duel, otherwise 62.5% / 23.44% / 14.06%. Players who tie share the places they cover equally — two players tied for first split first and second place.
  • Seat — just the entry. The escrow program needs a vault per seat, so a predictions seat carries a 1-unit vault (0.000001 USDC) that is returned at settlement.
  • Practice — the free walk-in pit at /a/PICKS runs predictions rounds against bots.

Streak pits#

A parlay across time. The game is a chain of short legs, each asking one question about BTC, ETH or SOL — a coin up or down, a head-to-head, or which of the three does best.

  • Pick window — each leg opens with a 20-second window. Picks are hidden until it closes (players see only who has picked). Leg 1 can be picked as soon as you take a seat.
  • The leg — when the window closes the leg starts at the live price of the coins it asks about and runs for the host's leg length: 1, 2 or 5 minutes. Everyone's picks are shown while it runs.
  • Out — a wrong pick, or no pick, knocks you out. If every player still in misses, or the leg ends dead level, nobody goes out.
  • The end — the game ends when one player is left, when no real player is left, or after 6 legs. Players are ranked by how many legs they survived.
  • Prizes — the usual split of the pool (winner takes all in a duel; otherwise 62.5% / 23.44% / 14.06%), ties sharing their places. The seat is just the entry, like Predictions.
  • Strategy — moves over a minute or two are close to a coin flip, so the edge is reading the room: if most players will call UP, DOWN is how you become the last one standing.
  • Practice — the free walk-in pit at /a/STREAK plays against a table of bots.

Seats, pool & payouts#

seat      = entry + vault          (both deposited into escrow)
pool      = entry × players who paid
vault pot = vault × players who paid
withdraw  = prize share + vault pot × (your final vault ÷ all final vaults)
            (prizes come from the pool after any host fee; 0.1% platform fee on withdrawal)
PlayersPrize split
2 (a duel)Winner takes 100% of the pool
3 or more1st 62.5% · 2nd 23.44% · 3rd 14.06%

The entry is what you put at risk for the prize. The vault is your trading bankroll: it rises and falls with your trades, and at the end the players' vault money is shared out in proportion to how each vault finished — one player's trading losses pay for another's gains. The escrow is always paid out in full: nothing is capped away and nothing stays locked. If every vault ends at $0, the vault money goes back equally.

Example: two players each deposit $6 ($1 entry + $5 vault). A calls UP, B calls DOWN, SOL closes higher: A's vault finishes at $10, B's at $0, so A withdraws $10 + the $2 pool = $12 and B withdraws $0. Playing alone against practice bots, your vault money simply comes back — there's no one to win it from. The Pit takes only a 0.1% fee on withdrawals (see Fees).

Fees#

FeeWho sets itHow it works
Host fee · 0–5%The pit's hostA share of the prize pool (the entries), paid into the host's own seat at settlement. It comes off the pool before the prize split, and players see it before they join. Cancelled pits pay no host fee.
Platform fee · 0.1%The PitTaken by the escrow program from each withdrawal of a settled pit's payout. Refunds of a cancelled pit and on-chain recoveries are free.
Market creationPantaCharged by Panta, not The Pit, when you create a new market. The amount comes from Panta's quote and is shown before you sign.
host fee  = pool × host fee %
prizes    = split of (pool − host fee)
withdraw  = payout − 0.1% platform fee

The platform fee is fixed in each pit's escrow vault when it is created and capped by the program at 1%, so it can't be raised on a pit that already exists. Pits created before fees were introduced withdraw with no fee.

Non-custodial escrow#

Each pit gets its own vault account in the escrow program (Ea9p…UyUx). Funds only leave it through three instructions, all signed by the player:

  1. Deposit — you sign a transfer of your seat (entry + vault) into the pit vault.
  2. Claim — after settlement you sign to withdraw your payout (prize plus your share of the vault money).
  3. Recover — if the round is never settled, you sign to take your full seat back after the deadline.

The server's operator key opens pit vaults and records each player's final entitlement. It cannot transfer anyone's USDC, and total entitlements can never exceed what was deposited.

Practice mode. When on-chain escrow isn't configured the header shows Practice: pits, ranking and trading work (you still sign in with X), but no USDC moves and nothing is signed.

Cancellations & recovery#

  • Host doesn't fund seat #1 — the host picks a side (YES/NO or UP/DOWN) or decide later and pays seat 1 like everyone else. If the host rejects the deposit, or no seat is confirmed within 3 minutes of opening, the pit closes before anyone else can join.
  • Your seat follows your deposit — the escrow vault is the source of truth. If your deposit confirms but the page loses its connection before the seat is registered, the pit seats you from your on-chain entry automatically (before it locks, with the username and call you chose). A pit that has received a deposit can't be cancelled as empty.
  • Full refunds — when a pit closes without starting, every wallet that deposited (including a deposit that confirmed after the close) is refunded its full seat. The refund opens about two minutes after the close; claim it from the pit page. A deposit that lands after the round has already started is refunded in full at settlement.
  • Settlement never happens — as a last resort, once the pit's recovery deadline passes (an hour after the longest the game could possibly run) any depositor can call Recover on the escrow program and receive their full seat. Your Positions page shows a Recover button when that applies.

Crypto pits & the price oracle#

A crypto pit asks one question — for example “Will Solana be up in 5 minutes?” UP (a YES share) pays $1 if the asset closes the round above its opening price; DOWN (a NO share) pays $1 if it closes below. A dead-flat close pays 50¢ each way.

  • Opening call — when you take a seat you pick UP, DOWN or decide later. A call puts a quarter, half (the default) or all of your vault on that side at the opening price (50¢ a share) the moment trading opens; the rest stays in cash for your trades. You can change it until then, and switch or sell any time while the round is live — switching sides sells your current position and buys the other side in one step. Other players can't see your call until the round starts.
  • Open — the asset's spot price when enrollment locks. BTC, ETH and SOL are all recorded (a Predictions pit is judged on all three).
  • Live price — the UP price is the chance the asset finishes above the open, given the move so far and the time left, so positions gain or lose value as the asset moves.
  • Close — the price sample nearest the deadline (the pit is polled every few seconds while anyone watches; otherwise the one-minute candle at the deadline).
  • Source — Coinbase's public spot price, with Kraken as backup. If no price is available the lock or the settlement waits up to a minute; a round that still can't be priced settles at 50¢ both ways.

Trading in a pit#

Buying a side (YES/NO, or UP/DOWN on a crypto pit) moves USDC from your vault into shares; selling closes the position. Your vault value — cash plus marked positions — decides your rank and is what the cut line compares. On a Panta market every trade fills against the room book (see The room book) and is marked at the room's price; the last-call and price-moved rules below apply there too.

On a crypto pit every player trades on the same live prices, and three rules keep it fair:

  • 1¢ spread — you buy 1¢ above and sell 1¢ below the market price. Changing your mind is allowed any time, but flipping back and forth costs something, so re-trading every small lag in the price doesn't pay. Opening calls and settlement don't pay the spread.
  • Last call — trading closes 30 seconds before the deadline, so nobody can pile onto a near-certain outcome in the final seconds.
  • Live quotes — each trade is priced on BTC/ETH/SOL quotes taken at that moment from Coinbase and Kraken. While the asset is jumping, or the two exchanges disagree, trading pauses for a few seconds until the price settles. If the price moved more than 5¢ from the one you were shown, the trade isn't filled and you see the new price instead.

On a crypto pit that runs on a real Panta market you can switch on Also fill on Panta. The same order is then placed on Panta's primary book from your wallet, in six steps shown live in the trade panel:

  1. Quote — price, expected shares and fee from /primaryorderquote/.
  2. Build — Panta returns raw Solana instructions and a blockhash from /primaryorderbuild/.
  3. Sign — your wallet signs a v0 transaction compiled in the browser, with you as fee payer.
  4. Submit — the signature is registered with /primaryordersubmit/.
  5. Verify — /primaryorderverify/ is polled until confirmed, failed or expired.
  6. Attribute — /trades/{signature}/ confirms the trade was credited.

Panta integration#

All Panta calls are made server-side through The Pit's /api/* routes; the API key never reaches the browser. Requests carry The Pit's X-User-Idso trades and created markets are attributed.

Panta endpointUsed for
GET /markets/…Open markets for hosting, Panta's line, and resolution
POST /markets/create/{quote,build}/ · /markets/register/Creating a market for a pit
GET /positions/Your pits, positions and withdrawals
POST /primaryorder{quote,build,submit,verify}/Mirrored orders
POST /claim/build/Claiming a winning Panta position
GET /trades/{signature}/Attribution check

Signing in with X#

The Pit is played with an X (Twitter) account — there is no other way to sign in. Press Sign in with X, approve on X, and you come straight back signed in. Your X handle is your username on the pit stage, standings, activity feed and results; it is set the first time you sign in, and an X account is one player, so nobody can play under someone else's name.

  • Your Solana wallet — signing in creates a Solana wallet for your X account (a Privy embedded wallet). It is yours: it holds your USDC, pays your seats and receives your payouts.
  • See it any time — open your account (your handle, top right) for the full address with copy, QR and explorer links, its USDC and SOL balances, and where to get devnet test tokens.
  • Export the key — Export private key in the account menu opens Privy's own window to copy the wallet's key into another wallet app. The key is shown on Privy's domain; The Pit never sees it.
  • Sessions — signing in keeps you signed in on this browser for up to a week; Sign out ends it.

Your wallet & signing#

  • Fund it — send devnet USDC (from faucet.circle.com, choose Solana Devnet) and a little SOL for network fees (faucet.solana.com) to the address in your account menu.
  • Approving — a seat deposit, a withdrawal or a market creation opens a confirmation from your X wallet; nothing moves until you approve it.
  • Escrow deposit, claim and recover are transactions built by the server, checked with a dry run on Solana devnet before you see them, and signed by your X wallet. The app sends each one to devnet itself. Approve within about a minute; an older transaction expires and nothing is taken. The deposit carries a memo with the pit, the seat amount and the game type, visible on the explorer. It never includes your opening call or picks, since those stay hidden until the round starts.
  • Panta orders and claims are v0 transactions compiled in your browser from Panta's instructions.
  • Your X wallet pays the network fee for every transaction it signs.

Before any deposit the server checks your X wallet holds enough USDC for the seat (plus Panta's fee when you create a market) and about 0.005 SOL for fees, so you're never asked to approve a transaction that would fail.

API reference#

RoutePurpose
GET /api/arenasOpen pits (enrolling, live, settling, advancing)
GET /api/round?arena=Round state, standings, cut line, YES price, Panta line, price tape and live spot price for one pit
POST /api/roundOpen a new pit (creates its on-chain vault); marketSource: "panta" with a pantaMarketId or your draftId
GET /api/round/read?arena=The Oracle read for a trading pit
GET /api/markets/catalogOpen Panta markets a pit can be hosted on
POST /api/markets/{quote,build,register}Create a Panta market (signed in; the quote returns the fee and a draft id)
POST /api/auth/xSign in: Privy's proof of the X account and its wallet → session cookie
GET /api/auth/sessionWho this browser is signed in as (wallet and X handle)
POST /api/round/enrollTake a seat (signed in); returns needsDeposit until your on-chain deposit exists, pending while it confirms
POST /api/round/callChange your opening UP/DOWN call while enrolling
POST /api/round/picksPredictions: change picks or your lock while enrolling. Streak: pick the open leg (signed in)
POST /api/round/cancelCancel a pit whose host never funded seat #1
POST /api/round/tradeBuy a side or sell inside the pit (signed in)
GET /api/escrow/statusOn-chain or practice mode
GET /api/escrow/balance?wallet=Devnet USDC and SOL for a wallet
POST /api/escrow/txUnsigned deposit, claim or recover transaction
POST /api/escrow/settleRecord final entitlements on-chain (idempotent)
POST /api/orders/{quote,build,submit,verify}Panta order proxies
GET /api/portfolio?wallet=A wallet's pits: live positions, standings, and payouts or refunds to withdraw (game ledger + on-chain deposits)
GET /api/positions?wallet=Panta positions for a wallet

Trust model#

You rely onForIf it fails
Escrow programHolding depositsFunds only move with your signature
The Pit serverRunning rounds, the room book and recording resultsRecover returns your full seat after the deadline
Price oracle (Coinbase, Kraken)Crypto pits: opening and closing pricesThe round waits up to a minute, then settles at 50¢ both ways
PantaMarkets, the opening line, resolution, mirrored ordersA pit already trading keeps its room book and settles on its own average
Claude (optional)Phrasing the Oracle readThe read falls back to the plain data read
Your X wallet (Privy)Every signatureNothing moves without your approval; export the key to use the wallet elsewhere
X and PrivySigning inYou can't sign in until they're back; deposits stay in escrow and recovery still works with the exported key

FAQ#

How do I sign in? Do I need a wallet?

Sign in with X — that is the only way in, and no wallet extension is needed. Signing in creates a Solana wallet for your X account (a Privy embedded wallet) that holds your USDC and signs your deposits and payouts. Open your account (your handle, top right) to see its address, balances and where to get test funds.

I already used a Phantom/Backpack wallet here — what happens?

Sign-in is now X-only, so you play with your X account's own wallet. Your username carries over. Any unclaimed payout still sitting in that old extension wallet can only be withdrawn by signing with that wallet directly on the escrow program — the app no longer drives extension wallets.

Where do I get test funds?

Devnet USDC from faucet.circle.com (choose Solana Devnet) and devnet SOL for fees from faucet.solana.com. Send them to the wallet address in your account menu.

Can I move my wallet to Phantom or Backpack?

Yes — Export private key in the account menu opens Privy's own window (on Privy's domain, never shown to The Pit) to copy the key into another wallet app.

Why doesn't the pit's price match Panta's?

It starts at Panta's line and then moves with the room's own trades. The gap between the two is part of the game — the stage and chart always show both.

Can the host take my deposit?

No. The host only chooses the settings. Deposits sit in the escrow program and only your signature can withdraw them.

Do I have to pick a side when I sit down?

No — choose decide later and trade once the round is live. If you do pick, the share of your vault you choose (a quarter, half or all of it) goes on that side at the opening price, and you can still switch or sell during the round. Predictions pits have no call: you answer five questions instead.

In a Predictions pit, can anyone see my picks before the start?

No. Until the round locks, other players only see how many of the five questions you have answered. Your picks aren't in the public deposit transaction either. Once the round starts, every player's picks are shown.

In a Streak, what if I miss a pick window?

No pick counts as a wrong pick, so you're out — unless every other player still in misses that leg too, or it ends level. Keep the pit open while you play; each window is 20 seconds.

What if I close the tab mid-round?

Your position stays open and is closed at the final price like everyone else's. Come back after the round to withdraw.

Why not trade on Panta directly?

You can. The Pit adds the game: equal seats, a shared pool, a room that trades its own odds, live rankings and eliminations.

Is The Pit part of Panta?

No. It is an independent product built on the Panta Public API for the Panta API Sidetrack of the Colosseum hackathon.