> ## 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.
# Copy trading
> Mirror one wallet's Polymarket trading into your own account, order for order, on your own rules.
A copy trade is a standing instruction: *watch this wallet, and whenever it trades,
place my own version of that trade*.
Ballista is a client for Polymarket, not an exchange. Every copy is a real order
placed on Polymarket's order book from your own Polymarket proxy wallet, with your
own funds. Nothing is pooled, nothing is netted against other users, and the leader
never sees or touches your account.
## How the engine follows a wallet
Ballista's worker holds a live feed of Polymarket settlements — the moment trades
settle on-chain — and an in-memory index of every wallet its users are watching.
The worker checks every fill in it against the watched-wallet index. Almost
all settlements touch nobody's target and are dropped immediately.
When a leader sweeps a book, one settlement can contain a dozen small fills.
Ballista folds them into a **single order per token, side and role**, at the
summed size and the volume-weighted average price. The leader took one
position, so you take one position — not a dozen minimum-sized ones.
The folded trade runs through your copy trade's filters, caps and sizing.
If anything rejects it, the reason is recorded and nothing is placed.
Ballista submits a fill-and-kill order from your proxy wallet at a limit
price derived from your slippage setting. If the exchange rejects it, the
order is retried up to the number of times you configured.
Because the fold happens before your filters run, price and value bands are tested
against the **sweep**, not against each individual fill. A leader sweeping from 53¢
to 57¢ is one decision at the average price, not six decisions at six prices.
Both sides of the leader's flow are followed. Ballista matches on the wallet
itself, so it sees the leader's trade whether they crossed the spread or had a
resting order filled — though a wallet whose edge is in resting orders is a poor
one to copy. See [Choosing a trader](/guides/choosing-a-trader).
## What gets skipped, and why
Three things stop a copy before your own settings are even consulted:
| Condition | What happens |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **The settlement is stale** | Events older than **60 seconds** are dropped. A minute-old event is a reconnect replay or a stalled feed, not a signal worth trading. |
| **The fill was already copied** | Every fill carrying an order hash is claimed once per copy trade, so a reconnect that replays history does not re-place it. A fill the feed reports *without* an order hash cannot be deduplicated, and is copied rather than silently dropped. |
| **Your credentials will not build** | A copy trade whose Polymarket account cannot be loaded is skipped for that refresh and picked up again once it can. |
Everything else — sides, price bands, value bands, size limits, spend caps, market
gates — is your configuration. Each is documented in
[Copy trade settings](/guides/copy-trade-settings).
## Take-profit and stop-loss
Take-profit and stop-loss are **live-only** features. They arm on the positions a
copy trade opens with a **buy**, and a position is tracked whenever the copy trade has
**any exit condition** — a TP or SL price, a TP or SL percentage, or a balance level.
* **Price levels** are checked event-driven, against the same settlement feed. The
instant anyone trades that token at or through your level, the exit order is sent.
If that order fails, the position goes back into the index and is retried on the
next price tick.
* **Balance levels** (`Balance TP` / `Balance SL`) are polled every 30 seconds. When
your wallet balance reaches either one, the copy trade is **switched off** and every
position it is tracking is market-sold.
A balance level is a **liquidation and a stop**, not a pause. The copy trade stops
mirroring immediately and stays off until you switch it back on yourself.
If a sell fails, the trade still stops and that position is **left open** — nothing
retries it, because the copy trade is no longer being monitored. You get a *copy
trade stopped* entry in your notifications naming the position, and closing it is
then yours to do by hand.
Switching the trade back on while your balance is still past the level stops it
again within 30 seconds. Adjust or clear the level first.
Exit orders are sells priced from your **sell slippage**, defaulting to 30 if you have
not set one. A balance liquidation prices its limit off the **live market**, falling
back to your entry price only when no quote is available — a stop-loss fires precisely
when the market has moved against you, and a limit derived from the entry price would
sit above the book and never fill.
Take-profit and stop-loss are **not simulated in backtests**. A backtest replays a
tape of the leader's own fills and has no price path in between them, so it cannot
know when a level was touched. The backtest API rejects those fields outright
rather than pretending. See [Backtest fidelity](/guides/backtest-fidelity).
## The lifecycle of a copy trade
| State | What it means |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Active** | In the watch index. Every qualifying trade the leader makes is mirrored. |
| **Paused** | Kept with all its settings, ignored by the engine. Nothing new is mirrored, and **its stops stay armed** — pausing stops it opening positions, it does not abandon the ones you hold. You pause it, or a balance level does. |
| **Deleted** | Removed from every list, and cannot be edited or switched back on. Its execution history survives and keeps showing in your history. |
The engine rebuilds its watch index **every 30 seconds**, so creating, pausing,
resuming or deleting a copy trade takes effect within about half a minute. Nothing is
backfilled: a copy trade mirrors trades the leader makes *after* it goes active, not
positions they already hold.
**Deleting is one-way.** The setup cannot be edited or re-activated afterwards, so
if there is any chance you will want it back, **pause it** instead — a paused trade
keeps everything and switches straight back on.
Deleting also **disarms its stops**, within the same half-minute. Any position it
was tracking stays open in your wallet — the shares are yours and nothing sells
them — but no take-profit, stop-loss or balance level applies to them any more.
Close them yourself, or pause instead and let the stops do their work.
A copy trade deployed from a backtest result is created **paused**, deliberately.
A simulation assumes every admitted order filled, so a one-click hop from a
simulation to real money would start mirroring a stranger the moment the form was
submitted. Switch it on yourself when you are ready.
## Where to manage it
The full form — every setting on this site, one button each. Your list marks
each setup active or paused.
A short form for the settings most people change, the Active switch for
pausing and resuming, and the execution history table.
Both surfaces drive the same account and the same engine. A copy trade created in
Telegram appears in the terminal and vice versa, and editing one from either surface
only changes what you actually changed — settings the surface you are on does not show
are left exactly as they were.
## What to read next
Every field, what it does, and what happens when you leave it blank.
Taker share, and why some profitable wallets cannot be copied at all.
Replay a leader's real trades through a configuration before you fund it.
Trading by hand, alongside your copy trades.