@candledottv/mcp 0.8.0 → 0.9.1

package/dist/index.js

@@ -106,7 +106,7 @@ function percentOfBalance(balanceRaw, percent) {
 import { randomUUID } from "node:crypto";
 
 // src/version.ts
-var SERVER_VERSION = "0.8.0";
+var SERVER_VERSION = "0.9.1";
 
 // src/update-notice.ts
 var PLAIN_VERSION = /^\d+\.\d+\.\d+$/;
@@ -224,6 +224,23 @@ async function readMarket(mint, cfg, doFetch, extra) {
     return { status: res.status, err: relayRead(text, extra) };
   return { market: JSON.parse(text).market ?? {} };
 }
+function isPaperFlag(value) {
+  return value === true || value === "true" || value === 1 || value === "1";
+}
+function heldPaperPosition(positions, mint) {
+  return positions.find((p) => p.mint === mint && p.amountRaw !== "0");
+}
+async function readPaperInventory(cfg, doFetch, extra) {
+  const res = await doFetch(`${base(cfg)}/api/v1/trade/agent/paper/inventory`, {
+    method: "GET",
+    headers: headers(cfg.apiKey)
+  });
+  const text = await res.text();
+  if (!res.ok)
+    return { err: relayRead(text, extra) };
+  const body = JSON.parse(text);
+  return { positions: body.positions ?? [] };
+}
 async function executeTrade(args, cfg, doFetch) {
   const apiKey = requireApiKey(cfg);
   const clientTradeId = args.clientTradeId ?? randomUUID();
@@ -237,7 +254,8 @@ async function executeTrade(args, cfg, doFetch) {
     return errText("percent is only valid on sells; buys take a quote-asset amount", { clientTradeId });
   }
   let amountRaw;
-  let resolved;
+  let resolved = {};
+  let paper = isPaperFlag(args.paper);
   try {
     if (args.side === "buy") {
       const amount = args.amount;
@@ -264,17 +282,36 @@ async function executeTrade(args, cfg, doFetch) {
       resolved = { amountDecimal: amount, decimals, amountRaw };
     } else if (args.amount !== undefined) {
       const read = await readMarket(args.mint, cfg, doFetch, { clientTradeId });
-      if (!("market" in read))
+      let decimals;
+      if ("market" in read) {
+        if (typeof read.market.decimals !== "number") {
+          return errText(`could not resolve decimals for mint ${args.mint}; pass a raw-ready amount via the SDK instead`, { clientTradeId });
+        }
+        decimals = read.market.decimals;
+      } else if (read.status === 404) {
+        const inventory = await readPaperInventory(cfg, doFetch, { clientTradeId });
+        if ("err" in inventory) {
+          return paper ? inventory.err : read.err;
+        }
+        const held = heldPaperPosition(inventory.positions, args.mint);
+        if (typeof held?.tokenDecimals !== "number") {
+          if (paper) {
+            return errText(`could not resolve decimals for mint ${args.mint}; no Candle market and no paper position with a known scale. Buy it in paper first, or pass a raw amount via the SDK`, { clientTradeId });
+          }
+          return read.err;
+        }
+        decimals = held.tokenDecimals;
+        paper = true;
+      } else {
         return read.err;
-      const decimals = read.market.decimals;
-      if (typeof decimals !== "number") {
-        return errText(`could not resolve decimals for mint ${args.mint}; pass a raw-ready amount via the SDK instead`, { clientTradeId });
       }
       const converted = rawOrError(args.amount, decimals, { clientTradeId });
       if ("err" in converted)
         return converted.err;
       amountRaw = converted.raw;
       resolved = { amountDecimal: args.amount, decimals, amountRaw };
+    } else if (paper) {
+      resolved = { percent: args.percent };
     } else {
       const percent = args.percent;
       const walletsRes = await doFetch(`${base(cfg)}/api/v1/agent/wallets/embedded`, {
@@ -287,23 +324,37 @@ async function executeTrade(args, cfg, doFetch) {
       const walletsBody = JSON.parse(walletsText);
       const chain = chainForMint(args.mint);
       const address = chain === "hood" ? walletsBody.wallets?.evm?.address : walletsBody.wallets?.solana?.address;
+      let walletEmpty;
       if (!address) {
-        return errText(`percent sells need an embedded ${chain === "hood" ? "EVM" : "Solana"} wallet, and this account has none`, { clientTradeId });
+        walletEmpty = errText(`percent sells need an embedded ${chain === "hood" ? "EVM" : "Solana"} wallet, and this account has none`, { clientTradeId });
+      } else {
+        const balRes = await doFetch(`${base(cfg)}/api/v1/tokens/${encodeURIComponent(args.mint)}/balance/${encodeURIComponent(address)}`, {
+          method: "GET",
+          headers: headers()
+        });
+        const balText = await balRes.text();
+        if (!balRes.ok)
+          return relayRead(balText, { clientTradeId });
+        const balBody = JSON.parse(balText);
+        const balance = balBody.payload?.balance;
+        if (balance) {
+          amountRaw = percentOfBalance(balance, percent);
+          resolved = { percent, balanceRaw: balance, amountRaw };
+        } else {
+          walletEmpty = errText(`the embedded wallet ${address} holds no ${args.mint}; nothing to sell`, {
+            clientTradeId
+          });
+        }
       }
-      const balRes = await doFetch(`${base(cfg)}/api/v1/tokens/${encodeURIComponent(args.mint)}/balance/${encodeURIComponent(address)}`, {
-        method: "GET",
-        headers: headers()
-      });
-      const balText = await balRes.text();
-      if (!balRes.ok)
-        return relayRead(balText, { clientTradeId });
-      const balBody = JSON.parse(balText);
-      const balance = balBody.payload?.balance;
-      if (!balance) {
-        return errText(`the embedded wallet ${address} holds no ${args.mint}; nothing to sell`, { clientTradeId });
+      if (walletEmpty) {
+        const inventory = await readPaperInventory(cfg, doFetch, { clientTradeId });
+        if (!("err" in inventory) && heldPaperPosition(inventory.positions, args.mint)) {
+          paper = true;
+          resolved = { percent };
+        } else {
+          return walletEmpty;
+        }
       }
-      amountRaw = percentOfBalance(balance, percent);
-      resolved = { percent, balanceRaw: balance, amountRaw };
     }
   } catch (err) {
     return errText(err instanceof Error ? err.message : String(err), { clientTradeId });
@@ -312,10 +363,11 @@ async function executeTrade(args, cfg, doFetch) {
     clientTradeId,
     mint: args.mint,
     side: args.side,
-    amountRaw,
+    ...amountRaw !== undefined ? { amountRaw } : { percent: args.percent },
     payer: { type: "main" },
     ...args.quoteAsset !== undefined ? { quoteAsset: args.quoteAsset } : {},
-    ...args.maxSlippageBps !== undefined ? { maxSlippageBps: args.maxSlippageBps } : {}
+    ...args.maxSlippageBps !== undefined ? { maxSlippageBps: args.maxSlippageBps } : {},
+    ...paper ? { paper: true } : {}
   }, doFetch);
   if ("thrown" in posted)
     return transportError("clientTradeId", clientTradeId, posted.thrown);
@@ -749,10 +801,11 @@ var tradeShape = {
   mint: z.string().describe("Token mint (solana) or contract address (hood)"),
   side: z.enum(["buy", "sell"]),
   amount: z.string().optional().describe("Decimal amount. Buys: how much of THIS TOKEN'S OWN quote asset to spend (SOL for a " + 'SOL-launched token, USDC for a USDC-quoted one, and so on: e.g. "0.5"). Sells: how many ' + "TOKENS to sell. Pass exactly one of amount or percent."),
-  percent: z.number().optional().describe("Sells only: sell this percent (integer 1-100) of the wallet's holding, on either chain."),
+  percent: z.number().optional().describe("Sells only: sell this percent (integer 1-100) of the holding. Live trades size against the " + "embedded wallet. Paper trades (`paper: true`) size against this key's paper inventory -- " + "the position a previous paper buy credited -- because paper never moves the live wallet."),
   quoteAsset: z.string().optional().describe('What the wallet spends on a buy or receives on a sell: "sol", "usdc" or "cndl" on Solana, ' + '"eth" or "usdg" on Hood. Safe to pass through from candle_quote. On Solana it applies only ' + "to an arbitrary mint Candle never launched (Pro/Max) and is ignored for a Candle token, " + "whose quote comes from the token itself. On Hood it is the settlement asset of a DEX " + "trade; a USDG buy adds an approval transaction an ETH buy does not. It is not the route: " + "the cheapest path to the asset is chosen separately. Defaults to sol / ETH settlement."),
   maxSlippageBps: z.number().optional().describe("Max slippage in basis points; API default applies when omitted"),
-  clientTradeId: z.string().optional().describe("Idempotency key. Auto-generated when omitted and echoed in the result. Retrying with the " + "SAME id is safe (idempotent replay); a new id is a SECOND trade.")
+  clientTradeId: z.string().optional().describe("Idempotency key. Auto-generated when omitted and echoed in the result. Retrying with the " + "SAME id is safe (idempotent replay); a new id is a SECOND trade."),
+  paper: z.preprocess((value) => value === "true" || value === 1 || value === "1" ? true : value === "false" || value === 0 || value === "0" ? false : value, z.boolean().optional().describe("Rehearse instead of trading. The request passes every admission rule a live trade passes " + "-- the same planner, spend gate, key cap and loss limits -- and records the quote, but " + "nothing is ever broadcast and no funds move. Use it to check that a strategy is admitted " + "before risking anything on it. A paper fill is optimistic by construction: it books the " + "quoted price, so the gap between a paper arm and a live one IS the execution cost. " + "A sell of a mint this key already paper-bought also closes that paper book when the " + "live wallet is empty, even if this flag is omitted."))
 };
 var { buyAmount: _rawBuyAmount, ...seedableLaunchShape } = launchTokenShape;
 var launchAndSeedShape = {
@@ -795,9 +848,9 @@ function registerTools(server, env = process.env) {
   }, async (args) => callAndRelay("candle_get_market", args, cfg));
   register("candle_token_forensics", {
     title: "Token forensics",
-    description: `Gate a buy before making it: deployer history, who bought in the deploy window (the creator's own wallets are marked disclosed; strangers in the same slot are the bundle signal), holder concentration, and a risk tier (LOW/MODERATE/HIGH/CRITICAL) with per-factor reasons. Every measurement carries a coverage note -- 'unavailable' is not 'clean'. No key needed.
+    description: `Gate a buy before making it: who launched it (resolved on-chain; pump.fun's shared updateAuthority is never the developer), their went-to-zero rate and last coins, who bought in the deploy window (the creator's own wallets are marked disclosed; strangers in the same slot are the bundle signal), holder concentration, same-funder insider share, same-funder deployer cluster, and a risk tier (LOW/MODERATE/HIGH/CRITICAL) with per-factor reasons. Every measurement carries a coverage note -- 'unavailable' is not 'clean'. No key needed.
 
-MARKET_NOT_FOUND means Candle has no market for that token and this could not run. That is also not 'clean': report that you could not check it, rather than reporting the token as safe. That refusal now carries error.coverage -- covered:false, a reason ('external_launchpad' when the token launched somewhere else, 'unknown_mint' when nobody has indexed it), the launchpad when known, and every check that consequently did not run. Read it instead of guessing. Most of the feed answers this way.`,
+MARKET_NOT_FOUND means Candle has no market for that token and this could not run. That is also not 'clean': report that you could not check it, rather than reporting the token as safe. That refusal now carries error.coverage -- covered:false, a reason ('external_launchpad' when the token launched somewhere else, 'unknown_mint' when nobody has indexed it), the launchpad when known, and every check that consequently did not run. Read it instead of guessing. Most of the feed now answers with a partial report instead.`,
     inputSchema: tokenForensicsShape
   }, async (args) => callAndRelay("candle_token_forensics", args, cfg));
   register("candle_get_feed", {
@@ -911,6 +964,8 @@ MARKET_NOT_FOUND means Candle has no market for that token and this could not ru
 
 ` + "Arguments: `mint` and `side` are required. Amounts are DECIMAL, never raw base units " + '(amount: "0.5", not lamports). Omitting the amount on a sell sells the whole ' + `position.
 
+` + "Pass `paper: true` to rehearse: every admission rule runs and the quote is recorded, but " + "nothing broadcasts and no funds move. A paper buy credits this key's paper inventory, " + "including for external Solana mints routed through Jupiter. A later sell by amount or " + "percent closes that book without reading the live wallet and without MARKET_NOT_FOUND " + "-- including when `paper` is omitted on the exit, as long as the paper position exists. " + "Do this before the first live trade of a new strategy, and whenever you are unsure a " + `trade would be admitted at all.
+
 ` + `After the call:
 ` + "- A timeout is not a failure. Retry with the SAME clientTradeId from the result -- it " + `coalesces the duplicate. A NEW id is a SECOND trade, and that is how you double-spend.
 ` + "- If you no longer hold the result, do not re-send to find out what happened. Ask " + "candle_get_operation with the clientTradeId; a 404 there means the trade never reached " + "the rail and nothing moved.",
@@ -936,16 +991,19 @@ START HERE — five tools need NO credential. Call these first to confirm the se
   candle_get_market       price, market cap, volume, curve state for one token
   candle_get_feed         the roster: hot streak, new pairs, graduated, blue chip
   candle_resolve_token    a ticker or partial name -> mint address + chain
-  candle_token_forensics  call this before quoting or buying, whenever the token has a Candle market. Returns deployer history, who bought in the deploy window (strangers in the same slot are the bundle signal), holder concentration, and a risk tier LOW/MODERATE/HIGH/CRITICAL with per-factor reasons
+  candle_token_forensics  call this before quoting or buying. Returns the on-chain developer (never a launchpad shared authority), their went-to-zero rate and last coins, who bought in the deploy window (strangers in the same slot are the bundle signal), holder concentration, same-funder insider share, same-funder cluster, and a risk tier LOW/MODERATE/HIGH/CRITICAL with per-factor reasons
   candle_get_agent_profile  your own tier, caps and verified activity
 
 COVERAGE — read this before you treat an error as a broken server.
 candle_get_feed indexes the wider market (pump.fun, pons.family and other external launchpads).
-candle_get_market and candle_token_forensics answer for tokens that have a CANDLE market. So a
-mint that candle_get_feed just returned can still come back MARKET_NOT_FOUND from those two, and
-that is a coverage boundary, not a fault and not a reason to retry, re-auth, or tell the human the
-integration is down. Report it as "Candle has no market for this token, so I could not run
-forensics on it" and let the human decide.
+candle_get_market answers for tokens that have a CANDLE market. candle_token_forensics also
+answers for Solana tokens the feed already knows, with a partial report: on-chain developer
+(never a launchpad shared authority), went-to-zero record, holder concentration, same-funder
+insiders and cluster. Deploy-window stays unavailable without a Candle launch record. Hood
+tokens Candle did not launch, and unknown mints, still come back MARKET_NOT_FOUND. That is a
+coverage boundary, not a fault and not a reason to retry, re-auth, or tell the human the
+integration is down. Report MARKET_NOT_FOUND as "Candle has no market for this token, so I
+could not run forensics on it" and let the human decide.
 
 Never let a MARKET_NOT_FOUND stand in for a clean bill of health. The same rule governs the
 coverage note on every forensics measurement: "unavailable" is NOT "clean" — say so rather than

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@candledottv/mcp",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "MCP server for the Candle agent rail: launch tokens, read markets, report activity",
   "type": "module",
   "license": "MIT",