@candledottv/mcp 0.10.29 → 0.10.30

package/README.md

@@ -1,20 +1,22 @@
 # @candledottv/mcp
 
 An MCP (Model Context Protocol) server for the Candle agent rail. The current source exposes Candle's REST API as
-eighty-three tools over stdio, plus four Hyperliquid market reads (eighty-seven in all), so an MCP-capable agent can launch tokens (optionally seeded with a dev
+eighty-seven tools over stdio, plus four Hyperliquid market reads (eighty-eight in all), so an MCP-capable agent can launch tokens (optionally seeded with a dev
 buy in the same call), trade, convert between base assets (including across chains), read market
 and feed data, read one token's signals and tracked-wallet trades and its card data, report on-chain activity,
 check an agent profile, and backtest a strategy in hacc's strategy lab without hand-rolling HTTP calls. The five
 strategy lab tools are unreleased source.
 
+Not sure this is the right tool? [How to choose: SDK, MCP or CLI](https://docs.candle.tv/developers/choose-a-surface).
+
 ## Try it without a key
 
-Eighteen tools are read-only and need nothing but `CANDLE_API_URL` (which already defaults to
-production): `candle_get_market`, `candle_get_feed`, `candle_token_events`, `candle_token_card`, `candle_token_history`,
+Nineteen tools are read-only and need nothing but `CANDLE_API_URL` (which already defaults to
+production): `candle_get_market`, `candle_get_price_history`, `candle_get_feed`, `candle_token_events`, `candle_token_card`, `candle_token_history`,
 `candle_token_page_about`, `candle_token_page_burns`, `candle_token_page_history`, `candle_token_page_updates`, `candle_token_page_comments`, `candle_token_forensics`, `candle_token_clusters`,
 `candle_get_agent_profile`, `candle_list_agents`, `candle_list_agent_posts`, `candle_get_agent_positions`, `candle_resolve_token` and `candle_get_plans`.
-The five token-page reads, `candle_token_clusters` and `candle_token_history` are unreleased source; published 0.10.25 has the original ten, and `candle_get_agent_positions` is new in 0.10.27.
-With a source build and token-page reads enabled on the deployment, those eighteen work immediately without a key.
+All of them but `candle_get_price_history` (new in source, not yet published) are in the published 0.10.29; `candle_get_agent_positions` is new since 0.10.27.
+With token-page reads enabled on the deployment, those nineteen work immediately without a key.
 Install the released server with no `env` block at all and its ten public reads work immediately:
 
 ```json
@@ -34,8 +36,10 @@ Environment below -- or skip env editing entirely: install the Candle CLI
 `candle auth login`, and `candle mcp` launches this server with the stored key and API URL in its
 environment.
 
+To mint a key for another agent without keeping it as the CLI profile's working key, run `candle keys create --access write --label agent-one --no-store` after device login. The key is printed once; put it in the intended agent's secret store. `--json` reports `stored: false` and exits 0. The profile's existing working key, prefix and scopes stay unchanged, even when it has no working key. Add `--embedded-wallet allow` at a terminal if this key needs the account's embedded wallet. This is a CLI storage option; it adds no MCP tool and does not change tool counts.
+
 `CANDLE_MCP_TOOLS` (optional) is a comma-separated allowlist of tool names; only those register.
-Unset means all eighty-three. An unknown name fails startup with the valid names in the message, rather
+Unset means all eighty-seven. An unknown name fails startup with the valid names in the message, rather
 than silently registering the wrong surface. `candle mcp --read-only` / `--tools` set this for
 you.
 
@@ -52,8 +56,8 @@ Both take decimal amounts, never raw base units, and resolve the scale themselve
 - A `candle_trade` **buy** is denominated in the token's OWN quote asset, whatever it was launched
   against (SOL for a SOL-launched token, USDC or CNDL for those quote pairs). The tool reads the
   market first and converts against its `quoteDecimals`; the `quoteAsset` field applies only to a
-  mint Candle never launched, the path traded through Jupiter (buying needs Pro or Max; selling
-  works on any plan). A
+  mint Candle never launched, the path traded through Jupiter (buying and selling work on any
+  plan). A
   **sell** is denominated in tokens and converts against the market's own `decimals`.
 - A `candle_launch_and_seed` `devBuy` is denominated in the quote asset that launch selects, since
   there the caller genuinely picks the new token's quote pair: `quoteAsset` if given, otherwise
@@ -71,6 +75,13 @@ rest, and omitted uses `curve_price` when allocations fit, otherwise `legacy`. `
 `discord`. See
 [Custom curves](https://docs.candle.tv/developers/headless-launch#custom-curves-choose-v-and-g-switched-off).
 
+On Solana, where the API has `CURVE_LAUNCH_RULES_ENABLED` on, both launch tools take
+`launchRules`, the request's nested object in seconds and raw units like their other amounts:
+`openDelaySecs`, `maxBuyPerWalletRaw` with `capWindowSecs`, `allowlist` with
+`allowlistWindowSecs`, and `devBuyMaxRaw`. The API checks the bounds and answers
+`LAUNCH_RULES_INVALID` with the field and the reason. See
+[Launch rules](https://docs.candle.tv/developers/headless-launch#launch-rules-solana).
+
 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).
@@ -85,7 +96,7 @@ tools, getting a key, funding the embedded wallet, and idempotent retries, see
   non-loopback host. For a trusted local endpoint that is not loopback, such as a devcontainer
   reaching its host; not for anything that leaves the machine.
 - `CANDLE_AGENT_API_KEY` -- an agent API key (`cndl_live_...` / `cndl_test_...`), issued from a
-  Candle account's agent settings page. Required by every tool except the eighteen read-only ones
+  Candle account's agent settings page. Required by every tool except the nineteen read-only ones
   listed above, which includes the account-scoped reads (`candle_get_wallets`,
   `candle_execution_status`, `candle_get_operation`) as well as the writes; those eighteen
   work without it, so the server is useful the moment it is installed and only asks for a key when
@@ -114,6 +125,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`); with `imagePath`, `POST /api/v1/uploads/agent-image` first | `CANDLE_AGENT_API_KEY` |
 | `candle_get_market` | Get market state | `GET /api/v1/markets/:chain/:mint` | none |
+| `candle_get_price_history` | One Solana token's OHLC bars in USD per token, oldest first (interval 1m-1d, limit 1-500, `to` unix seconds); `source` and `volumeUnit` say whose bars. Hood is refused with its REST route | `GET /api/v1/markets/solana/:mint/candles` | none |
 | `candle_get_feed` | Get a token feed | `GET /api/v1/markets/feed?bucket=...` | none |
 | `candle_token_edit` | As the token's creator, set Candle's copy of its description and links; an unknown `socials` key is refused locally. Needs a `launch:write` key from the launching account; reuse `idempotencyKey` to retry. Off until the deployment switches it on (503 `METADATA_EDIT_DISABLED`) | `PATCH /api/v1/tokens/:chain/:mint/metadata` | `x-api-key` |
 | `candle_token_history` | A token's metadata edits, newest first, with the previous values | `GET /api/v1/tokens/:chain/:mint/metadata/history?limit=...&cursor=...` | none |
@@ -157,11 +169,14 @@ 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 share of the account's P&L, the console's figures to the cent: realized on its sales, fees, and the open positions that belong to it at cost basis, marked at current prices (unpriced positions counted, not zeroed), with `totalUsd`, the closed positions as made, lost and partial sells (`closed`), dust flagged and counted apart (`openPositionsExDust`), split by wallet (`pnl.byWallet`, summing to the total) and by chain (`pnl.byChain`), with `chain` and `wallet` on every position | `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_get_profile_pnl` | An agent profile's share of the account's P&L, the console's figures to the cent: realized on its sales, fees, and the open positions that belong to it at cost basis, marked at current prices (unpriced positions counted, not zeroed), with `totalUsd`, the closed positions as made, lost and partial sells (`closed`), dust flagged and counted apart (`openPositionsExDust`), split by wallet (`pnl.byWallet`, summing to the total) and by chain (`pnl.byChain`), with `chain` and `wallet` on every position; `sinceMs` adds a `window` of realized and open mark changes, including older holdings (see "P&L since a time") | `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; page by time with `since`, `until` and `cursor` | `GET /api/v1/agent/keys/:prefix/trades` | `CANDLE_AGENT_API_KEY` |
+| `candle_get_profile_paper` | An agent profile's PAPER P&L and 50 latest paper trades, from quotes (`basis: "quote"`), never live figures | `GET /api/v1/agent/keys/:prefix/paper` | `CANDLE_AGENT_API_KEY` |
+| `candle_get_paper_inventory` | This key's paper positions in raw units (needs `swap:write`) | `GET /api/v1/trade/agent/paper/inventory` | `CANDLE_AGENT_API_KEY` |
+| `candle_get_account_pnl` | P&L for every agent profile on the account in one read (`candle pnl` without `--profile`) | `GET /api/v1/agent/keys/pnl` | `CANDLE_AGENT_API_KEY` |
 | `candle_get_portfolio` | What the account's embedded and TEE wallets hold on Solana and Hood (Hood in `hood`), with prices; unpriced holdings say why, never zero | `GET /api/v1/agent/portfolio` | `CANDLE_AGENT_API_KEY` (`account:read`) |
-| `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_execution_status` | One call before trading: wallets to spend from, tier, this key's limits (`limits.txLimitUse` has its USD limit use and when it resets), and its loss limits and stop state (a stopped key is `ready: false` with a top-level `stopped`) | Composes the wallet, tier, `GET /api/v1/agent/keys/self/limits` and `GET /api/v1/agent/keys/self/risk` reads | `CANDLE_AGENT_API_KEY` |
+| `candle_get_operation` | Look up a trade, swap or launch by the id its write used, and whether it landed. `kind: "swap"` reads a `candle_swap` by its `clientSwapId` and answers `job.outcome` (`in_flight`, `confirmed`, `failed`, `partial` or `indeterminate`) | `GET /api/v1/trade/agent/jobs/:clientId`, `/api/v1/agent/swap/by-client-id/: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_atomic_launch_dry_run` | Check a Solana launch with first buys and price each buy on the curve it would deploy; builds, reserves and writes nothing | `POST /api/v1/launch/atomic/dry-run` | `CANDLE_AGENT_API_KEY` (`launch:write`, `swap:write`, Pro or Max) |
 | `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`) |
@@ -240,7 +255,7 @@ explicitly. Assets with nothing spendable report `empty`; a failed asset never s
 ## Errors
 
 This package never reinterprets an error body, and that body is not one uniform shape across all
-eighty-three tools:
+eighty-seven tools:
 
 - `candle_token_events`, called with `kind`, is the one narrowing of a SUCCESS body, never an
   error one: the relayed `events` are filtered to that kind and the body gains `filteredByKind`.
@@ -410,10 +425,9 @@ Every JSON result carries `network`, epoch-ms `readAt`, `gate: { minOpenInterest
 
 SDK and local MCP cache market reads for five seconds; book and candle snapshots are never cached. CLI/MCP select testnet with `CANDLE_HYPERLIQUID_NETWORK=testnet`; SDK uses `hyperliquidNetwork: "testnet"`. These four tools are local-only and are absent from hosted MCP tool sets. MCP uses the existing `CANDLE_API_KEY` or `CANDLE_AGENT_API_KEY` configuration, with no signer PEM required. No signing, relay or `/exchange` request occurs.
 
-## Token page tools (unreleased local source)
+## Token page tools (local clients)
 
-The sixteen `candle_token_page_*` tools below are available in local MCP source and the bundled
-`candle mcp` source. They require a human-owned package release before npm installs receive them.
+The sixteen `candle_token_page_*` tools below are in the published 0.10.29 and the bundled `candle mcp`.
 They are not offered by the hosted OAuth connector. Existing OAuth consent and key grants are
 unchanged; local keys need explicit `token-pages:read` or `token-pages:write` scopes. All token-page
 switches default off: `404`/`feature_off` is a refusal, not an empty page or permission grant.
@@ -448,7 +462,7 @@ removed or unsafe versions cannot be restored. The four reads have read-only MCP
 and content mutations have mutation hints and approval classifications; content approvals retain
 `idempotencyKey` as their operation ID. The server never enables a deployment switch.
 
-Token update tools in unreleased source:
+Token update tools:
 
 | Tool | Behavior |
 | --- | --- |
@@ -462,7 +476,7 @@ All three mutations require `token-pages:write` and a durable `idempotencyKey`.
 Update bodies cannot be edited. Reporting and moderation apply to their exact post IDs.
 These tools grant no notification delivery or activation permission.
 
-Token comment tools in unreleased source:
+Token comment tools:
 
 | Tool | Behavior |
 | --- | --- |
@@ -472,3 +486,43 @@ Token comment tools in unreleased source:
 A comment uses the same eligibility, restriction and idempotency rules as a section edit. It is
 never pushed to holders and cannot be edited. `candle_token_page_post_delete` removes the key
 account's own comment, including after selling; no other account can. Flags apply to its exact ID.
+
+## Rate-limit cost per tool
+
+Every tool spends from the key's per-minute limit (`tierCaps.rateLimitPerMin` on `GET /api/v1/agent/tier`; Free 30, Pro 300, Max 600). Over `candle mcp` (stdio) a tool costs one per REST request it makes: `candle_execution_status` makes 4, and `candle_get_portfolio`, `candle_get_profile_pnl` and `candle_get_wallets` make 1 each. The hosted connector charges one per tool call at admission, and adds a separate 60 a minute per IP. A refusal is `429 RATE_LIMITED` with `Retry-After: 60`. Details: the developer docs, "Rate limits and what a call costs".
+
+
+## P&L since a time
+
+`GET /api/v1/agent/keys/{prefix}/pnl?sinceMs=<unix ms>` (SDK `getProfilePnl(prefix, { sinceMs })`, MCP
+`candle_get_profile_pnl` with `sinceMs`) adds a spot trading `window` beside the unchanged all-time
+`pnl`. LP, Hyperliquid and creator fee income are separate from this window.
+
+Holdings present immediately before T start at the last completed historical minute candle's close,
+not their lifetime purchase cost. The candle containing T is excluded to avoid using future trades.
+`boundary.marks` gives each price, `source: "candle-close"` and `updatedAt` (the candle's end, Unix ms);
+a quiet token's last candle can be older than T. These are historical observed marks, not interpolated
+prices at exactly T. Later buys enter at their actual trade cost. Partial sells, additional buys and
+moves between wallets use the account engine's average-cost rules on this opening book.
+
+`realizedGrossUsd` is sales' profit against window basis; `feesUsd` charges all in-window buy and sell
+fees exactly once, including buys still open. Fees are debited separately and never added to cost
+basis. Fees follow the key that placed each fill; a manual sale credits the original opener's gross
+but its fee stays with Manual.
+`realizedNetUsd = realizedGrossUsd - feesUsd`;
+`unrealizedUsd` is open holdings' change against window basis; `windowedUsd` is their sum. `closed`
+and `closedRounds` describe rounds closed during this replay, using window basis and only window
+fees. A pre-T buy fee is excluded even when that holding is sold after T. Fills exactly at T are included.
+
+`complete: false` and `incompleteReasons` explicitly identify missing boundary/current marks,
+truncated history, unvalued fills or unknown/incomplete cost. In that case **`windowedUsd` is null**;
+component figures are partial, never a complete zero. `boundary.missingMints` names missing opening
+prices, including holdings since fully closed. Boundary coverage is checked account-wide because
+other wallets' and unplaced holdings can fund this key's sales. Price history uses the existing
+Candle candle store; tokens without historical candles have incomplete coverage. There are no new
+vendor requests or fabricated opening prices. The window requires the Postgres account ledger
+(`API_DATABASE_URL`); an unavailable ledger/history read returns an error, not an all-time fallback.
+
+`sinceMs` must be a non-negative integer Unix timestamp in milliseconds at or before now; invalid,
+blank, fractional or future inputs return `VALIDATION_FAILED` (400). Omitting it returns the existing
+all-time response without `window`.

package/dist/index.js

@@ -189,7 +189,7 @@ function readClusterResult(value, mint) {
 }
 
 // src/version.ts
-var SERVER_VERSION = "0.10.29";
+var SERVER_VERSION = "0.10.30";
 
 // src/update-notice.ts
 var PLAIN_VERSION = /^\d+\.\d+\.\d+$/;
@@ -1536,6 +1536,171 @@ var LAUNCH_DEFINITION = {
         }
       }
     },
+    {
+      key: "launchRules.openDelaySecs",
+      type: "duration",
+      help: "Launch rules, Solana only, where the server has CURVE_LAUNCH_RULES_ENABLED on: how long after the launch buys open, at most 7 days (604800 seconds); before then only the launching wallet may buy. The CLI takes a duration (90m, 6h, 2d, or seconds); the request field is whole seconds.",
+      wireType: "number",
+      range: {
+        min: "0",
+        max: "604800",
+        unit: "seconds"
+      },
+      chains: [
+        "solana"
+      ],
+      surfaces: {
+        cli: {
+          flag: "--open-in",
+          value: "<duration>"
+        },
+        mcp: {
+          key: "launchRules.openDelaySecs"
+        },
+        sdk: {
+          key: "launchRules.openDelaySecs"
+        }
+      }
+    },
+    {
+      key: "launchRules.maxBuyPerWalletRaw",
+      type: "decimal",
+      help: "The most quote one wallet may spend on the curve during --cap-window, curve fee included and Candle's fee not; needs --cap-window. The CLI takes whole quote units; the request field is raw units as a decimal string.",
+      range: {
+        unit: "whole quote units"
+      },
+      chains: [
+        "solana"
+      ],
+      requires: [
+        "launchRules.capWindowSecs"
+      ],
+      surfaces: {
+        cli: {
+          flag: "--max-buy-per-wallet",
+          value: "<amount>"
+        },
+        mcp: {
+          key: "launchRules.maxBuyPerWalletRaw"
+        },
+        sdk: {
+          key: "launchRules.maxBuyPerWalletRaw"
+        }
+      }
+    },
+    {
+      key: "launchRules.capWindowSecs",
+      type: "duration",
+      help: "How long the per-wallet cap holds, counted from the open: 1 second to 24 hours (86400 seconds); needs --max-buy-per-wallet.",
+      wireType: "number",
+      range: {
+        min: "1",
+        max: "86400",
+        unit: "seconds"
+      },
+      chains: [
+        "solana"
+      ],
+      requires: [
+        "launchRules.maxBuyPerWalletRaw"
+      ],
+      surfaces: {
+        cli: {
+          flag: "--cap-window",
+          value: "<duration>"
+        },
+        mcp: {
+          key: "launchRules.capWindowSecs"
+        },
+        sdk: {
+          key: "launchRules.capWindowSecs"
+        }
+      }
+    },
+    {
+      key: "launchRules.allowlist",
+      type: "file",
+      help: "Only these wallets may buy during --allowlist-window: 1 to 4,096 distinct Solana addresses; needs --allowlist-window. The CLI reads a file, one address per line or comma separated; the request field is the list.",
+      wireType: "string[]",
+      range: {
+        min: "1",
+        max: "4096",
+        unit: "wallets"
+      },
+      chains: [
+        "solana"
+      ],
+      requires: [
+        "launchRules.allowlistWindowSecs"
+      ],
+      surfaces: {
+        cli: {
+          flag: "--allowlist",
+          value: "<path>"
+        },
+        mcp: {
+          key: "launchRules.allowlist"
+        },
+        sdk: {
+          key: "launchRules.allowlist"
+        }
+      }
+    },
+    {
+      key: "launchRules.allowlistWindowSecs",
+      type: "duration",
+      help: "How long the allowlist phase holds, counted from the open: 1 second to 24 hours (86400 seconds); needs --allowlist.",
+      wireType: "number",
+      range: {
+        min: "1",
+        max: "86400",
+        unit: "seconds"
+      },
+      chains: [
+        "solana"
+      ],
+      requires: [
+        "launchRules.allowlist"
+      ],
+      surfaces: {
+        cli: {
+          flag: "--allowlist-window",
+          value: "<duration>"
+        },
+        mcp: {
+          key: "launchRules.allowlistWindowSecs"
+        },
+        sdk: {
+          key: "launchRules.allowlistWindowSecs"
+        }
+      }
+    },
+    {
+      key: "launchRules.devBuyMaxRaw",
+      type: "decimal",
+      help: "The most the launching wallet may buy before the open, only with --open-in: at least the launch's own buy, at most the dev-buy ceiling, and the buy by default. That spend counts toward the per-wallet cap after the open. The CLI takes whole quote units; the request field is raw units as a decimal string.",
+      range: {
+        unit: "whole quote units"
+      },
+      chains: [
+        "solana"
+      ],
+      requires: [
+        "launchRules.openDelaySecs"
+      ],
+      surfaces: {
+        cli: {
+          flag: "--dev-buy-max",
+          value: "<amount>"
+        },
+        mcp: {
+          key: "launchRules.devBuyMaxRaw"
+        },
+        sdk: {
+          key: "launchRules.devBuyMaxRaw"
+        }
+      }
+    },
     {
       key: "dryRun",
       type: "boolean",
@@ -1558,7 +1723,7 @@ var LAUNCH_DEFINITION = {
 
 // src/launch-schema.ts
 var M2_TOP_KEYS = new Set(["wallet", "buy", "feeWallet", "feeWalletMultisig"]);
-var GROUPED_TOP_KEYS = new Set(["socials", "curve", "poolFee"]);
+var GROUPED_TOP_KEYS = new Set(["socials", "curve", "poolFee", "launchRules"]);
 function mcpKey(field) {
   const surface = field.surfaces.mcp;
   return "key" in surface ? surface.key : undefined;
@@ -1683,6 +1848,20 @@ function poolFeeSchema() {
     }).strict()
   ]).optional().describe([tierHelp, startHelp, endHelp, minutesHelp].join(" "));
 }
+function launchRulesSchema() {
+  const helps = [];
+  const shape = {};
+  for (const field of mcpLaunchFields()) {
+    const key = mcpKey(field);
+    if (!key?.startsWith("launchRules."))
+      continue;
+    const wire = "wireType" in field ? field.wireType : undefined;
+    const schema = wire === "number" ? z3.number().int() : wire === "string[]" ? z3.array(z3.string()) : z3.string();
+    shape[key.slice("launchRules.".length)] = schema.optional().describe(field.help);
+    helps.push(field.help);
+  }
+  return z3.object(shape).passthrough().optional().describe(helps.join(" "));
+}
 function scalarSchema(field) {
   const values = "values" in field ? field.values : undefined;
   let schema;
@@ -1714,6 +1893,7 @@ function buildLaunchTokenShape() {
   shape.socials = socialsSchema();
   shape.curve = curveSchema();
   shape.poolFee = poolFeeSchema();
+  shape.launchRules = launchRulesSchema();
   shape.buyAmount = z3.union([z3.string(), z3.number()]).optional().describe(BUY_AMOUNT_DESCRIPTION);
   return shape;
 }
@@ -2219,6 +2399,7 @@ async function resolveToken(args, cfg, doFetch) {
     return read.err;
   return { text: JSON.stringify({ success: true, chain, mint: args.mint, market: read.market }, null, 2) };
 }
+var STOP_CLEARED_BY = "An account owner reviews the profile and resumes it from the agent console; an API key cannot resume it.";
 async function executionStatus(cfg, doFetch) {
   const apiKey = requireApiKey(cfg);
   const get = async (path) => {
@@ -2233,27 +2414,33 @@ async function executionStatus(cfg, doFetch) {
     }
     return { ok: res.ok, status: res.status, body };
   };
-  const [wallets, tier, limits] = await Promise.all([
+  const [wallets, tier, limits, risk] = await Promise.all([
     get("/api/v1/agent/wallets/embedded"),
     get("/api/v1/agent/tier"),
-    get("/api/v1/agent/keys/self/limits")
+    get("/api/v1/agent/keys/self/limits"),
+    get("/api/v1/agent/keys/self/risk")
   ]);
   const unreadable = [
     ["wallets", wallets],
     ["tier", tier],
-    ["limits", limits]
+    ["limits", limits],
+    ["risk", risk]
   ].filter(([, r]) => !r.ok);
   const tierBody = tier.ok ? tier.body : undefined;
+  const riskBody = risk.ok ? risk.body : undefined;
+  const stopped = riskBody?.stopped === true;
   return {
     text: JSON.stringify({
       success: true,
-      ready: unreadable.length === 0 ? true : undefined,
+      ready: stopped ? false : unreadable.length === 0 ? true : undefined,
+      stopped: stopped ? { tripped: riskBody?.tripped ?? null, clearedBy: STOP_CLEARED_BY } : undefined,
       notice: tierBody?.maxExpired ? tierBody.maxExpiredNotice : undefined,
       updateAvailable: updateAvailable() ?? undefined,
       unreadable: unreadable.length > 0 ? unreadable.map(([name]) => name) : undefined,
       wallets: wallets.body,
       tier: tier.body,
-      limits: limits.body
+      limits: limits.body,
+      risk: risk.body
     }, null, 2),
     ...unreadable.length > 0 ? { isError: true } : {}
   };
@@ -6306,6 +6493,7 @@ var TOOL_NAMES = [
   "candle_vamp_candidates",
   "candle_token_events",
   "candle_token_card",
+  "candle_get_price_history",
   "candle_token_edit",
   "candle_token_history",
   "candle_token_page_about",
@@ -6347,6 +6535,9 @@ var TOOL_NAMES = [
   "candle_set_profile_wallets",
   "candle_get_profile_pnl",
   "candle_get_profile_trades",
+  "candle_get_paper_inventory",
+  "candle_get_profile_paper",
+  "candle_get_account_pnl",
   "candle_get_portfolio",
   "candle_resolve_token",
   "candle_execution_status",
@@ -6492,6 +6683,21 @@ function buildRequest(name, args, cfg) {
         init: { method: "GET", headers: jsonHeaders() }
       };
     }
+    case "candle_get_price_history": {
+      const { chain, mint, interval, limit, to } = args;
+      const query2 = new URLSearchParams;
+      if (interval !== undefined)
+        query2.set("interval", interval);
+      if (limit !== undefined)
+        query2.set("limit", String(limit));
+      if (to !== undefined)
+        query2.set("to", String(to));
+      const qs = query2.size > 0 ? `?${query2}` : "";
+      return {
+        url: `${base2}/api/v1/markets/${encodeURIComponent(chain ?? "solana")}/${encodeURIComponent(mint)}/candles${qs}`,
+        init: { method: "GET", headers: jsonHeaders() }
+      };
+    }
     case "candle_token_events": {
       const { chain, mint, since, limit, before } = args;
       const params = new URLSearchParams;
@@ -6649,7 +6855,8 @@ function buildRequest(name, args, cfg) {
     case "candle_get_operation": {
       const apiKey = requireApiKey2(cfg);
       const { clientId: clientId2, kind } = args;
-      const path = kind === "launch" ? `/api/v1/launch/headless/jobs/${encodeURIComponent(clientId2)}` : `/api/v1/trade/agent/jobs/${encodeURIComponent(clientId2)}`;
+      const id = encodeURIComponent(clientId2);
+      const path = kind === "launch" ? `/api/v1/launch/headless/jobs/${id}` : kind === "swap" ? `/api/v1/agent/swap/by-client-id/${id}` : `/api/v1/trade/agent/jobs/${id}`;
       return { url: `${base2}${path}`, init: { method: "GET", headers: jsonHeaders(apiKey) } };
     }
     case "candle_get_staking": {
@@ -6724,9 +6931,10 @@ function buildRequest(name, args, cfg) {
     }
     case "candle_get_profile_pnl": {
       const apiKey = requireApiKey2(cfg);
-      const { keyPrefix } = args;
+      const { keyPrefix, sinceMs } = args;
+      const query2 = sinceMs !== undefined ? `?sinceMs=${encodeURIComponent(String(sinceMs))}` : "";
       return {
-        url: `${base2}/api/v1/agent/keys/${encodeURIComponent(keyPrefix)}/pnl`,
+        url: `${base2}/api/v1/agent/keys/${encodeURIComponent(keyPrefix)}/pnl${query2}`,
         init: { method: "GET", headers: jsonHeaders(apiKey) }
       };
     }
@@ -6739,13 +6947,40 @@ function buildRequest(name, args, cfg) {
     }
     case "candle_get_profile_trades": {
       const apiKey = requireApiKey2(cfg);
-      const { keyPrefix, limit } = args;
-      const query2 = limit === undefined ? "" : `?limit=${encodeURIComponent(String(limit))}`;
+      const { keyPrefix, limit, since, until, cursor } = args;
+      const params = new URLSearchParams;
+      if (limit !== undefined)
+        params.set("limit", String(limit));
+      if (since !== undefined)
+        params.set("since", since);
+      if (until !== undefined)
+        params.set("until", until);
+      if (cursor !== undefined)
+        params.set("cursor", cursor);
       return {
-        url: `${base2}/api/v1/agent/keys/${encodeURIComponent(keyPrefix)}/trades${query2}`,
+        url: `${base2}/api/v1/agent/keys/${encodeURIComponent(keyPrefix)}/trades${params.size ? `?${params}` : ""}`,
         init: { method: "GET", headers: jsonHeaders(apiKey) }
       };
     }
+    case "candle_get_paper_inventory": {
+      return {
+        url: `${base2}/api/v1/trade/agent/paper/inventory`,
+        init: { method: "GET", headers: jsonHeaders(requireApiKey2(cfg)) }
+      };
+    }
+    case "candle_get_profile_paper": {
+      const { keyPrefix } = args;
+      return {
+        url: `${base2}/api/v1/agent/keys/${encodeURIComponent(keyPrefix)}/paper`,
+        init: { method: "GET", headers: jsonHeaders(requireApiKey2(cfg)) }
+      };
+    }
+    case "candle_get_account_pnl": {
+      return {
+        url: `${base2}/api/v1/agent/keys/pnl`,
+        init: { method: "GET", headers: jsonHeaders(requireApiKey2(cfg)) }
+      };
+    }
     case "candle_transfer": {
       const apiKey = requireApiKey2(cfg);
       return {
@@ -6781,10 +7016,10 @@ async function callAndRelay(name, args, cfg, doFetch) {
     ...res.ok ? {} : { isError: true }
   };
 }
-var OPERATION_NOT_FOUND_RULE = "No record exists under this id in the ledger `kind` asked. That does not prove the write did " + "not run: a write that is still starting has no record yet. If a write was sent with this id, " + "send the SAME request again with the SAME id. It returns the stored outcome, or reports the one " + "still running. It never executes a second time. A refusal of that resend (a conflict or a " + "limit) is an answer about the resend, not about the write: read candle_get_operation again " + "before reporting an outcome. Never send it under a new id: a new id is a second trade or " + "launch. Check `kind`: a swap id is not read here, so replay the swap with its `clientSwapId`.";
+var OPERATION_NOT_FOUND_RULE = "No record exists under this id in the ledger `kind` asked. That does not prove the write did " + "not run: a write that is still starting has no record yet. If a write was sent with this id, " + "send the SAME request again with the SAME id. It returns the stored outcome, or reports the one " + "still running. It never executes a second time. A refusal of that resend (a conflict or a " + "limit) is an answer about the resend, not about the write: read candle_get_operation again " + "before reporting an outcome. Never send it under a new id: a new id is a second trade, swap or " + "launch. Check `kind`: an id read under the wrong kind has no record there. A swap sent without " + "a `clientSwapId` has no record at all.";
 function operationNotFoundNext(clientId2, kind) {
-  const other = kind === "launch" ? "trade" : "launch";
-  return `No ${kind} record under id "${clientId2}" yet. That does not prove the write did not run: a ` + "write that is still starting has no record yet. If a write was sent with this id, send the " + `SAME request again with the SAME id ("${clientId2}"). It returns the stored outcome, or reports ` + "the one still running. It never executes a second time. A refusal of that resend (a conflict " + "or a limit) is an answer about the resend, not about the write: read candle_get_operation " + `again before reporting an outcome. Never send it under a new id: a new id is a second ${kind}. ` + `This read asked kind "${kind}": a ${other} id has no record there, and a swap id is not read by ` + "this tool at all, so replay the swap with its clientSwapId.";
+  const others = ["trade", "swap", "launch"].filter((k) => k !== kind).join(" or ");
+  return `No ${kind} record under id "${clientId2}" yet. That does not prove the write did not run: a ` + "write that is still starting has no record yet. If a write was sent with this id, send the " + `SAME request again with the SAME id ("${clientId2}"). It returns the stored outcome, or reports ` + "the one still running. It never executes a second time. A refusal of that resend (a conflict " + "or a limit) is an answer about the resend, not about the write: read candle_get_operation " + `again before reporting an outcome. Never send it under a new id: a new id is a second ${kind}. ` + `This read asked kind "${kind}": a ${others} id has no record there.`;
 }
 async function getOperation(args, cfg, doFetch) {
   const { url, init } = buildRequest("candle_get_operation", args, cfg);
@@ -6799,7 +7034,7 @@ async function getOperation(args, cfg, doFetch) {
     const code = body?.error?.code;
     if (code === "JOB_NOT_FOUND") {
       const { clientId: clientId2, kind } = args;
-      const next = operationNotFoundNext(clientId2, kind === "launch" ? "launch" : "trade");
+      const next = operationNotFoundNext(clientId2, kind === "launch" || kind === "swap" ? kind : "trade");
       text = JSON.stringify({ ...body, outcome: "unknown", next });
     }
   }
@@ -6834,6 +7069,13 @@ var getMarketShape = {
   chain: z9.string().describe('"solana" or "hood"'),
   mint: z9.string().describe("Token mint (solana) or contract address (hood)")
 };
+var priceHistoryShape = {
+  chain: z9.string().optional().describe('"solana" (the default). Hood is refused with the REST route that serves it'),
+  mint: z9.string().describe("Token mint"),
+  interval: z9.enum(["1m", "5m", "15m", "1h", "4h", "1d"]).optional().describe("Bar length. Default 1h"),
+  limit: z9.number().int().min(1).max(500).optional().describe("How many bars, 1-500. Default 100"),
+  to: z9.number().int().positive().optional().describe("Unix seconds: the newest bar opens at or before this. Default now; page back with the oldest bar's time")
+};
 var TOKEN_EVENTS_LIMIT_MESSAGE = "limit must be a whole number from 1 to 1000";
 var tokenEventsLimit = z9.preprocess((value) => {
   if (typeof value !== "string")
@@ -6912,8 +7154,8 @@ var getAgentPositionsShape = {
   kind: z9.enum(["spot", "perp"]).optional().describe("Only spot tokens or only Hyperliquid perps; omit for both")
 };
 var getOperationShape = {
-  clientId: z9.string().describe("The clientTradeId or clientLaunchId the write used, or that the tool echoed back to you"),
-  kind: z9.enum(["trade", "launch"]).describe("Which rail the id belongs to. Required: ids are caller-chosen strings with no shape to dispatch on")
+  clientId: z9.string().describe("The clientTradeId, clientSwapId or clientLaunchId the write used, or that the tool echoed back to you"),
+  kind: z9.enum(["trade", "swap", "launch"]).describe("Which rail the id belongs to. Required: ids are caller-chosen strings with no shape to dispatch on")
 };
 var vampCandidatesShape = {
   limit: z9.number().optional().describe("Entries to return, 1 to 50 (default 20)"),
@@ -6951,12 +7193,17 @@ var profileWalletsShape = {
   keyPrefix: z9.string().describe("The profile's API key prefix, as listed by candle keys list or in the dashboard")
 };
 var profilePnlShape = {
-  keyPrefix: z9.string().describe("The profile's API key prefix")
+  keyPrefix: z9.string().describe("The profile's API key prefix"),
+  sinceMs: z9.number().int().nonnegative().optional().describe("Unix time in milliseconds. Adds a `window` block: realized and open mark changes since then, including older holdings. Buy and sell fees are charged once. Read complete and incompleteReasons; windowedUsd is null when incomplete. The all-time `pnl` is unchanged.")
 };
 var profileTradesShape = {
   keyPrefix: z9.string().describe("The profile's API key prefix"),
-  limit: z9.number().optional().describe("How many of the most recent trades to return. Default 200, max 1000.")
+  limit: z9.number().optional().describe("How many of the most recent trades to return. Default 200, max 1000."),
+  since: z9.string().optional().describe("Inclusive lower bound on the trade's createdAt: an ISO 8601 time or epoch milliseconds."),
+  until: z9.string().optional().describe("Exclusive upper bound on createdAt, in the same forms as `since`."),
+  cursor: z9.string().optional().describe("The `nextCursor` of the previous page, to continue the same window.")
 };
+var noArgsShape = {};
 var setProfileWalletsShape = {
   keyPrefix: z9.string().describe("The profile's API key prefix"),
   walletIds: z9.array(z9.string()).describe("The linked-wallet ids the profile may spend from -- ids, not addresses. This REPLACES the " + "whole set: any wallet omitted loses access. An empty array assigns none.")
@@ -6974,7 +7221,7 @@ var tradeShape = {
   side: z9.enum(["buy", "sell"]),
   amount: z9.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: z9.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: z9.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. Echoing the `quoteAsset` a quote (POST /api/v1/trade/agent/quote) returned is safe. On Solana it applies only ' + "to an arbitrary mint Candle never launched (a buy needs Pro or Max; a sell works on any plan) 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."),
+  quoteAsset: z9.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. Echoing the `quoteAsset` a quote (POST /api/v1/trade/agent/quote) returned is safe. On Solana it applies only ' + "to an arbitrary mint Candle never launched (a buy or sell works on any plan) 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: z9.number().int().min(0).max(5000).optional().describe("Slippage bound in bps, 0-5000 (50%). Server defaults to 100 (1%)"),
   clientTradeId: z9.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: z9.preprocess((value) => value === "true" || value === 1 || value === "1" ? true : value === "false" || value === 0 || value === "0" ? false : value, z9.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."))
@@ -7160,9 +7407,7 @@ function registerToolSubset(server, options) {
   }, async (args) => callAndRelay("candle_get_market", args, getConfig(), doFetch));
   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; when no developer is on chain, deployer.attribution names the launchpad or issuer instead, e.g. launched via stonk.fun or issued by xStocks), 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, and any Solana mint Jupiter's index knows, now answers with a partial report instead. On Hood, a token Candle did not launch names its launch account (deployer.method cvc_launch_account) for pons.family and pools.trade launches, with no record of earlier coins; other Hood launchpads return no developer.`,
+    description: "Gate a buy before making it: who launched it (resolved on-chain; pump.fun's shared updateAuthority is never the developer; when no developer is on chain, deployer.attribution names the launchpad or issuer instead, e.g. launched via stonk.fun or issued by xStocks), 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. deployer.priorLaunches is counted (pump.fun curves for a curve creator; record.count says the source); deployer.launcher is the wallet that sent the launch, often a launch tool's signer, never the developer; launch.deployerLaunches is that wallet's inclusive informational count, never a warning. Every measurement carries a coverage note -- 'unavailable' is not 'clean'. No key needed.\n\nMARKET_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, and any Solana mint Jupiter's index knows, now answers with a partial report instead. On Hood, a token Candle did not launch names its launch account (deployer.method cvc_launch_account) for pons.family and pools.trade launches, with no record of earlier coins; other Hood launchpads return no developer.",
     inputSchema: tokenForensicsShape
   }, async (args) => callAndRelay("candle_token_forensics", args, getConfig(), doFetch));
   register("candle_token_clusters", {
@@ -7197,6 +7442,11 @@ MARKET_NOT_FOUND means Candle has no market for that token and this could not ru
     inputSchema: tokenHistoryShape,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
   }, async (args) => callAndRelay("candle_token_history", args, getConfig(), doFetch));
