@solard/sdk 0.2.31 → 0.2.33

package/README.md

@@ -25,4 +25,37 @@ converted prices are null. `unresolved` means reconcile with `resumeTrade(intent
 before another trade. Buy accepts `minOutputRaw`; sell accepts `minOutputLamports`.
 Both use confirmed/failed/unresolved results with phase, code, attempts and accounting.
 `quote`, `curveLiquidity`, `maxSendableSol`, `transferToken` and `exitWallet` share the
-core implementation. Raydium AMM/CPMM execution does not supply live pool prices.
+core implementation. Raydium AMM/CPMM execution does not supply live pool prices.
+
+In 0.2.32, sell an exact positive integer number of raw token units with the
+object API. For a six-decimal mint, `"1000000"` is one token:
+
+```ts
+const sold = await slrd.sell(
+  { wallet: "trader-1", token: mint, amountRaw: "1000000", slippageBps: 500 },
+  { intentKey: "example:sell:1", priorityFee: { cuLimit: 200_000, microLamports: 20_000 } },
+);
+```
+
+`amountRaw` also accepts bigint and is mutually exclusive with `amount`.
+An economic sell guard rejects output at or below the selected network fee plus
+tip before broadcasting, with `UNECONOMIC_SELL`. Its `sellEconomics` fields describe
+the expected output and selected costs; they are not charges already paid.
+`networkFeeLamports` is the actual on-chain charge only when known. Selected
+priority cost reserves the chosen CU limit, so it differs from consumed CUs.
+
+The configured client inherits its database path and RPC endpoints for listeners.
+Live history is recorded by default; disable recording with `history: false`:
+
+```ts
+const slrd = createSolard({ dbPath: "./slrd.db", rpcUrl });
+const listener = await slrd.listenTrades({ tokens: [mint] });
+listener.onTrade((event) => console.log(event));
+// await slrd.listenTrades({ tokens: [mint], history: false });
+await listener.close(); // Wait for queued history writes to flush.
+```
+
+The collected live tail is partial history, not a complete backfill. Processed
+events can later disappear; `slrd.historicalTape(mint)` excludes them by default.
+Pass `{ includeProcessed: true }` to inspect that provisional tail and check the
+returned completeness information before using it for backtests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solard/sdk",
-  "version": "0.2.31",
+  "version": "0.2.33",
   "description": "Public Solard SDK for wallets, trading, history, live market subscriptions and token metadata.",
   "type": "module",
   "main": "./src/index.ts",
@@ -27,7 +27,7 @@
   "license": "MIT",
   "dependencies": {
     "@solana/web3.js": "^1.98.4",
-    "@solard/core": "0.2.31"
+    "@solard/core": "0.2.33"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.browser.json",

package/src/client.exact-sell.test.ts

@@ -0,0 +1,45 @@
+import { expect, spyOn, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Solard } from "../../core/src/core/solard.ts";
+import { tradeResult } from "../../core/src/tx/trade-result.ts";
+import { createSolard, type SolardSellInput } from "./client.ts";
+import { isDefinitivePreSubmissionError } from "@solard/core";
+
+test("SDK exact raw sell forwards an isolated position without inserting default bps", async () => {
+  const folder = mkdtempSync(join(tmpdir(), "solard-sdk-exact-"));
+  const calls: Array<Record<string, unknown>> = [];
+  const sell = spyOn(Solard.prototype, "sell").mockImplementation(async (_token, _wallet, options) => {
+    calls.push(options as unknown as Record<string, unknown>);
+    return tradeResult({ signature: "fixture", sender: "rpc", status: "confirmed", slot: 1 });
+  });
+  const sdk = createSolard({ dbPath: join(folder, "test.sqlite") });
+  try {
+    await sdk.sell({ token: "mint", wallet: "wallet", amountRaw: "284725", slippageBps: 500, minOutputLamports: 1n }, { priorityFee: { microLamports: 20_000 } });
+    await sdk.sell({ token: "mint", wallet: "wallet", amount: { raw: 284725n } });
+    await sdk.sell({ token: "mint", wallet: "wallet", amount: { bps: 1000 } });
+    await sdk.sell({ token: "mint", wallet: "wallet", amount: "all" });
+    expect(calls[0]).toMatchObject({ amountRaw: "284725", slippageBps: 500, minOutputLamports: 1n, priorityFee: { microLamports: 20_000 } });
+    expect(calls[0]?.bps).toBeUndefined();
+    expect(calls[1]?.amountRaw).toBe(284725n);
+    expect(calls[1]?.bps).toBeUndefined();
+    expect(calls[2]?.bps).toBe(1000);
+    expect(calls[3]?.bps).toBe(10000);
+  } finally { sdk.close(); sell.mockRestore(); rmSync(folder, { recursive: true, force: true }); }
+});
+
+test("SDK rejects ambiguous and invalid raw quantities before invoking core sell", async () => {
+  const folder = mkdtempSync(join(tmpdir(), "solard-sdk-exact-invalid-"));
+  const sell = spyOn(Solard.prototype, "sell").mockImplementation(async () => { throw new Error("must not call core"); });
+  const sdk = createSolard({ dbPath: join(folder, "test.sqlite") });
+  try {
+    for (const size of [{ amountRaw: "284725", amount: { bps: 1000 } }, { amountRaw: 0n }, { amountRaw: "1.5" },
+      { amount: { raw: "-1" } }, { amount: { bps: 1.5 } }, { amount: { raw: "284725", bps: 1000 } }]) {
+      await expect(sdk.sell({ token: "mint", wallet: "wallet", ...size } as SolardSellInput)).rejects.toThrow();
+    }
+    expect(sell).not.toHaveBeenCalled();
+    try { await sdk.sell({ token: "mint", wallet: "wallet", amountRaw: 0n }); }
+    catch (error) { expect(isDefinitivePreSubmissionError(error)).toBe(true); }
+  } finally { sdk.close(); sell.mockRestore(); rmSync(folder, { recursive: true, force: true }); }
+});

package/src/client.listen-trades.test.ts

@@ -0,0 +1,34 @@
+import { expect, spyOn, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import * as live from "./live.ts";
+import { createSolard } from "./client.ts";
+
+test("client listener inherits its configured database and endpoint pool", async () => {
+  const folder = mkdtempSync(join(tmpdir(), "solard-sdk-listener-"));
+  const dbPath = join(folder, "test.sqlite");
+  const seen: Array<live.ListenTradesOptions> = [];
+  const fixture = {} as live.TradeListener;
+  const listen = spyOn(live, "listenTrades").mockImplementation(async (options) => { seen.push(options); return fixture; });
+  const sdk = createSolard({ dbPath, rpcUrls: ["https://first.example.com", "https://second.example.com"] });
+  try {
+    expect(await sdk.listenTrades({ tokens: ["mint"] })).toBe(fixture);
+    expect(seen[0]).toMatchObject({ dbPath, rpcUrls: ["https://first.example.com", "https://second.example.com"], tokens: ["mint"] });
+    await sdk.listenTrades();
+    expect(seen[1]?.tokens).toEqual([]);
+  } finally { sdk.close(); listen.mockRestore(); rmSync(folder, { recursive: true, force: true }); }
+});
+
+test("single RPC configuration is forwarded and absent URLs preserve live environment fallback", async () => {
+  const folder = mkdtempSync(join(tmpdir(), "solard-sdk-listener-url-"));
+  const seen: Array<live.ListenTradesOptions> = [];
+  const listen = spyOn(live, "listenTrades").mockImplementation(async (options) => { seen.push(options); return {} as live.TradeListener; });
+  const first = createSolard({ dbPath: join(folder, "first.sqlite"), rpcUrl: "https://configured.example.com" });
+  const second = createSolard({ dbPath: join(folder, "second.sqlite") });
+  try {
+    await first.listenTrades(); await second.listenTrades();
+    expect(seen[0]?.rpcUrls).toEqual(["https://configured.example.com"]);
+    expect(seen[1]?.rpcUrls).toBeUndefined();
+  } finally { first.close(); second.close(); listen.mockRestore(); rmSync(folder, { recursive: true, force: true }); }
+});

package/src/client.ts

@@ -20,8 +20,8 @@ import {
   type SendReceipt,
   type TradeLandingPolicy,
   type TradeResult,
-  type TradeExecutionOptions,
-  type LivePoolReserves,
+  type TradeExecutionOptions,
+  type LivePoolReserves,
   type SenderId,
   type SolardDecodedTransaction,
   type SolardTransactionOptions,
@@ -34,12 +34,14 @@ import {
   type TokenRef,
   type WalletRef,
   type WalletPrivateKeyExport,
-  type WalletPrivateKeyFormat,
-} from "@solard/core";
+  type WalletPrivateKeyFormat,
+  TradePreSubmissionError,
+} from "@solard/core";
+import { listenTrades as openTradeListener, type ListenTradesOptions, type TradeListener } from "./live.ts";
 
 export type SolardOptions = {
-  rpcUrl?: string;
-  rpcUrls?: readonly string[];
+  rpcUrl?: string;
+  rpcUrls?: readonly string[];
   dbPath?: string;
   cacheTtlMs?: number;
 };
@@ -63,9 +65,9 @@ export type SolardEventsApi = {
   merge(streams: readonly ReplayEventSubscription[]): MergedReplayEventStream;
 };
 
-export type SolardBuyInput = {
-  reserves?: LivePoolReserves;
-  maxPriceSol?: string | number;
+export type SolardBuyInput = {
+  reserves?: LivePoolReserves;
+  maxPriceSol?: string | number;
   wallet: WalletRef;
   token: TokenRef;
   amount: HumanAmount | string | number;
@@ -73,13 +75,15 @@ export type SolardBuyInput = {
   minOutputRaw?: bigint | string;
 };
 
-export type SolardSellInput = {
-  closeTokenAccount?: boolean;
-  reserves?: LivePoolReserves;
-  minPriceSol?: string | number;
+export type SolardSellInput = {
+  closeTokenAccount?: boolean;
+  reserves?: LivePoolReserves;
+  minPriceSol?: string | number;
   wallet: WalletRef;
   token: TokenRef;
-  amount?: "all" | { bps: number };
+  amount?: "all" | { bps: number } | { raw: bigint | string };
+  /** Exact raw token units; mutually exclusive with amount. */
+  amountRaw?: bigint | string;
   slippageBps?: number;
   minOutputLamports?: bigint | string;
 };
@@ -88,18 +92,20 @@ export type SolardTradeExecutionOptions = TradeExecutionOptions;
 
 export type SolardTradeExecutionResult = TradeResult;
 export type Solard = {
-  resolveCurrentMarket: ReturnType<typeof createCoreSolard>["resolveCurrentMarket"];
-  getClaimableCreatorFees: ReturnType<typeof createCoreSolard>["getClaimableCreatorFees"];
-  claimAllCreatorFees: ReturnType<typeof createCoreSolard>["claimAllCreatorFees"];
-  walletLedger: ReturnType<typeof createCoreSolard>["walletLedger"];
-  historicalTape: ReturnType<typeof createCoreSolard>["historicalTape"];
+  listenTrades(options?: Omit<ListenTradesOptions, "tokens"> & { tokens?: readonly string[] }): Promise<TradeListener>;
+  resolveCurrentMarket: ReturnType<typeof createCoreSolard>["resolveCurrentMarket"];
+  getClaimableCreatorFees: ReturnType<typeof createCoreSolard>["getClaimableCreatorFees"];
+  claimAllCreatorFees: ReturnType<typeof createCoreSolard>["claimAllCreatorFees"];
+  walletLedger: ReturnType<typeof createCoreSolard>["walletLedger"];
+  historicalTape: ReturnType<typeof createCoreSolard>["historicalTape"];
   getSupportedPumpPairs: ReturnType<typeof createCoreSolard>["getSupportedPumpPairs"];
-  listVanityMints: ReturnType<typeof createCoreSolard>["listVanityMints"];
-  releaseVanityMint: ReturnType<typeof createCoreSolard>["releaseVanityMint"];
-  closeEmptyTokenAccounts: ReturnType<typeof createCoreSolard>["closeEmptyTokenAccounts"];
-  prepareTokenDeployment: ReturnType<typeof createCoreSolard>["prepareTokenDeployment"];
-  deployToken: ReturnType<typeof createCoreSolard>["deployToken"];
-  warmBlockhash: ReturnType<typeof createCoreSolard>["warmBlockhash"];
+  getSupportedLaunchLabPairs: ReturnType<typeof createCoreSolard>["getSupportedLaunchLabPairs"];
+  listVanityMints: ReturnType<typeof createCoreSolard>["listVanityMints"];
+  releaseVanityMint: ReturnType<typeof createCoreSolard>["releaseVanityMint"];
+  closeEmptyTokenAccounts: ReturnType<typeof createCoreSolard>["closeEmptyTokenAccounts"];
+  prepareTokenDeployment: ReturnType<typeof createCoreSolard>["prepareTokenDeployment"];
+  deployToken: ReturnType<typeof createCoreSolard>["deployToken"];
+  warmBlockhash: ReturnType<typeof createCoreSolard>["warmBlockhash"];
   curveLiquidity: ReturnType<typeof createCoreSolard>["curveLiquidity"];
   maxSendableSol: ReturnType<typeof createCoreSolard>["maxSendableSol"];
   transferToken: ReturnType<typeof createCoreSolard>["transferToken"];
@@ -174,12 +180,22 @@ function tradeAmount(value: HumanAmount | string | number): HumanAmount {
     : value;
 }
 
-function sellBps(value: SolardSellInput["amount"]): number {
-  if (value == null || value === "all") return 10_000;
-  const bps = Math.trunc(value.bps);
-  if (!(bps > 0 && bps <= 10_000))
-    throw new Error("sell amount.bps must be between 1 and 10000");
-  return bps;
+function sellSize(input: SolardSellInput): { bps?: number; amountRaw?: bigint | string } {
+  const value = input.amount;
+  if (input.amountRaw !== undefined && value !== undefined) throw new Error("sell amountRaw and amount are mutually exclusive");
+  const raw = input.amountRaw !== undefined ? input.amountRaw : typeof value === "object" && value !== null && "raw" in value ? value.raw : undefined;
+  if (raw !== undefined) {
+    if (typeof value === "object" && value !== null && "bps" in value) throw new Error("sell raw and bps are mutually exclusive");
+    if ((typeof raw !== "bigint" && (typeof raw !== "string" || !/^\d+$/.test(raw))) || BigInt(raw) <= 0n)
+      throw new Error("sell amountRaw must be a positive raw integer");
+    return { amountRaw: raw };
+  }
+  if (value == null || value === "all") return { bps: 10_000 };
+  if (!("bps" in value)) throw new Error("sell amount must specify bps or raw");
+  const bps = value.bps;
+  if (!Number.isInteger(bps) || !(bps > 0 && bps <= 10_000))
+    throw new Error("sell amount.bps must be between 1 and 10000");
+  return { bps };
 }
 
 
@@ -191,10 +207,12 @@ async function executeTrade(
 ): Promise<SolardTradeExecutionResult> {
   if (side === "buy") {
     const buy = input as SolardBuyInput;
-    return await core.buy(buy.token, buy.wallet, tradeAmount(buy.amount), { ...options, slippageBps: buy.slippageBps, minOutputRaw: buy.minOutputRaw, maxPriceSol: buy.maxPriceSol, reserves: buy.reserves });
+    return await core.buy(buy.token, buy.wallet, tradeAmount(buy.amount), { ...options, slippageBps: buy.slippageBps, minOutputRaw: buy.minOutputRaw, maxPriceSol: buy.maxPriceSol, reserves: buy.reserves });
   }
-  const sell = input as SolardSellInput;
-  return await core.sell(sell.token, sell.wallet, { ...options, bps: sellBps(sell.amount), slippageBps: sell.slippageBps, minOutputLamports: sell.minOutputLamports, minPriceSol: sell.minPriceSol, reserves: sell.reserves, closeTokenAccount: sell.closeTokenAccount });
+  const sell = input as SolardSellInput;
+  let size: ReturnType<typeof sellSize>;
+  try { size = sellSize(sell); } catch (error) { throw new TradePreSubmissionError(error); }
+  return await core.sell(sell.token, sell.wallet, { ...options, ...size, slippageBps: sell.slippageBps, minOutputLamports: sell.minOutputLamports, minPriceSol: sell.minPriceSol, reserves: sell.reserves, closeTokenAccount: sell.closeTokenAccount });
 
 }
 
@@ -211,18 +229,25 @@ export function createSolard(options: SolardOptions = {}): Solard {
     { merge: core.events.merge },
   ) as SolardEventsApi;
   return Object.freeze({
-    resolveCurrentMarket: core.resolveCurrentMarket.bind(core),
-    getClaimableCreatorFees: core.getClaimableCreatorFees.bind(core),
-    claimAllCreatorFees: core.claimAllCreatorFees.bind(core),
-    walletLedger: core.walletLedger.bind(core),
-    historicalTape: core.historicalTape.bind(core),
+    listenTrades: (listenerOptions: Omit<ListenTradesOptions, "tokens"> & { tokens?: readonly string[] } = {}) => openTradeListener({
+      rpcUrls: options.rpcUrls ?? (options.rpcUrl ? [options.rpcUrl] : undefined),
+      dbPath: options.dbPath,
+      ...listenerOptions,
+      tokens: listenerOptions.tokens ?? [],
+    }),
+    resolveCurrentMarket: core.resolveCurrentMarket.bind(core),
+    getClaimableCreatorFees: core.getClaimableCreatorFees.bind(core),
+    claimAllCreatorFees: core.claimAllCreatorFees.bind(core),
+    walletLedger: core.walletLedger.bind(core),
+    historicalTape: core.historicalTape.bind(core),
     getSupportedPumpPairs: core.getSupportedPumpPairs.bind(core),
-    listVanityMints: core.listVanityMints.bind(core),
-    releaseVanityMint: core.releaseVanityMint.bind(core),
-    closeEmptyTokenAccounts: core.closeEmptyTokenAccounts.bind(core),
-    prepareTokenDeployment: core.prepareTokenDeployment.bind(core),
-    deployToken: core.deployToken.bind(core),
-    warmBlockhash: core.warmBlockhash.bind(core),
+    getSupportedLaunchLabPairs: core.getSupportedLaunchLabPairs.bind(core),
+    listVanityMints: core.listVanityMints.bind(core),
+    releaseVanityMint: core.releaseVanityMint.bind(core),
+    closeEmptyTokenAccounts: core.closeEmptyTokenAccounts.bind(core),
+    prepareTokenDeployment: core.prepareTokenDeployment.bind(core),
+    deployToken: core.deployToken.bind(core),
+    warmBlockhash: core.warmBlockhash.bind(core),
     curveLiquidity: core.curveLiquidity.bind(core),
     maxSendableSol: core.maxSendableSol.bind(core),
     transferToken: core.transferToken.bind(core),

package/src/default.ts

@@ -1,14 +1,12 @@
 import { getSolUsdPrice } from "@solard/core";
 import {
-  listenTrades,
-  subscribeLaunches,
+  subscribeLaunches,
   subscribeMigrations,
 } from "./live.ts";
 import { createSolard, type Solard } from "./client.ts";
 
 type DefaultSolard = Solard & {
   getSolUsdPrice: typeof getSolUsdPrice;
-  listenTrades: typeof listenTrades;
   subscribeLaunches: typeof subscribeLaunches;
   subscribeMigrations: typeof subscribeMigrations;
 };
@@ -22,8 +20,7 @@ function client(): Solard {
 
 const operations = {
   getSolUsdPrice,
-  listenTrades,
-  subscribeLaunches,
+  subscribeLaunches,
   subscribeMigrations,
 } as const;
 

package/src/export-surface.test.ts

@@ -29,11 +29,11 @@ function exportedNames(value: string) {
 describe("sdk membrane", () => {
   test("has an exact curated root export surface", () => {
     expect(exportedNames(source)).toEqual({
-      values: [
-        "normalizeValueBandPolicy", "planValueBandDecision", "valueBandThresholds",
-        "normalizeTargetWeightPolicy", "planTargetWeightRebalance",
-        "buildHistoricalCandles", "runHistoricalStrategy", "sweepHistoricalStrategies",
-        "LAUNCHLAB_PLATFORM_PRESETS", "resolveLaunchLabPlatform",
+      values: [
+        "normalizeValueBandPolicy", "planValueBandDecision", "valueBandThresholds",
+        "normalizeTargetWeightPolicy", "planTargetWeightRebalance",
+        "buildHistoricalCandles", "runHistoricalStrategy", "sweepHistoricalStrategies",
+        "LAUNCHLAB_PLATFORM_PRESETS", "resolveLaunchLabPlatform",
         "createSolard",
         "default",
         "fetchTokenMetadata",
@@ -48,17 +48,19 @@ describe("sdk membrane", () => {
         "tokenAmount",
       ].sort(),
       types: [
-        "TradeListenerMigration",
-        "ValueBandPolicy", "ValueBandRuntimeState", "ValueBandDecision",
-        "TargetWeightPolicy", "TargetWeightRebalancePlan",
-        "HistoricalTradeTape", "HistoricalCandle", "HistoricalStrategy",
-        "HistoricalExecutionOptions", "HistoricalStrategyResult",
-        "CreatorFeeDiscovery", "CreatorFeeGroup", "CreatorFeeItem",
-        "WalletLedger", "WalletLedgerEntry", "WalletLedgerOptions", "CurrentMarket",
-        "PreparedTokenDeployment", "PrepareDeploymentArgs",
-        "TradeLandingPolicy",
-        "LiveEndpointOptions",
-        "LivePoolReserves",
+        "SellEconomics",
+        "SupportedLaunchLabPair",
+        "TradeListenerMigration",
+        "ValueBandPolicy", "ValueBandRuntimeState", "ValueBandDecision",
+        "TargetWeightPolicy", "TargetWeightRebalancePlan",
+        "HistoricalTradeTape", "HistoricalCandle", "HistoricalStrategy",
+        "HistoricalExecutionOptions", "HistoricalStrategyResult",
+        "CreatorFeeDiscovery", "CreatorFeeGroup", "CreatorFeeItem",
+        "WalletLedger", "WalletLedgerEntry", "WalletLedgerOptions", "CurrentMarket",
+        "PreparedTokenDeployment", "PrepareDeploymentArgs",
+        "TradeLandingPolicy",
+        "LiveEndpointOptions",
+        "LivePoolReserves",
         "ClaimCreatorRewardsOptions",
         "CreatorRewardClaimPayout",
         "CreatorRewardClaimResult",
@@ -175,7 +177,7 @@ describe("sdk membrane", () => {
     expect(defaultClient).toContain("instance ??= createSolard()");
     expect(defaultClient).toContain('if (key === "close")');
     expect(defaultClient).toContain("getSolUsdPrice");
-    expect(defaultClient).toContain("listenTrades");
+    expect(client).toContain("listenTrades:");
     expect(defaultClient).toContain("subscribeLaunches");
     expect(defaultClient).toContain("subscribeMigrations");
     expect(defaultClient).not.toContain("export default createSolard()");
@@ -200,7 +202,7 @@ describe("sdk membrane", () => {
 
   test("does not expose core repositories or secret-bearing handles", () => {
     expect(client).not.toMatch(
-      /\b(?:db|wallets|tokens|groups|executions|positions|prices|alts|senders|venues|claimSources|launches|launchpads|connection|signer)\s*:/,
+      /^(?: {2}| {4})(?:db|wallets|tokens|groups|executions|positions|prices|alts|senders|venues|claimSources|launches|launchpads|connection|signer)\s*:/m,
     );
   });
 });

package/src/index.ts

@@ -1,38 +1,40 @@
 export { default } from "./default.ts";
-export { createSolard } from "./client.ts";
-export {
-  normalizeValueBandPolicy,
-  planValueBandDecision,
-  valueBandThresholds,
-  normalizeTargetWeightPolicy,
-  planTargetWeightRebalance,
-  buildHistoricalCandles,
-  runHistoricalStrategy,
-  sweepHistoricalStrategies,
-  LAUNCHLAB_PLATFORM_PRESETS,
-  resolveLaunchLabPlatform,
-} from "@solard/core";
+export { createSolard } from "./client.ts";
+export {
+  normalizeValueBandPolicy,
+  planValueBandDecision,
+  valueBandThresholds,
+  normalizeTargetWeightPolicy,
+  planTargetWeightRebalance,
+  buildHistoricalCandles,
+  runHistoricalStrategy,
+  sweepHistoricalStrategies,
+  LAUNCHLAB_PLATFORM_PRESETS,
+  resolveLaunchLabPlatform,
+} from "@solard/core";
 export type {
-  ValueBandPolicy,
-  ValueBandRuntimeState,
-  ValueBandDecision,
-  TargetWeightPolicy,
-  TargetWeightRebalancePlan,
-  HistoricalTradeTape,
-  HistoricalCandle,
-  HistoricalStrategy,
-  HistoricalExecutionOptions,
-  HistoricalStrategyResult,
-  CreatorFeeDiscovery,
-  CreatorFeeGroup,
-  CreatorFeeItem,
-  WalletLedger,
-  WalletLedgerEntry,
-  WalletLedgerOptions,
-  CurrentMarket,
-  PreparedTokenDeployment,
-  PrepareDeploymentArgs,
-} from "@solard/core";
+  SellEconomics,
+  SupportedLaunchLabPair,
+  ValueBandPolicy,
+  ValueBandRuntimeState,
+  ValueBandDecision,
+  TargetWeightPolicy,
+  TargetWeightRebalancePlan,
+  HistoricalTradeTape,
+  HistoricalCandle,
+  HistoricalStrategy,
+  HistoricalExecutionOptions,
+  HistoricalStrategyResult,
+  CreatorFeeDiscovery,
+  CreatorFeeGroup,
+  CreatorFeeItem,
+  WalletLedger,
+  WalletLedgerEntry,
+  WalletLedgerOptions,
+  CurrentMarket,
+  PreparedTokenDeployment,
+  PrepareDeploymentArgs,
+} from "@solard/core";
 export type {
   Solard,
   SolardBuyInput,
@@ -53,8 +55,8 @@ export {
 
 export type {
   ClaimCreatorRewardsOptions,
-  TradeLandingPolicy,
-  LivePoolReserves,
+  TradeLandingPolicy,
+  LivePoolReserves,
   CreatorRewardClaimPayout,
   CreatorRewardClaimResult,
   CumulativeDistributionExecuteOptions,
@@ -117,13 +119,13 @@ export {
   subscribeLaunches,
   subscribeMigrations,
 } from "./live.ts";
-export type {
-  ListenTradesOptions,
-  LiveEndpointOptions,
+export type {
+  ListenTradesOptions,
+  LiveEndpointOptions,
   SubscribeLaunchesOptions,
   SubscribeMigrationsOptions,
-  TradeListener,
-  TradeListenerMigration,
+  TradeListener,
+  TradeListenerMigration,
 } from "./live.ts";
 export type {
   LaunchEvent,

package/src/live.test.ts

@@ -1,6 +1,11 @@
-import { describe, expect, spyOn, test } from "bun:test";
+import { describe, expect, spyOn, test } from "bun:test";
 import { Connection } from "@solana/web3.js";
-import { deriveWebSocketEndpoint, LiveEndpointPool, redactRpcEndpoint, subscribeTrades } from "./live.ts";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { openDatabase, closeDatabase } from "../../core/src/db/database.ts";
+import { SqliteTokenHistoryRepository } from "../../core/src/chain/token-history/repository.ts";
+import { deriveWebSocketEndpoint, LiveEndpointPool, redactRpcEndpoint, subscribeTrades } from "./live.ts";
 
 describe("sdk live endpoint", () => {
   test("derives websocket from the one RPC endpoint", () => {
@@ -18,96 +23,105 @@ describe("sdk live endpoint", () => {
       ),
     ).toBe("https://mainnet.helius-rpc.com/?api-key=<redacted>&foo=bar");
   });
-});
-test("live endpoint selection requires readiness, sticks, and rotates after later failures", async () => {
-  const calls: string[] = [];
-  const unavailable = new Set(["https://first.example/"]);
-  const pool = new LiveEndpointPool(["https://first.example/", "https://second.example/", "https://public.example/"], async (endpoint) => {
-    calls.push(endpoint);
-    if (unavailable.has(endpoint)) throw new Error("probe failed");
-  });
-  expect(await pool.select()).toBe("https://second.example/");
-  calls.length = 0;
-  expect(await pool.select()).toBe("https://second.example/");
-  expect(calls).toEqual(["https://second.example/"]);
-  unavailable.add("https://second.example/");
-  expect(await pool.check()).toBe("https://public.example/");
-  unavailable.add("https://public.example/");
-  await expect(pool.check()).rejects.toThrow("probe failed");
-});
-
-test("pooled trade stream preserves dynamic watched tokens when it rotates and closes", async () => {
-  const originalSocket = globalThis.WebSocket;
-  let firstHealthy = true;
-  let nextId = 0;
-  const registrations: Array<{ endpoint: string; token: string }> = [];
-  const first = "https://live-primary.example/";
-  const second = "https://live-fallback.example/";
-  const mint = "So11111111111111111111111111111111111111112";
-  globalThis.WebSocket = class extends EventTarget {
-    constructor() { super(); queueMicrotask(() => this.dispatchEvent(new Event("open"))); }
-    close() {}
-  } as any;
-  const fetchMock = spyOn(globalThis, "fetch").mockImplementation(async (input) => {
-    if (String(input) === first && !firstHealthy) return new Response("", { status: 401 });
-    return new Response(JSON.stringify({ result: "ok" }));
-  });
-  const logsMock = spyOn(Connection.prototype, "onLogs").mockImplementation(function (token) {
-    registrations.push({ endpoint: this.rpcEndpoint, token: String(token) });
-    return ++nextId;
-  });
-  const removeMock = spyOn(Connection.prototype, "removeOnLogsListener").mockResolvedValue(undefined);
-  let subscription: Awaited<ReturnType<typeof subscribeTrades>> | undefined;
-  try {
-    subscription = await subscribeTrades({ tokens: [], rpcUrls: [first, second], healthCheckIntervalMs: 1000, onTrade() {} });
-    await subscription.addTokens(mint);
-    firstHealthy = false;
-    const deadline = Date.now() + 3000;
-    while (!registrations.some((row) => row.endpoint === second) && Date.now() < deadline) await Bun.sleep(25);
-    expect(registrations).toEqual([{ endpoint: first, token: mint }, { endpoint: second, token: mint }]);
-    expect(subscription.listTokens()).toEqual([mint]);
-    expect(subscription.hasToken(mint)).toBe(true);
-    await subscription.close();
-    await subscription.closed;
-    expect(subscription.listTokens()).toEqual([]);
-    expect(removeMock).toHaveBeenCalledTimes(2);
-  } finally {
-    await subscription?.close();
-    logsMock.mockRestore(); removeMock.mockRestore(); fetchMock.mockRestore(); globalThis.WebSocket = originalSocket;
-  }
-});
-
+});
+test("live endpoint selection requires readiness, sticks, and rotates after later failures", async () => {
+  const calls: string[] = [];
+  const unavailable = new Set(["https://first.example/"]);
+  const pool = new LiveEndpointPool(["https://first.example/", "https://second.example/", "https://public.example/"], async (endpoint) => {
+    calls.push(endpoint);
+    if (unavailable.has(endpoint)) throw new Error("probe failed");
+  });
+  expect(await pool.select()).toBe("https://second.example/");
+  calls.length = 0;
+  expect(await pool.select()).toBe("https://second.example/");
+  expect(calls).toEqual(["https://second.example/"]);
+  unavailable.add("https://second.example/");
+  expect(await pool.check()).toBe("https://public.example/");
+  unavailable.add("https://public.example/");
+  await expect(pool.check()).rejects.toThrow("probe failed");
+});
+
+test("pooled trade stream preserves dynamic watched tokens when it rotates and closes", async () => {
+  const originalSocket = globalThis.WebSocket;
+  let firstHealthy = true;
+  let nextId = 0;
+  const registrations: Array<{ endpoint: string; token: string }> = [];
+  const first = "https://live-primary.example/";
+  const second = "https://live-fallback.example/";
+  const mint = "So11111111111111111111111111111111111111112";
+  globalThis.WebSocket = class extends EventTarget {
+    constructor() { super(); queueMicrotask(() => this.dispatchEvent(new Event("open"))); }
+    close() {}
+  } as any;
+  const fetchMock = spyOn(globalThis, "fetch").mockImplementation(async (input) => {
+    if (String(input) === first && !firstHealthy) return new Response("", { status: 401 });
+    return new Response(JSON.stringify({ result: "ok" }));
+  });
+  const logsMock = spyOn(Connection.prototype, "onLogs").mockImplementation(function (token) {
+    registrations.push({ endpoint: this.rpcEndpoint, token: String(token) });
+    return ++nextId;
+  });
+  const removeMock = spyOn(Connection.prototype, "removeOnLogsListener").mockResolvedValue(undefined);
+  let subscription: Awaited<ReturnType<typeof subscribeTrades>> | undefined;
+  try {
+    subscription = await subscribeTrades({ tokens: [], rpcUrls: [first, second], healthCheckIntervalMs: 1000, onTrade() {} });
+    await subscription.addTokens(mint);
+    firstHealthy = false;
+    const deadline = Date.now() + 3000;
+    while (!registrations.some((row) => row.endpoint === second) && Date.now() < deadline) await Bun.sleep(25);
+    expect(registrations).toEqual([{ endpoint: first, token: mint }, { endpoint: second, token: mint }]);
+    expect(subscription.listTokens()).toEqual([mint]);
+    expect(subscription.hasToken(mint)).toBe(true);
+    await subscription.close();
+    await subscription.closed;
+    expect(subscription.listTokens()).toEqual([]);
+    expect(removeMock).toHaveBeenCalledTimes(2);
+  } finally {
+    await subscription?.close();
+    logsMock.mockRestore(); removeMock.mockRestore(); fetchMock.mockRestore(); globalThis.WebSocket = originalSocket;
+  }
+});
+
 test("listenTrades refreshes migrated identities without changing the watched token list", async () => {
-  const core = await import("@solard/core");
-  const { listenTrades } = await import("./live.ts");
-  const mint = "So11111111111111111111111111111111111111112";
+  const core = await import("@solard/core");
+  const { listenTrades } = await import("./live.ts");
+  const mint = "So11111111111111111111111111111111111111112";
   const endpoint = "https://migration-listener.example/";
-  const originalSocket = globalThis.WebSocket;
-  globalThis.WebSocket = class extends EventTarget { constructor() { super(); queueMicrotask(() => this.dispatchEvent(new Event("open"))); } close() {} } as any;
-  const fetchMock = spyOn(globalThis, "fetch").mockImplementation(async () => new Response(JSON.stringify({ result: "ok" })));
-  let onMigration: any; let onTrade: any;
-  const tokens = new Set<string>(); const changes: string[] = [];
-  let closeTrade!: () => void;
-  const tradeClosed = new Promise<void>(resolve => { closeTrade = resolve; });
-  const tradeMock = spyOn(core, "subscribeTrades").mockImplementation(async (options: any) => {
-    options.tokens.forEach((t: string) => tokens.add(t)); onTrade = options.onTrade;
-    return { addTokens: async (value: any) => { changes.push("add"); (typeof value === "string" ? [value] : value).forEach((t: string) => tokens.add(t)); },
-      removeTokens: async (value: any) => { changes.push("remove"); (typeof value === "string" ? [value] : value).forEach((t: string) => tokens.delete(t)); },
-      hasToken: (t: string) => tokens.has(t), listTokens: () => [...tokens], close: async () => closeTrade(), closed: tradeClosed };
-  });
-  const migrationMock = spyOn(core, "subscribeMigrations").mockImplementation(async (options: any) => {
-    onMigration = options.onMigration;
-    return { mode: "selected", addTokens: async () => {}, removeTokens: async () => {}, hasToken: () => true, listTokens: () => options.tokens, close: async () => {}, closed: Promise.resolve() } as any;
-  });
-  let listener: Awaited<ReturnType<typeof listenTrades>> | undefined;
-  try {
-    listener = await listenTrades({ tokens: [mint], rpcUrls: [endpoint] });
-    const received: any[] = []; listener.onMigration(event => { received.push(event); });
-    await onTrade({ signature: "trade", mint, pool: "old-pool" });
-    await onMigration({ type: "migration", mint, pool: "new-pool", signature: "migration", slot: 12, venue: "pump", destination: "pumpswap", quoteMint: mint, atMs: Date.now(), isMayhemMode: false, metadata: null });
-    expect(changes).toEqual(["remove", "add"]);
-    expect(listener.list()).toEqual([mint]);
-    expect(received[0]).toMatchObject({ oldPool: "old-pool", newPool: "new-pool", slot: 12 });
+  const dir = mkdtempSync(join(tmpdir(), "slrd-sdk-listener-"));
+  const dbPath = join(dir, "history.sqlite");
+  const originalSocket = globalThis.WebSocket;
+  globalThis.WebSocket = class extends EventTarget { constructor() { super(); queueMicrotask(() => this.dispatchEvent(new Event("open"))); } close() {} } as any;
+  const fetchMock = spyOn(globalThis, "fetch").mockImplementation(async () => new Response(JSON.stringify({ result: "ok" })));
+  let onMigration: any; let onTrade: any;
+  const tokens = new Set<string>(); const changes: string[] = [];
+  let closeTrade!: () => void;
+  const tradeClosed = new Promise<void>(resolve => { closeTrade = resolve; });
+  const tradeMock = spyOn(core, "subscribeTrades").mockImplementation(async (options: any) => {
+    options.tokens.forEach((t: string) => tokens.add(t)); onTrade = options.onTrade;
+    return { addTokens: async (value: any) => { changes.push("add"); (typeof value === "string" ? [value] : value).forEach((t: string) => tokens.add(t)); },
+      removeTokens: async (value: any) => { changes.push("remove"); (typeof value === "string" ? [value] : value).forEach((t: string) => tokens.delete(t)); },
+      hasToken: (t: string) => tokens.has(t), listTokens: () => [...tokens], close: async () => closeTrade(), closed: tradeClosed };
+  });
+  const migrationMock = spyOn(core, "subscribeMigrations").mockImplementation(async (options: any) => {
+    onMigration = options.onMigration;
+    return { mode: "selected", addTokens: async () => {}, removeTokens: async () => {}, hasToken: () => true, listTokens: () => options.tokens, close: async () => {}, closed: Promise.resolve() } as any;
+  });
+  let listener: Awaited<ReturnType<typeof listenTrades>> | undefined;
+  try {
+    listener = await listenTrades({ tokens: [mint], rpcUrls: [endpoint], dbPath });
+    const received: any[] = []; listener.onMigration(event => { received.push(event); });
+    const event = { signature: "trade", mint, pool: "old-pool", venue: "pumpswap", side: "buy", eventIndex: 0, slot: 11, atMs: Date.now(), baseRaw: 1000000n, quoteRaw: 10000000n,
+      market: { quoteMint: mint, baseDecimals: 6, quoteDecimals: 9, supplyRaw: 1000000000000000n, baseReserveRaw: 100000000n, quoteReserveRaw: 1000000000n,
+        priceQuotePerToken: .01, priceSol: .01, priceUsd: 1, marketCapSol: 10000000, marketCapUsd: 1000000000 } };
+    await onTrade(event); await onTrade(event);
+    await onMigration({ type: "migration", mint, pool: "new-pool", signature: "migration", slot: 12, venue: "pump", destination: "pumpswap", quoteMint: mint, atMs: Date.now(), isMayhemMode: false, metadata: null });
+    expect(changes).toEqual(["remove", "add"]);
+    expect(listener.list()).toEqual([mint]);
+    expect(received[0]).toMatchObject({ oldPool: "old-pool", newPool: "new-pool", slot: 12 });
     await listener.close(); await listener.closed;
-  } finally { await listener?.close(); tradeMock.mockRestore(); migrationMock.mockRestore(); fetchMock.mockRestore(); globalThis.WebSocket = originalSocket; }
+    const repository = new SqliteTokenHistoryRepository(openDatabase(dbPath));
+    expect(repository.loadTrades(mint)).toHaveLength(1);
+    expect(repository.loadCandles1s(mint)).toHaveLength(1);
+    closeDatabase(dbPath);
+  } finally { await listener?.close(); closeDatabase(dbPath); tradeMock.mockRestore(); migrationMock.mockRestore(); fetchMock.mockRestore(); globalThis.WebSocket = originalSocket; rmSync(dir, { recursive: true, force: true }); }
 });

package/src/live.ts

@@ -4,42 +4,48 @@ import {
   subscribeMigrations as subscribeCoreMigrations,
   subscribeTrades as subscribeCoreTrades,
   type TradeEvent,
-  type TradeSubscription,
+  type TradeSubscription,
   type MigrationEvent,
+  createLiveTradeHistoryRecorder,
+  type LiveTradeHistoryOptions,
 } from "@solard/core";
 
-export type LiveEndpointOptions = {
-  /** Ordered endpoints on the same cluster; public RPC can be supplied last. */
-  rpcUrls?: readonly string[];
-  /** Fresh HTTP and WebSocket readiness probes for pooled trade streams (default 30s). */
-  healthCheckIntervalMs?: number;
-};
-export type SubscribeLaunchesOptions = Omit<
+export type LiveEndpointOptions = {
+  /** Ordered endpoints on the same cluster; public RPC can be supplied last. */
+  rpcUrls?: readonly string[];
+  /** Fresh HTTP and WebSocket readiness probes for pooled trade streams (default 30s). */
+  healthCheckIntervalMs?: number;
+};
+export type SubscribeLaunchesOptions = Omit<
   Parameters<typeof subscribeCoreLaunches>[0],
   "connection"
-> & LiveEndpointOptions;
+> & LiveEndpointOptions;
 export type SubscribeMigrationsOptions = Omit<
   Parameters<typeof subscribeCoreMigrations>[0],
   "connection"
-> & LiveEndpointOptions;
+> & LiveEndpointOptions;
 export type SubscribeTradesOptions = Omit<
   Parameters<typeof subscribeCoreTrades>[0],
   "connection"
-> & LiveEndpointOptions;
+> & LiveEndpointOptions;
 
-export type ListenTradesOptions = Omit<SubscribeTradesOptions, "onTrade">;
+export type ListenTradesOptions = Omit<SubscribeTradesOptions, "onTrade"> & {
+  dbPath?: string;
+  /** Enabled by default; collected live history is partial and retains commitment. */
+  history?: false | Pick<LiveTradeHistoryOptions, "flushIntervalMs" | "batchSize" | "maxPending">;
+};
 
-export type TradeListener = {
+export type TradeListener = {
   add(tokens: string | readonly string[]): Promise<void>;
   remove(tokens: string | readonly string[]): Promise<void>;
   has(token: string): boolean;
   list(): string[];
-  onTrade(callback: (event: TradeEvent) => void | Promise<void>): () => void;
-  onMigration(callback: (event: TradeListenerMigration) => void | Promise<void>): () => void;
+  onTrade(callback: (event: TradeEvent) => void | Promise<void>): () => void;
+  onMigration(callback: (event: TradeListenerMigration) => void | Promise<void>): () => void;
   close(): Promise<void>;
   readonly closed: Promise<void>;
-};
-export type TradeListenerMigration = MigrationEvent & { oldPool: string | null; newPool: string };
+};
+export type TradeListenerMigration = MigrationEvent & { oldPool: string | null; newPool: string };
 
 type LiveConnection = {
   endpoint: string;
@@ -48,46 +54,46 @@ type LiveConnection = {
 };
 
 let shared: LiveConnection | null = null;
-let readiness: { endpoint: string; promise: Promise<void> } | null = null;
-
-/** HTTP + a fresh WebSocket handshake must both succeed before choosing an endpoint. */
-export class LiveEndpointPool {
-  private active = 0;
-  readonly endpoints: readonly string[];
-  constructor(endpoints: readonly string[], private readonly probe: (endpoint: string) => Promise<void> = async (endpoint) => {
-    await Promise.all([preflightRpc(endpoint), preflightWebSocket(endpoint)]);
-  }) {
-    this.endpoints = [...new Set(endpoints)];
-    if (!this.endpoints.length) throw new Error("Live RPC endpoint pool cannot be empty");
-    for (const endpoint of this.endpoints) deriveWebSocketEndpoint(endpoint);
-  }
-  get endpoint(): string { return this.endpoints[this.active]!; }
-  async select(skipCurrent = false): Promise<string> {
-    const start = this.active;
-    let lastError: unknown;
-    for (let offset = skipCurrent ? 1 : 0; offset < this.endpoints.length + (skipCurrent ? 1 : 0); offset++) {
-      const index = (start + offset) % this.endpoints.length;
-      try { await this.probe(this.endpoints[index]!); this.active = index; return this.endpoint; }
-      catch (error) { lastError = error; }
-    }
-    throw lastError;
-  }
-  async check(): Promise<string> {
-    try { await this.probe(this.endpoint); return this.endpoint; }
-    catch { return await this.select(true); }
-  }
-}
-const livePools = new Map<string, LiveEndpointPool>();
-function endpointPool(options: LiveEndpointOptions): LiveEndpointPool | undefined {
-  if (!options.rpcUrls?.length) return undefined;
-  const key = JSON.stringify(options.rpcUrls);
-  let pool = livePools.get(key);
-  if (!pool) { pool = new LiveEndpointPool(options.rpcUrls); livePools.set(key, pool); }
-  return pool;
-}
-function connectionFor(endpoint: string): LiveConnection {
-  return { endpoint, websocketEndpoint: deriveWebSocketEndpoint(endpoint), connection: new Connection(endpoint, "confirmed") };
-}
+let readiness: { endpoint: string; promise: Promise<void> } | null = null;
+
+/** HTTP + a fresh WebSocket handshake must both succeed before choosing an endpoint. */
+export class LiveEndpointPool {
+  private active = 0;
+  readonly endpoints: readonly string[];
+  constructor(endpoints: readonly string[], private readonly probe: (endpoint: string) => Promise<void> = async (endpoint) => {
+    await Promise.all([preflightRpc(endpoint), preflightWebSocket(endpoint)]);
+  }) {
+    this.endpoints = [...new Set(endpoints)];
+    if (!this.endpoints.length) throw new Error("Live RPC endpoint pool cannot be empty");
+    for (const endpoint of this.endpoints) deriveWebSocketEndpoint(endpoint);
+  }
+  get endpoint(): string { return this.endpoints[this.active]!; }
+  async select(skipCurrent = false): Promise<string> {
+    const start = this.active;
+    let lastError: unknown;
+    for (let offset = skipCurrent ? 1 : 0; offset < this.endpoints.length + (skipCurrent ? 1 : 0); offset++) {
+      const index = (start + offset) % this.endpoints.length;
+      try { await this.probe(this.endpoints[index]!); this.active = index; return this.endpoint; }
+      catch (error) { lastError = error; }
+    }
+    throw lastError;
+  }
+  async check(): Promise<string> {
+    try { await this.probe(this.endpoint); return this.endpoint; }
+    catch { return await this.select(true); }
+  }
+}
+const livePools = new Map<string, LiveEndpointPool>();
+function endpointPool(options: LiveEndpointOptions): LiveEndpointPool | undefined {
+  if (!options.rpcUrls?.length) return undefined;
+  const key = JSON.stringify(options.rpcUrls);
+  let pool = livePools.get(key);
+  if (!pool) { pool = new LiveEndpointPool(options.rpcUrls); livePools.set(key, pool); }
+  return pool;
+}
+function connectionFor(endpoint: string): LiveConnection {
+  return { endpoint, websocketEndpoint: deriveWebSocketEndpoint(endpoint), connection: new Connection(endpoint, "confirmed") };
+}
 
 function endpointFromEnv(): string {
   const endpoint = process.env.RPC_ENDPOINT?.trim();
@@ -289,9 +295,9 @@ async function ensureReady(endpoint: string): Promise<void> {
   }
 }
 
-async function liveConnection(options: LiveEndpointOptions = {}): Promise<LiveConnection> {
-  const pool = endpointPool(options);
-  if (pool) return connectionFor(await pool.select());
+async function liveConnection(options: LiveEndpointOptions = {}): Promise<LiveConnection> {
+  const pool = endpointPool(options);
+  if (pool) return connectionFor(await pool.select());
   const endpoint = endpointFromEnv();
   await ensureReady(endpoint);
   if (shared?.endpoint === endpoint) return shared;
@@ -317,78 +323,78 @@ function notifyReady(
   } catch {}
 }
 
-export async function subscribeTrades(options: SubscribeTradesOptions) {
-  let live = await liveConnection(options);
-  notifyReady(options, live);
-  const pool = endpointPool(options);
-  if (!pool) return await subscribeCoreTrades({ ...options, connection: live.connection });
-  // Keep duplicate suppression across connection changes. Provider probes detect
-  // dead credentials/quota; they cannot diagnose a silent old socket when a new
-  // handshake to that provider remains healthy.
-  const seen = new Set<string>();
-  const onTrade = async (event: TradeEvent) => {
-    const key = [event.signature, event.venue, event.mint, event.pool, event.side, String(event.baseRaw), String(event.quoteRaw)].join(":");
-    if (seen.has(key)) return;
-    seen.add(key);
-    if (seen.size > 4096) seen.delete(seen.values().next().value!);
-    await options.onTrade(event);
-  };
-  let subscription = await subscribeCoreTrades({ ...options, signal: undefined, onTrade, connection: live.connection });
-  let stopped = false;
-  let tail: Promise<unknown> = Promise.resolve();
-  const serial = <T>(work: () => Promise<T>): Promise<T> => {
-    const pending = tail.then(work, work); tail = pending.catch(() => undefined); return pending;
-  };
-  let settle!: () => void;
-  const closed = new Promise<void>((resolve) => { settle = resolve; });
-  const requestedInterval = options.healthCheckIntervalMs ?? 30_000;
-  if (!Number.isFinite(requestedInterval) || requestedInterval < 1000) {
-    await subscription.close();
-    throw new Error("healthCheckIntervalMs must be at least 1000");
-  }
-  let checking = false;
-  const timer = setInterval(() => {
-    if (stopped || checking) return;
-    checking = true;
-    void serial(async () => {
-      if (stopped) return;
-      try {
-        const endpoint = await pool.check();
-        if (stopped || endpoint === live.endpoint) return;
-        const tokens = subscription.listTokens();
-        const nextLive = connectionFor(endpoint);
-        const next = await subscribeCoreTrades({ ...options, signal: undefined, tokens, onTrade, connection: nextLive.connection });
-        await subscription.close();
-        subscription = next;
-        live = nextLive;
-        notifyReady(options, live);
-      } catch (error) {
-        try { options.onStatus?.("rpc-unavailable", { error: safeMessage(error) }); } catch {}
-      }
-    }).finally(() => { checking = false; });
-  }, Math.trunc(requestedInterval));
-  timer.unref?.();
-  const close = async () => {
-    if (stopped) return await closed;
-    stopped = true;
-    clearInterval(timer);
-    options.signal?.removeEventListener("abort", abort);
-    await serial(async () => { await subscription.close(); settle(); });
-  };
-  const abort = () => { void close(); };
-  if (options.signal?.aborted) await close();
-  else options.signal?.addEventListener("abort", abort, { once: true });
-  return {
-    addTokens: (tokens: string | readonly string[]) => serial(async () => { if (stopped) throw new Error("Trade subscription is closed"); await subscription.addTokens(tokens); }),
-    removeTokens: (tokens: string | readonly string[]) => serial(async () => { if (!stopped) await subscription.removeTokens(tokens); }),
-    hasToken: (token: string) => !stopped && subscription.hasToken(token),
-    listTokens: () => stopped ? [] : subscription.listTokens(),
-    close, closed,
-  } satisfies TradeSubscription;
-}
+export async function subscribeTrades(options: SubscribeTradesOptions) {
+  let live = await liveConnection(options);
+  notifyReady(options, live);
+  const pool = endpointPool(options);
+  if (!pool) return await subscribeCoreTrades({ ...options, connection: live.connection });
+  // Keep duplicate suppression across connection changes. Provider probes detect
+  // dead credentials/quota; they cannot diagnose a silent old socket when a new
+  // handshake to that provider remains healthy.
+  const seen = new Set<string>();
+  const onTrade = async (event: TradeEvent) => {
+    const key = [event.signature, event.venue, event.mint, event.pool, event.eventIndex ?? `${event.side}:${event.baseRaw}:${event.quoteRaw}`].join(":");
+    if (seen.has(key)) return;
+    seen.add(key);
+    if (seen.size > 4096) seen.delete(seen.values().next().value!);
+    await options.onTrade(event);
+  };
+  let subscription = await subscribeCoreTrades({ ...options, signal: undefined, onTrade, connection: live.connection });
+  let stopped = false;
+  let tail: Promise<unknown> = Promise.resolve();
+  const serial = <T>(work: () => Promise<T>): Promise<T> => {
+    const pending = tail.then(work, work); tail = pending.catch(() => undefined); return pending;
+  };
+  let settle!: () => void;
+  const closed = new Promise<void>((resolve) => { settle = resolve; });
+  const requestedInterval = options.healthCheckIntervalMs ?? 30_000;
+  if (!Number.isFinite(requestedInterval) || requestedInterval < 1000) {
+    await subscription.close();
+    throw new Error("healthCheckIntervalMs must be at least 1000");
+  }
+  let checking = false;
+  const timer = setInterval(() => {
+    if (stopped || checking) return;
+    checking = true;
+    void serial(async () => {
+      if (stopped) return;
+      try {
+        const endpoint = await pool.check();
+        if (stopped || endpoint === live.endpoint) return;
+        const tokens = subscription.listTokens();
+        const nextLive = connectionFor(endpoint);
+        const next = await subscribeCoreTrades({ ...options, signal: undefined, tokens, onTrade, connection: nextLive.connection });
+        await subscription.close();
+        subscription = next;
+        live = nextLive;
+        notifyReady(options, live);
+      } catch (error) {
+        try { options.onStatus?.("rpc-unavailable", { error: safeMessage(error) }); } catch {}
+      }
+    }).finally(() => { checking = false; });
+  }, Math.trunc(requestedInterval));
+  timer.unref?.();
+  const close = async () => {
+    if (stopped) return await closed;
+    stopped = true;
+    clearInterval(timer);
+    options.signal?.removeEventListener("abort", abort);
+    await serial(async () => { await subscription.close(); settle(); });
+  };
+  const abort = () => { void close(); };
+  if (options.signal?.aborted) await close();
+  else options.signal?.addEventListener("abort", abort, { once: true });
+  return {
+    addTokens: (tokens: string | readonly string[]) => serial(async () => { if (stopped) throw new Error("Trade subscription is closed"); await subscription.addTokens(tokens); }),
+    removeTokens: (tokens: string | readonly string[]) => serial(async () => { if (!stopped) await subscription.removeTokens(tokens); }),
+    hasToken: (token: string) => !stopped && subscription.hasToken(token),
+    listTokens: () => stopped ? [] : subscription.listTokens(),
+    close, closed,
+  } satisfies TradeSubscription;
+}
 
 export async function subscribeLaunches(options: SubscribeLaunchesOptions) {
-  const live = await liveConnection(options);
+  const live = await liveConnection(options);
   notifyReady(options, live);
   return await subscribeCoreLaunches({
     ...options,
@@ -397,44 +403,51 @@ export async function subscribeLaunches(options: SubscribeLaunchesOptions) {
 }
 
 export async function subscribeMigrations(options: SubscribeMigrationsOptions) {
-  const live = await liveConnection(options);
+  const live = await liveConnection(options);
   notifyReady(options, live);
   return await subscribeCoreMigrations({
     ...options,
     connection: live.connection,
   });
 }
-export async function listenTrades(
+export async function listenTrades(
   options: ListenTradesOptions,
 ): Promise<TradeListener> {
-  const callbacks = new Set<(event: TradeEvent) => void | Promise<void>>();
-  const pending: TradeEvent[] = [];
-  const migrationCallbacks = new Set<(event: TradeListenerMigration) => void | Promise<void>>();
-  const pendingMigrations: TradeListenerMigration[] = [];
-  const watched = new Set(options.tokens);
-  const lastPools = new Map<string, string | null>();
-  let subscription: TradeSubscription;
+  const callbacks = new Set<(event: TradeEvent) => void | Promise<void>>();
+  const history = options.history === false ? undefined : createLiveTradeHistoryRecorder({ ...options.history, dbPath: options.dbPath, commitment: options.commitment, onStatus: options.onStatus });
+  const pending: TradeEvent[] = [];
+  const migrationCallbacks = new Set<(event: TradeListenerMigration) => void | Promise<void>>();
+  const pendingMigrations: TradeListenerMigration[] = [];
+  const watched = new Set(options.tokens);
+  const lastPools = new Map<string, string | null>();
+  let subscription: TradeSubscription;
   let migrations: Awaited<ReturnType<typeof subscribeMigrations>> | undefined;
   let stopped = false;
-  let tail: Promise<unknown> = Promise.resolve();
-  const serial = <T>(work: () => Promise<T>): Promise<T> => { const job = tail.then(work, work); tail = job.catch(() => undefined); return job; };
-  const onMigration = async (event: MigrationEvent) => {
-    if (stopped || !watched.has(event.mint)) return;
-    const migration = { ...event, oldPool: lastPools.get(event.mint) ?? null, newPool: event.pool };
-    lastPools.set(event.mint, event.pool);
-    await serial(async () => {
-      if (stopped || !watched.has(event.mint)) return;
-      // Mint mentions cover the new pool; rebuilding resets cached identities,
-      // decimals and supply without changing the caller's watched token list.
-      await subscription.removeTokens(event.mint);
-      await subscription.addTokens(event.mint);
-    });
-    if (!migrationCallbacks.size) { pendingMigrations.push(migration); if (pendingMigrations.length > 1000) pendingMigrations.shift(); }
-    else await Promise.all([...migrationCallbacks].map(callback => callback(migration)));
-  };
+  let resolveClosed!: () => void;
+  let rejectClosed!: (error: unknown) => void;
+  const closed = new Promise<void>((resolve, reject) => { resolveClosed = resolve; rejectClosed = reject; });
+  void closed.catch(() => undefined);
+  let tail: Promise<unknown> = Promise.resolve();
+  const serial = <T>(work: () => Promise<T>): Promise<T> => { const job = tail.then(work, work); tail = job.catch(() => undefined); return job; };
+  const onMigration = async (event: MigrationEvent) => {
+    if (stopped || !watched.has(event.mint)) return;
+    const migration = { ...event, oldPool: lastPools.get(event.mint) ?? null, newPool: event.pool };
+    lastPools.set(event.mint, event.pool);
+    await serial(async () => {
+      if (stopped || !watched.has(event.mint)) return;
+      // Mint mentions cover the new pool; rebuilding resets cached identities,
+      // decimals and supply without changing the caller's watched token list.
+      await subscription.removeTokens(event.mint);
+      await subscription.addTokens(event.mint);
+    });
+    if (!migrationCallbacks.size) { pendingMigrations.push(migration); if (pendingMigrations.length > 1000) pendingMigrations.shift(); }
+    else await Promise.all([...migrationCallbacks].map(callback => callback(migration)));
+  };
   const dispatch = async (event: TradeEvent) => {
     if (!watched.has(event.mint) || stopped) return;
     lastPools.set(event.mint, event.pool);
+    try { await history?.record(event); }
+    catch (error) { options.onStatus?.("history-persistence-error", { error: safeMessage(error) }); }
     if (callbacks.size === 0) {
       pending.push(event);
       if (pending.length > 1_000) pending.shift();
@@ -446,30 +459,34 @@ export async function listenTrades(
       }),
     );
   };
-  const onStatus = (event: string, data?: Record<string, unknown>) => {
-    options.onStatus?.(event, data);
-    if (event === "rpc-ready" && migrations && !stopped) void serial(async () => {
-      if (stopped) return;
-      const next = await subscribeMigrations({ rpcUrls: options.rpcUrls, tokens: [...watched], commitment: options.commitment, metadata: options.metadata, onMigration, onStatus: options.onStatus });
-      await migrations?.close(); migrations = next;
-    }).catch(error => options.onStatus?.("migration-resubscribe-error", { error: safeMessage(error) }));
-  };
-  subscription = await subscribeTrades({ ...options, signal: undefined, onStatus, onTrade: dispatch });
-  try { migrations = await subscribeMigrations({ rpcUrls: options.rpcUrls, tokens: [...watched], commitment: options.commitment, metadata: options.metadata, onMigration, onStatus: options.onStatus }); }
-  catch (error) { await subscription.close(); throw error; }
+  const onStatus = (event: string, data?: Record<string, unknown>) => {
+    options.onStatus?.(event, data);
+    if (event === "rpc-ready" && migrations && !stopped) void serial(async () => {
+      if (stopped) return;
+      const next = await subscribeMigrations({ rpcUrls: options.rpcUrls, tokens: [...watched], commitment: options.commitment, metadata: options.metadata, onMigration, onStatus: options.onStatus });
+      await migrations?.close(); migrations = next;
+    }).catch(error => options.onStatus?.("migration-resubscribe-error", { error: safeMessage(error) }));
+  };
+  try { subscription = await subscribeTrades({ ...options, signal: undefined, onStatus, onTrade: dispatch }); }
+  catch (error) { await history?.close(); throw error; }
+  try { migrations = await subscribeMigrations({ rpcUrls: options.rpcUrls, tokens: [...watched], commitment: options.commitment, metadata: options.metadata, onMigration, onStatus: options.onStatus }); }
+  catch (error) { await subscription.close(); await history?.close(); throw error; }
   const close = async () => {
-    if (stopped) return;
+    if (stopped) return await closed;
     stopped = true; options.signal?.removeEventListener("abort", abort);
-    await serial(async () => { await Promise.all([subscription.close(), migrations?.close()]); watched.clear(); });
-  };
-  const abort = () => { void close(); };
-  if (options.signal?.aborted) await close();
-  else options.signal?.addEventListener("abort", abort, { once: true });
-  return {
-    add: (tokens) => serial(async () => { if (stopped) throw new Error("Trade listener is closed"); const values = typeof tokens === "string" ? [tokens] : [...tokens]; await subscription.addTokens(values); await migrations!.addTokens(values); values.forEach(token => watched.add(token)); }),
-    remove: (tokens) => serial(async () => { const values = typeof tokens === "string" ? [tokens] : [...tokens]; values.forEach(token => { watched.delete(token); lastPools.delete(token); }); await Promise.all([subscription.removeTokens(values), migrations!.removeTokens(values)]); }),
-    has: (token) => !stopped && watched.has(token),
-    list: () => stopped ? [] : [...watched],
+    try {
+      await serial(async () => { await Promise.all([subscription.close(), migrations?.close()]); watched.clear(); await history?.close(); });
+      resolveClosed();
+    } catch (error) { rejectClosed(error); throw error; }
+  };
+  const abort = () => { void close(); };
+  if (options.signal?.aborted) await close();
+  else options.signal?.addEventListener("abort", abort, { once: true });
+  return {
+    add: (tokens) => serial(async () => { if (stopped) throw new Error("Trade listener is closed"); const values = typeof tokens === "string" ? [tokens] : [...tokens]; await subscription.addTokens(values); await migrations!.addTokens(values); values.forEach(token => watched.add(token)); }),
+    remove: (tokens) => serial(async () => { const values = typeof tokens === "string" ? [tokens] : [...tokens]; values.forEach(token => { watched.delete(token); lastPools.delete(token); }); await Promise.all([subscription.removeTokens(values), migrations!.removeTokens(values)]); }),
+    has: (token) => !stopped && watched.has(token),
+    list: () => stopped ? [] : [...watched],
     onTrade(callback) {
       callbacks.add(callback);
       if (pending.length) {
@@ -480,14 +497,14 @@ export async function listenTrades(
       }
       return () => callbacks.delete(callback);
     },
-    onMigration(callback) {
-      migrationCallbacks.add(callback);
-      if (pendingMigrations.length) { const rows = pendingMigrations.splice(0); void Promise.resolve().then(async () => { for (const event of rows) await callback(event); }); }
-      return () => migrationCallbacks.delete(callback);
-    },
+    onMigration(callback) {
+      migrationCallbacks.add(callback);
+      if (pendingMigrations.length) { const rows = pendingMigrations.splice(0); void Promise.resolve().then(async () => { for (const event of rows) await callback(event); }); }
+      return () => migrationCallbacks.delete(callback);
+    },
     close,
-    get closed() {
-      return subscription.closed;
+    get closed() {
+      return closed;
     },
   };
 }