@candledottv/mcp 0.9.1 → 0.10.1

package/README.md

@@ -85,7 +85,7 @@ tools, getting a key, funding the embedded wallet, and idempotent retries, see
 | `candle_launch_token` | Launch a token on Candle | `POST /api/v1/launch/headless` (or `/dry-run` when `dryRun: true`) | `CANDLE_AGENT_API_KEY` |
 | `candle_get_market` | Get market state | `GET /api/v1/markets/:chain/:mint` | none |
 | `candle_get_feed` | Get a token feed | `GET /api/v1/markets/feed?bucket=...` | none |
-| `candle_token_forensics` | Deployer history, deploy-window buyers, holder concentration, risk tier | `GET /api/v1/markets/:chain/:mint/forensics` | none |
+| `candle_token_forensics` | Deployer history, deploy-window buyers, sourced token safety flags | `GET /api/v1/markets/:chain/:mint/forensics` | none |
 | `candle_report_activity` | Report on-chain activity | `POST /api/v1/activity/report` | `CANDLE_AGENT_API_KEY` |
 | `candle_get_agent_profile` | Get an agent profile | `GET /api/v1/users/:idOrWallet/agent` | none |
 | `candle_trade` | Buy or sell a token | Reads the market for its decimals (or wallet balance, for a percent sell) then `POST /api/v1/trade/agent/build` | `CANDLE_AGENT_API_KEY` (`swap:write`) |
@@ -97,7 +97,7 @@ tools, getting a key, funding the embedded wallet, and idempotent retries, see
 | `candle_get_wallets` | The account's embedded wallets, one per chain, with delegation state | `GET /api/v1/agent/wallets/embedded` | `CANDLE_AGENT_API_KEY` |
 | `candle_get_profile_wallets` | Which wallets an agent profile may spend from, and whether it is scoped | `GET /api/v1/agent/keys/:prefix/wallets` | `CANDLE_AGENT_API_KEY` |
 | `candle_set_profile_wallets` | Replace the wallets an agent profile may spend from | `PUT /api/v1/agent/keys/:prefix/wallets` | `CANDLE_AGENT_API_KEY` |
-| `candle_get_profile_pnl` | An agent profile's realized P&L, fees, and open positions at cost basis | `GET /api/v1/agent/keys/:prefix/pnl` | `CANDLE_AGENT_API_KEY` |
+| `candle_get_profile_pnl` | An agent profile's realized P&L, fees, and open positions at cost basis, marked at current prices (unpriced positions counted, not zeroed) | `GET /api/v1/agent/keys/:prefix/pnl` | `CANDLE_AGENT_API_KEY` |
 | `candle_get_profile_trades` | An agent profile's orders, fills, fees and transaction hashes | `GET /api/v1/agent/keys/:prefix/trades` | `CANDLE_AGENT_API_KEY` |
 | `candle_execution_status` | One call before trading: wallets to spend from, tier, and whether trading is possible | Composes the wallet and tier reads | `CANDLE_AGENT_API_KEY` |
 | `candle_get_operation` | Look up a trade or launch by the id its write used, and whether it landed | `GET /api/v1/trade/agent/jobs/:clientId` or `/api/v1/launch/headless/jobs/:clientId` | `CANDLE_AGENT_API_KEY` |

package/dist/index.js

@@ -106,7 +106,7 @@ function percentOfBalance(balanceRaw, percent) {
 import { randomUUID } from "node:crypto";
 
 // src/version.ts
-var SERVER_VERSION = "0.9.1";
+var SERVER_VERSION = "0.10.1";
 
 // src/update-notice.ts
 var PLAIN_VERSION = /^\d+\.\d+\.\d+$/;
@@ -220,15 +220,24 @@ async function readMarket(mint, cfg, doFetch, extra) {
     headers: headers()
   });
   const text = await res.text();
-  if (!res.ok)
-    return { status: res.status, err: relayRead(text, extra) };
+  if (!res.ok) {
+    let reason;
+    try {
+      reason = JSON.parse(text)?.error?.routing?.reason;
+    } catch {}
+    return { status: res.status, err: relayRead(text, extra), reason };
+  }
   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");
