candle-launch-bot 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- Detection from Candle's token list and the launch-curve program on chain, with latency for both.
+- Filters: launch mode, age, price impact, creator allow/deny, name/symbol match; caps for ticket, open positions,
+  lifetime spend and entries per coin.
+- Payers `embedded` (Candle signs) and `linked` (TEE wallet, local key signer).
+- Exits `hold`, `tpsl`, `time`, `ladder`, `preGrad`, and custom strategy files; three example strategies.
+- Fills booked from the chain; sell clamp to the wallet balance; capped retries with backoff; recovery of trades that
+  may have executed; alerts to a command or a webhook.
+- `init` (interactive or from flags), `scan`, `run`, `status`, `sell`; STOP and PAUSE_BUYS controls; `status.json`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 candle-launch-bot contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,401 @@
-# Temporary Holding Version
+# candle-launch-bot
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Every Candle launch. First in line. Your size, your exit.**
+
+Built by [Bruce Jeet](https://github.com/BruceJeet).
+
+Somebody is first on every coin that drops on [Candle](https://candle.tv). Might as well be you.
+
+candle-launch-bot watches the chain and Candle's token list at the same time, sizes in the second a launch clears your
+filters, and works your exit while you sleep. One config file. One process. A local SQLite ledger that books what
+actually landed, not what somebody quoted you.
+
+- **Sees it first.** Two feeds race: Candle's public token list and the launch-curve program on chain (`logsSubscribe`,
+  signature polling as backup). First sighting wins, and both latencies get logged so you know which feed is carrying.
+- **Picks its fights.** Launch mode, coin age, the price impact of your own buy on the curve, creator allow and deny
+  lists, name and symbol regex. Hard caps on ticket size, open bags, lifetime spend and entries per coin.
+- **Pulls the trigger.** Candle's trade API, from your account's embedded wallet (Candle signs) or a TEE wallet you
+  sign for on your own box.
+- **Gets paid.** `ladder`, `tpsl`, `time`, `preGrad`, `hold`, or drop in your own exit as one file.
+- **Dry mode** runs the whole hunt with paper fills priced off Candle's own curve quote. Watch it work before it
+  spends a lamport.
+
+Built on Candle's official SDK, [`@candledottv/agent-sdk`](https://www.npmjs.com/package/@candledottv/agent-sdk)
+(pinned at 0.6.14). Solana only for now.
+
+## House rules
+
+The bot runs on four rules. They're in the code, not in a promise:
+
+1. **Book what landed.** Every fill is read off the transaction. A quote is not a fill.
+2. **Never sell what you can't see.** Every sell is clamped to the wallet's real balance, and the clamp only goes down.
+3. **Never loop on your SOL.** Retries have a cap, a backoff and an end. A stuck order stops; it doesn't spin.
+4. **One live transaction per order.** No double buys from a retry storm.
+
+The full details are under "How it handles your money".
+
+Words you'll see: a **launch mode** is how a Candle coin's bonding curve was set up (`open`, `exclusive`, and the
+experimental `exp-a`, `exp-b`, `exp-c` and `exp-custom`, whose curves can take any shape); **graduation** is the moment
+a curve fills and the coin moves to its DAMM v2 pool; a **TEE wallet** is a Candle trading wallet held in a secure
+enclave (through Privy, Candle's wallet provider) and signed for by your key's signer.
+
+## Get in (five minutes)
+
+Node 22.18 or newer.
+
+```sh
+npx candle-launch-bot init                               # a few questions; writes bot.json in dry mode
+npx candle-launch-bot scan --config bot.json --for 600   # print what it would buy; never trades
+npx candle-launch-bot run  --config bot.json             # dry run: the whole loop with paper fills
+```
+
+Dry run looks right? Set your API key, fund the wallet, and go live:
+
+```sh
+export CANDLE_API_KEY=cndl_live_...
+npx candle-launch-bot init --mode live --force [your flags again]   # or edit bot.json: "mode": "live", your wallet
+npx candle-launch-bot run  --config bot.json
+```
+
+`init` also runs without questions, from flags (`--yes`), for scripts and agents. `candle-launch-bot --help` lists the
+flags:
+
+```sh
+npx candle-launch-bot init --yes --payer embedded --sol 0.01 --max-open 3 --lifetime-sol 0.1 \
+  --modes open,exp-custom --max-age 60 --max-impact 300 --exit tpsl --take-profit 2 --stop-loss 0.5
+```
+
+With the API key in the environment, `init` looks up the key's wallet for you. Without a wallet, a dry config gets a
+placeholder address; live mode needs the real one.
+
+### Or let your agent set it up
+
+Paste this to a coding agent (Claude Code, or any agent with a shell):
+
+> Install and set up candle-launch-bot for me. Read `npx candle-launch-bot --help` and the package's README.md. Ask me
+> for: payer (embedded or linked), ticket size in SOL, max open positions, lifetime SOL cap, launch modes, and the exit
+> strategy. My Candle API key is in the env var CANDLE_API_KEY; never print it. Run `npx candle-launch-bot init --yes`
+> with my answers, then `scan --for 600` and show me what it would have bought. Then start a dry run
+> (`run --mode dry`) and show me `status.json` after a launch. Do not go live until I say so.
+
+The package also ships an agent skill, `skills/candle-launch-bot/SKILL.md`, that walks an agent through the same steps.
+
+## Setup in detail
+
+### 1. Install
+
+`npx candle-launch-bot ...` needs nothing else. To keep a copy: `npm install -g candle-launch-bot`. From source:
+
+```sh
+git clone <this repo> && cd candle-launch-bot
+npm ci
+npm test
+```
+
+A source checkout runs the TypeScript in `src/` directly (Node strips the types); the package runs the compiled `dist/`.
+
+### 2. Candle API key
+
+Make an agent key for your Candle account (`cndl_live_…`; on candle.tv's agents page, or `candle keys create` with
+the Candle CLI). Trading needs the **`swap:write`** scope, which a key only gets when it is asked for (pass it in the
+key's scopes when you create it). The key decides which Candle profile the trades show under. Put the key in an
+environment variable, never in the config file:
+
+```sh
+export CANDLE_API_KEY=cndl_live_...
+```
+
+If your account caps SOL per trade on the key, set the cap at or above `buy.sol`.
+
+### 3. Pick a payer
+
+| `payer` | Pays from | Signs | Needs |
+|---|---|---|---|
+| `embedded` | your Candle account's embedded Solana wallet | Candle, server-side, inside the trade call | the API key only |
+| `linked` (default) | a TEE wallet bound to the API key | this machine, with the key's signer, through Candle's relay | the API key and the key signer (below) |
+
+`embedded` is the simple one: it needs nothing but the API key, so it also suits a server with no OS keychain (a Linux
+box without `secret-tool`, where the Candle CLI keeps its secrets in an encrypted file). At start the bot reads the key's embedded wallet (`GET /api/v1/agent/wallets/embedded`)
+and refuses to run unless `wallet` is its Solana address, the key isn't denied the wallet, and the wallet is
+delegated (so Candle can sign). There is no signer to set up: leave `signer`, `privyAppId`, `linkedWalletId` and
+`privyWalletId` out (the config refuses them with `embedded`).
+
+```json
+{ "mode": "live", "payer": "embedded", "apiKeyEnv": "CANDLE_API_KEY", "wallet": "<your embedded wallet address>", ... }
+```
+
+With `embedded`, Candle signs and broadcasts inside the build call, so the bot can't save a signature before sending
+(it can with `linked`). What it does instead:
+
+- every order has one `clientTradeId` for life;
+- a build that fails in any way other than Candle's own 4xx refusal counts as possibly executed (it counts against
+  `lifetimeSol` and `maxPerCoin`);
+- the next attempt first reads Candle's trade job: `confirmed` is booked from its transaction, an id still in flight
+  is waited on (also at the attempt cap), and a same-id rebuild is Candle's replay of that trade, never a second one.
+
+The embedded wallet is shared by the whole account: other API keys, the candle.tv app and you by hand all trade from
+it. The bot's caps (`lifetimeSol`, `maxOpen`, `maxPerCoin`) count only this bot's own orders, not the wallet's other
+trades. A sell of the same coin by someone else shows up as a wallet shortfall: the position is written down to what
+the wallet still holds (alert `shortfall`). When a possibly executed buy can't be confirmed through Candle, the bot looks for its
+transaction in the history of the wallet's token account for that coin (a buy since the order was made, for about the
+ticket's SOL, landed while one of the order's attempts could have, not booked by another order, read back to the
+order's creation) and books that (alert `found_tx`; two
+such transactions are a double execution, booked together, alert `double_execution`). Without one, it adopts only tokens
+that arrived *after* the order was made in buys that spent SOL (never a transfer or airdrop), and at most 1.5 x the
+order's expected fill plus slippage (alert `adopted`).
+Tokens that nothing explains yet may be an RPC that lags the balance: the order stays open and the scan repeats on the
+backoff, up to 10 times (alert `rescan`). From then on the order only scans; it never builds again. A bag that was
+already in the wallet, or anything bigger than this order could have bought, is left alone with an alert
+(`unexplained_tokens`). `sell` on that coin reopens the ended buy's position by the same rule: its own transaction if the
+history now shows it (its tokens, its cost), else only tokens bought since the order, capped (cost the ticket); never a
+bag that was already there (alert `reopened`). Every 10 min the bot also compares the wallet's balance of each held coin
+with what it booked (also for an hour after a position ends); more than booked on two readings a minute apart is
+alerted (`surplus`), never adopted. Trading the bot's coins by hand in the same wallet confuses these checks; a wallet of its own (a separate account, or
+`linked`) avoids all of it.
+
+Everything else is the same for both payers: fills booked from the transaction, the sell clamp (on the wallet that
+pays), capped retries, alerts.
+
+### 4. TEE wallet and its signer (payer `linked`)
+
+The bot pays from a Candle **TEE wallet bound to the API key**. At start it lists the wallets the key can trade
+from (`GET /api/v1/agent/wallets/trading`) and refuses to run unless `wallet` is one of them. The same answer gives the
+key's prefix and Candle's Privy app id, so `privyAppId`, `linkedWalletId` and `privyWalletId` need no config. Set them
+only to pin values; a pin that disagrees with Candle stops the bot.
+
+Signing happens on your machine with the key's P-256 **key signer**, made once with the Candle CLI on the machine that
+will run the bot (`candle tee signer new --key <key prefix>`) and approved by the account owner
+(`candle keys signer approve <code> --key <key prefix>`). Bind the wallet to the key with the CLI as Candle documents.
+Then tell the bot where the signer is with `signer`:
+
+| `signer.store` | Where the key is |
+|---|---|
+| `keychain` | Where the Candle CLI keeps it in the OS keychain (service `tv.candle.cli`): account `key_signer_<keyPrefix>_<spkiSha256>`, found through `keySigners.entries` in `~/.config/candle/config.json` by key prefix and the wallet's signer quorum, and checked against that index. For an imported (non-TEE) linked wallet, account `wallet_signer_<linkedWalletId>`. Uses `security` on macOS, `secret-tool` on Linux. A CLI that keeps its secrets in an encrypted file instead of an OS keychain can't be read this way: use `file` or `env`. |
+| `file` | An `EncryptedFileSecretStore` file from the SDK (`path`, relative to the config file), passphrase in an env var (`passphraseEnv`), keyed by the wallet's linked-wallet id |
+| `env` | The PEM (or the CLI's single-line base64 PKCS#8 form) in an env var (`pemEnv`) |
+
+`keychain` reads where the Candle CLI stores the signer today (its config index and keychain account names). If a
+later CLI version stores it differently, the bot reports the signer as missing at start; `file` or `env` don't depend
+on the CLI.
+
+### 5. Funding
+
+Send SOL to the wallet that pays (embedded or TEE): tickets (`buy.sol` × the number of entries you allow) plus about 0.003 SOL per coin for
+token-account rent and network fees. Every buy also pays Candle's platform fee on top of the ticket.
+
+### 6. Run
+
+```sh
+candle-launch-bot init [--out bot.json]             # write a config
+candle-launch-bot scan --config bot.json            # watch and print what it would buy; never trades
+candle-launch-bot run  --config bot.json --mode dry # the whole loop with paper fills
+candle-launch-bot run  --config bot.json            # live, if the config says "mode": "live"
+candle-launch-bot status --config bot.json          # the last status.json
+candle-launch-bot sell <mint> --config bot.json [--fraction 0.5]
+```
+
+`sell` goes through the same order path as the bot (balance clamp, retries). If the bot is running, `sell` hands it
+the request through `<stateDir>/requests/` and the bot runs it. A position whose exits Candle keeps refusing
+(`exit_stuck`) gets one automatic try every `retry.stuckRetryMs` and an alert until it sells; `sell` tries at once.
+
+Each cycle runs exits first (sell orders, then the strategy's new exits), then entries, within a time budget. A slow
+market read while filtering times out after 3 s, and STOP or a signal is checked between steps and between orders.
+
+## Controls (the brakes)
+
+Files in the state dir, read at the top of every cycle:
+
+- `STOP`: finish the cycle, write status, exit 0. The file stays: a restart exits again at once until you remove it.
+- `PAUSE_BUYS`: no new entries; exits keep running.
+
+`SIGINT`/`SIGTERM` stop the same way as `STOP`. A restart picks up from the ledger: open positions, orders in flight
+(a signed transaction is checked on chain before anything is rebuilt), caps used.
+
+## State dir
+
+| File | What |
+|---|---|
+| `ledger.sqlite` | positions, orders, every attempt with its full error (program logs included), launches seen, alerts |
+| `status.json` | written every cycle: equity, open positions with price and multiple, caps used, order-queue health, detection stats and latencies |
+| `events.jsonl` | one JSON line per event (also on stdout) |
+| `lock` | one process per state dir |
+
+Every line that leaves the process is redacted first: the values of env vars whose names look secret
+(`KEY`, `TOKEN`, `SECRET`, `PASSPHRASE`, `RPC`, …), the API key, the RPC URLs' keys, and common key patterns.
+
+## Config reference
+
+```json
+{
+  "mode": "live",
+  "apiUrl": "https://api.alpha.candle.tv",
+  "apiKeyEnv": "CANDLE_API_KEY",
+  "rpcUrlEnv": "SOLANA_RPC_URL",
+  "rpcWsUrlEnv": "SOLANA_WS_URL",
+  "payer": "linked",
+  "wallet": "<TEE wallet address>",
+  "signer": { "store": "keychain" },
+  "stateDir": "./state",
+  "loopMs": 2000,
+  "buy": { "sol": 0.05, "maxSlippageBps": 500, "maxOpen": 3, "lifetimeSol": 1, "maxPriorityFeeLamports": 200000 },
+  "sell": { "maxSlippageBps": 1000 },
+  "filters": {
+    "chains": ["solana"],
+    "launchModes": ["open", "exp-custom"],
+    "maxAgeSec": 60,
+    "maxImpactBps": 300,
+    "creatorAllow": [],
+    "creatorDeny": [],
+    "nameMatch": "dog|cat",
+    "symbolMatch": "^[A-Z]{3,6}$",
+    "inferModeFromCurve": true
+  },
+  "detect": { "api": true, "chain": true, "apiPollMs": 3000, "chainPollMs": 15000, "apiLimit": 20 },
+  "exit": { "strategy": "ladder", "rungs": [{ "at": 2, "sell": 0.5 }, { "at": 5, "sell": 0.25 }], "stopLoss": 0.4 },
+  "retry": { "maxAttempts": 6, "baseDelayMs": 2000, "maxDelayMs": 120000, "maxExitOrders": 3, "stuckRetryMs": 600000, "builtProbeMs": 600000 },
+  "alerts": { "command": ["/usr/local/bin/notify-me", "launch-bot"], "webhookEnv": "ALERT_WEBHOOK_URL", "renotifyMs": 3600000 }
+}
+```
+
+Unknown keys are refused at every level, so a typo fails at start instead of being ignored.
+
+| Key | Meaning |
+|---|---|
+| `mode` | `dry` (decide and log, paper fills) or `live` |
+| `apiUrl` | Candle API host (must be https) |
+| `apiKeyEnv` | name of the env var holding the API key |
+| `rpcUrlEnv`, `rpcWsUrlEnv` | env vars with your Solana RPC http and websocket URLs. Default: the public mainnet RPC, websocket derived from the http URL |
+| `payer` | `embedded` (Candle signs; API key only) or `linked` (TEE wallet, local key signer; default) |
+| `wallet` | the wallet that pays: the key's embedded wallet, or the TEE wallet |
+| `linkedWalletId`, `privyWalletId`, `privyAppId` | optional pins; Candle supplies all three, and a pin that disagrees stops the bot |
+| `buy.sol` | SOL per ticket |
+| `buy.maxSlippageBps` | slippage tolerance on buys |
+| `buy.maxOpen` | most positions open at once (open, opening, or stuck) |
+| `buy.lifetimeSol` | most SOL in tickets ever committed to buys by this state dir. Candle's platform fee (its `bps`, about 0.25 %) and network fees come on top. A buy refused before anything was signed, or reverted, doesn't count; a refusal after signing does, because it might have landed |
+| `buy.maxPerCoin` | entries per coin: 1 (the only value; re-entering a coin is not supported) |
+| `buy.maxPriorityFeeLamports`, `sell.maxPriorityFeeLamports` | priority-fee ceiling Candle's build may bid (Jupiter venue) |
+| `sell.maxSlippageBps` | slippage tolerance on sells (default: the larger of the buy's and 1000) |
+| `filters.launchModes` | Candle launch modes to buy: `open`, `exclusive`, `exp-a`, `exp-b`, `exp-c`, `exp-custom` (also `test-open`, `test-exclusive`); anything else is a config error |
+| `filters.maxAgeSec` | skip a coin older than this at decision time (age from the launch transaction's block time) |
+| `filters.maxImpactBps` | skip when your ticket's average fill price would be more than this above the spot price (`s1/s0 - 1` on the curve's square-root price, after the curve's fee), from the curve account; checked again before every buy retry |
+| `filters.inferModeFromCurve` | a launch seen on chain before Candle's list has it counts as `open` when its curve account matches the open preset exactly (threshold, fee, both liquidity segments, start price). Every other curve, `exclusive` and all `exp-*` modes included, waits for Candle's `tier`, since an exp-custom curve can take any threshold. Default true |
+| `filters.creatorAllow` / `creatorDeny` | addresses; matched against the token list's creator and the launch transaction's signer. The bot's own `wallet` is always denied |
+| `filters.nameMatch` / `symbolMatch` | case-insensitive regular expressions |
+| `detect.*` | turn a source off, set poll intervals |
+| `exit` | `{ "strategy": "<name>", ...params }`, or `{ "strategy": "x", "module": "./my-exit.ts", ... }` |
+| `retry.maxAttempts` | attempts per order before it is terminal |
+| `retry.baseDelayMs`, `maxDelayMs` | exponential backoff with jitter, per order |
+| `retry.maxExitOrders` | exit orders Candle *refuses* (or that revert) before a position goes `exit_stuck`. Orders that run out of attempts on network errors, timeouts, 5xx or rate limits don't count: the next exit is minted on the position's backoff, without limit |
+| `retry.builtProbeMs` | payer `embedded`: a trade Candle still shows as `built` after this long (default 10 min) gets one same-id build that asks Candle for its signature. For a buy it runs only while the buy would still be placed (before its deadline, buys not paused, impact passing) |
+| `retry.builtHoldMs` | payer `embedded`: a buy past its deadline whose job stays `built` this long (default 6 h) is ended after a wallet scan (alert `built_held`); it stays counted in `lifetimeSol` |
+| `retry.stuckRetryMs` | an `exit_stuck` position still gets one more exit try this often (default 10 min), and its alert keeps repeating until an exit fills |
+| `alerts.command` | argv run (no shell) for each alert; the alert is JSON on stdin and in `ALERT_KEY` / `ALERT_MESSAGE`. It gets a minimal environment: `PATH`, those two, and the names in `alerts.commandEnv`; never the API key, signer or RPC URL |
+| `alerts.commandEnv` | extra env var names to pass to the alert command |
+| `alerts.webhookEnv` | env var holding a URL that gets each alert as a JSON POST |
+| `alerts.renotifyMs` | how often a condition that lasts (an `exit_stuck` position, a fill that can't be read) is announced again; default 1 h |
+| `alerts.holdAlertMs` | exits held for want of a sell route (migrating, pool at its floor, no price, unreadable) longer than this reach the alert sinks as `no_route`; default 5 min |
+
+A filter that needs a field the bot doesn't have yet (a launch seen on chain before Candle's list has its mode or
+name) waits for it and asks Candle's market endpoint. A field that never arrives never counts as a pass.
+
+## Exit strategies
+
+| Strategy | Params | Does |
+|---|---|---|
+| `hold` | none | never sells by itself |
+| `tpsl` | `takeProfit` (×), `stopLoss` (×), `trailing` (fraction off the peak) | sells all on any of them |
+| `time` | `afterSec` | sells all N seconds after entry |
+| `ladder` | `rungs: [{ at, sell }]`, `stopLoss` | sells `sell` of the original size at each multiple, keeps the rest as a core |
+| `preGrad` | `progress` (0..1), `fraction`, `stopLoss` | sells before graduation at a curve-progress threshold |
+
+Multiples are against your all-in entry price (SOL spent including Candle's fee, over tokens received). `preGrad`
+exists because graduated Candle coins sell only through Jupiter, and `exp-custom` pools often sit at their price floor
+with no sell route at all. Selling while the curve can still take it avoids that.
+
+### Writing one
+
+A strategy is one file that exports `create(params)` and returns `{ name, onTick }`. Put it next to your config and
+point `exit.module` at it (a path relative to the config file); the other keys of `exit` are its params. The engine
+needs no change. A `.js` file works everywhere; a `.ts` file works too on Node 22.18+ (outside `node_modules`).
+
+```js
+// my-exit.js   "exit": { "strategy": "breakeven", "module": "./my-exit.js", "arm": 1.5 }
+export function create(params) {
+  const arm = Number(params.arm ?? 1.5);
+  return {
+    name: "breakeven",
+    onTick(p, m) {
+      if (m.priceSol === null) return { action: "hold" };
+      const armed = p.peakPriceSol >= p.entryPriceSol * arm;
+      return armed && m.priceSol <= p.entryPriceSol ? { action: "sell", fraction: 1, reason: "back to entry" } : { action: "hold" };
+    },
+  };
+}
+```
+
+`examples/strategies/` has three to start from: `timeboxed-tp.js` (take profit inside a time window, else sell when it
+closes), `breakeven-stop.js` (a stop that arms at a multiple and sits at entry) and `stale-coin.js` (sell a coin that
+has not moved after a while). Types for TypeScript authors: `import type { ExitStrategy } from "candle-launch-bot"`.
+
+`onTick(position, market)` runs once per cycle for each open position with no exit order in flight:
+
+- `position`: `mint, openedAtMs, qtyRaw, remainingRaw, decimals, entryPriceSol, peakPriceSol, soldFraction`
+- `market`: `priceSol` (null if unreadable this cycle), `progress` (graduation, 0..1), `migrated`, `venue`
+  (`curve` / `damm`), `nowMs`
+- return `{ action: "hold" }` or `{ action: "sell", fraction, reason }`, where `fraction` is a share of what remains
+
+## How it handles your money
+
+- **Quantity is what the chain says.** After a fill the bot reads the transaction and books the wallet's token and
+  SOL balance changes, with the network fee and token-account rent kept apart. If the transaction can't be read it
+  keeps reading; after several failed reads it asks Candle again (`confirm` replay) for `actualOutRaw`, else books the
+  build's `minOutRaw`, and raises
+  an alert. Every position records which source it used.
+- **Sells are clamped** to the wallet's on-chain balance when the order is made, less what the bot's other positions
+  in the same coin own. The clamp only reduces, never sells more than the position holds (so tokens held by others in
+  the same wallet are left alone), and a zero or unreadable balance refuses the sell and raises an alert. When the
+  wallet holds less than the ledger, the position is written down to the balance (alert `shortfall`) so it can close.
+- **One live transaction per order.** The signature and the transaction's blockhash are saved before submit. Before
+  any rebuild, the saved signature is checked on chain, and the rebuild waits until the chain says that blockhash can no
+  longer be used (`isBlockhashValid`, judged by block height, not by the clock). Rebuilds reuse the order's
+  `clientTradeId`. `IDEMPOTENCY_CONFLICT` is never treated as a failure: `prior_attempt_on_chain` is booked as the fill,
+  and anything else waits and reconciles.
+- **Retries** have a cap, jittered exponential backoff on each order's own clock, and a terminal state. A throw costs
+  an attempt like any failure. Errors are read by `code`, `status`, `stage` and `reason`, never by message text.
+  Only Candle's own non-retryable 4xx refusal at build or sign (nothing broadcast yet) ends an order at once. Network
+  errors (`fetch failed` with ECONNRESET, ENOTFOUND, …), timeouts and 5xx are always retried. A refusal from Candle's
+  submit is treated as possibly broadcast, because it doesn't say whether the transaction went out: the bot waits and
+  reconciles on chain before it builds again. Every SDK and RPC call has a timeout, and settling a fill never sleeps
+  inside the loop.
+- **Exits wait for a route.** While a coin is migrating to its pool (its curve full, or flagged migrated with the pool
+  not there yet; about 3.5 min), has no readable price, or its pool sits at its price floor, no sell is placed and no
+  exit attempt is used up.
+- **A conflict is never a failure.** An order Candle answered with `IDEMPOTENCY_CONFLICT` is not rebuilt and can't go
+  terminal until Candle's trade job settles: `confirmed` is booked, gone or failed allows a same-id rebuild.
+- **Stale buys stop.** A buy order carries a deadline (launch time + `maxAgeSec`) and is never built past it, nor
+  while `PAUSE_BUYS` is set. A dry run never touches live orders, and a state dir holds one mode only.
+- **Alerts** carry the worsening dimension in their key (attempt buckets, terminal states, stuck exits), so a
+  condition that gets worse raises a new alert; a repeat of the same one is announced again every `alerts.renotifyMs`.
+
+## Know the terrain
+
+- **Thin curves.** Candle curves start thin: a ticket of a few tenths of a SOL can move the price several percent.
+  `filters.maxImpactBps` is checked against the curve before every buy.
+- **Graduated coins.** After graduation a coin trades in its DAMM v2 pool and sells route through Jupiter. Some
+  `exp-custom` pools sit at their price floor with no sell route; the bot holds exits until a route exists and alerts
+  when that lasts (`alerts.holdAlertMs`). `preGrad` sells while the curve can still take it.
+- **Shared embedded wallet.** With `payer: "embedded"` the wallet belongs to the whole account (see "Pick a payer").
+- **One entry per coin.** `buy.maxPerCoin` is 1; re-entering a coin is not supported.
+- **The keychain signer follows the Candle CLI's storage layout** (see "TEE wallet and its signer").
+- **Solana only.**
+
+## Development
+
+`npm test` runs `scripts/check-neutral.sh` (no home paths, emails, keys) and the suite (`node --test`, no network). `npm run typecheck` checks types and
+`npm run build` compiles `dist/` (run on `npm pack`). See CONTRIBUTING.md.
+
+## License
+
+MIT. Fork it, tune it, run it.
+
+Ladder out. Keep a core. Keep the receipts.

package/bin/candle-launch-bot

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// The published package runs the compiled dist/; a source checkout runs src/ directly (Node strips types).
+import { existsSync } from "node:fs";
+const dist = new URL("../dist/cli.js", import.meta.url);
+const entry = existsSync(dist) ? dist : new URL("../src/cli.ts", import.meta.url);
+const { main } = await import(entry.href);
+process.exit(await main(process.argv.slice(2)));

package/dist/alerts.d.ts

@@ -0,0 +1,28 @@
+import type { Ledger } from "./ledger.ts";
+import type { Logger } from "./log.ts";
+export interface AlertConfig {
+    command?: string[];
+    /** Env var names passed to the command besides PATH, ALERT_KEY, ALERT_MESSAGE (nothing else is inherited). */
+    commandEnv?: string[];
+    webhookEnv?: string;
+    renotifyMs: number;
+}
+export type AlertSink = (a: {
+    key: string;
+    message: string;
+    at: string;
+}) => Promise<void>;
+export declare function commandSink(argv: string[], timeoutMs?: number, passEnv?: string[], env?: NodeJS.ProcessEnv): AlertSink;
+export declare function webhookSink(url: string, f?: typeof fetch, timeoutMs?: number): AlertSink;
+export declare class Alerter {
+    private ledger;
+    private log;
+    private sinks;
+    private now;
+    readonly renotifyMs: number;
+    sent: number;
+    constructor(ledger: Ledger, log: Logger, sinks: AlertSink[], renotifyMs: number, now?: () => number);
+    /** Record an alert; announce it (log + sinks) when it is new or its renotify time has come. */
+    raise(key: string, message: string, fields?: Record<string, unknown>): boolean;
+}
+export declare function makeAlerter(cfg: AlertConfig, ledger: Ledger, log: Logger, env?: NodeJS.ProcessEnv, now?: () => number): Alerter;

package/dist/alerts.js

@@ -0,0 +1,82 @@
+/**
+ * Alerts that leave the process. Every alert is deduped in the ledger under a key that carries the worsening
+ * dimension (attempt bucket, terminal state); a key is announced when first seen and again after `renotifyMs`
+ * while it keeps recurring. Conditions that need a human (exit_stuck, a fill that cannot be read) are re-raised by
+ * the engine every cycle, so they re-announce on that schedule until cleared.
+ *
+ * Sinks (both optional, both redacted, both bounded by a timeout, neither can stop the bot):
+ *  - command: an argv list run without a shell; the alert is JSON on its stdin, ALERT_KEY / ALERT_MESSAGE in env
+ *  - webhook: POST JSON {key, message, at} to the URL held in the env var named by webhookEnv
+ */
+import { spawn } from "node:child_process";
+import { addSecret, redact } from "./redact.js";
+export function commandSink(argv, timeoutMs = 10_000, passEnv = [], env = process.env) {
+    return (a) => new Promise((resolve) => {
+        try {
+            // A minimal environment: the API key, signer, RPC URL and webhook never reach the alert command.
+            const childEnv = { PATH: env.PATH ?? "/usr/bin:/bin", ALERT_KEY: a.key, ALERT_MESSAGE: a.message };
+            for (const n of passEnv)
+                if (env[n] !== undefined)
+                    childEnv[n] = env[n];
+            const child = spawn(argv[0], argv.slice(1), { stdio: ["pipe", "ignore", "ignore"], env: childEnv, timeout: timeoutMs });
+            child.on("error", () => resolve());
+            child.on("exit", () => resolve());
+            child.stdin.on("error", () => undefined);
+            child.stdin.end(JSON.stringify(a) + "\n");
+        }
+        catch {
+            resolve();
+        }
+    });
+}
+export function webhookSink(url, f = fetch, timeoutMs = 10_000) {
+    addSecret(url);
+    return async (a) => {
+        try {
+            await f(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(a), signal: AbortSignal.timeout(timeoutMs) });
+        }
+        catch {
+            /* a dead webhook never stops the bot; the ledger and the log keep the alert */
+        }
+    };
+}
+export class Alerter {
+    ledger;
+    log;
+    sinks;
+    now;
+    renotifyMs;
+    sent = 0;
+    constructor(ledger, log, sinks, renotifyMs, now = Date.now) {
+        this.ledger = ledger;
+        this.log = log;
+        this.sinks = sinks;
+        this.renotifyMs = renotifyMs;
+        this.now = now;
+    }
+    /** Record an alert; announce it (log + sinks) when it is new or its renotify time has come. */
+    raise(key, message, fields = {}) {
+        const due = this.ledger.alert(key, message, this.now(), this.renotifyMs);
+        if (!due)
+            return false;
+        const msg = redact(message);
+        this.log.warn("alert", { key, message: msg, ...fields });
+        const a = { key: redact(key), message: msg, at: new Date(this.now()).toISOString() };
+        this.sent++;
+        for (const s of this.sinks)
+            void s(a).catch(() => undefined);
+        return true;
+    }
+}
+export function makeAlerter(cfg, ledger, log, env = process.env, now) {
+    const sinks = [];
+    if (cfg.command?.length)
+        sinks.push(commandSink(cfg.command, 10_000, cfg.commandEnv ?? [], env));
+    if (cfg.webhookEnv) {
+        const url = env[cfg.webhookEnv];
+        if (!url)
+            throw new Error(`alerts.webhookEnv: ${cfg.webhookEnv} is not set`);
+        sinks.push(webhookSink(url));
+    }
+    return new Alerter(ledger, log, sinks, cfg.renotifyMs, now);
+}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+export declare const HELP = "candle-launch-bot: buys Candle launches as they appear and exits them by a strategy.\n\n  candle-launch-bot init   [--out bot.json] [--yes] [flags]   write a config (dry mode unless --mode live)\n  candle-launch-bot scan   --config bot.json [--for 600]       detect and print what it would buy; never trades\n  candle-launch-bot run    --config bot.json [--mode dry|live] run the bot\n  candle-launch-bot status --config bot.json                   print status.json\n  candle-launch-bot sell   <mint> --config bot.json [--fraction 1]\n\ninit flags (all optional; with --yes nothing is asked; defaults shown):\n  --mode dry|live (dry)  --payer embedded|linked (embedded)  --key-env <env var with the API key> (CANDLE_API_KEY)\n  --wallet <address> (looked up when the key is set)  --api-url <https url>\n  --sol 0.01  --max-open 3  --lifetime-sol (10 tickets)  --modes open,exp-custom  --max-age 60  --max-impact 300\n  --slippage 500\n  --exit hold|tpsl|time|ladder|preGrad (tpsl)  --take-profit 2  --stop-loss 0.5  --trailing <0-1>  --after-sec 900\n  --progress 0.8  --fraction 1  --rungs 2:0.3,5:0.3,10:0.2\n  --exit-module ./my-exit.js  --exit-params '{\"arm\":1.5}'   your own strategy file and its params\n  --signer keychain|file|env (keychain)  --signer-env <env var with the PEM>  --signer-path <file>\n  --signer-pass-env <env var with the file's passphrase>      payer linked only\n  --rpc-env <env var with an RPC url>  --rpc-ws-env <env var with a websocket url>\n  --webhook <env var with an alert webhook url>  --state-dir <dir> (./state-dry or ./state-live)\n  --out bot.json  --force (overwrite)\n\nControls: create STOP or PAUSE_BUYS in the state folder. Docs: the README.\n";
+/** The entry point: never lets an error out unredacted (the SDK puts RPC URLs in its messages). */
+export declare function main(argv?: string[]): Promise<number>;