@candledottv/mcp 0.10.15 → 0.10.17

package/README.md

@@ -55,6 +55,12 @@ Both take decimal amounts, never raw base units, and resolve the scale themselve
   there the caller genuinely picks the new token's quote pair: `quoteAsset` if given, otherwise
   SOL on Solana and ETH on Hood.
 
+Both launch tools also take `mode: "exp-custom"` with `curve: { virtualQuote, threshold }`: a
+Solana curve with your own V and G, in whole SOL or CNDL as decimal strings, inside limits the
+API enforces and each tool's description states. Dry-run first: the dry run returns the curve's
+terms. It works only where the deployment has switched it on. See
+[Custom curves](https://docs.candle.tv/developers/headless-launch#custom-curves-choose-v-and-g-switched-off).
+
 For a full walkthrough of `candle_launch_and_seed` and `candle_trade`, including the keyless read
 tools, getting a key, funding the embedded wallet, and idempotent retries, see
 [Candle MCP server](https://docs.candle.tv/developers/mcp-server).
@@ -120,7 +126,7 @@ tools, getting a key, funding the embedded wallet, and idempotent retries, see
 | `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` |
 | `candle_get_fees` | The creator fees the account's launched tokens can pay: raw amounts from chain reads, and the reason a token cannot be claimed | `GET /api/v1/agent/fees` | `CANDLE_AGENT_API_KEY` (`account:read`) |
-| `candle_claim_fees` | Collect one token's creator fees to the wallet fixed at launch (no destination argument); `dryRun` sends nothing. Answers `LAUNCH_DISABLED` until the server enables agent claims | `POST /api/v1/agent/fees/:mint/claim` | `CANDLE_AGENT_API_KEY` (`launch:write`) |
+| `candle_claim_fees` | Collect one token's creator fees to the wallet fixed at launch (no destination argument); `dryRun` sends nothing | `POST /api/v1/agent/fees/:mint/claim` | `CANDLE_AGENT_API_KEY` (`launch:write`) |
 | `candle_get_staking` | Read CNDL/sCNDL, withdrawals, rewards, pool wait and wallet eligibility notes | `GET /api/v1/agent/staking` |
 | `candle_stake` | Stake raw CNDL; stable clientStakeId, dryRun first | `POST /api/v1/agent/staking/stake/build` |
 | `candle_unstake` | Start a withdrawal of raw sCNDL; no instant unstake | `POST /api/v1/agent/staking/unstake/build` |
@@ -307,8 +313,9 @@ the section and its coverage fields. Agent boards are outside this slice.
 
 Solana staking is available through the agent rail while the deployment enables it (off by
 default). There is no instant unstake. Read the pool wait and wallet eligibility notes first:
-pending withdrawal CNDL counts toward nothing for Pro; outside the primary wallet sCNDL earns
-Solana rewards but no Hood rewards, and Pro follows the served tier mode.
+pending withdrawal CNDL counts toward nothing for Pro; sCNDL in any eligible account wallet
+counts toward Pro and earns the account's Hood reward, except a wallet another account also
+claims, wallets past the 200-wallet cap, and an account with no EVM wallet.
 
 Tools: `candle_get_staking`, `candle_stake`, `candle_unstake`, `candle_finish_unstake`,
 `candle_claim_staking_reward`. Build tools accept stable `clientStakeId`, raw `amountRaw`

package/dist/index.js

@@ -57,6 +57,45 @@ function assertTransportSecurity(apiUrl, env) {
     return;
   throw new Error(`Refusing to send credentials in the clear to ${parsed.origin}. Set CANDLE_API_URL to an https:// ` + (isPrivateHost(parsed.hostname) ? "URL, or set CANDLE_ALLOW_INSECURE_HTTP=1 if this really is a trusted local endpoint." : "URL. CANDLE_ALLOW_INSECURE_HTTP does not apply here: it covers private networks only, " + "and this is a public address."));
 }
+var REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+var MAX_REDIRECTS = 5;
+
+class CrossOriginRedirectError extends Error {
+  from;
+  to;
+  constructor(from, to) {
+    super(`The API at ${from} redirected to ${to}, another origin. Not followed, so the API key was not sent there.`);
+    this.from = from;
+    this.to = to;
+    this.name = "CrossOriginRedirectError";
+  }
+}
+function keyedRedirectGuard(doFetch) {
+  return async (url, init) => {
+    if (!init?.headers || !new Headers(init.headers).has("x-api-key"))
+      return doFetch(url, init);
+    let current = url;
+    let next = { ...init, redirect: "manual" };
+    for (let hops = 0;; hops++) {
+      const response = await doFetch(current, next);
+      const headers = response.headers;
+      const location = REDIRECT_STATUSES.has(response.status) ? headers?.get?.("location") : null;
+      if (!location)
+        return response;
+      const from = new URL(current);
+      const target = new URL(location, from);
+      if (target.origin !== from.origin)
+        throw new CrossOriginRedirectError(from.origin, target.origin);
+      if (hops >= MAX_REDIRECTS)
+        throw new Error(`More than ${MAX_REDIRECTS} redirects from ${url}`);
+      const method = (next.method ?? "GET").toUpperCase();
+      if (response.status === 303 && method !== "GET" && method !== "HEAD" || (response.status === 301 || response.status === 302) && method === "POST") {
+        next = { ...next, method: "GET", body: undefined };
+      }
+      current = target.href;
+    }
+  };
+}
 function resolveConfig(env = process.env) {
   const apiUrl = env.CANDLE_API_URL?.trim() || DEFAULT_API_URL;
   assertTransportSecurity(apiUrl, env);
@@ -112,7 +151,7 @@ import { lstat, open, realpath } from "node:fs/promises";
 import { dirname, isAbsolute, relative, sep } from "node:path";
 
 // src/version.ts
-var SERVER_VERSION = "0.10.15";
+var SERVER_VERSION = "0.10.17";
 
 // src/update-notice.ts
 var PLAIN_VERSION = /^\d+\.\d+\.\d+$/;
@@ -796,6 +835,10 @@ var HYPERLIQUID_EXCHANGE_URLS = {
   mainnet: "https://api.hyperliquid.xyz/exchange",
   testnet: "https://api.hyperliquid-testnet.xyz/exchange"
 };
+var HYPERLIQUID_INFO_URLS = {
+  mainnet: "https://api.hyperliquid.xyz/info",
+  testnet: "https://api.hyperliquid-testnet.xyz/info"
+};
 var CANDLE_HYPERLIQUID_BUILDER_ADDRESS = null;
 var HYPERLIQUID_MAX_BUILDER_FEE_TENTHS_BPS = 100;
 var HYPERLIQUID_MAX_BUILDER_FEE_RATE = "0.1%";
@@ -1101,6 +1144,67 @@ async function hyperliquidCloseOrder(fetcher, network, address, params) {
   const size = asked < held ? String(params.size) : String(szi).replace(/^-/, "");
   return { asset, isBuy: signed < 0n, size };
 }
+var HYPERLIQUID_DEFAULT_SLIPPAGE_BPS = 100;
+var HYPERLIQUID_MID_DRIFT_BPS = 100;
+async function hyperliquidOrderMarket(fetcher, network, address, method, params) {
+  const read = async (body) => {
+    const res = await fetcher(HYPERLIQUID_INFO_URLS[network], {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok)
+      throw new Error("Cannot read the market from Hyperliquid");
+    return JSON.parse(await res.text());
+  };
+  let coin = String(params.coin ?? "").toUpperCase();
+  let order;
+  if (method === "modify") {
+    const status = await read({ type: "orderStatus", user: address, oid: params.cloid });
+    const resting = status?.order?.order ?? null;
+    if (!resting || typeof resting.coin !== "string" || decimal(resting.limitPx) === null)
+      throw new Error("No resting order with this cloid on Hyperliquid");
+    coin = resting.coin.toUpperCase();
+    order = { isBuy: resting.side === "B", limitPx: String(resting.limitPx) };
+  }
+  const [meta, contexts] = await read({ type: "metaAndAssetCtxs" });
+  const asset = meta.universe.findIndex((m) => m.name.toUpperCase() === coin);
+  if (asset < 0 || asset >= 1e4)
+    throw new Error("No main-universe market for this coin on Hyperliquid");
+  const context = contexts[asset];
+  const midPx = context?.midPx ?? context?.markPx;
+  if ((decimal(midPx) ?? 0n) <= 0n)
+    throw new Error("No Hyperliquid price for this coin");
+  return { asset, midPx: String(midPx), ...order ? { order } : {} };
+}
+function checkOrderMarket(action, intent, market) {
+  const list = action.type === "modify" ? [action.order] : action.orders;
+  if (!Array.isArray(list) || list.length === 0)
+    return "missing requested order";
+  if (list.some((o) => !o || o.a !== market.asset))
+    return "order asset is not the requested coin's on Hyperliquid";
+  const first = list[0];
+  const p = intent.params;
+  if (intent.method === "open" && p.price == null) {
+    const requested = p.slippageBps;
+    const slippage = typeof requested === "number" && Number.isInteger(requested) && requested > 0 ? requested : HYPERLIQUID_DEFAULT_SLIPPAGE_BPS;
+    const bound = BigInt(slippage + HYPERLIQUID_MID_DRIFT_BPS);
+    const px = decimal(first.p) ?? 0n;
+    const mid = decimal(market.midPx) ?? 0n;
+    const within = first.b === true ? px * 10000n <= mid * (10000n + bound) : px * 10000n >= mid * (10000n - bound);
+    if (mid <= 0n || !within)
+      return "market order price is outside its slippage of Hyperliquid's mid";
+  }
+  if (intent.method === "modify") {
+    if (!market.order)
+      return "no resting order on Hyperliquid to check the modify against";
+    if (first.b !== market.order.isBuy)
+      return "modify changes the resting order's side";
+    if (p.price == null && decimal(first.p) !== decimal(market.order.limitPx))
+      return "modify changes the resting order's price";
+  }
+  return null;
+}
 function verifyPerpsBuild(build, opts) {
   try {
     const network = opts.network ?? "mainnet";
@@ -1128,6 +1232,13 @@ function verifyPerpsBuild(build, opts) {
       if (!order || order.a !== opts.closeOrder.asset || order.b !== opts.closeOrder.isBuy || decimal(order.s) !== decimal(opts.closeOrder.size) || order.r !== true)
         return { ok: false, reason: "close side, asset or size does not match the requested position" };
     }
+    if (opts.market) {
+      if (opts.intent?.method !== "open" && opts.intent?.method !== "modify")
+        return { ok: false, reason: "a market check needs an open or modify intent" };
+      const marketRefusal = checkOrderMarket(action, opts.intent, opts.market);
+      if (marketRefusal)
+        return { ok: false, reason: marketRefusal };
+    }
     if (typed.primary_type === "Agent") {
       const type = action.type;
       if (typeof type !== "string" || !HYPERLIQUID_ALLOWED_ACTION_TYPES.includes(type)) {
@@ -1345,6 +1456,18 @@ async function executePerps(tool, args, cfg, env, fetch2) {
       if (!closeCheck.ok)
         return fail("PERPS_BUILD_REFUSED", `Refused to sign this build: ${closeCheck.reason}. Nothing was signed.`);
     }
+    if (method === "open") {
+      const market = await hyperliquidOrderMarket(fetch2, network, row.address, method, fields);
+      const marketCheck = verifyPerpsBuild(build, {
+        builder,
+        network,
+        address: row.address,
+        intent: { method, params: fields },
+        market
+      });
+      if (!marketCheck.ok)
+        return fail("PERPS_BUILD_REFUSED", `Refused to sign this build: ${marketCheck.reason}. Nothing was signed.`);
+    }
     if (!willSubmit || signerPem === null)
       return { text: JSON.stringify({ ...build, signed: false, submitted: false }) };
     if (!appId || !row.privyWalletId)
@@ -1591,7 +1714,7 @@ var PLAN_CAPABILITY_LABELS = {
   createLinkedWallets: "Create linked wallets",
   importLinkedWallets: "Import linked wallets",
   limitOrders: "Limit orders",
-  quant: "Quant on Telegram"
+  quant: "Quant deep analyses (Max)"
 };
 var PLAN_LABELS = { free: "Free", believer: "Believer", pro: "Pro", max: "Max" };
 function planLabel(plan) {
@@ -1653,8 +1776,9 @@ function planTableMarkdown(table) {
 
 // src/tools.ts
 var VAMP_CANDIDATES_DESCRIPTION = "Lists Solana tokens that are close to graduating or graduated in the last 6 hours whose ticker other tokens " + "are copying, most-copied in the last 24 hours first. Each entry carries a launch draft (name, ticker, image URL) " + "for `candle_launch_token` or `candle_launch_and_seed`; draft notes identify fields you must supply or adjust. " + "Upload your own image through the agent image upload when the image is unavailable. Use `dryRun: true` first. " + "Counts exclude the candidate itself and cover both Solana and Hood launches at the venues returned in " + "`coverage`, not Candle's own. `coverage.since` is the returned Solana coverage date; Hood history may differ.";
+var CUSTOM_CURVE_RULE = 'mode "exp-custom" with curve { virtualQuote, threshold } launches a Solana curve with your own V (the virtual ' + "quote it starts with) and G (the quote it raises before graduating), in whole SOL or CNDL as decimal strings, " + "accepted when V is 1 to 100 SOL and G 1 to 250 SOL (66,000 to 6,600,000 and 66,000 to 16,500,000 CNDL), when " + "every price up to 20 x G stays under the ceiling (V + 20G)^2 < V x X at this stakerAllocationBps, when neither " + "is finer than the quote's decimals, and when the dev buy is at most 10% of G; a curve past a limit is " + "CURVE_OUT_OF_RANGE, and at the ceiling it carries maxThresholdRaw, the largest G that fits. " + "Dry-run it first (dryRun: true): the dry run spends nothing and returns curveTerms, the market cap at start and " + "at graduation and the supply sold by graduation. Only where the API has EXP_CUSTOM_CURVES on; " + "elsewhere exp-custom is refused as an unknown mode.";
 var localProfileTools = new WeakMap;
-var STAKING_DISCLOSURE = "No instant unstake. Read pool.withdrawalTimelockSeconds for the wait. Solana rewards accrue to the holding wallet. Outside the account's main wallet, sCNDL earns no Hood staking rewards; Pro eligibility follows the deployment's tier mode (main-wallet mode excludes it). CNDL in a pending withdrawal counts toward nothing for Pro.";
+var STAKING_DISCLOSURE = "No instant unstake. Read pool.withdrawalTimelockSeconds for the wait. Solana rewards accrue to the holding wallet. sCNDL in any eligible account wallet counts toward Pro and earns the account's Hood staking reward, except a wallet another account also claims, wallets past the 200-wallet cap, and an account with no EVM wallet. CNDL in a pending withdrawal counts toward nothing for Pro.";
 var stakingWriteShape = {
   payer: z2.enum(["main", "linked"]).optional().describe("main is the embedded wallet; linked names a linked or TEE wallet"),
   linkedWalletId: z2.string().min(1).optional(),
@@ -2072,7 +2196,11 @@ var launchTokenShape = {
   bannerUrl: z2.string().optional().describe("Optional https URL to WIDE artwork for the token page's banner strip (wider than 1.5:1, " + "e.g. 1200x630). This is where a share card or OG image belongs. A square image here is " + "rejected with BANNER_WRONG_SHAPE. Omit it and the strip falls back to imageUrl"),
   chain: z2.string().optional().describe('"solana" or "hood"; defaults to solana'),
   quoteAsset: z2.string().optional().describe("Quote asset symbol; defaults per chain"),
-  mode: z2.string().optional().describe('"open" or "exclusive"; defaults to open. "test-open" / "test-exclusive" launch the ' + "low-threshold test curves (~1/80 economics) where the API has ENABLE_TEST_CURVES on"),
+  mode: z2.string().optional().describe('"open" or "exclusive"; defaults to open. "test-open" / "test-exclusive" launch the ' + "low-threshold test curves (~1/80 economics) where the API has ENABLE_TEST_CURVES on. " + '"exp-custom" launches a Solana curve with your own V and G, given in curve, where the API has it ' + "switched on"),
+  curve: z2.object({
+    virtualQuote: z2.string().describe('V: the virtual quote the curve starts with, in whole quote units, e.g. "12" SOL'),
+    threshold: z2.string().describe('G: the quote the curve raises before it graduates, in whole quote units, e.g. "40" SOL')
+  }).strict().optional().describe('mode "exp-custom" only, and required there. Decimal strings in whole units of the quote asset (sol or ' + "cndl), never raw units. Dry-run first: the API checks the limits and returns the curve's terms"),
   stakerAllocationBps: z2.number().optional().describe("Staker allocation in basis points"),
   dexVersion: z2.string().nullable().optional().describe('"v3" or "v4"; required for hood launches'),
   buyAmount: z2.union([z2.string(), z2.number()]).optional().describe("Initial buy, in quote base units (string or number)"),
@@ -2229,7 +2357,7 @@ function registerToolSubset(server, options) {
   const allowed = new Set(options.tools);
   const getConfig = options.getConfig;
   const env = options.env ?? {};
-  const doFetch = options.fetch ?? ((url, init) => fetch(url, init));
+  const doFetch = keyedRedirectGuard(options.fetch ?? ((url, init) => fetch(url, init)));
   const register = (name, definition, handler) => {
     if (!allowed.has(name))
       return;
@@ -2243,7 +2371,7 @@ function registerToolSubset(server, options) {
   const imageDir = configuredImageDir(env);
   register("candle_launch_token", {
     title: "Launch a token on Candle",
-    description: "Launch a new token via the Candle headless launch API, from the account's embedded wallet. Works on every plan, Free included. Set dryRun: true to validate without spending anything." + (imageDir ? IMAGE_PATH_DISCLOSURE : ""),
+    description: "Launch a new token via the Candle headless launch API, from the account's embedded wallet. Works on every plan, Free included. Set dryRun: true to validate without spending anything. " + CUSTOM_CURVE_RULE + (imageDir ? IMAGE_PATH_DISCLOSURE : ""),
     inputSchema: imageDir ? localLaunchTokenShape : launchTokenShape
   }, async (args) => {
     const image = await resolveLaunchImage(args, imageDir, getConfig(), doFetch);
@@ -2390,7 +2518,7 @@ MARKET_NOT_FOUND means Candle has no market for that token and this could not ru
   }, async (args) => callAndRelay("candle_get_fees", args, getConfig(), doFetch));
   register("candle_claim_fees", {
     title: "Claim a token's creator fees",
-    description: "Collect one token's creator fees and pay them to the wallet fixed at launch. There is no destination " + "argument and the tool cannot send funds anywhere else. Candle signs with the embedded wallet, which " + "pays the network fee. Needs launch:write, and the server keeps it off until it is enabled (LAUNCH_DISABLED). " + "Call it with dryRun: true first; a real claim moves real funds into the recipient wallet, which may be " + "the wallet this agent trades from. Not idempotent by id: if the result is lost, read candle_get_fees " + "before claiming again.",
+    description: "Collect one token's creator fees and pay them to the wallet fixed at launch. There is no destination " + "argument and the tool cannot send funds anywhere else. Candle signs with the embedded wallet, which " + "pays the network fee. Needs launch:write. " + "Call it with dryRun: true first; a real claim moves real funds into the recipient wallet, which may be " + "the wallet this agent trades from. Not idempotent by id: if the result is lost, read candle_get_fees " + "before claiming again.",
     inputSchema: claimFeesShape
   }, async (args) => callAndRelay("candle_claim_fees", args, getConfig(), doFetch));
   register("candle_get_wallets", {
@@ -2494,7 +2622,7 @@ MARKET_NOT_FOUND means Candle has no market for that token and this could not ru
   });
   register("candle_launch_and_seed", {
     title: "Launch a token and seed it",
-    description: "Launch a new token from the account's embedded wallet, with an optional dev-buy seed (in the " + "launch transaction on solana, a best-effort follow-up on hood). Works on every plan, Free included (this is not the atomic launch). Then " + "return the fresh market state and token links in one result. MOVES REAL FUNDS unless " + "dryRun. Seeds above the platform dev-buy ceiling are rejected (DEV_BUY_TOO_HIGH); " + "launch, then top up with candle_trade." + (imageDir ? IMAGE_PATH_DISCLOSURE : ""),
+    description: "Launch a new token from the account's embedded wallet, with an optional dev-buy seed (in the " + "launch transaction on solana, a best-effort follow-up on hood). Works on every plan, Free included (this is not the atomic launch). Then " + "return the fresh market state and token links in one result. MOVES REAL FUNDS unless " + "dryRun. Seeds above the platform dev-buy ceiling are rejected (DEV_BUY_TOO_HIGH); " + "launch, then top up with candle_trade. " + CUSTOM_CURVE_RULE + (imageDir ? IMAGE_PATH_DISCLOSURE : ""),
     inputSchema: imageDir ? localLaunchAndSeedShape : launchAndSeedShape
   }, async (args) => {
     const result = await executeLaunchAndSeed(args, getConfig(), doFetch, imageDir);
@@ -2556,7 +2684,7 @@ async function registerEligibleProfileTool(server, env = process.env, doFetch =
   let eligible = false;
   if (cfg.apiKey && wanted.length > 0) {
     try {
-      const res = await doFetch(`${cfg.apiUrl}/api/v1/agent/keys/self/public-profile`, {
+      const res = await keyedRedirectGuard(doFetch)(`${cfg.apiUrl}/api/v1/agent/keys/self/public-profile`, {
         method: "GET",
         headers: { "x-api-key": cfg.apiKey },
         signal: AbortSignal.timeout(15000)

package/package.json

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