Wallets, delegation & custody

The one page to read before you authorize anything.

Whose money moves

Your agent acts from your embedded wallet, created when you sign in. It spends only what that wallet holds. Candle does not custody an agent trading balance, does not front funds, and takes zero platform fee on base-pair swaps; API-built transactions carry your plan’s fee, listed in Plans, pricing & limits.

What delegation actually grants

Enabling agent access adds Candle’s signer to your embedded wallet(s). From then on, requests made with your API key can sign transactions from those wallets, limited to each key’s scopes. Delegation is per chain: authorize Solana, Hood, or both.

What it does not grant:

• No access for anyone without your API key.
• Nothing outside a key’s scopes (a key without the trading scope cannot trade).
• Nothing above your spend limits.

Spend limits

Per-asset caps apply at two levels, both editable on your dashboard:

• Embedded wallet: caps on what API-built transactions can spend from it. Unlimited by default until you set caps.
• Linked wallets: imported wallets (Pro and Max tiers) get default spend policies at import, and cap changes fan out to every active linked wallet.

Reference: Agent wallets & spend limits.

Creator fees

Creator fees on a token you launched are paid to the recipient fixed at launch: on Solana the wallet the token’s fee vault names, on Hood the streamer its fee splitter names, which is the wallet that launched it. An agent cannot change that, and the claim has no destination field.

For new Solana launches through an agent key paid by your embedded Candle wallet, both fee-vault wallets are that Candle wallet. Fees therefore add to the wallet your agent trades from, including when you signed up with Phantom or another external wallet. Your account stays the token’s creator, and you can still claim on /dev using your embedded wallet. The launch response and headless dry run expose the intended destination as feeWallet; this does not confirm that vault registration has finished. Tokens launched before this change keep their original fee wallet. Linked-wallet, self-signed and web launches are unchanged.

• Reading: a key with account:read can list the tokens launched from your account and what each could pay now (client.fees.list(), candle fees, candle_get_fees). It reads, and moves nothing.
• Claiming: a key with launch:write can claim one token’s fees (client.fees.claim(), candle fees claim <mint>, candle_claim_fees). A claim uses the delegation above: Candle signs from your embedded wallet, which pays the network fee, and the key must be allowed to use that wallet. It covers tokens you launched by hand too. A claim adds to the balance the agent can spend whenever the recipient is the embedded wallet it trades from, and your caps bound that spending only where you set them.
• What it cannot do: if a token’s fees go to a wallet Candle cannot sign for, the agent cannot claim them. That still applies to older Solana tokens whose fees were credited to Phantom or another external sign-up wallet: the agent can read the amount, and the read says wallet_not_signable, but only you can collect it, from that wallet. The same applies to a token whose fees were credited to someone else (not_recipient), a wallet without enough SOL or ETH for the fee (insufficient_gas), an account with delegation off (delegation_off), and a key not allowed to use the embedded wallet (embedded_wallet_not_permitted). Fees too small to be worth a transaction read below_dust. Every reason, response field and error: Claim creator fees and staking rewards.

Custody tiers: the vault and TEE wallets

The embedded wallet above is the dashboard’s path. The Candle CLI adds two custody tiers of its own. They are about who holds a key, and are separate from the account plans (Free, Pro and Max).

• Tier 1: the vault (self-custody). An encrypted file on your machine, opened by a passphrase or a security key, holding keys derived from a 24-word recovery phrase. No API, relay, or server ever sees a vault key. Use it for funds you hold yourself: a treasury, a cold wallet, the place an agent’s money goes home to.
• Tier 2: TEE wallets (agent access). A Solana or Hood wallet you promote out of the vault so one API key can trade with it without the vault being unlocked. A copy of its key is also held in Privy’s TEE; the vault keeps its own copy, so you never lose control. Every TEE wallet is pinned to one cold vault key, and sweeping or demoting it sends everything back there. Candle always accepts it on trades and the signing relay; swaps and launches only where the deployment enables them; LP with the opt-in lp:write scope; and transfers only by a Withdraw key. Everything else refuses it.

A promoted TEE wallet is a linked wallet, so it counts against your plan’s linked-wallet cap. A copy of its key stays in the TEE even after you demote it.

How to create a vault, promote a wallet, fund it, and get funds back: Custody tiers: the vault and TEE wallets.

Revocation

Two levers, both immediate:

• Revoke a key: that key stops working; everything else stands.
• Revoke agent access: removes Candle’s signer from your wallets, so the next server-signed action fails closed with DELEGATION_REVOKED. This is the emergency stop for signing. It does not revoke your keys: they stay valid and resume working if you re-approve delegation, so to retire a key, revoke the key itself.

For a TEE wallet, stop the agent with candle tee disable <address> and bring the funds home with candle tee sweep <address> --rpc-url <url>. With the API down or the key revoked, see In an emergency.

Custody summary

Thing	Who holds it
Your agent’s funds	Your embedded wallet (you)
Your API key	You; Candle stores only a hash
The delegation	Your wallet’s signer list; removable by you
Launched token fees	Paid to the recipient fixed at launch. You claim them from the dashboard; a key with launch:write can too, where Candle has enabled it, and only to that recipient
Vault keys (custody Tier 1)	You, in vault.enc on your machine; never sent to Candle
TEE wallet keys (custody Tier 2)	Privy’s TEE, for the one API key the wallet is bound to, plus your vault’s own copy