AI models.
Real accounts.

01Overview & how the operator earns

PIT has three parts, all served by one Node.js server from one codebase:

How a decision happens

1. Your browser tab at #/runner reads live market data and the competitor's account from Hyperliquid.
2. It sends them to your server (POST /api/decide). The server calls the model's API with your key and returns the model's decision (long, short, close or hold, with its reasoning).
3. The runner re-reads prices, runs the risk gate (leverage cap, position size, stop loss required, and so on) and, if the decision passes, signs and sends the order in your tab. The server never signs.
4. The runner reports what it sent. The public page marks the decision On-chain only when its order ids appear in the account's public fills.

How the operator earns: the Hyperliquid builder fee

Hyperliquid lets an interface add a builder fee to orders it sends. Hyperliquid collects it from the trader on top of its own trading fees and pays it to the builder address. In PIT:

• The fee is set in config as builder: { "address": "0x…", "feeTenthsBps": 10 }, or in Admin → Fees. It ships as null (no fee), and there is never a default address.
• feeTenthsBps is in tenths of a basis point: 10 = 1 bp = 0.01%. The config schema accepts 0 to 100, and 100 = 0.1%, the maximum for perps.
• When set, the fee is attached to every order the arena runner sends and every order Ride sends for viewers. Only the Ride orders earn you anything: on the arena's own sub-accounts you pay the fee to yourself, so it nets to zero (Hyperliquid also charges its own trading fee on top).
• Example: at 10 (0.01%), $100,000 of order volume pays $10. At 100 (0.1%) it pays $100. The Fees screen shows this calculation live.
• 100 USDC rule: Hyperliquid accepts builder fees only if the builder address holds at least 100 USDC in perps account value. If it holds less, Hyperliquid refuses every order carrying the fee. Both the runner and Ride check this and block sending until it is fixed.
• Approval: each trading account must approve the fee once (approveBuilderFee, signed by the master wallet in the runner and by each viewer in Ride). The runner shows the approved maximum (maxBuilderFee) for the master and for every competitor sub-account.

Builder-fee income therefore depends only on how much your riders trade through Ride. Since v0.3.0 the main revenue streams are membership, sponsor slots, white-label work and affiliate links; see How you earn on the product site. PIT does not estimate or promise any revenue figure.

02Requirements

03Installation (local)

Open a terminal in the project folder, then:

npm install
cp .env.example .env                           # then edit .env
cp arena.config.example.json arena.config.json
npm run dev                                    # web on :5173 + API on :8787

Open http://localhost:5173/ in your browser. In development Vite serves the web app on port 5173 and forwards /api to the server on port 8787.

• If arena.config.json is missing, the server falls back to arena.config.example.json and logs a warning. GET /api/health shows which file is in use (configSource).
• The log line ExperimentalWarning: SQLite is an experimental feature comes from Node itself and is harmless.
• Without OPERATOR_TOKEN (or a token generated in Admin → Operator) the operator endpoints answer 503. Without ADMIN_PASSWORD the admin panel is off.
• arena.config.example.json ships with "network": "mainnet". Set season.network to "testnet" in your copy before your first run (see Running a season).
• .env.example sets RIDE_ENABLED=false and RIDE_BLOCKED_COUNTRIES. Both override the config file and the admin Ride switch for as long as they are in your .env.

npm run build
HOST=127.0.0.1 ADMIN_COOKIE_SECURE=false npm start    # then open http://127.0.0.1:8787/#/admin

Useful commands

04Configuration

PIT reads settings from two places:

• arena.config.json: everything about the arena (season, competitors, fee, league, Ride, branding). The server validates it and hot-reloads it about one second after you save by hand. The admin panel writes the same file. If you edit it by hand and the new file is invalid, the server keeps the previous config and logs the error.
• Environment variables (.env locally, host secrets in production): secrets and server settings. Values already set in the real environment win over .env.

arena.config.json: every field

The schema lives in shared/admin.ts (configSchema). The server and the admin panel both use it. Fields marked "optional" may be left out.

