Rules bots

A rules bot is a strategy the Candle Harness runs itself. It watches Hacc’s tape, buys a token when a signal matches its rules, and sells each position by its exits: a take profit, a stop, a time limit, or a trailing exit. It needs no model and no turn, so it acts within seconds, the same way every time, with the Candle Harness’s window open or closed.

Its rules are a Hacc strategy definition, the same one Hacc’s strategy lab saves, backtests and replays. Your agent writes it with you, and your press on its card starts it.

For logic of your own in code, there are code bots, written in the Build tab. Their trades follow the same rules: a wallet of its own first, exits with no card, the kill switch and Candle’s breaker.

Bots need a Pro or Max plan. On Free, the Bots tab and overlay say so, with a chip that types candle plan buy, and nothing is proposed or entered. If your plan ends, every bot is kept and its entries held; its exits still sell what it holds, and the Bots tab still lists each, with what it holds, under the plan’s words. It comes back on as it was when the plan returns.

A wallet of its own first

For a live bot, the better way is a wallet of its own: a new TEE wallet just for that bot, funded with what you’re willing for it to lose, and set to trade inside limits in settings ▾ → approvals (Limits).

• It fences the risk. The bot can lose only what that wallet holds, whatever its rules do.
• Its figures are its own. The wallet’s per-trade and per-day figures bound the bot’s buys alone, not the agent’s and yours as well.
• Its book is exact. Nothing else trades from the wallet, so what it holds is the bot’s.

The bot’s card offers one where its wallet is shared or asks every time, and so does the bot on the Bots tab, so you can come back to it after approving the bot: its chip types the first step on the input line for you to send, and the steps after it follow as chips. Once the new wallet can pay, ask the agent to move the bot onto it: that’s a change card. Without a vault on this machine, the first step is setting one up. A TEE wallet takes Pro or Max, which bots do too (Wallets). Then fund the wallet, and set its figures in settings ▾ → approvals. If approvals marks the new wallet “Candle can’t sign for it yet”, it’s waiting on Candle’s side: no enable or rebind changes it, and the agent will say so.

A bot can also pay from a wallet you share, the embedded wallet included. That’s yours to pick, and the card says what it means: who else trades from it, and how its buys will run.

Making a bot

Ask the agent in your own words: “run a confluence bot under 500k, $2 a trade, stop at 30%, take profit at 2×”. It:

1. asks for what your words leave open: paper or live, the wallet it pays from, what it enters on, the stake and how many at once, its exits, and a short name;
2. proposes the bot as a card. The card shows the bot in words, its agent and wallet, paper or live, how its buys and exits will run, its worst case (how many at once, times the stake), and the backtest of that exact definition where there is one.

Your press on the card saves it and starts it. Nothing runs before. ctrl-n rejects it. On a short terminal the card is drawn tight, one line a part, so what your press approves stays on it.

The agent can also start one from a tape trigger of yours (its pattern and filters become the bot’s entry, and the agent offers to switch the trigger off), or, on Max, from a strategy saved in Hacc’s lab.

There’s no minimum time on paper and no backtest required: paper or live is your pick.

What a bot runs

A bot enters on one of Hacc’s patterns: confluence, new_ticker, large_move, deployer, dormancy, intra_book or kol_mention, on Solana, Hood or both.

	Runs live
Filters	market cap (a floor, a ceiling or both), the token’s age, its venues (or venues to leave out), hours of the day (US Eastern); the wallets or groups behind the signal, on single-wallet patterns; the signal’s size, on new tickers, large moves and deployer; the direction, in or out, on large moves, deployer and intra-book
Exits	a take profit, a stop, a max hold in hours, and a trailing exit (armed once the price reaches a multiple of the entry, then sells on a fall from its peak)
Sizing	a stake a trade and how many at once; a cap on the stake; rules on the market cap at entry that double a stake, add to it, or skip the token

Backtested, not run. Hacc’s lab replays more than a bot can watch live: entries on Hacc’s trade signals or conviction scores, exits on a signal, ladders, score thresholds, and sizing rules on anything but the market cap at entry. The agent says so plainly, and the card won’t take them. It offers what runs instead, often a trigger or the nearest pattern.

A bot with no exit holds what it buys until you flatten it, so the agent asks for one. A filter that lists wallets, groups or venues must name at least one: an empty list is refused, since it would read as a filter and match everything.

How a bot enters

