> ## 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.
# Price alerts
> Get a desktop notification when a market crosses a price you picked.
A price alert watches one market outcome and fires when it **trades through** a
threshold you set. Alerts are a Chrome extension feature — they are created,
listed and delivered there, and nowhere else.
Neither the Telegram bot nor the web terminal has an alerts screen. If you want
price alerts, you need the [extension](/extension/install).
## Creating one
Two places do it:
* **On a Polymarket page** — the Ballista panel has an alert form for the
outcome you are looking at. Pick **above** or **below**, type a threshold, and
it is created against that market.
* **From the notifications panel** — the bell in the extension popup opens a
sheet that lists your alerts and lets you add one.
An alert is a condition and a number:
| Field | Values |
| --------- | ------------------------------------------------- |
| Condition | `above` or `below` |
| Threshold | A price strictly between 0 and 1 — 0.62 means 62¢ |
Setting `above 0.62` fires when the outcome trades over 62¢. Setting
`below 0.62` fires when it trades under.
## How it fires
Ballista watches Polymarket's trade feed continuously on its own servers, so an
alert works whether or not your browser is open. When the price crosses your
threshold, the alert triggers once and is done — it does not re-arm and it does
not fire again on the next tick. If you want to be told about the same level
again, create it again.
Alerts fire on **trades**, not on quotes. If nobody trades the outcome, an
alert does not fire even though the quoted price has moved past your
threshold. On an illiquid market this can mean a long wait, or no alert at all.
The extension checks every 30 seconds while your browser is running and raises a
Chrome desktop notification for anything new, naming the market by its Polymarket
slug along with the direction and the threshold in cents.
Each trigger is announced **once**. The extension remembers what it has already
shown you, so a notification you did not click is not repeated on the next check
and does not keep reappearing until you read it. A burst of triggers costs one
desktop notification rather than one per check for as long as the backlog lasts.
Nothing is lost when several arrive at once. The desktop notification is a
nudge, not the record — the bell in the extension popup shows everything you
have not read, however many that is.
The notification arrives when your browser next checks, not at the instant the
price crossed. The trigger itself is recorded on the server the moment it
happens, so nothing is lost if your machine was asleep — you get it when you come
back.
## Notifications
A triggered alert becomes a notification. The bell in the extension popup shows
the ones you have not read yet, and **marking one read** is what clears it. The
list is per account, so it is the same wherever you have the extension signed
in.
Notifications cannot be deleted, only marked read. Alerts and notifications are
two states of the same thing: an alert is one waiting for its price, a
notification is one that already fired.
Not everything in the feed is a price alert. The copy-trading engine writes a
**copy trade stopped** notice here when a copy trade hits its balance limit and
is switched off holding a position it could not sell — it carries a written
message naming that position instead of a direction and a threshold, and it
means something of yours is still open in the market. When one of these is
waiting alongside price alerts, it is the one raised as the desktop
notification. See [Extension alerts](/extension/alerts).
## Managing your alerts
The notifications sheet lists your active alerts alongside your notifications,
each with a delete button. Deleting an alert that has not fired stops it for
good. Deleting is for alerts only — anything already in the notification feed,
price alert or copy-trade notice, is cleared by reading it.
## What to read next
The screens themselves, step by step.
Act on an alert in one click.