+  register("candle_get_price_history", {
+    title: "Get price history",
+    description: "One Solana token's price history: OHLC bars in USD per token, oldest first, the same bars as the token's chart on Candle. interval 1m, 5m, 15m, 1h, 4h or 1d (default 1h); limit 1-500 (default 100); to is unix seconds (default now). The answer is up to limit bars at or before to (limit is a maximum). Coverage is bounded by source: Candle's own bars come from the latest 1,500 active minutes and a bar whose start cannot be established is left out; the indexer is searched only (limit + 1) x interval seconds back from to. A quiet token can therefore return fewer bars than limit, and a minute with no trades has no bar, so read each bar's time rather than assuming a gapless series. source says which answered: candle (Candle's own curve bars, volumeUnit usd) or birdeye (the indexer's, volumeUnit token). An empty candles list means no bars in the searched coverage, not no history and not a zero price; page back with to. No key needed and none is sent. Hood is refused (400 VALIDATION_FAILED naming GET /api/v1/hood/token/:address/candles). For the current price and 5m/1h/24h change, read candle_get_market.",
+    inputSchema: priceHistoryShape
+  }, async (args) => callAndRelay("candle_get_price_history", args, getConfig(), doFetch));
   register("candle_token_events", {
     title: "Token events",
     description: `One token's event list, newest first: every signal (pattern and summary, new_ticker included), every callout, and every tracked-wallet trade (buys and sells, W or L on a sell whose outcome is known), plus trades Candle's own agents and users made. Each wallet carries its display name or short address, its kind (dev, kol, smart, agent, tracked) and its public group names. No key needed; none is sent even when one is configured, so group names follow the public tier. Off on a deployment until it switches TOKEN_EVENTS on: off, the call answers 503 TOKEN_EVENTS_DISABLED (retryable: false) and that is the server's answer, not a broken tool.
@@ -7294,13 +7544,13 @@ MARKET_NOT_FOUND means Candle has no market for that token and this could not ru
   });
   register("candle_get_operation", {
     title: "What happened to a write",
-    description: "Look up a trade or launch by the id its write used, and find out whether it landed. " + `Reads only; moves nothing.
+    description: "Look up a trade, swap or launch by the id its write used, and find out whether it landed. " + `Reads only; moves nothing.
 
 ` + "Call this after a timeout, after a restart, or any time you hold an id and do not know " + `the outcome. Do NOT re-send the write to find out.
 
-` + `Four answers, four different next moves:
+` + `The answers, and the next move for each:
 ` + "- `confirmed`/`failed`: it is over. `signature` proves the first, `errorCode` explains " + `the second.
-` + "- `built`/`submitted`: still in flight. Wait and ask again.\n" + `- 404 (\`JOB_NOT_FOUND\`): unknown, not an outcome. ${OPERATION_NOT_FOUND_RULE} The result ` + 'says the same in `outcome: "unknown"` and `next`.\n\n' + "Amounts come back RAW, deliberately: the answer you need after a timeout is the outcome, " + "and you already know what you asked for.",
+` + "- `built`/`submitted`: still in flight. Wait and ask again.\n" + "- kind `swap` (candle_swap's `clientSwapId`) answers `job.outcome` instead: `in_flight` " + "(ask again), `confirmed` (`job.hashes`), `failed` (refused before any broadcast; the SAME " + "request with the SAME id starts over), `partial` (`hashes[0]` landed, " + "a later leg did not) or `indeterminate` (broadcast, outcome unknown; check " + "`error.message`). `partial` and `indeterminate` are final for that id.\n" + `- 404 (\`JOB_NOT_FOUND\`): unknown, not an outcome. ${OPERATION_NOT_FOUND_RULE} The result ` + 'says the same in `outcome: "unknown"` and `next`.\n\n' + "Amounts come back RAW, deliberately: the answer you need after a timeout is the outcome, " + "and you already know what you asked for.",
     inputSchema: getOperationShape
   }, async (args) => getOperation(args, getConfig(), doFetch));
   register("candle_get_staking", {
@@ -7357,14 +7607,29 @@ MARKET_NOT_FOUND means Candle has no market for that token and this could not ru
   }, async (args) => callAndRelay("candle_set_profile_wallets", args, getConfig(), doFetch));
   register("candle_get_profile_pnl", {
     title: "Read an agent profile's P&L",
-    description: "Optional `board` beside `pnl` carries profileId, creatorFeesUsd, feeClaimsUnvalued, feeClaimsPartial and " + "totalPnlUsd (absent before a board entry exists): the all-time public board total, including fee claims " + "at their value when claimed, credited to the agent that launched the token when the claiming account " + "is the launching account. `feesUsd` is fees paid; `creatorFeesUsd` is fees earned. Check feeClaimsPartial " + "and feeClaimsUnvalued. `board` is absent on an older backend or a failed board read; it does not change " + "ledger pnl.totalUsd. Staking rewards are held at zero cost; claim value is informational, never added again. " + "This profile's share of the account's P&L: realized profit on the sales it made and on positions its buy opened that closed through a sale made by hand in the web app or an exit outside Candle (the fee and trade count stay under Manual), the Candle fees " + "charged against it, and the positions that belong to it (the wallet's bound key, else the key " + "whose buy opened them) 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 and withdrawals are " + "excluded: funding a wallet is not profit. Check `unvalued` and `truncated` before quoting the " + "number; they mean the total is partial. The figures come from the account's one P&L read, the " + "same as the console's, to the cent: `pnl.totalUsd` (realized net plus unrealized) is the " + "console's P&L, plus the Hyperliquid net when `perpsInTotal` is true. Positions live in wallets: each wallet is its own average-cost pool, the total " + "is the sum of `pnl.byWallet` (one row per wallet, main or linked, with the linked wallet's " + "label; `unknown:solana` or `unknown:hood` is the row for fills no record places in a wallet), " + "and one token held in two wallets is two positions, each with its `wallet`. A recorded move " + "between the account's wallets carries its cost and realizes nothing. Moved-in positions and " + "`closedPositions` carry additive `transferredIn`, `basisSource` and `basisComplete`; " + "`basisSource` says whether cost comes from Candle history, on-chain trades or the arrival price; " + "`zero-cost` (with `zeroCostQuantity`) is Solana CNDL with no purchase found, carried at $0. " + "Public `realizedFromTransfersUsd` and `unrealizedFromTransfersUsd` are shares already included in " + "total P&L and rank; do not add them again. Moved-in closes count toward W/L and eligibility. Each position carries " + "`agent` (the key it belongs to) and `dust` when it is worth under one cent; dust stays listed " + "and counted, and `openPositionsExDust` leaves it out. `closed` gives the closed positions as " + "`madeUsd` + `lostUsd` + `partialSellsUsd` = `realizedNetUsd`, with `wins` and `losses`. " + "`lookback` and `truncated` are the account's activity bound, and `tradesConsidered` counts this " + "key's ledger fills. Since 2026-10-02 the total is the sum of wallets rather than one pool across " + "them, so realized figures can differ from earlier reads; a server that predates it omits " + "`totalUsd`, `closed`, `openPositionsExDust`, `wallet`, `agent` and `dust`. " + "Every open position and every `byWallet` row (and its positions) carries `chain` ('solana' or " + "'hood'), and `pnl.byChain` has the total's figures over each chain's fills alone, both chains " + "always present, with `openPositions` there a count (the positions are in `pnl.openPositions`, by " + "`chain`). The two chains sum to the total. A " + "server that predates per-chain P&L omits `chain` and `byChain`. " + PROFILE_PNL_HYPERLIQUID + " Reads only.",
+    description: "Optional `board` beside `pnl` carries profileId, creatorFeesUsd, feeClaimsUnvalued, feeClaimsPartial and " + "totalPnlUsd (absent before a board entry exists): the all-time public board total, including fee claims " + "at their value when claimed, credited to the agent that launched the token when the claiming account " + "is the launching account. `feesUsd` is fees paid; `creatorFeesUsd` is fees earned. Check feeClaimsPartial " + "and feeClaimsUnvalued. `board` is absent on an older backend or a failed board read; it does not change " + "ledger pnl.totalUsd. Staking rewards are held at zero cost; claim value is informational, never added again. " + "This profile's share of the account's P&L: realized profit on the sales it made and on positions its buy opened that closed through a sale made by hand in the web app or an exit outside Candle (the fee and trade count stay under Manual), the Candle fees " + "charged against it, and the positions that belong to it (the wallet's bound key, else the key " + "whose buy opened them) 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 and withdrawals are " + "excluded: funding a wallet is not profit. Check `unvalued` and `truncated` before quoting the " + "number; they mean the total is partial. The figures come from the account's one P&L read, the " + "same as the console's, to the cent: `pnl.totalUsd` (realized net plus unrealized) is the " + "console's P&L, plus the Hyperliquid net when `perpsInTotal` is true. Positions live in wallets: each wallet is its own average-cost pool, the total " + "is the sum of `pnl.byWallet` (one row per wallet, main or linked, with the linked wallet's " + "label; `unknown:solana` or `unknown:hood` is the row for fills no record places in a wallet), " + "and one token held in two wallets is two positions, each with its `wallet`. A recorded move " + "between the account's wallets carries its cost and realizes nothing. Moved-in positions and " + "`closedPositions` carry additive `transferredIn`, `basisSource` and `basisComplete`; " + "`basisSource` says whether cost comes from Candle history, on-chain trades or the arrival price; " + "`zero-cost` (with `zeroCostQuantity`) is Solana CNDL with no purchase found, carried at $0. " + "Public `realizedFromTransfersUsd` and `unrealizedFromTransfersUsd` are shares already included in " + "total P&L and rank; do not add them again. Moved-in closes count toward W/L and eligibility. Each position carries " + "`agent` (the key it belongs to) and `dust` when it is worth under one cent; dust stays listed " + "and counted, and `openPositionsExDust` leaves it out. `closed` gives the closed positions as " + "`madeUsd` + `lostUsd` + `partialSellsUsd` = `realizedNetUsd`, with `wins` and `losses`. " + "`lookback` and `truncated` are the account's activity bound, and `tradesConsidered` counts this " + "key's ledger fills. Since 2026-10-02 the total is the sum of wallets rather than one pool across " + "them, so realized figures can differ from earlier reads; a server that predates it omits " + "`totalUsd`, `closed`, `openPositionsExDust`, `wallet`, `agent` and `dust`. " + "Every open position and every `byWallet` row (and its positions) carries `chain` ('solana' or " + "'hood'), and `pnl.byChain` has the total's figures over each chain's fills alone, both chains " + "always present, with `openPositions` there a count (the positions are in `pnl.openPositions`, by " + "`chain`). The two chains sum to the total. A " + "server that predates per-chain P&L omits `chain` and `byChain`. " + PROFILE_PNL_HYPERLIQUID + " Pass `sinceMs` for a `window` block beside all-time `pnl`: existing holdings start at the last " + "completed historical minute candle's close, returned in `boundary.marks` with its timestamp. " + "Sales and open positions use that window basis, with later buys at trade cost. `feesUsd` includes " + "both buy and sell fees once, separately from basis. `windowedUsd` is " + "realizedNetUsd plus unrealizedUsd. Missing boundary/current marks or incomplete history return " + "complete:false, incompleteReasons and windowedUsd:null; component sums are partial then. " + "This is spot trading P&L; LP, perps and fee income remain separate. Reads only.",
     inputSchema: profilePnlShape
   }, async (args) => callAndRelay("candle_get_profile_pnl", args, getConfig(), doFetch));
   register("candle_get_profile_trades", {
     title: "Read an agent profile's trade history",
-    description: "Orders, actual fills, fees, timestamps and transaction hashes for this profile. Includes FAILED " + "trades, with an errorCode saying why each did not go through, so this answers 'what happened to " + "my order' as well as 'what did I trade'. Reads only; moves nothing.",
+    description: "Orders, actual fills, fees, timestamps and transaction hashes for this profile. Page by time with " + "`since`, `until` and `cursor` (continue with the response's `nextCursor`). Includes FAILED " + "trades, with an errorCode saying why each did not go through, so this answers 'what happened to " + "my order' as well as 'what did I trade'. Reads only; moves nothing.",
     inputSchema: profileTradesShape
   }, async (args) => callAndRelay("candle_get_profile_trades", args, getConfig(), doFetch));
+  register("candle_get_paper_inventory", {
+    title: "Read this key's paper inventory",
+    description: "This key's PAPER book in raw units: the positions that paper buys have credited and a paper " + "percent sell sizes itself from. Derived from admitted quotes; no money moved and the live " + "wallet is untouched. Never mix it with live holdings (candle_get_portfolio). Fails retryably " + "when the book cannot be read completely. Needs swap:write on the key. Reads only.",
+    inputSchema: noArgsShape
+  }, async (args) => callAndRelay("candle_get_paper_inventory", args, getConfig(), doFetch));
+  register("candle_get_profile_paper", {
+    title: "Read an agent profile's paper P&L",
+    description: "One profile's PAPER results: the same accounting as candle_get_profile_pnl, from trades that " + "never happened. `pnl` is the paper P&L and `trades` its 50 most recent paper trades. Carries " + '`basis: "quote"`: the figures come from quotes at admission and are optimistic by the ' + "slippage and fees real execution pays. Never add them to live P&L. Reads only.",
+    inputSchema: profilePnlShape
+  }, async (args) => callAndRelay("candle_get_profile_paper", args, getConfig(), doFetch));
+  register("candle_get_account_pnl", {
+    title: "Read P&L across all of an account's agent keys",
+    description: "The account's P&L split by agent profile in one read, as `candle pnl` without `--profile` " + "does: one row per profile with its ledger figures and, where it has a board entry, `board` " + "(all-time public total with creator-fee claims credited to the launching agent, so a profile's " + "board total can differ from its per-key ledger P&L). A wallet shared by several keys books a " + "round to its bound key, else the key whose buy opened it. Use candle_get_profile_pnl for one " + "profile's positions. Reads only.",
+    inputSchema: noArgsShape
+  }, async (args) => callAndRelay("candle_get_account_pnl", args, getConfig(), doFetch));
   register("candle_get_portfolio", {
     title: "Read what the account holds, on Solana and Hood",
     description: "Balances and prices for the wallets Candle already knows on this account, on both chains: the " + "embedded wallet and every TEE wallet. Solana wallets are in `embedded` and `tee` (SOL as raw " + "`lamports`, tokens as raw `amountRaw` with `decimals`). Hood wallets are in `hood.embedded` and " + "`hood.tee` (ETH as raw `wei`, ERC-20s including USDG), never in the top-level arrays. Every " + "wallet and holding carries `chain`. Prices are in `prices`: a Solana mint under its own " + "address, Hood ETH under `hood:native`, and a Hood token under `hood:<contract lowercased>`, so " + "lowercase the address before looking it up. An unpriced entry is `priceUsd: null`, never zero; " + "a Hood one says why in `unpricedReason` (no-market-row, unusable-price, stale-mark, " + "source-unavailable), and `hood.unpriced` / `hood.unpricedByReason` count them. A Hood token " + "mark older than six hours is not used, so many Hood tokens read unpriced. A wallet whose read " + "failed has null balances, never zero, and is listed in `unavailable` (Solana) or " + "`hood.unavailable`; check `complete` before quoting a total. `walletsComplete` is false only " + "when the wallet list itself was cut off, and is absent on a server that predates it: then " + "`complete: false` may be a cut-off list or a failed read. Vault and external wallets are " + "not included: Candle does not know their addresses (the Candle CLI's `candle portfolio` reads " + "them over your own RPC). Needs a key with the account:read scope; without it the answer is " + "SCOPE_MISSING. A server that predates Hood in the portfolio omits `hood` and `chain`. Reads " + "only; moves nothing." + (options.localHyperliquid ? " This local server adds `hyperliquid`: each Hood TEE wallet's Hyperliquid account (account value, " + "unrealized P&L, positions, risk level at the default thresholds) read live from Hyperliquid, with a " + "subtotal. It is not in the ledger and is never part of any total. `read: false` with a reason, or " + "entries in `unread`, means those accounts are unknown, not empty." : ""),
@@ -7386,7 +7651,7 @@ MARKET_NOT_FOUND means Candle has no market for that token and this could not ru
   });
   register("candle_execution_status", {
     title: "Can this key execute right now",
-    description: "One call before trading: the embedded wallets to spend from, the tier that decides what " + "may be traded, and this key's own spend limits. Reads only; moves nothing. Call it when " + "a run starts, or after an authorization error, rather than inferring readiness from a " + "failed trade. If a read could not be completed the tool says which one and does NOT " + "claim the account is unready: an unreachable endpoint and a missing tier are different " + "problems with different fixes.",
+    description: "One call before trading: the embedded wallets to spend from, the tier that decides what " + "may be traded, this key's own spend limits, and its loss limits and stop state (risk: " + "lossLimits, state, stopped, tripped). A stopped key reports ready: false and a top-level " + "stopped naming the bound that broke; every trade answers RISK_LIMIT_REACHED until an " + "account owner resumes it, so stop trading and say why rather than retrying. Any scope " + "can read its own. Reads only; moves nothing. Call it when " + "a run starts, or after an authorization error, rather than inferring readiness from a " + "failed trade. If a read could not be completed the tool says which one and does NOT " + "claim the account is unready: an unreachable endpoint and a missing tier are different " + "problems with different fixes.",
     inputSchema: {}
   }, async () => {
     const result = await executionStatus(getConfig(), doFetch);
@@ -7433,7 +7698,7 @@ 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.
 
-` + "Plans: every plan can buy and sell Candle-launched tokens and base assets, and SELL a token it holds that " + "Candle did not launch. BUYING such a token needs Pro or Max (TIER_REQUIRED otherwise). Each trade pays the " + `plan's agent fee on top (feeBps in candle_get_plans).
+` + "Plans: every plan can buy and sell Candle-launched tokens, base assets, and a token " + "Candle did not launch. Each trade pays the " + `plan's agent fee on top (feeBps in candle_get_plans).
 
 ` + "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.
 
@@ -7657,8 +7922,9 @@ async function registerEligibleProfileTool(server, env = process.env, doFetch =
 // src/server.ts
 var INSTRUCTIONS = `Candle is a trading and token-launch rail for agents. You hold a scoped API key, never a private key; signing and funding stay with the key owner's wallet.
 
-START HERE — fourteen tools need NO credential. Call these first to confirm the server is wired before asking anyone for anything:
+START HERE — fifteen tools need NO credential. Call these first to confirm the server is wired before asking anyone for anything:
   candle_get_market       price, market cap, volume, curve state for one token
+  candle_get_price_history one Solana token's OHLC bars in USD (1m to 1d, up to 500, page back with to); source and volumeUnit say whose bars
   candle_get_feed         the roster: hot streak, new pairs, graduated, final stretch, blue chip (final stretch is refused where it is not switched on; use another bucket)
   candle_token_page_about public About summary, switches default off
   candle_token_page_burns completed CNDL burn history
@@ -7673,7 +7939,7 @@ START HERE — fourteen tools need NO credential. Call these first to confirm th
   candle_token_events     one token's signals, callouts and tracked-wallet trades, newest first, W or L on sells. kind filters the page on this server; page with nextCursor/before until null. Off until the deployment switches it on (503 TOKEN_EVENTS_DISABLED)
   candle_token_card       one token's card data: market, all-time high since launch, safety and same-name facts, tracked wallets in the last hour, each block with its source; null means no source, not zero. Off until the deployment switches it on (503 TOKEN_CARD_DISABLED)
   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; deployer.attribution names the launchpad or issuer when no developer is on chain), 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_token_forensics  call this before quoting or buying. Returns the on-chain developer (never a launchpad shared authority; deployer.attribution names the launchpad or issuer when no developer is on chain), 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. deployer.priorLaunches is counted (pump.fun curves for a curve creator; record.count says the source); deployer.launcher is the wallet that sent the launch, often a launch tool's signer, never the developer; launch.deployerLaunches is that wallet's inclusive informational count, never a warning
   candle_token_clusters   optional third-party linked-wallet estimates for a Solana token, always a result: usually status unavailable with a reason, which is not zero clustered supply or clearance. Report its caveat with any figure; keep it separate from forensics
   candle_get_agent_profile  your own tier, caps and verified activity
   candle_list_agents      the agent directory: every published agent with its strategy, declared models, all-time P&L, trades and launches; sort newest, active or pnl

package/package.json

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