Bots read Hacc’s full tape, every signal Hacc records, where the Signals tab shows Hacc’s curated one. That’s the tape Hacc’s replays run on. A bot acts only on signals from after it was switched on, and only on one at most 2 minutes old when it decides. A signal read back after a restart or a dropped stream that’s older is skipped as heard too late: a young token can move a long way in a few minutes. (Triggers act on signals up to 10 minutes old.)

For each signal that matches its pattern and filters, the bot buys only when:

• it doesn’t already hold the token, or have a buy of it under way, and it has a free slot. A signal still being checked holds no slot: the first to pass its checks takes it;
• Candle can price the token. A token with no price yet is waited for a minute, then skipped;
• the token’s market cap, on Candle, is inside its band, and Hacc’s read of its age and venues passes;
• its sizing gives a stake, and the wallet has the SOL for it with Candle’s fee.

Each buy goes through the wallet’s figures, as the bot’s own trade, never as yours. Inside them it runs with a receipt. Over them, or from a wallet that asks every time, it’s a card that waits 60 seconds for your press, and names the bot on its second line; one you miss is skipped, and isn’t offered again: the bot buys on its next signal. The agent’s own limits, Candle’s caps on the key and the kill switch hold it as they hold every trade.

What it skips, it says why: no free slot, heard too late, no price on Candle, its market cap, Hacc’s filters, the wallet’s balance, or the bot changed while the signal was being checked. A bot you pause, stop or remove while a signal waits on its checks doesn’t buy it. The Bots tab counts them over the last day.

How a bot exits

Every open position is checked about every 5 seconds against Candle’s own market price, the one a sell fills at:

• take profit when the price is that far over what the position cost;
• stop when it’s that far under;
• max hold when the time since the buy filled runs out, whatever the price;
• trailing once the price has reached its multiple of the entry, then when it falls that far from its highest since.

The entry is what the position cost a token, with Candle’s fee in it, so a take profit at +100% is +100% on what you paid. A price more than 30 seconds old isn’t one to exit on, and neither is one read before the position’s buy filled. If Candle stops pricing a token the bot holds, the Bots tab says “no price on Candle since” the time it stopped, rather than its last figure, and you’re told once: its stop and target wait until Candle prices it again, and its max hold still sells. After the machine sleeps or the core restarts, every position is checked at once, and an exit found then says it was found on the core’s first read after it woke or started: the core can’t know when the price crossed while nothing watched. A stop isn’t guaranteed: a fast move can pass through it before the sell is sent, and the sell fills at the price then. A sell that’s refused or reverts on chain (a revert spends the network fee) is tried again with a fresh quote at the next check, a flatten’s included, as a stop order would; after two failed sells of a token in a row the next waits (Candle’s circuit breaker), and the Bots tab offers retry.

A bot’s exits sell without a card, on any wallet, a wallet that asks every time included. You approved its exits when you approved the bot, and a stop that waits for a press isn’t a stop. A sell still becomes a card when its slippage bound is looser than the bot was approved with.

Nothing is sold twice. Each exit is recorded before its sell is sent, so a restart mid-exit reads back what was sent. If Candle has no record of it, the Candle Harness sends it once more by itself, under the same id, which Candle never runs twice, and the Journal says so. That’s the only trade the Candle Harness ever re-sends on its own; if it’s still unanswered after that, it waits in the agent pane for your resend or abandon, like any trade Candle didn’t answer.

The bot’s own book

Each bot keeps its own book, from its own fills: its open positions, what it paid for each, and what each made when it sold. It’s the Candle Harness’s count, apart from Candle’s books for the key.

A bot sells only its own. From a TEE wallet, and for a token Candle launched, it sells its exact amount. From the embedded wallet, for a token Candle didn’t launch, Candle takes only a percent, so the bot sells its share of the wallet’s balance as a whole percent, rounded down; under 1% of the balance, it sells nothing and says why. If the wallet holds less than the bot’s position (you or the agent sold some), it sells what’s there and says how much was sold outside the bot. On a wallet two bots share, a shortfall is split between them.

A buy whose answer was lost. When a buy had to be read back from Candle by its id, the answer may not say how many tokens it bought. The bot then sells about what its spend bought at Candle’s first price within a minute of the buy, never more than the quote’s expected out with its slippage bound, and never more than the wallet holds less other bots’ own. With no price in that minute it sells none of it, says so, and the position is left to you.

On a wallet of its own, none of that comes up.