brand

season

competitors[] (up to 20)

builder, league, ride

Optional sections (usually edited in the admin panel)

Environment variables: every variable the server reads

This list was built by searching the server code for every environment read (server/** and deploy/backup.mjs). Empty values count as "not set".

Precedence: a provider key in the environment always wins over a key saved in the admin panel. RIDE_ENABLED and RIDE_BLOCKED_COUNTRIES win over the config file and the admin panel, and the panel shows which fields are overridden.

05Admin panel guide

Set ADMIN_PASSWORD and PIT_SECRET, restart the server, then open /#/admin on your site (the public footer also links to Admin). See the note on local development.

• Sign-in: 5 wrong passwords lock that client out for 15 minutes, and there is also a global limit across all clients. A session lasts 12 hours in an httpOnly, SameSite=Strict cookie.
• Saving: edits collect in a save bar. Every save is validated with the same schema as the server, written atomically, versioned and audited. Open public pages update live.
• Safety confirmations: switching the network to mainnet and turning Ride on each ask for an explicit confirmation. If the file changed in another tab or by hand since you loaded it, the save is refused (stale) until you reload.
• The panel never touches a trading key or an order.

The 12 sections

1. Dashboard

Live status, refreshed every 10 s: uptime and version, open stream connections ("Live viewers"), runners with a recent heartbeat, providers with a key, each competitor's live equity and positions from Hyperliquid and its decisions in the last 24 h, league status and last error, operator token source and encryption key source. Test makes one small real call to a provider using the first matching competitor's model id.

2. Brand & site

Site name, tagline, hero headline (up to 3 lines), accent colour with contrast checks, default theme (system/dark/light), announcement banner (text, tone, optional link), SEO title and description, OG image, footer links, social links and the disclaimer.

3. Season

Id, name, start and end (UTC), network (testnet or mainnet, with confirmation), coin picker (reads the live Hyperliquid list, sorted by 24 h volume and shows each coin's own max leverage), decision interval and risk limits, with a worst-case exposure line. Start a new season archives the current id into pastSeasons and starts a fresh leaderboard. Nothing is deleted, and an archived id cannot be reused.

4. Competitors

Add, duplicate, remove, reorder (drag or arrows), enable or disable. Per competitor: name, id, avatar initials, provider and model id, colour, Hyperliquid account (checked live: checksum, existence, equity), public style prompt, and optional leverage and interval overrides.

5. Models & API keys

Paste a provider key. It is stored AES-256-GCM encrypted in the database and never shown again, only a ••••abcd hint. Environment keys win. Per provider you can set base URL (for an OpenAI-compatible gateway), timeout, max output tokens and temperature, and test the key. Keys save immediately. Call settings save with the save bar.

6. Prompts

Edit the trading and forecast system prompts with {{variables}}. Click a chip to insert one. The live preview renders the draft with real Hyperliquid data (trade) or a real league market (forecast). Keep {{outputSchema}} in both templates: parsing depends on it. See Customization.

7. Fees

Builder code on or off, builder address, fee in tenths of a bp (0–100), presets 0.5 / 1 / 2.5 / 5 / 10 bp, and a worked example on $100,000 of volume.

8. Ride

On/off switch with legal warning and confirmation, blocked countries (with a "strict preset": US, CA, GB, SG, HK, MY), and rider limits and starting values (rideCaps). A warning appears when an environment variable overrides the switch or the list.

9. League

Status, Refresh now and Forecast now buttons, selection rules (markets in play, closes within, min volume, re-forecast hours, price band), pin a market by Polymarket URL, slug or id (binary markets only), and exclude a market from play.

10. Operator

Generate a new operator token (shown once; only its hash is stored; the previous generated token stops working), revoke it, and see the last heartbeat per competitor. OPERATOR_TOKEN from the environment keeps working until you remove it there.

11. Audit log

Every admin write and sign-in, with time, anonymous session label, section and a redacted diff. Addresses are shortened and secrets are never recorded.

12. Config history

Every saved version, including hand edits of the file. Compare any version with the current one and roll back (the rollback is itself a new version). Export downloads the stored arena.config.json. Import validates a file and shows the exact diff before applying.

06Running a season

1 · Accounts: master + sub-accounts

1. Use one Hyperliquid master wallet. Create one sub-account per competitor under it and fund each. One competitor may use the master itself.
2. Put each address in competitors[].address (or Admin → Competitors). Until then the competitor shows "Awaiting account".
3. Keep a USDC balance on the master too. Hyperliquid prunes an API wallet (the runner's agent key) when the account that registered it has no funds. If you move every dollar to the sub-accounts, the agent disappears, orders fail, and the runner stops with "agent no longer approved". The runner's Setup shows a warning while the master is empty.
4. Start each season with flat accounts (no open positions), so the season PnL can be computed exactly. See How the numbers are computed.

2 · Keys, token and season

• Set the provider keys you have and OPERATOR_TOKEN (or generate one in Admin → Operator).
• Set season.startsAt, coins, interval and risk limits. Check that every model id is current.
• Optional: set the builder fee and make sure the builder address holds ≥100 USDC perps account value.

3 · The operator console (#/runner)

Open #/runner (footer → Operator) in a desktop browser with your wallet. Setup has four steps:

1. Operator token. Paste it and click Use. It is kept in this tab's sessionStorage only.
2. Master wallet. Connect it. The console lists the master and its sub-accounts with equity and which competitor each belongs to.
3. Agent key. Choose 1, 7, 30 or 90 days and click Authorise agent. The tab generates a key, and your wallet signs one approveAgent named pit-runner. The agent can place and cancel orders for the master and its sub-accounts and can never withdraw. Approving again replaces it.
4. Builder fee (only if configured). Approve the fee from the master. The table shows maxBuilderFee per trading account.

4 · Dry run, then live

• Dry run is ON when the console opens. Models are asked, the risk gate runs on live data, but no order is sent. The public feed shows "rejected · dry run", so viewers see honestly what happened.
• Click Start all (or start one competitor). Competitors run on their interval, staggered. Watch the live log and the "Market feed" check (coins, 96 × 15 m and 60 × 4 h closed candles).
• When dry run looks right, untick Dry run. The console then requires a valid agent key, a matched master or sub-account, and a working builder setup (if configured) before a competitor can start.

What the runner does each tick: build the market and account snapshot → safety sweep (a position without a PIT stop gets a protective stop, and leftover PIT orders with no position are cancelled) → ask the model → re-read prices and reject if the price moved more than minStopDistance → risk gate (allowed coin, leverage ≤ season / competitor / exchange / liquidation-safe cap, margin ≤ share of equity, stop required and within bounds, ≥ $10 notional, one position per coin, max open positions) → send an isolated-margin entry (IOC) with resting stop and optional target → report to the server. After 5 consecutive failures a competitor stops with an error.

5 · Keep the tab open

6 · Kill switch

The red Kill switch in the console header stops every loop immediately. In-flight ticks check it before sending any order. Open positions keep their resting stop and target orders. Use Reset kill switch and start competitors again when ready. To close positions, use Hyperliquid itself. The kill switch does not close them.

7 · Ending and starting seasons

Use Admin → Season → Start a new season. The old season id is archived; its decisions stay in the database but the public site shows only the new season.

07How the numbers are computed

Every performance figure is read live from Hyperliquid by address, in the viewer's browser. The server stores only what the models said and what the runner reported. Nothing is seeded, simulated or interpolated.

On-chain verification by cloid

Every order the runner sends carries a 16-byte client order id (cloid) tagged 0x9171… (Ride uses 0x9172…), with a role byte for entry, stop, target, close or guard. A decision is labelled On-chain only when one of its cloids appears in the competitor's public fills. An executed decision without such a fill shows "Sent · unconfirmed". The other states are Proposed, Held, Rejected (with the risk note) and Failed (with the error). Each decision also stores servedModel (the model id the provider says answered) and snapshotHash (sha256 of the market and account data the model was shown).

"—" means unknown

When a figure cannot be computed honestly, PIT shows "—", never 0 and never an estimate. Unfunded competitors show "Awaiting account", and competitors without a key show "No model key".

08Prediction league

The same models forecast real Polymarket markets. No money is involved. The server runs this on its own; no runner tab is needed.

• Every 10 minutes the server refreshes tracked markets, records resolutions and fills open slots with eligible markets: binary, open, accepting orders, closing between 30 minutes and maxDaysToClose days from now, with 24 h volume ≥ minVolume24h, priced between 2% and 98% (and inside your optional band). Busiest markets are picked first.
• Each model with a key forecasts the probability of the first outcome, at most once per reforecastHours per market. The market price at that moment is stored as the benchmark.
• Scoring: Brier score (p − outcome)² on each model's last forecast before the market closed, averaged over resolved markets. Lower is better: 0 is perfect and 0.25 is a coin flip. The market's own Brier at the same moments is shown as the bar to beat. Scores exist only for markets Polymarket has resolved.
• Admin → League can refresh, run a forecast pass, pin a market and exclude a market.

09Ride (viewer copy trading)

What it does

A viewer opens a competitor page and mirrors that model from their own Hyperliquid account, in their own browser tab. Nothing passes through your server. The steps are: accept the risks → connect wallet → authorise a trading key named pit ride (1 or 7 days, cannot withdraw) → approve the builder fee if set → choose sizes → ride. Ride watches the competitor's public fills. It acts only on PIT-tagged fills that happen after the viewer pressed Start: an entry becomes one IOC order with the viewer's own resting stop, and a stop, target or close becomes a reduce-only close. It never chases a price, and it halts itself at the viewer's loss stop. Viewers choose every amount. Your rideCaps maxima are always enforced. Starting values are pre-filled only if you saved your own in Admin → Ride.

Country gate: Cloudflare + TRUSTED_PROXY_SECRET required

• The server believes the country header (RIDE_COUNTRY_HEADER, default cf-ipcountry) only when the request also carries x-pit-proxy-secret equal to TRUSTED_PROXY_SECRET. Otherwise the country is unknown and Ride is refused (it fails closed).
• Fly.io and Render send no country header, so the site must sit behind Cloudflare (proxied). Add a Transform Rule: Rules → Transform Rules → Modify Request Header, when hostname equals your arena host, set static header x-pit-proxy-secret = your secret. Set the same value on the server.
• Unknown countries (XX, T1 for Tor and similar) are refused. Blocked countries are refused.
• The Ride code ships in the public bundle even when disabled. The gate is an operator control, not a technical impossibility.

Enable it (only after the above)

1. Cloudflare proxy with the Transform Rule, and TRUSTED_PROXY_SECRET set on the server.
2. Remove RIDE_ENABLED=false from the host environment (it overrides everything).
3. Admin → Ride: review blocked countries and rider limits, switch on, save, confirm.
4. Check GET /api/ride/eligibility from an allowed and a blocked location.

10Customization

Branding (no code)

Admin → Brand & site covers name, tagline, headline, accent colour, theme, banner, SEO, OG image, footer and social links, and the disclaimer. The accent replaces the built-in volt #D7FF32. Market green and red never change.

Competitors

Add or edit them in Admin → Competitors or in arena.config.json. Any mix of the five providers works, up to 20 competitors. The model id must be exactly what the provider's API expects. The example config ships claude-opus-5-5, gpt-6-sol, gemini-3.8-flash, grok-4.7 and deepseek-v4-pro, checked against provider docs on 2026-09-23.

Prompts

Trade template variables: {{name}}, {{brand}}, {{network}}, {{season}}, {{seasonId}}, {{intervalMin}}, {{coins}}, {{maxLeverage}}, {{maxPositionPct}}, {{maxOpenPositions}}, {{minStopPct}}, {{maxStopPct}}, {{slippageBps}}, {{risk}}, {{outputSchema}}, {{style}}. Forecast template variables: {{brand}}, {{outputSchema}}. Unknown variables are left in place and reported in the preview. The built-in defaults are in server/prompts/trade.ts and server/league/prompt.ts. Changing the prompt does not loosen the risk gate: the runner enforces the limits regardless.

Design tokens

Colours, fonts, radii and motion are CSS variables in web/src/styles/tokens.css (dark first, light theme included). Fonts: Big Shoulders Display (display), Geist (UI), Geist Mono (numbers), loaded from Google Fonts in web/index.html. Admin styles: web/src/admin/admin.css. Arena styles: web/src/app/site.css, web/src/styles/app.css. Favicon and share image: web/public/. After code changes run npm run typecheck && npm test && npm run build.

11Deployment & updating

Full reference: docs/DEPLOY.md in the package. In short:

• The arena needs exactly one always-on instance with a persistent disk. It holds SSE connections, runs league timers and writes one SQLite file. Never scale to two machines.
• Docker: the Dockerfile builds the SPA and bundles the server, runs as the non-root node user on port 8080, keeps data in /data (pit.db, arena.config.json, backups/), and health-checks /api/health. Note: at v0.2.0 the image has not been built by the author yet (no Docker available); the CI workflow builds it.

Fly.io (recommended)

fly auth login
fly apps create <your-app>                  # change `app` in deploy/fly.toml to match
fly volumes create pit_data --app <your-app> --region fra --size 1
fly secrets set --app <your-app> --stage OPERATOR_TOKEN="$(openssl rand -hex 32)" ANTHROPIC_API_KEY=...
#   optional admin: ADMIN_PASSWORD="$(openssl rand -base64 24)" PIT_SECRET="$(openssl rand -hex 32)"
fly deploy . --config deploy/fly.toml --dockerfile Dockerfile --ha=false
curl -fsS https://<your-app>.fly.dev/api/health

Upload your config with fly sftp shell → put arena.config.json /data/arena.config.json, then chown node:node it. It hot-reloads. Custom domain: fly certs add plus a CNAME to <your-app>.fly.dev.

Render (alternative)

deploy/render.yaml is a Blueprint: one Docker instance with a 1 GB disk at /data (needs a paid plan). Go to New → Blueprint, choose deploy/render.yaml, fill in the secrets, and paste your config into /data/arena.config.json via the Shell tab.

Landing page on Vercel

The optional marketing page in landing/ is static files with no build step, and landing/vercel.json (security headers, Content-Security-Policy, clean URLs) is ready to use. Run npm run sync:docs first so this guide is served at /docs/, then, from landing/, vercel link and vercel deploy --prod. Vercel cannot host the arena itself.

Backups

• The database runs in WAL mode, so never copy pit.db alone.
• Fly volume snapshots: daily, kept 14 days. Create one before every upgrade.
• deploy/backup.mjs makes a consistent copy (VACUUM INTO) in /data/backups and keeps the newest 14 (PIT_BACKUP_KEEP).
• To restore, upload a backup as /data/restore.db and restart. The entrypoint swaps it in and keeps the old files.

Updating to a new version

npm ci && npm run typecheck && npm test && npm run build
fly volumes snapshots create <volume-id>      # migrations are forward-only
fly deploy . --config deploy/fly.toml --dockerfile Dockerfile --ha=false

A deploy restarts the single machine. Viewers reconnect on their own, runner heartbeats reset, and the operator tab must stay open. To roll back, deploy the previous image. If a migration ran, restore the pre-upgrade backup with it. Keep your own arena.config.json and .env. They are not part of the package.

12Security & custody model

• The server never holds a trading key and never signs. It stores config, calls model APIs with your keys (server-side, never sent to browsers), stores decisions and runner reports, and serves the live stream.
• Arena orders are signed in your browser tab by an agent key generated there (sessionStorage only), approved once by your master wallet. The agent can trade and cancel but cannot withdraw, and it expires.
• Ride orders are signed in the viewer's tab with the viewer's own agent key.
• Operator token: compared in constant time. Wrong tokens are slowed down and then refused per client IP. A correct token is never throttled.
• Admin: off unless ADMIN_PASSWORD is set. Login lockout, signed 12 h session cookie (httpOnly, SameSite=Strict, Secure in production), a custom header plus same-origin check on every write, API keys encrypted with AES-256-GCM, and an audit log with shortened addresses.
• Proxy headers (country, client IP) are trusted only with TRUSTED_PROXY_SECRET.
• The server sends a Content-Security-Policy and never serves source maps (*.map).
• Treat OPERATOR_TOKEN, ADMIN_PASSWORD, PIT_SECRET, TRUSTED_PROXY_SECRET and provider keys as passwords. Never commit .env.

13Troubleshooting

14FAQ

Has PIT traded real money?

Not at v0.2.0. The order path is unit-tested but has not sent a real order on testnet or mainnet. Your testnet run is the first live check.

Will the models make money?

Nobody can say. Results are never guaranteed, and past results say nothing about the future. PIT's job is to show results honestly, including losses.

Does the server need my private key?

No. The server never signs. Your wallet signs the agent approval (and builder fee) in your browser.

Can I run it without the builder fee?

Yes. builder: null is the default.

Can I use only one or two models?

Yes. Disable or remove the others. A competitor without a key simply stays idle.

Can I run it on Vercel, Netlify or shared PHP hosting?

No. It needs a persistent Node.js process and a disk. Use Fly.io, Render or your own server or VPS with Docker.

Is the Ride feature legal where I am?

PIT cannot tell you. Get advice for your jurisdiction and your viewers' before enabling it.

What happens to open positions if my computer sleeps?

Trading stops. Positions keep their resting stop and target orders on Hyperliquid.

Where is my data?

Config in arena.config.json, decisions, forecasts, admin audit and encrypted keys in the SQLite file (PIT_DB). Performance itself lives on-chain.

15Credits & licences

Production dependencies, including transitive ones (npm ls --omit=dev --all), with the licence read from each package's LICENSE file in node_modules:

No production dependency uses a GPL, AGPL or other copyleft licence. Development tools (Vite, Vitest, tsx, esbuild, concurrently, @vitejs/plugin-react, type packages) are not shipped in the runtime image.

Fonts: Big Shoulders Display, Geist and Geist Mono are loaded from Google Fonts at runtime and are not bundled. Google Fonts lists them under the SIL Open Font License 1.1 (not verifiable from files in this package).

Services: Hyperliquid (market data and execution), Polymarket Gamma API (league), and the model providers you choose. Their terms apply to your use.

PIT's own licence: package.json points to LICENSE.md. Read the licence delivered with your purchase.

16Changelog

0.2.0 · 2026-09-23

• Admin panel #/admin with 12 sections: signed sessions, encrypted provider keys, audit log, config history with rollback, live apply to public pages.
• Exact season PnL from fills; "—" instead of zeros for unknown values; current model ids; operator-token lockout; Ride stop-failure protection; runner price re-check; proxy-secret country gate; 100 USDC builder rule.
• Provenance: servedModel stored per decision and forecast, snapshotHash per decision (database migration v2).
• Deploy kit: Dockerfile (bundled server, non-root, /data volume), Fly.io and Render configs, CI, backups.

0.1.0 · 2026-09-22/23

• First version: API contract, server (API, SSE, SQLite, 5 model providers, Polymarket league), public arena, operator console with risk gate, Ride module, landing page.

Known limits at 0.2.0

• No real order sent yet. Builder-fee coverage of sub-accounts unverified. Docker image not yet built by the author.
• Admin sessions, login lockouts and runner heartbeats are in memory and reset on restart.
• Hyperliquid serves at most 10,000 recent fills per account.