Limits

Two sets of limits hold your agents’ trading, and they hold in different places:

• The Candle Harness’s, enforced by its core, for what the core runs: every card, every trade the agent makes through the Candle Harness, every trade you type.
• Candle’s, enforced by Candle’s server on each agent key, for every trade Candle builds with that key, whatever asks for it: the Candle Harness, the candle CLI, a script, the web app.

Neither covers the other’s gap. The Candle Harness’s limits don’t reach the key when something else uses it, and Candle’s don’t know about wallets, only keys. Wherever the Candle Harness shows a limit (the approvals menu, a card’s limits line, harness_limits, candle-harness doctor), it names who holds it: Candle Harness or Candle.

At a glance

Limit	Held by	Set in	Covers	Doesn’t reach
An agent’s per trade and per day	Candle Harness	config.toml	that agent’s buys and swaps through the core	sells; anything run outside the core
A wallet’s figures for trading without a card	Candle Harness	settings ▾ → approvals	what runs with no card from that wallet	anything run outside the core
A code bot’s figures: a trade’s, a day’s, open at most	Candle Harness	the code bot’s card	every buy and swap that bot sends through the core	its sells of its own; anything the program does outside the core
The kill switch	Candle Harness	ctrl-x twice	every agent’s turn, buys and swaps, triggers’ buys, rules bots’ entries and code bots’ buys and swaps	sells; anything run outside the core
The pace for bots and triggers	Candle Harness	always on	20 trades in any 75 seconds on a key from bots and triggers, the last 5 kept for sells and sells going first, to keep clear of Candle’s breaker	your trades and the agent’s; anything run outside the core
A key’s volume cap (txLimit)	Candle	the Agent Console, or candle keys create --tx-limit	the key’s buys, sells and swaps over a window	other keys; refusing a sell
A key’s per-asset caps	Candle	the Agent Console	each spend of SOL, USDC or CNDL in one trade	sells; swaps between SOL, USDC and CNDL
A key’s loss limits	Candle	the Agent Console	the key’s realized losses	an open position: they stop the next trade
The circuit breaker	Candle	always on	every key	nothing to set

The Candle Harness’s limits

Each agent’s own limits are in config.toml, under [agents.<name>.limits]: perTradeUsd and perDayUsd. candle-harness key add starts an agent at $10 a trade and $50 a day.

• They cover buys and swaps. A buy is valued with Candle’s fee, so buy $1 counts as about $1.01.
• The day runs from local midnight, and counts every buy and swap the agent’s trades sent today, with a card or without.
• Over either limit, a trade is refused, with the figures. It never becomes a card you could approve.
• Sells are never limited. Getting out is always allowed. A sell may settle in SOL, USDC, CNDL, ETH or USDG, and isn’t limited whichever it is: a token sold into CNDL included.
• What trades spend can’t be a trade’s token. A buy or sell of SOL, USDC, ETH or USDG is refused, live and on paper: converting one is a swap, which is limited as a buy is. CNDL trades like any token.
• A buy or swap the core can’t price is always a card, and the card says in amber that its limits can’t check it. Once it fills it’s valued at what it spent and counts toward the day, where a price can be read then. USDG on Hood has no price yet, so a buy or swap that spends USDG is always such a card, and isn’t counted toward the day.
• A swap whose first leg went and whose second failed still counts toward the day, since the first leg spent. The card, Activity and the Journal say “part done”.

The kill switch (ctrl-x twice) stops every agent’s turn, withdraws open buy and swap cards, and refuses new ones until you resume. Sells still go, each on a fresh card at a fresh price.

What the Candle Harness’s limits don’t reach: anything the core doesn’t run. That’s the candle CLI in your own terminal, a script or app with the same key, Candle’s web app, and the agent’s shell if you’ve turned it on (Engines). Only Candle’s limits hold there.

Candle’s limits

Candle’s limits are per key. Nothing on Candle’s side is per wallet: two keys that share the account’s embedded wallet each have their own caps. Every key starts uncapped.

The volume cap (txLimit) is a dollar amount over a UTC day, an ISO week (from Monday), a UTC month, or the key’s life. It counts buys, sells and swaps, and never refuses a token sell. It’s checked when Candle builds a trade, and Candle calls it an approximate guardrail: trades built at the same moment can pass it together.

Per-asset caps bound how much SOL, USDC or CNDL one trade may spend. Sells aren’t spend-capped, and nor are swaps between SOL, USDC and CNDL.

Loss limits bound how much the key may lose: a day’s realized loss (UTC), a fall from its highest value, which never resets, and losing trades in a row. The circuit breaker is on every key and can’t be turned off: 30 trades in a rolling minute, or 3 failed sells of one token in a row.

• A breach of either stops the key, sells included. No clock clears it: the account’s owner reviews the key and resumes it in Candle’s Agent Console.
• They’re guardrails, not a hard boundary. They stop the next trade, and can’t unwind a position already open.
• The Candle Harness can’t read them yet, so it names them rather than showing them.

Setting them. Only the account’s owner raises or clears a cap or a loss limit. An agent’s key can tighten its own per-asset caps and loss limits, never loosen them. The Candle Harness never changes a key’s caps for you.

• On a key you already have: the Agent Console, on the key in its Agents tab (alpha.candle.tv/agents). The CLI can’t change an existing key’s caps today.
• On a new key: candle keys create --access write --embedded-wallet allow --tx-limit <usd>, with --reset daily, weekly, monthly or never for its window. Then candle-harness key add --agent <name>.

