@candledottv/agent-sdk 0.4.6 → 0.4.8

package/dist/index.js

@@ -1,6 +1,9 @@
 import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
+// src/client.ts
+import { keccak_256 as keccak_2562 } from "@noble/hashes/sha3";
+
 // src/authorization-signature.ts
 import canonicalize from "canonicalize";
 
@@ -84,6 +87,12 @@ class CandleApiError extends Error {
   coverage;
   uiHint;
   docsPath;
+  stage;
+  signature;
+  recorded;
+  feeRaw;
+  quoteAsset;
+  treasury;
   constructor(args) {
     super(args.message);
     this.name = "CandleApiError";
@@ -97,6 +106,37 @@ class CandleApiError extends Error {
     this.coverage = args.coverage;
     this.uiHint = args.uiHint;
     this.docsPath = args.docsPath;
+    if (args.stage !== undefined)
+      this.stage = args.stage;
+    if (args.signature !== undefined)
+      this.signature = args.signature;
+    if (args.recorded !== undefined)
+      this.recorded = args.recorded;
+    if (args.feeRaw !== undefined)
+      this.feeRaw = args.feeRaw;
+    if (args.quoteAsset !== undefined)
+      this.quoteAsset = args.quoteAsset;
+    if (args.treasury !== undefined)
+      this.treasury = args.treasury;
+  }
+}
+
+class TradeLandedFeeLegError extends Error {
+  clientTradeId;
+  tradeTxHash;
+  feeTxHash;
+  feeOutcome;
+  stage = "executed";
+  constructor(args) {
+    const reason = args.cause instanceof Error ? args.cause.message : String(args.cause);
+    const recover = args.feeOutcome === "unknown" ? args.feeTxHash ? `Do NOT repeat the trade. Do NOT pay again: the fee may already be pending or mined. Check feeTxHash ` + `${args.feeTxHash} and re-confirm clientTradeId ${args.clientTradeId} with tradeTxHash ` + `${args.tradeTxHash} and that same feeTxHash.` : `Do NOT repeat the trade. Do NOT pay again: the fee broadcast outcome is unknown and it may already ` + `be pending or mined. Check the payer wallet before any new payment, then re-confirm clientTradeId ` + `${args.clientTradeId} with tradeTxHash ${args.tradeTxHash} and the fee hash you find.` : `Do NOT repeat the trade: pay the fee, then call confirmTrade for clientTradeId ${args.clientTradeId} ` + `with tradeTxHash and the fee's feeTxHash.`;
+    super(`trade executed; fee/booking incomplete: the trade landed (tradeTxHash ${args.tradeTxHash}) but its fee ` + `transfer ${args.feeOutcome === "unknown" ? "outcome is unknown" : "failed"} (${reason}). The trade is ` + `NOT confirmed or booked. ${recover}`, { cause: args.cause });
+    this.name = "TradeLandedFeeLegError";
+    this.clientTradeId = args.clientTradeId;
+    this.tradeTxHash = args.tradeTxHash;
+    this.feeOutcome = args.feeOutcome;
+    if (args.feeTxHash !== undefined)
+      this.feeTxHash = args.feeTxHash;
   }
 }
 function isSolanaRpcErrorData(data) {
@@ -138,7 +178,13 @@ function envelopeError(body) {
     code: error.code,
     message: error.message,
     ...typeof error.field === "string" ? { field: error.field } : {},
-    ...typeof error.retryable === "boolean" ? { retryable: error.retryable } : {}
+    ...typeof error.retryable === "boolean" ? { retryable: error.retryable } : {},
+    ...typeof error.stage === "string" ? { stage: error.stage } : {},
+    ...typeof error.signature === "string" ? { signature: error.signature } : {},
+    ...typeof error.recorded === "boolean" ? { recorded: error.recorded } : {},
+    ...typeof error.feeRaw === "string" ? { feeRaw: error.feeRaw } : {},
+    ...typeof error.quoteAsset === "string" ? { quoteAsset: error.quoteAsset } : {},
+    ...typeof error.treasury === "string" ? { treasury: error.treasury } : {}
   };
 }
 function candleApiErrorFromResponse(status, bodyText) {
@@ -750,6 +796,34 @@ ${lines.join(`
 }
 
 // src/client.ts
+function historyTime(value) {
+  return value instanceof Date ? String(value.getTime()) : String(value);
+}
+var HYPERLIQUID_RELAY_CHAIN_ID = 1337;
+var HYPERLIQUID_RELAY_USDC = "0x00000000000000000000000000000000";
+function perpsDepositProblem(build, params) {
+  const same = (a, b) => typeof a === "string" && a.toLowerCase() === b.toLowerCase();
+  if (build.walletId !== params.walletId)
+    return "the build names another paying wallet";
+  if (build.asset !== params.asset || build.amountRaw !== params.amountRaw)
+    return "the build is for another amount";
+  if (build.destination?.chainId !== HYPERLIQUID_RELAY_CHAIN_ID)
+    return "the build does not land on Hyperliquid";
+  if (build.destination.currency !== HYPERLIQUID_RELAY_USDC)
+    return "the build does not deliver Hyperliquid USDC";
+  if (!same(build.destination.address, params.account))
+    return "the build lands on another account";
+  if (build.fee?.bps !== 0 || build.fee.feeRaw !== "0")
+    return "the build carries a Candle fee";
+  const hood = params.asset === "ETH" || params.asset === "USDG";
+  if (hood !== (build.chain === "hood"))
+    return "the build pays from the wrong chain";
+  if (hood && !same(build.walletAddress, params.account))
+    return "a Hood deposit lands only on the paying wallet's own account";
+  if (!hood && build.transactionsBase64?.length !== 1)
+    return "the build is not one Solana deposit";
+  return null;
+}
 var BACKOFF_BASE_MS = 250;
 var BACKOFF_CAP_MS = 8000;
 function retryDelayMs(retry) {
@@ -964,6 +1038,9 @@ class CandleClient {
   async getAgentTier() {
     return this.requestJson("GET", "/api/v1/agent/tier");
   }
+  async getPlans() {
+    return this.requestJson("GET", "/api/v1/agent/plans");
+  }
   async dryRunLaunch(req) {
     this.requireKey("dryRunLaunch()");
     return this.requestJson("POST", "/api/v1/launch/headless/dry-run", req);
@@ -1034,7 +1111,16 @@ class CandleClient {
   }
   async getProfileTrades(keyPrefix, opts = {}) {
     this.requireKey("getProfileTrades()");
-    const query = opts.limit !== undefined ? `?limit=${encodeURIComponent(String(opts.limit))}` : "";
+    const params = new URLSearchParams;
+    if (opts.limit !== undefined)
+      params.set("limit", String(opts.limit));
+    if (opts.since !== undefined)
+      params.set("since", historyTime(opts.since));
+    if (opts.until !== undefined)
+      params.set("until", historyTime(opts.until));
+    if (opts.cursor !== undefined)
+      params.set("cursor", opts.cursor);
+    const query = params.toString() === "" ? "" : `?${params.toString()}`;
     return this.requestJson("GET", `/api/v1/agent/keys/${encodeURIComponent(keyPrefix)}/trades${query}`);
   }
   async getProfilePnl(keyPrefix) {
@@ -1092,6 +1178,10 @@ class CandleClient {
       ...params.label !== undefined ? { label: params.label } : {}
     });
   }
+  async dryRunSelfLaunch(req) {
+    this.requireKey("dryRunSelfLaunch()");
+    return this.requestJson("POST", "/api/v1/launch/self/dry-run", req);
+  }
   async buildSelfLaunch(req) {
     this.requireKey("buildSelfLaunch()");
     return this.requestJson("POST", "/api/v1/launch/self/build", req);
@@ -1242,18 +1332,26 @@ class CandleClient {
       const leg = legs[i];
       if (!leg)
         continue;
-      const txHash = await this.signBroadcastAndWaitEvmLeg({
-        rpc,
-        from,
-        to: leg.to,
-        data: leg.data,
-        valueDecimal: leg.value,
-        nonce: baseNonce + i,
-        chainId,
-        feeData,
-        linkedWalletId,
-        privyWalletId
-      });
+      let txHash;
+      try {
+        txHash = await this.signBroadcastAndWaitEvmLeg({
+          rpc,
+          from,
+          to: leg.to,
+          data: leg.data,
+          valueDecimal: leg.value,
+          nonce: baseNonce + i,
+          chainId,
+          feeData,
+          linkedWalletId,
+          privyWalletId
+        }, { surfaceLegOutcome: leg.kind === "feeTransfer" });
+      } catch (err) {
+        if (leg.kind === "feeTransfer" && tradeTxHash) {
+          throw tradeLandedFeeLegError({ clientTradeId: built.clientTradeId, tradeTxHash, err });
+        }
+        throw err;
+      }
       if (leg.kind === "trade")
         tradeTxHash = txHash;
       if (leg.kind === "feeTransfer")
@@ -1409,7 +1507,16 @@ class CandleClient {
       callRaw: (method, params) => this.jsonRpcCallRaw(url, method, params)
     };
   }
-  async signBroadcastAndWaitEvmLeg(params) {
+  async signBroadcastAndWaitEvmLeg(params, opts = {}) {
+    try {
+      return await this.broadcastAndWaitEvmLeg(params);
+    } catch (err) {
+      if (opts.surfaceLegOutcome || !(err instanceof EvmLegOutcome))
+        throw err;
+      throw err.cause;
+    }
+  }
+  async broadcastAndWaitEvmLeg(params) {
     const gasLimitHex = await estimateGas(params.rpc, {
       from: params.from,
       to: params.to,
@@ -1432,8 +1539,23 @@ class CandleClient {
       chain: "evm",
       evmTxParams
     });
-    const txHash = await this.broadcastSignedTransaction("evm", signed.signedTransaction, signed.encoding);
-    await waitForReceipt(params.rpc, txHash);
+    const predicted = evmSignedTxHash(signed.signedTransaction, signed.encoding);
+    let txHash;
+    try {
+      txHash = await this.broadcastSignedTransaction("evm", signed.signedTransaction, signed.encoding);
+    } catch (err) {
+      if (!isDefiniteBroadcastRejection(err)) {
+        throw new EvmLegOutcome({ kind: "unknown", txHash: predicted, cause: err });
+      }
+      throw err;
+    }
+    try {
+      await waitForReceipt(params.rpc, txHash, evmReceiptWaitForTest ?? {});
+    } catch (err) {
+      if (isRevertedReceipt(err))
+        throw new EvmLegOutcome({ kind: "reverted", txHash, cause: err });
+      throw new EvmLegOutcome({ kind: "unknown", txHash, cause: err });
+    }
     return txHash;
   }
   async perpsConfig() {
@@ -1522,6 +1644,79 @@ class CandleClient {
       params.set("startTime", String(startTime));
     return this.requestJson("GET", `/api/v1/agent/perps/funding?${params}`);
   }
+  async perpsDeposit(params) {
+    this.requireKey("perpsDeposit()");
+    const build = await this.requestJson("POST", "/api/v1/agent/perps/deposit", {
+      clientDepositId: params.clientDepositId,
+      walletId: params.walletId,
+      asset: params.asset,
+      amountRaw: params.amountRaw,
+      ...params.perpsWalletId !== undefined ? { perpsWalletId: params.perpsWalletId } : {},
+      ...params.maxSlippageBps !== undefined ? { maxSlippageBps: params.maxSlippageBps } : {}
+    });
+    if (build.job !== undefined)
+      throw new Error(`perpsDeposit(): ${params.clientDepositId} already names a deposit; read it with perpsDepositStatus()`);
+    const problem = perpsDepositProblem(build, params);
+    if (problem)
+      throw new Error(`perps: refused to sign this deposit: ${problem}`);
+    if (params.submit === false)
+      return { build, submitted: false, result: null };
+    const submitPath = "/api/v1/agent/perps/deposit/submit";
+    const ids = { clientDepositId: params.clientDepositId, depositId: build.depositId };
+    if (build.chain === "solana") {
+      const signed = await this.signLinkedTransaction({
+        chain: "solana",
+        linkedWalletId: params.walletId,
+        privyWalletId: params.privyWalletId,
+        unsignedTransactionBase64: build.transactionsBase64[0]
+      });
+      const result = await this.requestJson("POST", submitPath, {
+        ...ids,
+        signedTransactionsBase64: [signed.signedTransaction]
+      });
+      return { build, submitted: true, result };
+    }
+    const allowed = params.asset === "USDG" ? ["approval", "bridgeDeposit"] : ["bridgeDeposit"];
+    const planned = build.plannedLegCount ?? 0;
+    const hex = (value) => `0x${BigInt(value).toString(16)}`;
+    let body = build;
+    const signedKinds = new Set;
+    while (body.mode === "sequenced") {
+      const leg = body.nextLeg;
+      const kind = String(body.legKind);
+      if (!leg || body.operationId !== build.operationId || body.plannedLegCount !== planned || planned > allowed.length || !allowed.includes(kind) || signedKinds.has(kind) || leg.chainId !== 4663) {
+        throw new Error(`perps: refused to sign deposit leg ${kind}: it is not the plan this deposit was built with`);
+      }
+      signedKinds.add(kind);
+      const signed = await this.signLinkedTransaction({
+        chain: "evm",
+        linkedWalletId: params.walletId,
+        privyWalletId: params.privyWalletId,
+        evmTxParams: {
+          chain_id: leg.chainId,
+          data: leg.data,
+          from: build.walletAddress,
+          gas_limit: hex(leg.gas),
+          max_fee_per_gas: hex(leg.maxFeePerGas),
+          max_priority_fee_per_gas: hex(leg.maxPriorityFeePerGas),
+          nonce: leg.nonce,
+          to: leg.to,
+          type: 2,
+          value: hex(leg.value)
+        }
+      });
+      body = await this.requestJson("POST", submitPath, {
+        ...ids,
+        operationId: build.operationId,
+        signedTransaction: signed.signedTransaction
+      });
+    }
+    return { build, submitted: true, result: body };
+  }
+  async perpsDepositStatus(clientDepositId) {
+    this.requireKey("perpsDepositStatus()");
+    return this.requestJson("GET", `/api/v1/agent/perps/deposit/${encodeURIComponent(clientDepositId)}`);
+  }
   async perpsBuilder() {
     if (this.hyperliquidBuilder)
       return this.hyperliquidBuilder;
@@ -1675,6 +1870,66 @@ class CandleClient {
     return parsed.result;
   }
 }
+
+class EvmLegOutcome extends Error {
+  kind;
+  txHash;
+  cause;
+  constructor(args) {
+    super(args.cause instanceof Error ? args.cause.message : String(args.cause), { cause: args.cause });
+    this.name = "EvmLegOutcome";
+    this.kind = args.kind;
+    this.txHash = args.txHash;
+    this.cause = args.cause;
+  }
+}
+var evmReceiptWaitForTest = null;
+function tradeLandedFeeLegError(args) {
+  if (args.err instanceof EvmLegOutcome) {
+    return new TradeLandedFeeLegError({
+      clientTradeId: args.clientTradeId,
+      tradeTxHash: args.tradeTxHash,
+      cause: args.err.cause,
+      feeOutcome: args.err.kind,
+      ...args.err.txHash !== undefined ? { feeTxHash: args.err.txHash } : {}
+    });
+  }
+  return new TradeLandedFeeLegError({
+    clientTradeId: args.clientTradeId,
+    tradeTxHash: args.tradeTxHash,
+    cause: args.err,
+    feeOutcome: "not-broadcast"
+  });
+}
+function evmSignedTxHash(signedTransaction, encoding) {
+  const enc = encoding.toLowerCase();
+  let bytes;
+  if (enc === "base64") {
+    bytes = fromBase64(signedTransaction);
+  } else if (enc === "hex" || enc === "rlp" || signedTransaction.startsWith("0x")) {
+    const hex2 = signedTransaction.startsWith("0x") ? signedTransaction.slice(2) : signedTransaction;
+    if (!/^[0-9a-fA-F]+$/.test(hex2) || hex2.length % 2 !== 0)
+      return;
+    bytes = new Uint8Array(hex2.length / 2);
+    for (let i = 0;i < bytes.length; i++)
+      bytes[i] = Number.parseInt(hex2.slice(i * 2, i * 2 + 2), 16);
+  }
+  if (!bytes || bytes.length === 0)
+    return;
+  let hex = "";
+  for (const b of keccak_2562(bytes))
+    hex += b.toString(16).padStart(2, "0");
+  return `0x${hex}`;
+}
+function isDefiniteBroadcastRejection(err) {
+  if (!(err instanceof JsonRpcError))
+    return false;
+  const rpcMessage = err.message.match(/\(code -?\d+\): (.*)$/)?.[1]?.toLowerCase();
+  return rpcMessage === "insufficient funds for gas * price + value" || rpcMessage === "intrinsic gas too low" || rpcMessage === "invalid sender";
+}
+function isRevertedReceipt(err) {
+  return err instanceof Error && err.message.includes("transaction reverted (receipt status 0x0)");
+}
 function generateSdkId() {
   return `sdk-${crypto.randomUUID()}`;
 }
@@ -1684,7 +1939,7 @@ function generateClientLaunchId() {
 function generateClientTradeId() {
   return generateSdkId();
 }
-var SDK_VERSION = "0.4.6";
+var SDK_VERSION = "0.4.8";
 var sdkUpdateWarned = false;
 function noteLatestSdkVersion(value) {
   if (sdkUpdateWarned || !value || !/^\d+\.\d+\.\d+$/.test(value))
@@ -1809,6 +2064,79 @@ class KeychainSecretStore {
     await this.exec("secret-tool", ["clear", "service", SERVICE, "account", ref]);
   }
 }
+// src/plans.ts
+var PLAN_CAPABILITY_NOTE = "A capability marked yes is what the plan allows. It is subject to the deployment's own switches (perps and own-wallet bridges each have one) and to the wallet, scopes and setup the feature needs. Every plan can launch a token from its embedded wallet, with an optional dev buy (same transaction on Solana; best-effort follow-up on Hood), through the headless launch; the two launch rows are additional routes, not the only ones.";
+var PLAN_CAPABILITY_LABELS = {
+  tradeCandleTokens: "Trade Candle-launched tokens",
+  tradeBaseAssets: "Trade base assets",
+  freeBaseTransfers: "Base-pair swaps and own-wallet bridges (when enabled), no Candle fee",
+  sellExternalTokens: "Sell tokens not launched on Candle",
+  buyExternalTokens: "Buy tokens not launched on Candle",
+  hyperliquidPerps: "Hyperliquid perps (when enabled)",
+  selfLaunch: "Launch from a linked or TEE wallet (self-signed)",
+  atomicLaunch: "Atomic launch: launch + 1–4 first buys in one bundle",
+  createLinkedWallets: "Create linked wallets",
+  importLinkedWallets: "Import linked wallets",
+  limitOrders: "Limit orders",
+  quant: "Quant on Telegram"
+};
+var PLAN_LABELS = { free: "Free", believer: "Believer", pro: "Pro", max: "Max" };
+function planLabel(plan) {
+  return Object.hasOwn(PLAN_LABELS, plan) ? PLAN_LABELS[plan] : plan;
+}
+function formatPlanBps(bps) {
+  return bps === 0 ? "none" : `${Number((bps / 100).toFixed(4))}%`;
+}
+function count(n) {
+  return n.toLocaleString("en-US");
+}
+function priceCell(entry) {
+  if (entry.price)
+    return `$${count(entry.price.pricePerMonthUsd)} a month`;
+  return entry.plan === "free" ? "free" : "not sold";
+}
+function planTableRows(table) {
+  const plans = table.plans;
+  const row = (label, cell) => [label, ...plans.map(cell)];
+  const rows = [
+    row("Price", priceCell),
+    row("Agent trade fee", (e) => formatPlanBps(e.feeBps)),
+    row("Perps builder fee", (e) => formatPlanBps(e.perpFeeBps)),
+    row("Requests per minute", (e) => count(e.limits.rateLimitPerMin)),
+    row("Launches per day", (e) => count(e.limits.dailyLaunchCap)),
+    row("Uploads per minute", (e) => count(e.limits.uploadsPerMin)),
+    row("Linked wallets", (e) => count(e.limits.linkedWallets))
+  ];
+  const known = Object.keys(PLAN_CAPABILITY_LABELS);
+  const served = new Set;
+  for (const entry of plans)
+    for (const key of Object.keys(entry.capabilities ?? {}))
+      served.add(key);
+  const keys = [
+    ...known.filter((k) => served.has(k)),
+    ...[...served].filter((k) => !Object.hasOwn(PLAN_CAPABILITY_LABELS, k))
+  ];
+  for (const key of keys) {
+    const label = Object.hasOwn(PLAN_CAPABILITY_LABELS, key) ? PLAN_CAPABILITY_LABELS[key] : key;
+    rows.push(row(label, (e) => {
+      const value = e.capabilities?.[key];
+      return value === true ? "yes" : value === false ? "no" : "-";
+    }));
+  }
+  return { headers: ["", ...plans.map((e) => planLabel(e.plan))], rows };
+}
+function planPromotionLine(table) {
+  if (!(table.promoMaxDays > 0))
+    return null;
+  const days = table.promoMaxDays === 1 ? "1 day" : `${table.promoMaxDays} days`;
+  return `A first Pro purchase includes Max for its first ${days}, then continues on Pro.`;
+}
+function planTableMarkdown(table) {
+  const { headers, rows } = planTableRows(table);
+  const line = (cells) => `| ${cells.map((c) => c.replace(/\|/g, "\\|")).join(" | ")} |`;
+  return [line(headers), line(headers.map(() => "---")), ...rows.map(line)].join(`
+`);
+}
 // src/file-lock.ts
 var STALE_MS = 30000;
 var RETRY_MS = 25;
@@ -1970,10 +2298,19 @@ function verifyWebhookSignature(secret, header, body, nowSec, toleranceSec = 300
 export {
   verifyWebhookSignature,
   verifyPerpsBuild,
+  planTableRows,
+  planTableMarkdown,
+  planPromotionLine,
+  planLabel,
+  perpsDepositProblem,
   isSolanaRpcErrorData,
   hyperliquidActionHash,
   generateSignerKeypair,
+  formatPlanBps,
   encryptWalletKeyForImport,
+  TradeLandedFeeLegError,
+  PLAN_CAPABILITY_NOTE,
+  PLAN_CAPABILITY_LABELS,
   KeychainSecretStore,
   JsonRpcError,
   InMemorySecretStore,

package/dist/plans.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The served plan table (Plans v2, PL-ED-1 and PL-ED-14): its types and one way to render it.
+ *
+ * `GET /api/v1/agent/plans` (no credential) and the `planTable` field of `GET /api/v1/agent/tier`
+ * return the table in force on the deployment that answered: each plan's price, agent fee, perps
+ * builder fee, the limits a new key gets, and what the plan can do. A client quotes these numbers
+ * rather than numbers it bundled, so it never shows a price or a fee the server is not charging.
+ *
+ * Dependency-free on purpose. The CLI and the MCP server carry byte-identical copies
+ * (`plans.drift.test.ts` in each), and the repo's docs freshness gate renders the docs plan table
+ * through this file, so the CLI, the MCP text and the docs say the same thing in the same words.
+ * Copy any change verbatim: `cp packages/sdk/src/plans.ts packages/cli/src/plans.ts` and the same
+ * for `packages/mcp/src/plans.ts`.
+ */
+/**
+ * A plan name. `believer` is served only by a deployment that has not switched to the three plans
+ * (Free, Pro, Max); it is accepted here for one release after that launch, then removed.
+ */
+export type PlanName = "free" | "pro" | "max" | "believer";
+/** A sold plan's price, in the shape the tier response's `maxPricing` has always had. */
+export interface PlanPrice {
+    pricePerMonthUsd: number;
+    currency: string;
+    approval: string;
+}
+/** What a freshly issued key on the plan gets. Enforcement never lowers a key set higher by hand. */
+export interface PlanLimits {
+    rateLimitPerMin: number;
+    dailyLaunchCap: number;
+    uploadsPerMin: number;
+    /** Linked wallets the account may have active at once. */
+    linkedWallets: number;
+}
+/** What a plan can do, one flag per gate the API enforces (PL-ED-14). */
+export interface PlanCapabilities {
+    /** Buy a token that was not launched on Candle and is not a base asset. */
+    buyExternalTokens: boolean;
+    /** Sell such a token. True on every plan, so losing a plan never traps a position. */
+    sellExternalTokens: boolean;
+    tradeBaseAssets: boolean;
+    tradeCandleTokens: boolean;
+    selfLaunch: boolean;
+    atomicLaunch: boolean;
+    createLinkedWallets: boolean;
+    importLinkedWallets: boolean;
+    /** Plan eligibility only: whether perps are open on the deployment is its own switch, and trading needs the wallet and scopes. */
+    hyperliquidPerps: boolean;
+    limitOrders: boolean;
+    /** The quant bot on Telegram. */
+    quant: boolean;
+    /** Base-pair swaps and base-asset bridges between the key's own wallets carry no Candle fee. A bridge also needs its own deployment switch. */
+    freeBaseTransfers: boolean;
+}
+export interface PlanTableEntry {
+    plan: PlanName;
+    /**
+     * Absent from a deployment that predates the capability table. A newer deployment may add a
+     * capability this release does not name; `planTableRows` shows it under its own key.
+     */
+    capabilities?: PlanCapabilities;
+    /** The agent platform fee this deployment charges, in basis points, overrides included. */
+    feeBps: number;
+    /** The Hyperliquid perps builder fee, in basis points. */
+    perpFeeBps: number;
+    /** Null when the plan is not sold: Free, Believer, and Pro before the three-plan launch. */
+    price: PlanPrice | null;
+    limits: PlanLimits;
+}
+export interface PlanTable {
+    plans: PlanTableEntry[];
+    /** Days of Max a first Pro purchase grants. 0 when there is no promotion. */
+    promoMaxDays: number;
+}
+/** `GET /api/v1/agent/plans`. */
+export interface AgentPlansResult extends PlanTable {
+    success: true;
+}
+/**
+ * What a capability "yes" means. It is the plan's eligibility, not a statement that the deployment has
+ * the feature switched on, so perps and own-wallet bridges say "when enabled" in their labels.
+ */
+export declare const PLAN_CAPABILITY_NOTE = "A capability marked yes is what the plan allows. It is subject to the deployment's own switches (perps and own-wallet bridges each have one) and to the wallet, scopes and setup the feature needs. Every plan can launch a token from its embedded wallet, with an optional dev buy (same transaction on Solana; best-effort follow-up on Hood), through the headless launch; the two launch rows are additional routes, not the only ones.";
+/** The row label for each capability, in the order the rows are shown. */
+export declare const PLAN_CAPABILITY_LABELS: Record<keyof PlanCapabilities, string>;
+/** "Free", "Pro", "Max", "Believer"; an unknown name as served. */
+export declare function planLabel(plan: string): string;
+/** Basis points as a percentage: 100 is "1%", 25 is "0.25%", 0 is "none". */
+export declare function formatPlanBps(bps: number): string;
+/**
+ * The table as rows of text cells: a header row of plan names, then price, fees, limits and one
+ * row per capability. The CLI prints it as a terminal table and the docs as a Markdown table.
+ * Capabilities this release does not name are appended under their own key, so a newer server's
+ * additions are shown rather than dropped.
+ */
+export declare function planTableRows(table: PlanTable): {
+    headers: string[];
+    rows: string[][];
+};
+/** The promotion as a sentence, or null when there is none. */
+export declare function planPromotionLine(table: PlanTable): string | null;
+/** The table as Markdown: what the MCP tool returns beside the JSON, and what the docs embed. */
+export declare function planTableMarkdown(table: PlanTable): string;
+//# sourceMappingURL=plans.d.ts.map

package/dist/plans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plans.d.ts","sourceRoot":"","sources":["../src/plans.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,UAAU,CAAA;AAE1D,yFAAyF;AACzF,MAAM,WAAW,SAAS;IACxB,gBAAgB,EAAE,MAAM,CAAA;IACxB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,qGAAqG;AACrG,MAAM,WAAW,UAAU;IACzB,eAAe,EAAE,MAAM,CAAA;IACvB,cAAc,EAAE,MAAM,CAAA;IACtB,aAAa,EAAE,MAAM,CAAA;IACrB,0DAA0D;IAC1D,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,iBAAiB,EAAE,OAAO,CAAA;IAC1B,sFAAsF;IACtF,kBAAkB,EAAE,OAAO,CAAA;IAC3B,eAAe,EAAE,OAAO,CAAA;IACxB,iBAAiB,EAAE,OAAO,CAAA;IAC1B,UAAU,EAAE,OAAO,CAAA;IACnB,YAAY,EAAE,OAAO,CAAA;IACrB,mBAAmB,EAAE,OAAO,CAAA;IAC5B,mBAAmB,EAAE,OAAO,CAAA;IAC5B,kIAAkI;IAClI,gBAAgB,EAAE,OAAO,CAAA;IACzB,WAAW,EAAE,OAAO,CAAA;IACpB,iCAAiC;IACjC,KAAK,EAAE,OAAO,CAAA;IACd,+IAA+I;IAC/I,iBAAiB,EAAE,OAAO,CAAA;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAA;IACd;;;OAGG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAA;IAC/B,2FAA2F;IAC3F,MAAM,EAAE,MAAM,CAAA;IACd,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAA;IAClB,4FAA4F;IAC5F,KAAK,EAAE,SAAS,GAAG,IAAI,CAAA;IACvB,MAAM,EAAE,UAAU,CAAA;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,cAAc,EAAE,CAAA;IACvB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,iCAAiC;AACjC,MAAM,WAAW,gBAAiB,SAAQ,SAAS;IACjD,OAAO,EAAE,IAAI,CAAA;CACd;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,ibAC+Y,CAAA;AAEhb,0EAA0E;AAC1E,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,gBAAgB,EAAE,MAAM,CAazE,CAAA;AAID,mEAAmE;AACnE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjD;AAWD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAA;CAAE,CA+BvF;AAED,+DAA+D;AAC/D,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAIjE;AAED,iGAAiG;AACjG,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAI1D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@candledottv/agent-sdk",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "TypeScript SDK for the Candle agent rail: typed headless launches, market reads, and webhook verification",
   "type": "module",
   "main": "./dist/index.js",