candle-event-bot 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog: candle-event-bot
+
+## 0.1.0
+
+First version, on candle-bot-core 0.6.0.
+
+- `events`: a list of coins, each with a dated event (ISO 8601 with its offset) and a label.
+- Buys each coin once (`buy.maxPerCoin`) in a window before its event (`entry.fromHours` to `entry.untilMin`), on its
+  own venue: the Candle curve, its DAMM v2 pool, the pump.fun curve or the canonical PumpSwap pool, quoted by that
+  venue's math. Refused venues (mayhem-mode, cashback, another quote mint, a venue it does not know) and an impact over
+  `entry.maxImpactBps` are skipped before any attempt. Retries are rechecked on the venue (impact and drift).
+- The `event` exit (core): optional ladder rungs and a stop loss during the build-up, a hedge at the event (keep
+  `hedgeKeep`), a moonshot core after it (keep `coreKeep`), and the core's own take profit and max hold.
+- `plan` prints each event's buy window and exit phases in clock time; never trades.

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,91 @@
-# Temporary Holding Version
+# candle-event-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.
+Buys coins tied to a dated event (a launch, a keynote, a listing) in a window before it, and exits them in phases
+keyed to the event: ride the build-up, hedge at the event, keep a moonshot core. A Solana bot built on
+[candle-bot-core](../core) and `@candledottv/agent-sdk`.
+
+```sh
+npm install -g candle-event-bot
+candle-event-bot plan --config examples/dry.json   # each event's buy window and exit phases; never trades
+candle-event-bot run  --config examples/dry.json   # dry run: decides and logs, never trades
+```
+
+## Events
+
+```json
+"events": [{ "mint": "<the coin>", "at": "2026-12-01T17:00:00Z", "label": "the keynote" }]
+```
+
+One event per coin. `at` is an ISO 8601 time **with its offset**; a time without one is refused, so it can never be
+read in the machine's local time by mistake. Check the date yourself. A wrong day is the costliest mistake this bot
+can make, and `plan` prints every phase in clock time to catch it.
+
+## When it buys
+
+`entry`:
+
+| key | default | meaning |
+|---|---|---|
+| `fromHours` | 72 | the buy window opens this long before the event |
+| `untilMin` | 60 | and closes this long before it (no attempt is built after) |
+| `maxImpactBps` | 300 | the ticket's impact on the venue (also the retry limit) |
+| `buyWithinSec` | 60 | no attempt is built later than this after the decision |
+| `retryMin` | 10 | a coin skipped in its window is looked at again after this long |
+| `checkPrograms` / `extraPrograms` | true / [] | linked payer: only builds calling known programs are signed. With payer `main` none of these three checks applies (Candle signs inside the build) |
+| `sellFloorMarginBps` | 200 | linked payer: a sell is never signed below the venue's expected out less `sell.maxSlippageBps` and this. pump.fun venues only: on a Candle curve or DAMM v2 coin, or when the read fails, only Candle's own floor applies |
+| `buyFloorMarginBps` | 200 | linked payer: a buy is never signed with a floor under the decision fill less `buy.maxSlippageBps` and this (the first attempt too) |
+
+Each coin is bought once (`buy.maxPerCoin`, default 1) with a ticket of `buy.sol`. The coin's venue is read fresh at
+the decision: the Candle curve, its DAMM v2 pool, the pump.fun curve or the canonical PumpSwap pool. The buy must be
+quoted by that venue's own math. These are skipped before any attempt:
+- a venue the math refuses (mayhem-mode, cashback, another quote mint, a buy past the curve's tokens);
+- a coin on a venue it does not know (e.g. a Raydium or Orca pool);
+- an impact over the limit.
+
+The engine keeps the smaller of the bot's expected fill and its own read. A retry is rechecked on the venue: the
+ticket's impact, and the drift against the decision fill (`retry.maxPriceDriftBps`, else `maxImpactBps`). The core's
+caps, `PAUSE_BUYS` and `STOP` apply as in every bot.
+
+## Exits
+
+Any core strategy, or `event` (the phased exit; the bot gives it each coin's event time):
+
+```json
+{ "strategy": "event", "rungs": [{ "at": 3, "sell": 0.2 }], "stopLoss": 0.3,
+  "hedgeAtMin": 0, "hedgeKeep": 0.5, "afterMin": 60, "coreKeep": 0.2,
+  "coreTakeProfit": 20, "coreMaxHoldHours": 168 }
+```
+
+| phase | when | what |
+|---|---|---|
+| build-up | until `hedgeAtMin` after the event | only `rungs` (the ladder's: at a multiple, sell that share of the original, in all) and `stopLoss` (a multiple: everything goes), each optional |
+| hedge | from `hedgeAtMin` (default 0; negative is before the event) | keep at most `hedgeKeep` (default 0.5) of the original |
+| core | from `afterMin` (default 60) | keep at most `coreKeep` (default 0.2): the moonshot core |
+| core exit | any time after `afterMin` | `coreTakeProfit` (a multiple) or `coreMaxHoldHours` after the event: the core goes; without them it is held |
+
+Every phase is a target for the share of the original position kept, so a restart, a failed sell or a late tick
+never sells twice. Without `rungs` and `stopLoss` nothing sells before the hedge. `stopLoss` acts only in the build-up:
+from the hedge on there is no stop loss, and what is kept rides the event down as well as up, until `coreTakeProfit`
+or `coreMaxHoldHours`.
+
+- **The buy window must close before the hedge:** a config whose window (`entry.untilMin`) reaches the hedge time
+  (`hedgeAtMin`) is refused at load, and a decision at or past the hedge is skipped. A buy then would be sold down at
+  once.
+- **The phases follow the event time in the config as it is now.** An event moved while a coin is held moves its
+  phases. Moved into the past, the phases already due sell at the next tick. Edit an event's time only while flat in
+  that coin, unless moving its phases is what you want.
+- **A coin held with no event in the list** (removed or changed in the config) gets no phase at all. The bot alerts
+  on it while it lasts. List it again, or `sell` it by hand.
+- Event times are checked as real dates: Feb 30 or 24:00 are refused, not rolled over.
+
+## Known limits
+
+- The venues are the four above. A coin that trades elsewhere is skipped, not guessed.
+- The bot buys at the first look inside the window that passes its checks. It does not time the entry within the
+  window.
+- Spend: `buy.lifetimeSol` counts tickets only. Candle's platform fee (0.25 % a side), network fees and about
+  0.002 SOL of token-account rent per new coin come on top.
+
+## License
+
+MIT

package/bin/candle-event-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/cli.d.ts

@@ -0,0 +1,22 @@
+import { Engine } from "candle-bot-core/engine";
+import { Ledger } from "candle-bot-core/ledger";
+import { type Ctx as CoreCtx } from "candle-bot-core/runtime";
+import { type Config } from "./config.ts";
+import { EventTrigger } from "./trigger.ts";
+export declare const HELP = "candle-event-bot: buys coins tied to a dated event (a launch, a keynote, a listing) in a window before it, and exits\nthem in phases keyed to the event: ride the build-up, hedge at the event, keep a moonshot core.\n\n  candle-event-bot run    --config bot.json [--mode dry|live]  run the bot\n  candle-event-bot plan   --config bot.json                    print each event's buy window and exit phases; never trades\n  candle-event-bot status --config bot.json                    print status.json\n  candle-event-bot sell   <mint> --config bot.json [--fraction 1]\n\nStart from examples/dry.json. Controls: create STOP or PAUSE_BUYS in the state folder. Docs: the README.\n";
+type Ctx = CoreCtx<Config>;
+/**
+ * The engine: buys checked on their own venue (Candle curve, DAMM v2 pool, pump.fun curve, PumpSwap pool) by the
+ * engine and the executor's retry recheck; the `event` exit gets each coin's event time.
+ */
+export declare function makeEngine(ctx: Ctx, ledger: Ledger, d?: {
+    now?: () => number;
+}): Promise<{
+    engine: Engine;
+    trigger: EventTrigger;
+}>;
+/** Each event's buy window and, for the event exit, its phases in clock time. */
+export declare function plan(cfg: Config, now?: number): Array<Record<string, unknown>>;
+/** 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>;
+export {};

package/dist/cli.js

@@ -0,0 +1,110 @@
+/** The command line: run, plan, status, sell. */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { Engine } from "candle-bot-core/engine";
+import { Executor } from "candle-bot-core/exec/executor";
+import { KNOWN_PROGRAMS } from "candle-bot-core/exec/trader";
+import { Ledger } from "candle-bot-core/ledger";
+import { sellFloor } from "candle-bot-core/market/reader";
+import { args, context as coreContext, die, guardMain, parts, run, sell, status } from "candle-bot-core/runtime";
+import { loadConfig, ConfigError, eventTimes } from "./config.js";
+import { EventTrigger, windowOf } from "./trigger.js";
+import { EVENT_DEFAULTS } from "candle-bot-core/strategies/event";
+export const HELP = `candle-event-bot: buys coins tied to a dated event (a launch, a keynote, a listing) in a window before it, and exits
+them in phases keyed to the event: ride the build-up, hedge at the event, keep a moonshot core.
+
+  candle-event-bot run    --config bot.json [--mode dry|live]  run the bot
+  candle-event-bot plan   --config bot.json                    print each event's buy window and exit phases; never trades
+  candle-event-bot status --config bot.json                    print status.json
+  candle-event-bot sell   <mint> --config bot.json [--fraction 1]
+
+Start from examples/dry.json. Controls: create STOP or PAUSE_BUYS in the state folder. Docs: the README.
+`;
+function context(configPath, modeOverride) {
+    let cfg;
+    try {
+        cfg = loadConfig(configPath);
+    }
+    catch (e) {
+        if (e instanceof ConfigError)
+            die(e.message);
+        throw e;
+    }
+    return coreContext(cfg, modeOverride);
+}
+/**
+ * The engine: buys checked on their own venue (Candle curve, DAMM v2 pool, pump.fun curve, PumpSwap pool) by the
+ * engine and the executor's retry recheck; the `event` exit gets each coin's event time.
+ */
+export async function makeEngine(ctx, ledger, d = {}) {
+    const c = ctx.cfg;
+    const linked = c.payer === "linked";
+    const known = linked && c.entry.checkPrograms ? new Set([...KNOWN_PROGRAMS, ...c.entry.extraPrograms]) : undefined;
+    const floor = linked ? sellFloor(ctx.rpc, c.sell.maxSlippageBps, c.entry.sellFloorMarginBps) : undefined;
+    const { strategy, alerter, executor } = await parts(ctx, ledger, {
+        maxBuyImpactBps: c.entry.maxImpactBps,
+        executor: (x) => new Executor({ ...x, dammBuys: true, pumpBuys: true, ...(known ? { knownPrograms: known } : {}), ...(floor ? { sellFloor: floor, buyFloorMarginBps: c.entry.buyFloorMarginBps } : {}) }),
+        venues: { pump: true },
+        ...(c.exit.strategy === "event" ? { exitParams: { events: eventTimes(c) } } : {}),
+        ...(d.now ? { now: d.now } : {}),
+    });
+    const trigger = new EventTrigger({ cfg: c, log: ctx.log, ...(d.now ? { now: d.now } : {}) });
+    const engine = new Engine({ cfg: c, ledger, trigger, executor, strategy, rpc: ctx.rpc, log: ctx.log, alerter, pumpBuys: true, venues: { pump: true }, ...(d.now ? { now: d.now } : {}) });
+    return { engine, trigger };
+}
+const openLedger = (ctx) => () => new Ledger(join(ctx.cfg.stateDir, "ledger.sqlite"));
+/** Each event's buy window and, for the event exit, its phases in clock time. */
+export function plan(cfg, now = Date.now()) {
+    const x = cfg.exit;
+    return cfg.events.map((e) => {
+        const w = windowOf(cfg, e);
+        const iso = (t) => new Date(t).toISOString();
+        const row = { mint: e.mint, label: e.label, event: iso(e.atMs), buyFrom: iso(w.opens), buyUntil: iso(w.closes), window: now < w.opens ? "not open" : now >= w.closes ? "closed" : "open" };
+        if (x.strategy === "event") {
+            const v = { ...EVENT_DEFAULTS, ...x };
+            row.hedge = `${iso(e.atMs + v.hedgeAtMin * 60_000)}: keep ${(v.hedgeKeep * 100).toFixed(0)} %`;
+            row.core = `${iso(e.atMs + v.afterMin * 60_000)}: keep ${(v.coreKeep * 100).toFixed(0)} %`;
+            if (x.coreMaxHoldHours !== undefined)
+                row.coreEnds = iso(e.atMs + x.coreMaxHoldHours * 3_600_000);
+        }
+        return row;
+    });
+}
+/** The entry point: never lets an error out unredacted (the SDK puts RPC URLs in its messages). */
+export async function main(argv = process.argv.slice(2)) {
+    return guardMain(async () => {
+        const { pos, opt } = args(argv);
+        const cmd = pos[0];
+        if (!cmd || cmd === "help" || opt.help) {
+            process.stdout.write(HELP);
+            return cmd || opt.help ? 0 : 2;
+        }
+        if (cmd === "version" || opt.version) {
+            process.stdout.write(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version + "\n");
+            return 0;
+        }
+        const config = opt.config ?? "bot.json";
+        switch (cmd) {
+            case "run": {
+                const ctx = context(config, opt.mode);
+                return run(ctx, openLedger(ctx), (ledger) => makeEngine(ctx, ledger));
+            }
+            case "plan": {
+                const ctx = context(config, "dry");
+                for (const r of plan(ctx.cfg))
+                    process.stdout.write(JSON.stringify(r) + "\n");
+                return 0;
+            }
+            case "status":
+                return status(context(config));
+            case "sell": {
+                if (!pos[1])
+                    die("sell <mint> [--fraction f]");
+                const ctx = context(config);
+                return sell(ctx, pos[1], opt.fraction ? Number(opt.fraction) : 1, openLedger(ctx), (ledger) => makeEngine(ctx, ledger));
+            }
+            default:
+                die(`unknown command ${cmd}`);
+        }
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The one config file: the core's shared sections (candle-bot-core) plus `events` (the dated events: a coin and a
+ * time each) and `entry` (when, before each event, the coin is bought, and the limits). The exit is any core strategy;
+ * `event` (the phased exit) gets each coin's event time from `events` (a config never sets exit.events itself).
+ * Unknown keys are refused at every level.
+ */
+import { type Config as CoreConfig } from "candle-bot-core/config";
+export { ConfigError } from "candle-bot-core/config";
+export interface EventItem {
+    mint: string;
+    /** The event time (ms), from an ISO 8601 time with its offset (e.g. "2026-12-01T17:00:00Z"). */
+    atMs: number;
+    label: string;
+}
+export interface Entry {
+    /** The buy window opens this many hours before the event... */
+    fromHours: number;
+    /** ...and closes this many minutes before it (a buy is never built after). */
+    untilMin: number;
+    /** The ticket's price impact on the venue, bps (the fee apart). Also the buy-retry limit. */
+    maxImpactBps: number;
+    /** No attempt of a buy is built more than this many seconds after its decision (nor after the window closes). */
+    buyWithinSec: number;
+    /** A coin skipped in its window is looked at again after this long (min). */
+    retryMin: number;
+    /** Linked payer: sign only builds whose programs are known (the core's list plus extraPrograms). Default true. */
+    checkPrograms: boolean;
+    extraPrograms: string[];
+    /**
+     * Linked payer: a sell is never signed below the venue's own expected out less sell.maxSlippageBps and this (pump.fun
+     * venues only; on another venue, or when the read fails, only Candle's own floor applies).
+     */
+    sellFloorMarginBps: number;
+    /** Linked payer: a buy is never signed with a floor under the decision fill less buy.maxSlippageBps and this. */
+    buyFloorMarginBps: number;
+}
+export type Config = CoreConfig & {
+    events: EventItem[];
+    entry: Entry;
+};
+declare function parseEvents(raw: unknown): EventItem[];
+declare function parseEntry(raw: unknown): Entry;
+export declare const SECTIONS: {
+    events: typeof parseEvents;
+    entry: typeof parseEntry;
+};
+/** The exit's event times, from the event list (the `event` strategy reads them). */
+export declare function eventTimes(c: Pick<Config, "events">): Record<string, number>;
+export declare function parseConfig(raw: unknown, baseDir?: string): Config;
+export declare function loadConfig(path: string): Config;

package/dist/config.js

@@ -0,0 +1,94 @@
+/**
+ * The one config file: the core's shared sections (candle-bot-core) plus `events` (the dated events: a coin and a
+ * time each) and `entry` (when, before each event, the coin is bought, and the limits). The exit is any core strategy;
+ * `event` (the phased exit) gets each coin's event time from `events` (a config never sets exit.events itself).
+ * Unknown keys are refused at every level.
+ */
+import { parseConfig as parseCore, loadConfig as loadCore, ConfigError, isObj, only, num, bool, str, strList } from "candle-bot-core/config";
+import { asAddress } from "candle-bot-core/solana/base58";
+import { create as eventExit, EVENT_DEFAULTS } from "candle-bot-core/strategies/event";
+export { ConfigError } from "candle-bot-core/config";
+function parseEvents(raw) {
+    const w = "config.events";
+    if (!Array.isArray(raw) || raw.length === 0)
+        throw new ConfigError(`${w}: a non-empty list of { mint, at, label? }`);
+    if (raw.length > 200)
+        throw new ConfigError(`${w}: at most 200 events`);
+    const seen = new Set();
+    return raw.map((e, i) => {
+        const k = `${w}[${i}]`;
+        if (!isObj(e))
+            throw new ConfigError(`${k}: { mint, at, label? }`);
+        only(e, ["mint", "at", "label"], k);
+        const mint = str(e, "mint", k);
+        if (asAddress(mint) !== mint)
+            throw new ConfigError(`${k}.mint: "${mint}" is not a Solana address`);
+        const at = str(e, "at", k);
+        // An explicit offset is required: a time without one would read as the machine's local time.
+        const g = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/.exec(at);
+        if (!g)
+            throw new ConfigError(`${k}.at: an ISO 8601 time with its offset, e.g. "2026-12-01T17:00:00Z"`);
+        // A date that does not exist (Feb 30, 24:00) would roll over to another day without a word: refused.
+        const [y, mo, d, hh, mm, ss] = [g[1], g[2], g[3], g[4], g[5], g[6] ?? "0"].map(Number);
+        if (mo < 1 || mo > 12 || d < 1 || d > new Date(Date.UTC(y, mo, 0)).getUTCDate() || hh > 23 || mm > 59 || ss > 59)
+            throw new ConfigError(`${k}.at: "${at}" is not a real date and time`);
+        const atMs = Date.parse(at);
+        if (!Number.isFinite(atMs))
+            throw new ConfigError(`${k}.at: not a time`);
+        if (seen.has(mint))
+            throw new ConfigError(`${k}.mint: ${mint} is listed twice (one event per coin)`);
+        seen.add(mint);
+        return { mint, atMs, label: str(e, "label", k, { def: "" }) };
+    });
+}
+function parseEntry(raw) {
+    const w = "config.entry";
+    const d = raw === undefined ? {} : raw;
+    if (!isObj(d))
+        throw new ConfigError(`${w}: must be an object`);
+    only(d, ["fromHours", "untilMin", "maxImpactBps", "buyWithinSec", "retryMin", "checkPrograms", "extraPrograms", "sellFloorMarginBps", "buyFloorMarginBps"], w);
+    const out = {
+        fromHours: num(d, "fromHours", w, { min: 0.1, max: 8760, def: 72 }),
+        untilMin: num(d, "untilMin", w, { min: -10_080, max: 525_600, def: 60 }),
+        maxImpactBps: num(d, "maxImpactBps", w, { min: 0, max: 10_000, def: 300 }),
+        buyWithinSec: num(d, "buyWithinSec", w, { min: 5, max: 3600, int: true, def: 60 }),
+        retryMin: num(d, "retryMin", w, { min: 1, max: 1440, int: true, def: 10 }),
+        checkPrograms: bool(d, "checkPrograms", w, true),
+        extraPrograms: strList(d, "extraPrograms", w, { def: [], address: true }),
+        sellFloorMarginBps: num(d, "sellFloorMarginBps", w, { min: 0, max: 10_000, int: true, def: 200 }),
+        buyFloorMarginBps: num(d, "buyFloorMarginBps", w, { min: 0, max: 10_000, int: true, def: 200 }),
+    };
+    if (out.untilMin >= out.fromHours * 60)
+        throw new ConfigError(`${w}: the window closes (untilMin before the event) before it opens (fromHours before it)`);
+    return out;
+}
+export const SECTIONS = { events: parseEvents, entry: parseEntry };
+/** The exit's event times, from the event list (the `event` strategy reads them). */
+export function eventTimes(c) {
+    return Object.fromEntries(c.events.map((e) => [e.mint, e.atMs]));
+}
+/** The event exit is checked at load, with the event times filled in (a config never sets exit.events). */
+function checked(c) {
+    if (c.exit.strategy === "event") {
+        if (c.exit.events !== undefined)
+            throw new ConfigError("config.exit.events: filled from config.events; leave it out");
+        // The buy window must close before the hedge: a buy after it would be sold down at the next exit tick.
+        const hedgeAtMin = typeof c.exit.hedgeAtMin === "number" ? c.exit.hedgeAtMin : EVENT_DEFAULTS.hedgeAtMin;
+        if (-c.entry.untilMin >= hedgeAtMin)
+            throw new ConfigError(`config.entry.untilMin: the buy window closes ${-c.entry.untilMin} min after the event, at or after the hedge (exit.hedgeAtMin ${hedgeAtMin}): a buy then would be sold at once`);
+        try {
+            const { strategy: _s, ...params } = c.exit;
+            eventExit({ ...params, events: eventTimes(c) });
+        }
+        catch (e) {
+            throw new ConfigError(String(e.message));
+        }
+    }
+    return c;
+}
+export function parseConfig(raw, baseDir = process.cwd()) {
+    return checked(parseCore(raw, baseDir, SECTIONS));
+}
+export function loadConfig(path) {
+    return checked(loadCore(path, SECTIONS));
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/** candle-event-bot: the trigger, the config and the wiring, for use as a library. */
+export { EventTrigger, windowOf } from "./trigger.ts";
+export type { TriggerDeps } from "./trigger.ts";
+export { parseConfig, loadConfig, eventTimes, SECTIONS, ConfigError } from "./config.ts";
+export type { Config, EventItem, Entry } from "./config.ts";
+export { main, HELP, makeEngine, plan } from "./cli.ts";

package/dist/index.js

@@ -0,0 +1,4 @@
+/** candle-event-bot: the trigger, the config and the wiring, for use as a library. */
+export { EventTrigger, windowOf } from "./trigger.js";
+export { parseConfig, loadConfig, eventTimes, SECTIONS, ConfigError } from "./config.js";
+export { main, HELP, makeEngine, plan } from "./cli.js";

package/dist/trigger.d.ts

@@ -0,0 +1,38 @@
+import type { Logger } from "candle-bot-core/log";
+import type { Candidate, PendingInfo, Trigger, TriggerContext, Verdict } from "candle-bot-core/trigger";
+import type { Config, EventItem } from "./config.ts";
+export interface TriggerDeps {
+    cfg: Config;
+    log: Logger;
+    now?: () => number;
+}
+/** The buy window of an event: [opens, closes) in ms. */
+export declare function windowOf(cfg: Config, e: EventItem): {
+    opens: number;
+    closes: number;
+};
+export declare class EventTrigger implements Trigger {
+    readonly name = "event";
+    readonly candidateLabel = "events";
+    readonly buyIdPrefix = "ceb";
+    readonly sellIdPrefix = "ces";
+    private d;
+    private now;
+    private nextLook;
+    private decimals;
+    last: Array<{
+        mint: string;
+        label: string;
+        at: number;
+        decision: string;
+        reason: string;
+    }>;
+    constructor(d: TriggerDeps);
+    /** With the event exit: when, after the event, the hedge begins (a buy is never made from then on). */
+    private hedgeAtMs;
+    poll(ctx: TriggerContext): Candidate[];
+    private decimalsOf;
+    decide(c: Candidate, ctx: TriggerContext): Promise<Verdict>;
+    onVerdict(c: Candidate, v: Verdict, _ctx: TriggerContext, _p: PendingInfo): void;
+    status(): Record<string, unknown>;
+}

package/dist/trigger.js

@@ -0,0 +1,142 @@
+/**
+ * The event bot's trigger: each listed coin is a candidate while its buy window is open (from `entry.fromHours` before
+ * its event to `entry.untilMin` before it) and the bot has not bought it (the engine's maxPerCoin). decide() reads the
+ * coin's venue fresh: the Candle curve, its DAMM v2 pool, the pump.fun curve or the canonical PumpSwap pool, quoted by
+ * that venue's own math (buyQuote). A venue the math refuses (mayhem-mode, cashback, another quote mint, a buy past
+ * the curve's tokens, a venue it does not know) is skipped before any attempt; so is an impact over `maxImpactBps`.
+ * The verdict's expected fill is the venue's quote, with a deadline: `buyWithinSec`, never past the window.
+ */
+import { lamportsOf } from "candle-bot-core/engine";
+import { decodeMint } from "candle-bot-core/market/mint";
+import { buyQuote, readMarkets } from "candle-bot-core/market/reader";
+import { EVENT_DEFAULTS } from "candle-bot-core/strategies/event";
+/** The buy window of an event: [opens, closes) in ms. */
+export function windowOf(cfg, e) {
+    return { opens: e.atMs - cfg.entry.fromHours * 3_600_000, closes: e.atMs - cfg.entry.untilMin * 60_000 };
+}
+export class EventTrigger {
+    name = "event";
+    candidateLabel = "events";
+    buyIdPrefix = "ceb";
+    sellIdPrefix = "ces";
+    d;
+    now;
+    nextLook = new Map();
+    decimals = new Map();
+    last = [];
+    constructor(d) {
+        this.d = d;
+        this.now = d.now ?? Date.now;
+    }
+    /** With the event exit: when, after the event, the hedge begins (a buy is never made from then on). */
+    hedgeAtMs() {
+        const x = this.d.cfg.exit;
+        if (x.strategy !== "event")
+            return null;
+        return (typeof x.hedgeAtMin === "number" ? x.hedgeAtMin : EVENT_DEFAULTS.hedgeAtMin) * 60_000;
+    }
+    poll(ctx) {
+        const now = this.now();
+        const out = [];
+        // A coin held with no event in the list (removed or changed in the config) gets no phase at all: said, while it lasts.
+        const listed = new Set(this.d.cfg.events.map((e) => e.mint));
+        for (const p of ctx.ledger.positions("opening", "open", "exit_stuck")) {
+            if (listed.has(p.mint))
+                continue;
+            ctx.alerter.raise(`event:no_event:${p.mint}`, `event bot: position ${p.id} ${p.mint} has no event in config.events, so no exit phase applies to it (held until it is listed again or sold by hand)`);
+        }
+        for (const e of this.d.cfg.events) {
+            const w = windowOf(this.d.cfg, e);
+            if (now < w.opens || now >= w.closes)
+                continue;
+            if ((this.nextLook.get(e.mint) ?? 0) > now)
+                continue;
+            if (ctx.caps(e.mint).entriesForMint >= this.d.cfg.buy.maxPerCoin)
+                continue;
+            this.nextLook.set(e.mint, now + this.d.cfg.entry.retryMin * 60_000);
+            out.push({ mint: e.mint, chain: "solana", seenAtMs: now, source: "event", reason: `${e.label || e.mint} in ${Math.round((e.atMs - now) / 60_000)} min`, meta: { label: e.label, eventAt: new Date(e.atMs).toISOString() } });
+        }
+        return out;
+    }
+    async decimalsOf(mint, ctx) {
+        const have = this.decimals.get(mint);
+        if (have !== undefined)
+            return have;
+        let d = 6;
+        try {
+            d = decodeMint((await ctx.rpc.call("getAccountInfo", [mint, { encoding: "base64", commitment: "confirmed" }]))?.value).decimals;
+            this.decimals.set(mint, d);
+        }
+        catch {
+            /* decimals only scale prices */
+        }
+        return d;
+    }
+    async decide(c, ctx) {
+        const e = this.d.cfg.events.find((x) => x.mint === c.mint);
+        if (!e)
+            return { verdict: "skip", reason: "not an event coin" };
+        const now = this.now();
+        const w = windowOf(this.d.cfg, e);
+        if (now < w.opens || now >= w.closes)
+            return { verdict: "skip", reason: "outside its buy window" };
+        const hedge = this.hedgeAtMs();
+        if (hedge !== null && now >= e.atMs + hedge)
+            return { verdict: "skip", reason: "past the event's hedge" };
+        const caps = ctx.caps(c.mint);
+        if (caps.paused)
+            return { verdict: "skip", reason: "PAUSE_BUYS" };
+        if (caps.entriesForMint >= ctx.cfg.buy.maxPerCoin)
+            return { verdict: "skip", reason: `maxPerCoin ${ctx.cfg.buy.maxPerCoin}` };
+        if (caps.open >= ctx.cfg.buy.maxOpen)
+            return { verdict: "skip", reason: `maxOpen ${ctx.cfg.buy.maxOpen}` };
+        const ticket = lamportsOf(ctx.cfg.buy.sol);
+        if (caps.lifetimeLamports + ticket > lamportsOf(ctx.cfg.buy.lifetimeSol))
+            return { verdict: "skip", reason: `lifetimeSol ${ctx.cfg.buy.lifetimeSol}` };
+        const decimals = await this.decimalsOf(c.mint, ctx);
+        let m = null;
+        try {
+            m = (await readMarkets(ctx.rpc, [{ mint: c.mint, decimals }], now, { pump: true })).get(c.mint) ?? null;
+        }
+        catch {
+            m = null;
+        }
+        if (!m)
+            return { verdict: "skip", reason: "venue not readable" };
+        const q = buyQuote(m, ticket);
+        if ("why" in q)
+            return { verdict: "skip", reason: `venue refused: ${q.why}` };
+        if (q.impactBps > this.d.cfg.entry.maxImpactBps)
+            return { verdict: "skip", reason: `impact ${q.impactBps} bps > ${this.d.cfg.entry.maxImpactBps}` };
+        return {
+            verdict: "buy",
+            reason: `${e.label || "event"} at ${new Date(e.atMs).toISOString()}; impact ${q.impactBps} bps on ${q.venue}`,
+            lamports: ticket,
+            deadlineAtMs: Math.min(now + this.d.cfg.entry.buyWithinSec * 1000, w.closes),
+            expectedOutRaw: q.expectedOutRaw,
+            decimals,
+            context: { label: e.label, eventAt: new Date(e.atMs).toISOString(), venue: q.venue, impactBps: q.impactBps },
+            log: { label: e.label, venue: q.venue, impactBps: q.impactBps, eventInMin: Math.round((e.atMs - now) / 60_000) },
+        };
+    }
+    onVerdict(c, v, _ctx, _p) {
+        if (v.verdict === "wait")
+            return;
+        const e = this.d.cfg.events.find((x) => x.mint === c.mint);
+        if (v.verdict === "skip")
+            this.d.log.info("event_skip", { mint: c.mint, label: e?.label, reason: v.reason });
+        this.last.push({ mint: c.mint, label: e?.label ?? "", at: this.now(), decision: v.verdict, reason: v.reason });
+        if (this.last.length > 20)
+            this.last.shift();
+    }
+    status() {
+        const now = this.now();
+        return {
+            events: this.d.cfg.events.map((e) => {
+                const w = windowOf(this.d.cfg, e);
+                return { mint: e.mint, label: e.label, at: new Date(e.atMs).toISOString(), window: now < w.opens ? "not open" : now >= w.closes ? "closed" : "open", inMin: Math.round((e.atMs - now) / 60_000) };
+            }),
+            recent: this.last,
+        };
+    }
+}

package/examples/dry.json

@@ -0,0 +1,48 @@
+{
+  "comment": "Dry run: decides and logs, never trades. No API key needed. Replace the event's mint with your coin and its time with the event's (ISO 8601 with its offset). Set your wallet (and a key for live) before going live.",
+  "mode": "dry",
+  "payer": "embedded",
+  "apiKeyEnv": "CANDLE_API_KEY",
+  "rpcUrlEnv": "SOLANA_RPC_URL",
+  "wallet": "11111111111111111111111111111111",
+  "stateDir": "./state-dry",
+  "buy": {
+    "sol": 0.01,
+    "maxSlippageBps": 500,
+    "maxOpen": 3,
+    "lifetimeSol": 0.1,
+    "maxPerCoin": 1
+  },
+  "sell": {
+    "maxSlippageBps": 1000
+  },
+  "events": [
+    {
+      "mint": "11111111111111111111111111111111",
+      "at": "2026-12-01T17:00:00Z",
+      "label": "replace me: the coin and its event"
+    }
+  ],
+  "entry": {
+    "fromHours": 72,
+    "untilMin": 60,
+    "maxImpactBps": 300,
+    "buyWithinSec": 60,
+    "retryMin": 10
+  },
+  "exit": {
+    "strategy": "event",
+    "rungs": [
+      {
+        "at": 3,
+        "sell": 0.2
+      }
+    ],
+    "hedgeAtMin": 0,
+    "hedgeKeep": 0.5,
+    "afterMin": 60,
+    "coreKeep": 0.2,
+    "coreTakeProfit": 20,
+    "coreMaxHoldHours": 168
+  }
+}

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "candle-event-bot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Buys coins tied to a dated event in a window before it, and exits them in phases keyed to the event: ride the build-up, hedge at the event, keep a moonshot core. A Solana bot built on @candledottv/agent-sdk.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BruceJeet/candle-bots.git",
+    "directory": "packages/event-bot"
+  },
+  "homepage": "https://github.com/BruceJeet/candle-bots/tree/main/packages/event-bot#readme",
+  "bugs": {
+    "url": "https://github.com/BruceJeet/candle-bots/issues"
+  },
+  "bin": {
+    "candle-event-bot": "bin/candle-event-bot"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p .",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "candle-bot-core": "0.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.6",
+    "typescript": "7.0.2"
+  },
+  "keywords": [
+    "candle",
+    "solana",
+    "trading-bot",
+    "event",
+    "launch",
+    "memecoin",
+    "bot",
+    "agent"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  }
+}