+  const key = (value) => {
+    const trimmed = value.trim();
+    return /^0x[0-9a-fA-F]{40}$/.test(trimmed) ? trimmed.toLowerCase() : trimmed;
+  };
+  return positions.find((p) => key(p.mint) === key(mint) && p.amountRaw !== "0");
 }
 async function readPaperInventory(cfg, doFetch, extra) {
   const res = await doFetch(`${base(cfg)}/api/v1/trade/agent/paper/inventory`, {
@@ -261,13 +270,18 @@ async function executeTrade(args, cfg, doFetch) {
       const amount = args.amount;
       const read = await readMarket(args.mint, cfg, doFetch, { clientTradeId });
       let decimals;
-      if ("market" in read) {
+      if ("market" in read && (read.market.external === true || read.market.candleLaunched === false)) {
+        const q = quoteIdDecimals(args.quoteAsset, chainForMint(args.mint), { clientTradeId });
+        if ("err" in q)
+          return q.err;
+        decimals = q.decimals;
+      } else if ("market" in read) {
         const quoteDecimals = read.market.quoteDecimals;
         if (typeof quoteDecimals !== "number") {
           return errText(`could not resolve the quote decimals for mint ${args.mint}; a buy is denominated in that token's own quote asset and this market does not report its scale. Read the market with candle_get_market, then trade a raw amount via the SDK instead`, { clientTradeId });
         }
         decimals = quoteDecimals;
-      } else if (read.status === 404) {
+      } else if (read.status === 404 && read.reason !== "chain_mismatch") {
         const q = quoteIdDecimals(args.quoteAsset, chainForMint(args.mint), { clientTradeId });
         if ("err" in q)
           return q.err;
@@ -288,7 +302,7 @@ async function executeTrade(args, cfg, doFetch) {
           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) {
+      } else if (read.status === 404 && read.reason !== "chain_mismatch") {
         const inventory = await readPaperInventory(cfg, doFetch, { clientTradeId });
         if ("err" in inventory) {
           return paper ? inventory.err : read.err;
@@ -795,7 +809,7 @@ var swapShape = {
   amount: z.string().optional().describe('Decimal amount of `from` to spend, e.g. "0.5". Preferred. Pass exactly one of amount or amountRaw.'),
   amountRaw: z.string().optional().describe("Raw base units of `from`, as a positive integer string. Kept for callers that already " + "compute raw units; new callers should use `amount`."),
   maxSlippageBps: z.number().optional().describe("Slippage bound in bps, 0-10000. Server defaults to 100 (1%)"),
-  clientSwapId: z.string().optional().describe("Optional dedup key. Only coalesces a duplicate that arrives while the first call is still " + "in flight; one arriving after it settled will swap again")
+  clientSwapId: z.string().optional().describe("Durable idempotency key. Same id + same from/to/amountRaw/effective slippage (omitted means " + "100 bps) replays the stored result, including an indeterminate SWAP_FAILED with the " + "signature in the message. A different body is rejected. Omit it and nothing is coalesced. " + "Pass one so a timeout retry returns that stored result.")
 };
 var tradeShape = {
   mint: z.string().describe("Token mint (solana) or contract address (hood)"),
@@ -841,14 +855,12 @@ function registerTools(server, env = process.env) {
   }, async (args) => callAndRelay("candle_launch_token", args, cfg));
   register("candle_get_market", {
     title: "Get market state",
-    description: "Read the current market state for a token: lifecycle, pool address, whether buys are " + `open. Reads only; moves nothing. No key needed.
-
-` + "COVERAGE: this answers for tokens that have a CANDLE market. candle_get_feed indexes " + "the wider market too (pump.fun, pons.family), so a mint that feed just returned can " + "still come back MARKET_NOT_FOUND here. That is a coverage boundary, not a fault and " + "not a reason to retry or re-authenticate -- say Candle has no market for it and move on.",
+    description: "Read Candle and indexed external markets, including indexed-but-not-routable tokens. No key needed. " + "Read candleLaunched, launchpad, venue and trade.routable; jupiterOk and discovery flags are distinct. " + "Routability is stored eligibility, not a quote or permission. General quotes use POST /api/v1/trade/agent/quote. " + "Curve quotes and lifecycle describe Candle launches. MARKET_NOT_FOUND is a legacy code: read " + "error.routing.reason, error.discovery and sibling error.retryable. A curve-only 404 does not mean untradeable.",
     inputSchema: getMarketShape
   }, async (args) => callAndRelay("candle_get_market", args, cfg));
   register("candle_token_forensics", {
     title: "Token forensics",
-    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.
+    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), same-funder insider share, same-funder deployer cluster, and safety.summary with six sourced flags (mintAuthority, freezeAuthority, tokenExtensions, lpLock, sellability, liquidityDrain). Refuse an unprompted buy when flagged; incomplete or unknown is not clearance. launch.deployerLaunches is an inclusive informational count, never a warning. 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 now answers with a partial report instead.`,
     inputSchema: tokenForensicsShape
@@ -857,7 +869,7 @@ MARKET_NOT_FOUND means Candle has no market for that token and this could not ru
     title: "Get a token feed",
     description: "Read one of the trade page's public feeds: new, graduated, onfire, or bluechip. Reads " + `only; moves nothing. No key needed. Start here when nobody has named a token.
 
-` + "This indexes the WIDER market, not just Candle's own launches, so rows carry a " + "`launchpad` (pump.fun, pons.family, ...). A row appearing here does NOT mean Candle " + "has a market for it: candle_get_market and candle_token_forensics can legitimately " + `answer MARKET_NOT_FOUND for a mint this returned.
+` + "This indexes the WIDER market, not just Candle's own launches. Rows carry launchpad and " + "discovery flags (jupiterOk, externalTradeable, paperDiscoveryOk, organic0LiveOk). " + "candle_get_market resolves Jupiter-indexed rows; do not hard-skip organicScore=0 on live " + "when organic0LiveOk is true. liquidityDrawdownBps is a signal only — nothing here blocks " + `resolve or trade on drain; filter with where if you want to avoid draining pools.
 
 ` + "Filter, sort and pick fields SERVER-SIDE rather than reading the whole feed: an " + "unfiltered response is around 135KB and will not fit in a tool result. See `where`, " + "`sort` and `fields`.\n\n" + "One rule to know before screening on safety: a missing field is NOT a false one. " + "mintAuthorityDisabled and freezeAuthorityDisabled are absent on a real share of rows, " + "and absent means nobody checked, not that the authority is disabled. `where` never lets " + 'an absent field satisfy a comparison, so {"mintAuthorityDisabled":{"eq":true}} returns ' + "only tokens that actually say so.",
     inputSchema: getFeedShape
@@ -901,8 +913,8 @@ MARKET_NOT_FOUND means Candle has no market for that token and this could not ru
     inputSchema: setProfileWalletsShape
   }, async (args) => callAndRelay("candle_set_profile_wallets", args, cfg));
   register("candle_get_profile_pnl", {
-    title: "Read an agent profile's realized P&L",
-    description: "Realized profit for this profile's own fills, the Candle fees charged against it, and the " + "positions it still holds with their COST BASIS -- not their current value, which is not marked " + "here. Deposits, withdrawals and transfers are excluded: funding a wallet is not profit. Check " + "`unvalued` and `truncated` before quoting the number; they mean the total is partial. Reads only.",
+    title: "Read an agent profile's P&L",
+    description: "Realized profit for this profile's own fills, the Candle fees charged against it, and the " + "positions it still holds with their cost basis, each MARKED at Candle's current price where one " + "exists: `markPriceUsd`, `marketValueUsd` and `unrealizedUsd` per position, and `unrealizedUsd` " + "overall. A position with no price is counted in `unmarkedPositions` and left out of unrealized, " + "never valued at zero; `oldestMarkAt` says how old the marks are. Deposits, withdrawals and " + "transfers are excluded: funding a wallet is not profit. Check `unvalued` and `truncated` before " + "quoting the number; they mean the total is partial. Reads only.",
     inputSchema: profilePnlShape
   }, async (args) => callAndRelay("candle_get_profile_pnl", args, cfg));
   register("candle_get_profile_trades", {
@@ -935,7 +947,8 @@ MARKET_NOT_FOUND means Candle has no market for that token and this could not ru
 ` + `A bridge behaves differently and the difference matters:
 ` + `- It is several transactions, not one, and it takes time rather than settling on the call.
 ` + "- A confirmed source transaction is NOT proof the destination was credited. Read the " + "returned status before treating the funds as arrived; the response carries the venue's " + `own status URLs for the cross-chain fill.
-` + "- Do NOT re-send after a timeout. `clientSwapId` only coalesces a duplicate that arrives " + "while the first call is still in flight; once the first has settled, a second call with " + `the same id bridges AGAIN. If a bridge times out, check its status rather than retrying.
+` + "- A timeout is unknown, not failed. Pass a `clientSwapId` and retry the SAME request, " + "including the same slippage. The replay returns the stored result: the original success, " + "or a stored error. An indeterminate first leg comes back as SWAP_FAILED, retryable false, " + "with the signature in the message -- verify that on-chain before a new id. A swap that is " + "still running, with no stored outcome, is a retryable conflict. A different body under the " + "same id is rejected. A confirmed first leg is replayed with its hash, retryable false, and " + "is not run again. retryable true on the first LEG2_FAILED means send leg 2 as a new request. " + `Omitting the id never coalesces -- do not retry a timed-out call that had no id.
+` + "- If a bridge times out, check the returned status URLs rather than treating the funds " + `as arrived or lost.
 
 ` + 'Amounts are decimal (`amount`, e.g. "0.5"); `amountRaw` still accepts raw base units for ' + "callers that already compute them. Test-environment keys are refused: every leg settles " + "on a live venue.",
     inputSchema: swapShape
@@ -960,7 +973,7 @@ MARKET_NOT_FOUND means Candle has no market for that token and this could not ru
 ` + `Before the first trade of a run, once:
 ` + "1. candle_execution_status  -- confirms the wallets, the tier and this key's spend " + "limits. Call it at the start, or after an auth error; do not infer readiness from a " + `failed trade.
 ` + "2. candle_resolve_token  -- if a human handed you a bare address. It returns the chain, " + `so you never have to guess it.
-` + "3. candle_token_forensics  -- before you quote or buy anything. It returns a risk tier " + "and per-factor reasons. MARKET_NOT_FOUND there means Candle has no market for the " + `token, NOT that the token is clean.
+` + "3. candle_token_forensics  -- before you quote or buy anything. It returns safety.summary and sourced flags " + "with timestamps and details. Unknown is not clean. MARKET_NOT_FOUND there means Candle has no market for the " + `token, NOT that the token is clean.
 
 ` + "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.
 
@@ -991,19 +1004,30 @@ 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. 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_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), same-funder insider share, same-funder cluster, and safety.summary with six sourced flags. Refuse an unprompted buy when flagged; incomplete or unknown is not clearance. launch.deployerLaunches is an inclusive informational count, never a warning
   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 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.
+Feed rows carry jupiterOk / externalTradeable / paperDiscoveryOk / organic0LiveOk on external
+Solana mints. Use discovery=paper on candle_get_feed when rehearsing; on live screens do NOT
+hard-skip organicScore=0 when organic0LiveOk is true (visible m5 momentum). Hard-skip organic0
+only when organic0LiveOk is false.
+candle_get_market and candle_resolve_token answer for same-chain indexed external mints even
+when trade.routable is false. Read candleLaunched, launchpad, venue and trade; jupiterOk and
+paperDiscoveryOk are separate signals. Identity-only Solana reads have route_unverified.
+General quotes use POST /api/v1/trade/agent/quote; curve quotes/lifecycle describe Candle launches.
+Stored eligibility is not a successful quote or permission. MARKET_NOT_FOUND remains a legacy
+code: read error.routing.reason, error.discovery and sibling error.retryable. A curve-only
+404 is endpoint guidance, not a verdict that Candle cannot trade external tokens.
+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, token
+safety flags, same-funder insiders and cluster. Deploy-window stays unavailable without a
+Candle launch record. Indexed external Hood tokens also answer, with unknown hacc flags.
+Unknown mints can still come back MARKET_NOT_FOUND. That remaining gap 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.9.1",
+  "version": "0.10.1",
   "description": "MCP server for the Candle agent rail: launch tokens, read markets, report activity",
   "type": "module",
   "license": "MIT",