> ## 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.
# Running a backtest
> Submitting a run: the form, the queue, and what the run list can and cannot show you.
A backtest replays a wallet's real fills through a copy-trade configuration and tells
you what that configuration would have done. Nothing here places an order. What a
simulation can and cannot tell you is covered in [Backtesting](/guides/backtesting)
and [Backtest fidelity](/guides/backtest-fidelity).
The backtester is a terminal-only feature.
## The form
Seven sections. The three that change the answer most are open when the page loads;
the rest start collapsed.
The wallet to replay, the **starting capital** the simulation is given (default
\$1,000), and the **window**: the last 7, 14, 30, 60, 90 or 180 days. 180 is the
ceiling.
Starting capital is badged **not deployable** — it shapes the simulation but has
no counterpart in a live copy trade. It is required.
Once the address is complete, the same two panels the copy-trade form shows
appear under it: a **passive wallet** warning when at or under 30% of that
wallet's volume crossed the spread, and a small research panel with its P\&L and
most recent activity. The warning is a caution, not a block — finding out how
much of a passive wallet's P\&L survives being copied is a fair reason to run
this.
**% of target** or **Fixed USDC**, and the value — which is required. There is
one value box and one mode, so setting both is impossible.
Then three switches: **Copy buys**, **Copy sells** (both on) and **Reverse
sides** — buy what they sell and sell what they buy. Turning both buy and sell
off is rejected: nothing would be copied.
Buy and sell slippage, prefilled at 1%.
Here it is a **simulated execution cost** — a real setting, not a formatting
detail, which is why the section is open rather than hiding a default you never
saw. `0` fills at the leader's own price. It means something different on a live
copy trade and is not carried into one; see
[Backtesting](/guides/backtesting).
Minimum and maximum entry price in cents; ignore the leader's trades under or
over a size; minimum and maximum per copied trade. Plus **Buy at the minimum
instead of skipping**, for when a sized order lands under your minimum.
These six are decided per tape row here and per folded sweep once deployed, so
they behave slightly differently live.
Total spend cap, max per market, max per YES and max per NO.
Only copy within N seconds of resolution, or within N seconds of a market
opening; a maximum holder count; and market tags — comma-separated Polymarket
tag slugs, any one of which admits a market.
A category allowlist, required keywords and excluded keywords. These exist only
in the simulator. A run that uses them cannot carry them into a copy trade, and
the section is badged to say so.
The target wallet, the starting capital and the sizing value are required. Every filter,
cap and gate may be left blank, and blank means "not set" rather than zero — a blank
bound is no bound at all, not a bound of nothing.
## Errors
Nothing turns red until you press **Run backtest** for the first time — a half-typed
wallet is not an error yet.
After that, invalid fields are flagged inline and a collapsed section holding one is
forced open with a count on its header, so "fix the highlighted fields" never points
at something you cannot see.
## The queue
You may have **at most two runs queued or running at once**. Submitting a third is
refused with a message that stays on the page rather than a toast that vanishes.
A run pulls the whole trade tape for the target wallet from a rate-limited source, so
it can take minutes. Wide windows take longer.
## Duplicates
Submitting a configuration identical to one already in flight does not start a second
run. The terminal tells you *"An identical backtest is already running — opening it"*
and takes you to the existing run. A genuinely new run says *"Backtest queued"*
instead. Either way you land on the run's page.
## Watching a run
The run page shows a progress bar and names the stage: waiting for a runner, fetching
the leader's trade tape, loading market metadata and resolutions, simulating your
configuration. It updates itself — leaving and coming back is safe.
It also shows the **configuration as it was normalised**, in a collapsible panel: the
values the run actually used, not the ones you typed. That is where to check what a
blank field resolved to.
A failed run says so and shows the runner's own reason. Nothing partial is displayed,
because a partial result would be worse than none. Submitting the same configuration
again queues a fresh run.
## Your runs
The list at the top of the backtester page: target wallet, window, status (with a
percentage while running), **Sim P\&L**, and when it was queued. Click any row to open
it.
The **Sim P\&L** column only has a figure for runs you have already opened in this
browser session. The list itself does not carry results, so a finished run you have
not opened yet shows an em dash. That dash means "not loaded here", not "zero" and
not "failed" — open the run to see the number.
## What to read next
The stat tiles, the charts, and the skip breakdown.
Turning a run into a copy trade.