> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ballista.gg/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Ballista is a trading client for Polymarket, not an exchange. Every order Ballista places goes to Polymarket's CLOB.
> There are three end-user surfaces — the Telegram bot, the web terminal and the Chrome extension — and they share ONE account and ONE balance. Never attribute a feature to a surface without checking that surface's source.
> Every user registers in the Telegram bot first. The terminal and the extension sign in with the Telegram login widget. There is no other sign-up path.
> Deposits arrive through EVM, Solana and Bitcoin bridge addresses and a Polymarket proxy wallet, with a $10 minimum. There is NO withdrawal UI — Export Keys is how a user takes custody of their funds.
> Feature parity is uneven and must never be assumed. The full ~30-field copy-trade form exists only in Telegram; the terminal's copy form has 7 fields; the backtester, leaderboard and trader profiles are terminal-only; alerts and notifications are extension-only; referrals are Telegram-only.
> Slippage means two different things. On a live copy trade it is a fill tolerance (default 30). In a backtest it is the simulated fill price (default 1). Deploying a backtest does not carry its slippage over to the live copy trade.
> Take-profit and stop-loss run on live copy trades but are NOT simulated in backtests — the backtest API rejects those fields.
> A backtest never places an order and never moves funds. Its fidelity caveats are published with every result and must be quoted, not paraphrased.
> Leaderboard PnL is own-tape: harvested by Ballista from its own trade tape. The leaderboard sorts by one transparent metric at a time and there is NO composite score or grade. The sparkline exists only for harvested wallets — a blank sparkline means unmeasured, never zero.
> Copy friction (slip) and a toxic flag DO exist and are own-engine: the wallet's own 30-day fills replayed as a taker (1% slippage per fill plus the real Polymarket taker fee schedule) against its actual 30-day PnL over the same fills, so the delta is pure friction. slip_pct is already a percentage, not a 0-1 fraction. The toxic flag is server-computed under evidence guards and is never re-derived client-side. Slip is not a sortable column. Blank means unmeasured — never zero and never clean.
> Copyability is a taker share, reported in aggressive (≥60%), passive (≤30%) and mixed bands. It is never a score.
> Do not document Feeds, the Twitter Tracker, the Telegram Settings button, percentage buy buttons, GTD orders, the Discord bot, or withdrawals.
# Backtest fidelity
> The standing list of ways a simulated run is not reality — shipped with every result, in full.
Every backtest result carries the same disclosure list. It is part of the **result**,
not of the page rendering it, so no caller can drop it for being inconvenient, and it
does not change from run to run.
Alongside it, each result states the assumptions it actually ran under: the resolved
buy and sell slippage percentages, that fees were modelled, and that the slippage
model was **fill price**. Read the headline number with both in view — a P\&L figure
quoted without the execution cost it assumed is not a number.
Here is that list, in full.
## Fills
**Every admitted order fills completely.** There is no order-book depth, no queue
position and no latency model. If your configuration allowed the order, the
simulation placed it and got all of it.
**Slippage is applied as the fill price, not as a limit that might go unfilled.** A
wider slippage setting makes the simulated fill *worse*, never *rarer*. This is the
single largest difference from live behaviour, where slippage is a tolerance and an
order outside it simply does not fill.
**Limit prices are quantized to whole cents**, matching the live executor's default
tick grid, and the fill is booked at that limit — except where the limit would beat
the leader's own fill price. A buy limit clamped to 99¢ under a leader fill above it,
or a sell limit that rounds up toward \$1.00, is instead booked at the leader's price,
because live that order would simply not have filled. Results report how many fills
this correction touched.
**Rows the engine cannot price are dropped entirely** — a fill at exactly \$1.00 or 0,
an unrecognised direction, a non-positive size. They are dropped from the copier *and*
from the leader baseline, so the two stay comparable, and they appear as `invalid_fill`
data gaps.
## Decisions
**Decisions are made per tape row.** The live engine first folds a settlement's fills
into one order per wallet, token, side and role, and decides on the fold. Six $6 fills
of one sweep are **six $6 decisions here\*\* and **one \$37 decision live**, and a sweep
that straddles a price band is copied partially here and all-or-none live.
The settings this changes are **min price, max price, ignore trades under, ignore
trades over, min per trade and max per trade**. Configure them against **fill size**
when reading a result, and against **sweep size** when deploying the same
configuration as a copy trade.
## Spend caps
**The cumulative USDC spend caps run through the same gate as live, at the same point
in the pipeline, but against different accounting:**
* The **simulator** charges them against **open exposure at cost** and releases the
budget as positions close, so a market it has sold out of can be re-entered.
* **Live** charges **lifetime committed spend** and never gives it back. A copy trade
that has spent its total spend limit stops buying **permanently**, and one that has
spent its per-market cap never buys that market again.
A configuration whose caps let it keep trading all window here can go quiet within
days of being deployed.
## Valuation
**Open positions are valued at the price as of the window end** you supplied. Markets
that resolved *after* the window end are marked, not settled.
**A mark is the last print at or before the window end** within the loader's lookback,
which is 300 hourly buckets wide — so a book that stopped trading is marked at an older
price rather than at nothing. Marks struck **more than 24 hours** before the window end
are reported as `stale_mark` data gaps and count towards the stale-valuation reliability
check, alongside positions with no mark at all.
**A market that resolves inside the window is redeemed to cash at the next fill on the
tape**, not at the instant it resolved. The equity curve values it at its payout from
the resolution onward, but the cash-versus-positions split in the daily buckets catches
up only at that next fill.
**Mid-window equity values a resolved position at its payout** rather than at the last
tape price carried forward — so an equity bucket can move on a resolution with no tape
event behind it. Carrying a price forward applies only until a market resolves.
## Fees
**Fees are modelled from a pinned per-category taker schedule, not read from the
tape.** The fee on the tape is the *leader's*, including the leader's own builder and
referral basis points, which are not yours.
**Maker rebates, gas and any Ballista platform fee are excluded.**
## Not simulated at all
**Take-profit, stop-loss and balance-level take-profit and stop-loss are not
simulated.** They need an intra-window price path that a tape of the leader's own
fills does not contain. This is why the backtester rejects those fields outright
rather than accepting and ignoring them — see [Backtesting](/guides/backtesting).
**The leader's splits, merges, NegRisk conversions and redemptions are not
simulated.** None of them is a copyable order. How much of the wallet's activity they
account for is measured and disclosed on the result as **structural share** — see
[Reading a result](/guides/reading-a-result).
## What to read next
Reliability, boundary exposure, data gaps and fee confidence.
What a run is, and what it accepts.
The live behaviour these notes are measured against.
Why a good backtest on a passive wallet still copies badly.