Paper or live

Each bot is paper or live, whatever the Candle Harness’s own mode. A paper bot trades on paper while the Candle Harness is live, and a live bot trades live while the Candle Harness is on paper. Switching the Candle Harness’s mode changes no bot.

A paper bot shares the key’s paper book with the agent’s own paper trades, and still sells only its own. To take one live, use its go live chip, or ask the agent: it’s a new card, since a live bot spends. While the Candle Harness is on paper, a live bot’s card or trade says in amber that it’s real funds.

Slippage

New tokens off the tape often move more than the default slippage bound allows: 1% from the embedded wallet, 0.5% from a TEE wallet. A bot can have its own bound, offered by the agent with a figure and set only once you agree. The card shows it in amber when it’s looser than the default, and when it’s tighter (“under the route’s 1%: its sells may not fill”). A bound under 0.1% is refused: almost nothing fills there, sells included. Inside its bound, its trades run inside the wallet’s figures, and each receipt names it. Your own trade at the same bound is still a card.

Pausing, stopping and changing one

	What it does	Who
Pause	No new entries. Its exits still sell, so what it holds stays protected.	you, from any view, or its agent
Back on	Back as you approved it.	you, from the main window
Stop	Nothing trades: no entries, and its exits don’t sell. Its open positions are left to you.	you, from the main window
Flatten	Sells every open position now, at market, as its exits sell. The bot stays on, so its next signal may buy again; the question offers pause, then flatten to pause it first. Asks once.	you, from the main window, or the agent on a card
Remove	Takes it out. With positions open, it asks whether to flatten them or leave them to you. Positions left are yours from then on: a new bot of the same name starts with an empty book and an empty day, and the earlier one’s history is in the Journal. A flatten’s sell that fails after the bot is removed isn’t tried again: those tokens stay in the wallet, yours to sell.	you, from the main window

“Stop all my bots”, to the agent, pauses them all. Only you put a bot back on or stop it.

Changing one. Ask the agent. A change that only narrows the bot takes at once, and Activity says what changed (“a stop at -25%, from -40%”): a smaller stake, fewer at once, a lower cap, a tighter stop, a sooner take profit, a shorter hold, a filter added or made stricter, a skip rule added, a slippage bound tightened as far as the route’s default (1% from the embedded wallet, 0.5% from a TEE wallet). Anything wider, another wallet, or going live is a new card. So are three changes that look narrower and aren’t safe to take at once:

• new exits that would sell an open position now. That’s a flatten, and the card’s changes line leads with “its new exits would sell its open position now”;
• an exit under 1%, or a hold under 5 minutes: the bot would sell almost as soon as it buys;
• a slippage bound under the route’s default, which can make its sells fail.

An emptied filter list counts as the filter taken away, so it’s wider too. A change you approve keeps a bot you paused or stopped as it was, and its card says so: putting it back on is your own click. Every version you approved is kept, numbered.

A turn a trigger woke may read, pause and narrow bots, and nothing more: it can’t make any change that would be a card.

The kill switch and bots

ctrl-x twice holds every bot’s entries until you resume. Its exits still sell: a stop still gets you out. The kill report names each bot it holds, and the positions its exits still guard. Resuming leaves each bot as it was: one you’d paused stays paused.

Candle’s circuit breaker

Candle stops a key at 30 trades in a rolling minute, or 3 failed sells of one token in a row, sells included, until the account’s owner resumes it in Candle’s Agent Console (Limits). A bot trades with its agent’s key, so a bot that tripped it would stop the agent too. The Candle Harness keeps clear of it:

• Bots and triggers keep to 20 trades in any 75 seconds on a key. Candle counts a trade when it reaches it, which can be seconds after it’s sent, so the extra 15 seconds keep a slow burst from sharing Candle’s minute with the next. Buys take at most 15 of the 20, so 5 are always there for a sell, and while a sell waits for room no buy takes a slot that frees: a stop never waits behind new entries. Past that, a bot’s entry is skipped and its exit waits for the next free slot, then sells as a stop order does: once its stop or target has been passed, it sells even if the price has moved back meanwhile. Your trades and the agent’s never wait.
• One sell of a token at a time on a key. While a sell of it is under way, a bot’s next sell of it waits, so a run of sells can’t all fail and stop the key. A lost exit the core sends again after a restart waits the same way, and for the pace.
• After two failed sells of a token on a key, a bot’s next sell of it waits, and tells you. Check why the sells failed (on a young token, often slippage), then use the bot’s retry its sells chip to let it try once more.
• A route Candle says is failing is waited out, for as long as Candle says.
• If Candle stops the key anyway, every bot of that agent is paused, saying so with the Agent Console step. Resume the key there, then put each bot back on.

