> ## 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 trade settings
> Every field on a copy trade, what it does to your orders, and what happens when you leave it blank.
This is the reference for every setting a copy trade has. The full set lives in the
[Telegram form](/telegram/copy-trade-form); the [web terminal](/terminal/copy-trading)
exposes the handful people change most often and leaves the rest at their defaults.
Three rules apply throughout:
* **Blank means off.** Every numeric filter and cap is inactive until you give it a
value. A blank price band does not clamp anything; a blank spend cap does not stop
anything.
* **Order of evaluation is fixed.** Sides, then price band, then value band, then the
market gates, then sizing, then the spend caps. A trade rejected early never
reaches the later checks.
* **An edit changes only what you edited.** Settings a surface does not show survive
being edited from it, so a copy trade you built in full in Telegram keeps its filters
when you change its size in the terminal.
## Target
| Setting | What it does |
| ----------------- | ---------------------------------------------------------------------------------------------------- |
| **Target wallet** | The wallet to follow. Required. Case does not matter — it is normalised before it is indexed. |
| **Label** | A name for your own list. Purely cosmetic; if you leave it blank the list shows a shortened address. |
## Direction
| Setting | Default | What it does |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Copy buy** | On | Mirror the leader's buys. Turn it off and every buy is skipped. |
| **Copy sell** | On | Mirror the leader's sells. |
| **Reverse copy** | Off | Flips the side before anything else runs: their buy becomes your sell and their sell becomes your buy. Note that the copy buy and copy sell switches are then tested against **your** side, not theirs. |
## Sizing
You must set exactly one of the two sizing modes. Setting both, or neither, is
rejected.
| Setting | What it does |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Copy percentage** | Your order is a percentage of the leader's. On a buy, you spend their trade value × your percentage. On a sell, you sell their share count × your percentage. Accepts up to 10000, so copying at more than 1× is possible. |
| **Fixed USDC** | Every buy spends the same amount regardless of the leader's size. On a sell, that amount is converted to shares at the fill price. Telegram will not accept a fixed size under **\$5**. |
Fixed sizing does not track your position. On a sell it sizes from the amount you
set, not from what you actually hold, so a leader closing a position you sized
differently will not close yours cleanly.
### Per-trade bounds
| Setting | What it does |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Min per trade** | An order worth less than this is not placed. On a **buy** you can change that with the setting below; on a **sell**, an undersized order is always skipped. |
| **Max per trade** | An order worth more than this is **clamped down** to it, not skipped. This is the setting that keeps one enormous leader trade from consuming your account. |
| **Below min limit, buy at min** | Off by default — but the Telegram form starts it on and always sends its value, so bot-created copy trades have it on unless you switch it off. When on, a buy that came out under your minimum is raised to the minimum instead of being skipped. Buys only. |
## Execution
| Setting | Default | What it does |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Buy slippage** | 30 | How far past the leader's price your buy may fill, as a percentage, from 0 to 100. Your limit is set to their price plus this much, capped one tick below certainty. |
| **Sell slippage** | 30 | The same in the other direction: your sell may fill down to their price minus this much, floored at one tick. Also used for take-profit and stop-loss exits. |
| **Retry on failure** | 1 | Extra attempts if the exchange rejects the order, 0 to 5. Attempts are 200 ms apart and each is given 10 seconds. |
| **Buy / sell order type** | Market | Recorded on the setup. Every copy order is submitted as a fill-and-kill order priced from your slippage setting — nothing rests on the book waiting. |
**A live slippage of 0 does not mean zero.** The engine reads 0 as "unset" and
applies the default of 30. There is no way to configure a live copy trade that
only fills at exactly the leader's price. In the backtester the same number is
an execution cost and an explicit 0 *is* honoured — the two are opposite, and
neither is carried into the other. See [Backtesting](/guides/backtesting).
## Trade filters
Tested against the leader's trade, before any sizing happens. Remember that a
leader's sweep is folded into one trade first, so these describe the whole sweep.
| Setting | What it does |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Min price** | Skip the trade if the leader's price is below this. Between 0 and 1 exclusive — a probability, shown in the terminal as cents. |
| **Max price** | Skip the trade if the leader's price is above this. |
| **Ignore trades under** | Skip the trade if its total value in USDC is below this. Filters out the leader's dust. |
| **Ignore trades over** | Skip the trade if its total value in USDC is above this. Filters out their outsized bets. |
## Spend caps
Cumulative limits, counted across the whole life of the copy trade. They are tested
against **your** order's value, after sizing, and only **buys** consume budget —
selling never does.
| Setting | What it counts |
| --------------------- | ------------------------------------------------------------------------------------------- |
| **Total spend limit** | Every buy this copy trade has made. Once the next order would take you over, it is skipped. |
| **Max per market** | Buys in one market. |
| **Max per YES** | Buys of an outcome named "yes", per outcome token. |
| **Max per NO** | Buys of **every other outcome**, per outcome token. |
The YES / NO split is literal: an outcome named "yes" is checked against **Max per
YES**, and **anything else** — including every leg of a multi-outcome market, which
is named after a candidate, a team or a range rather than "no" — is checked against
**Max per NO**. Setting only the YES cap therefore leaves every non-binary leg
uncapped.
A cap is a hard "skip", not a clamp. An order that would breach the cap is not
shrunk to fit — it is not placed. Budget is reserved before your order is
submitted and released only if the order never reached the exchange, so two
simultaneous fills cannot both slip under the same cap.
Caps count **lifetime committed spend and never give it back**. Selling out of a
market does not restore its budget: a copy trade that has spent its total cap
stops buying permanently. (A backtest of the same configuration behaves
differently — see [Backtest fidelity](/guides/backtest-fidelity).)
## Market gates
These need market metadata. When that lookup is unavailable they **fail open** — an
outage degrades to "copy everything", never to "copy nothing" — and each date gate
individually fails open when the market carries no date to test against.
| Setting | What it does |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Only copy market final time** | Copy only when the market ends within this many seconds. For late-resolution strategies. Skipped entirely for a market with no end date. |
| **Only copy market start time** | Copy only when the market opened within this many seconds. Skips markets that have been running longer. Skipped entirely for a market with no start date. |
| **Max holder market number** | Skip markets with more unique holders than this. |
| **Only copy specific market types** | A whitelist of market tags. See below. |
### Market types
The setting is a **list of Polymarket tag slugs**, matched **exactly** against the tags
Polymarket carries on the market being traded. An **empty list means no filter**; any
non-empty list is a whitelist, and a market is copied only if it carries at least one
of your tags.
Two surfaces write the same field differently:
* **Telegram** gives you five checkboxes — Sports, Politics, Crypto, Weather and Other
— each of which writes its tag slug. **All** clears the selection, which is what "no
filter" is: there is no separate "everything ticked" state to be in.
* **The terminal's backtester** takes free-text, comma-separated tag slugs, so you can
target any tag Polymarket uses.
While a filter is on, a market carrying **none** of your tags is skipped — and so is
a market that is untagged or tagged in some way you did not list. Narrowing to one
category is therefore narrower than it looks. A metadata outage still fails open, as
above.
## Take-profit and stop-loss
Live only, and armed on positions your copy trade opened with a buy. Setting **any**
of the six starts tracking those positions.
| Setting | What it does |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **TP price** | An absolute price. When the token trades at or above it, the position is sold. |
| **TP percentage** | A percentage above your entry price. Ignored if a TP price is set, and dropped if it would land at or above certainty. |
| **SL price** | An absolute price. When the token trades at or below it, the position is sold. |
| **SL percentage** | A percentage below your entry price. Ignored if an SL price is set, and dropped if it would land at or below zero. |
| **Balance TP** | A USDC wallet balance. Reaching it **switches the copy trade off** and market-sells every position it is tracking. |
| **Balance SL** | A USDC wallet balance. Falling to it does the same. |
Price levels are checked the instant anyone trades that token. Balance levels are
polled every 30 seconds. A balance liquidation prices its limit off the live market,
falling back to your entry price only when no quote is available.
A balance level **stops the copy trade as well as liquidating it**. It goes off, and
stays off until you switch it back on — while your balance is still past the level,
switching it on again stops it again within 30 seconds, so adjust or clear the level
first.
If one of the liquidating sells fails, the trade still stops and that position is
left open with nothing retrying it. You get a *copy trade stopped* entry in your
notifications naming the position, and closing it is yours to do by hand.
Exit orders are sized from the share count your copy order was *expected* to
produce — the USDC it spent divided by the entry price — and are not reconciled
against what the order actually filled. A copy order that filled only partially
will have its exit sized for more shares than you hold.
## What to read next
How the engine follows a wallet, and what a copy trade's lifecycle looks like.
Run these settings against a leader's real history before you fund them.
Where every one of these lives in Telegram.
Saved order configurations for trading by hand.