What the Candle Harness shows of them. Each key’s volume cap and per-asset caps come with Candle’s status read, so they show in the approvals menu and harness_limits. How much of the volume cap is used is only on the owner’s key list, so candle-harness doctor shows it, when your candle CLI is signed in. Loss limits and the circuit breaker aren’t on any read the Candle Harness uses yet.

When Candle refuses

The Candle Harness doesn’t keep sending what Candle will refuse:

• The volume cap is used up (KEY_LIMIT_REACHED): that agent’s buys and swaps are refused at once, in Candle’s words, until the cap resets. Its sells still go. A cap over the key’s life holds until the owner raises it. When Candle couldn’t check the cap for a moment, its buys and swaps wait about 30 seconds.
• A buy over a per-asset cap is refused before it’s sent.
• The key is stopped (RISK_LIMIT_REACHED): every trade from that agent, sells included, is refused at once in Candle’s words. The Candle Harness asks Candle again every 5 minutes, since only the owner can resume the key. The agent’s rules bots are paused, so none buys when the key comes back; you put each back on.
• Two sells of a token failed in a row on a key: a third would stop the key. A bot’s next sell of it waits until you let it try again, and a trigger’s is refused and said; yours and the agent’s go, with an amber line on the card.
• A sell of a token still under way on a key counts as one that may fail. The core sends its own sells of a token (a bot’s, a trigger’s, a lost exit sent again) one at a time per key, so a run of them can’t fail past the hold together. Yours and the agent’s go, with the amber line when one more failure could stop the key.

Each hold survives a restart, and candle-harness doctor names any key held now and when it lifts.

Trading inside limits

By default every wallet asks every time: every live trade is a card, and you approve it with one press. You can let a wallet trade inside limits instead: a trade inside its figures runs at once, with no card.

Turning it on. In the view’s settings ▾ → approvals, pick the wallet, then “trade inside limits…”. Type its two figures (how much a trade, and how much a day, may run without a card), then click to turn it on. Esc leaves it as it was. Each wallet is set on its own: the embedded wallet and each TEE wallet.

• Only you turn it on or raise a figure, from the Candle Harness’s main view. An agent can’t, nor can a popped view or anything else that talks to the core.
• An agent can narrow it (back to asking every time, or lower figures) only on a card you approve.
• The setting holds while the Candle Harness is closed, so a turn still running after you quit trades by it. “While you were away” says what ran.
• The kill switch leaves the setting as it is: while it’s on, it holds buys and swaps either way, and sells still go.

On a wallet that trades inside limits, these run with no card:

• a buy or swap at or under the wallet’s figure for a trade, that keeps today’s total without a card at or under its figure for a day. It must have a price, and a buy is valued with Candle’s fee: a buy $1 is over a $1.00 figure;
• every sell, whatever its size, unless its slippage bound is looser than the route’s default. Sells were never limited;
• proposed by the agent, typed by you, fired by a trigger, or bought by a rules bot or a code bot, and each part of a chain when its turn comes.

Each at the route’s default slippage or a tighter bound: 1%, or 0.5% from a TEE wallet.

They’re live trades only. Paper trades never had a card.

A rules bot’s exits sell with no card on any wallet, one that asks every time included: you approved its exits when you approved the bot. A bot’s buys go through the wallet’s figures like anyone’s, at the bot’s own slippage bound where you approved one (Rules bots).

A code bot’s sells of its own, and the exits the core holds for it, sell with no card on any wallet too. Its buys and swaps go through the wallet’s figures, and before them through its own figures from its card: over its trade’s, its day’s or open at most, a buy is refused with nothing sent. Those figures hold what the bot sends through the core; the bot itself is a program you run, and the core doesn’t confine it (Code bots).

Everything is still checked: the agent’s own limits (over them, refused), the kill switch, a key Candle refused, the address check, and a fresh price.

These become a card all the same, and the card says why: a trade over either figure, a buy or swap with no price, any trade, a sell included, whose slippage bound is looser than the default, or the same trade from the same agent while one sent without a card hasn’t settled.

These always have a card, on any wallet: launches, staking, claims, posts and profile edits, image uploads, Hacc’s changes that are cards (unfollowing, removing, retiring, adding an alert rule), less access the agent proposes, owner steps, and anything that moves funds out.

The day figure counts only trades that ran without a card, from local midnight, across every agent that pays from the wallet. A card you approved counts towards the agent’s own day limit, not the wallet’s figure. So the figure means “what ran without me today”, and the agent’s own limits still bound the whole.

Typed trades. With [cards] typedTrades = "instant" in config.toml, a trade you type always runs at once, inside the agent’s own limits, and never uses up a wallet’s figures. A wallet’s figures only take cards away, never add them. A trigger’s or a bot’s trades never count as typed: they always go through the wallet’s figures.

Where it shows. A trade that ran without a card leaves a receipt where its card would be:

In Activity, the Journal and P&L’s Trades it says “without a card”. The Wallets pane shows each such wallet’s use today, and the agent’s harness_limits read tells it what it may do without asking.

Before you turn it on, set a Candle cap on each key that pays from the wallet. Candle’s cap is the only limit that holds outside the Candle Harness, and every key starts uncapped. The approvals menu and candle-harness doctor say so in amber for any key without one.

What candle-harness doctor says

• Each wallet’s setting, its figures, who pays from it, and how much ran without a card today.
• A wallet figure an agent’s own limit binds before (“a trade between the two is refused”).
• A key Candle doesn’t cap, on a wallet that trades inside limits.
• Each key’s volume cap and how much of it is used, when your candle CLI is signed in.
• That Candle’s loss limits and circuit breaker exist, and that the Candle Harness can’t read them yet.
• Any key held now, why, and when it lifts.
• When the Candle Harness’s main view last closed, and the last gap “while you were away” covered.