The Bots tab

Your bots on the left: each one’s state, paper or live, its P&L from its own fills, and its open positions. The one you pick, on the right:

• its words, paper or live, since when, and the wallet it pays from;
• its chips: pause, back on, stop, flatten, remove, retry its sells where they’re held, go live for a paper bot, replay its live days on Max, and ask the agent to change it, which puts the words on the input line;
• each open position on a line from its stop to its target, with its entry, the price now and, once armed, its trailing level;
• its book: realized, open and today, and its exits by why;
• its backtest, the newest replay of its exact definition;
• what it skipped over the last day, by why, and its newest fills.

The status bar’s 3 bots chip, settings ▾ → bots and the palette (ctrl-k) open it. With no tab showing the Bots pane, the same list opens over the screen.

Where it shows

• Activity folds a bot’s trades into one line while nothing else comes between: “bot conf bought BONK, WIF · took profit on MOON · 3 skipped”. An exit at a stop, and anything that goes wrong, gets a line of its own.
• The Journal has a bots kind: each bot’s entries, exits, skips and changes, in words.
• Receipts and cards a bot causes name it, so nothing it did reads as yours.
• The P&L tab shows each bot’s figures from its own fills, and Trades marks a bot’s fill.
• The note when you come back has a Bots section: each bot’s trades, its P&L over the gap, what’s still open, and anything held (While you were away).
• A trigger can watch a bot: on bot "conf" entered, on bot "conf" exited or on bot "conf" paused, to notify you or wake an agent (Triggers).

Notifications

A bot’s trades notify you while the Candle Harness’s window isn’t in front, one notice a bot every 5 minutes at most, folding what it bought and sold: “conf · bought BONK, WIF · took profit on MOON”. A stop, a sell refused or failed, a sell held and a buy that waits for you notify at once. It’s bots in [notify] on in config.toml, on by default (Triggers).

A live run and Hacc’s backtest

A backtest describes the past, and a live bot doesn’t run the way a replay does:

• A replay buys at Hacc’s first price after the signal, often a minute or more later, with nobody else after the same entry. A live bot buys within seconds, at the market.
• A replay fills a stop 5% under its level. A live bot sells at the market price when the stop is crossed.
• About a third of the tape’s tokens have no price on Candle when their signal lands. A live bot skips those after a minute; a replay may not.

A passing backtest is a reason to run a bot on paper, not to fund it. On Max, a live bot’s replay its live days chip asks the agent to replay its definition over the days it ran live; the replay shows beside the bot once it’s done.

bots.toml

Bots are kept in bots.toml beside config.toml, written by the Candle Harness when you approve, change, pause, stop or remove one. Each holds its agent, wallet, paper or live, its state, its slippage bound and its definition in Hacc’s own field names.

An edit by hand can’t add a bot or widen one. Setting state = "paused" or "stopped" always takes, and only your resume undoes it. A bot added by hand runs nothing until it’s approved on a card; one changed by hand takes no new entries, while its exits still sell as it was approved. A file the Candle Harness can’t read is never written over: candle-harness doctor names the line to fix. Configuration lists its keys.

Kept running

A bot that enters, or holds a position its exits watch, keeps the Candle Harness’s core running after you quit. Quitting says “2 bots and 3 triggers keep running in the background”, and candle-harness stop ends the core. For bots that run with no terminal open, candle-harness service install starts the core at login, and on a Mac keep-awake keeps it from sleeping while a bot or trigger is on (Triggers, Running on a VPS).

While any bot enters, the core holds one more connection to Hacc’s stream, for the full tape.

What candle-harness doctor says

• Each bot: paper or live, what it does now (enters and sells, sells only, paused, stopped), its agent and wallet, and its open positions.
• How many bots keep the core running, or the bots on in bots.toml with no core to run them.
• A bot held, and why: an edit by hand, an agent gone, your plan.
• A bot paused because Candle stopped its key, with the Agent Console step.
• A bot’s sell held after two failed sells, with the retry.
• A live bot on a shared wallet, as a note: its book is its own fills, and a wallet of its own would fence what it can lose.
• bots.toml’s problems, by line.