@candledottv/mcp 0.10.18 → 0.10.20

package/README.md

@@ -1,7 +1,7 @@
 # @candledottv/mcp
 
 An MCP (Model Context Protocol) server for the Candle agent rail. The current source exposes Candle's REST API as
-forty-two tools over stdio, so an MCP-capable agent can launch tokens (optionally seeded with a dev
+fifty-four tools over stdio, 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, report on-chain activity, and check an agent profile without hand-rolling HTTP
 calls.
@@ -31,7 +31,7 @@ Environment below -- or skip env editing entirely: install the Candle CLI
 environment.
 
 `CANDLE_MCP_TOOLS` (optional) is a comma-separated allowlist of tool names; only those register.
-Unset means all forty-two. An unknown name fails startup with the valid names in the message, rather
+Unset means all fifty-four. 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.
 
@@ -89,8 +89,10 @@ tools, getting a key, funding the embedded wallet, and idempotent retries, see
   to publish. Set, `candle_launch_token` and `candle_launch_and_seed` accept `imagePath` for a
   file inside it; unset, they take `imageUrl` only and the server reads no image file. See
   [Launching with an image file](#launching-with-an-image-file).
-- `CANDLE_HYPERLIQUID_BUILDER` / `CANDLE_HYPERLIQUID_NETWORK` -- the perps tools: pin Candle's
-  Hyperliquid builder address for the pre-sign check, and set `testnet` to trade testnet.
+- `CANDLE_HYPERLIQUID_BUILDER` / `CANDLE_HYPERLIQUID_NETWORK` -- the perps tools: the builder override deliberately
+  replaces this release's trust anchor with a nonzero EVM address and is shown in
+  `preview.builderTrust`. Unset uses the release pin, never the API's builder. Set the network
+  to `testnet` to trade testnet.
 - `CANDLE_API_KEY` -- alias for `CANDLE_AGENT_API_KEY`, the same variable name the Candle CLI uses
   for this credential. Set either one; if both are set, `CANDLE_AGENT_API_KEY` takes precedence.
 
@@ -137,9 +139,21 @@ tools, getting a key, funding the embedded wallet, and idempotent retries, see
 | `candle_perps_close` | Close all or part of a perps position, reduce-only | `POST /api/v1/agent/perps/close`, the same | `CANDLE_AGENT_API_KEY` (`perps:write`), `CANDLE_KEY_SIGNER_PEM_FILE` |
 | `candle_perps_cancel` | Cancel a perps order Candle built, by cloid | `POST /api/v1/agent/perps/cancel`, the same | `CANDLE_AGENT_API_KEY` (`perps:write`), `CANDLE_KEY_SIGNER_PEM_FILE` |
 | `candle_perps_leverage` | Set a market's leverage and margin mode | `POST /api/v1/agent/perps/leverage`, the same | `CANDLE_AGENT_API_KEY` (`perps:write`), `CANDLE_KEY_SIGNER_PEM_FILE` |
+| `candle_perps_modify` | Change a resting order's price or size; side, time in force and reduce-only kept from Hyperliquid's record | `POST /api/v1/agent/perps/modify`, the same | `CANDLE_AGENT_API_KEY` (`perps:write`), `CANDLE_KEY_SIGNER_PEM_FILE` |
+| `candle_perps_margin` | Add isolated margin (positive only), or set a coin's margin mode keeping its leverage | `POST /api/v1/agent/perps/margin` or `/perps/leverage`, the same | `CANDLE_AGENT_API_KEY` (`perps:write`), `CANDLE_KEY_SIGNER_PEM_FILE` |
+| `candle_perps_tpsl` | Attach, move or remove position take-profit / stop-loss; a move cancels the old leg first | `GET` and `POST /api/v1/agent/perps/tpsl`, one checked step at a time | `CANDLE_AGENT_API_KEY` (`perps:write`), `CANDLE_KEY_SIGNER_PEM_FILE` |
+| `candle_perps_schedule_cancel` | Set or clear Hyperliquid's wallet-wide cancel-all timer | `POST /api/v1/agent/perps/schedule-cancel`, the same, then `/schedule-cancel/ack` | `CANDLE_AGENT_API_KEY` (`perps:write`), `CANDLE_KEY_SIGNER_PEM_FILE` |
+| `candle_perps_flatten` | Cancel every main-perp order, then close every main-perp position; at most 100 signed steps a call | `POST /api/v1/agent/perps/flatten/cancel` and `/perps/close`, one checked step at a time | `CANDLE_AGENT_API_KEY` (`perps:write`), `CANDLE_KEY_SIGNER_PEM_FILE` |
+| `candle_perps_reduce_only` | Read this key's reduce-only setting, or turn it on (never off) | `GET` / `PUT /api/v1/agent/keys/self/perps-reduce-only` | `CANDLE_AGENT_API_KEY` |
 | `candle_perps_deposit` | Deposit onto the key's Hyperliquid account through Relay, from its Solana or Hood TEE wallet | `POST /api/v1/agent/perps/deposit`, checked here, relay-signed, `POST /api/v1/agent/perps/deposit/submit` | `CANDLE_AGENT_API_KEY` (`swap:write`), `CANDLE_KEY_SIGNER_PEM_FILE` |
 | `candle_perps_orders` | Open Hyperliquid orders and every action Candle built | `GET /api/v1/agent/perps/orders` | `CANDLE_AGENT_API_KEY` |
-| `candle_perps_positions` | Perps positions and account value, read live | `GET /api/v1/agent/perps/positions` | `CANDLE_AGENT_API_KEY` |
+| `candle_perps_positions` | Perps positions and account value, read live, with the per-position table, account line and risk | `GET /api/v1/agent/perps/positions`, then Hyperliquid `/info` directly | `CANDLE_AGENT_API_KEY` |
+| `candle_perps_account` | The Hyperliquid account line and recent realized P&L, fees and funding | Hyperliquid `/info` directly; wallet and thresholds from Candle | `CANDLE_AGENT_API_KEY` |
+| `candle_perps_risk` | The liquidation risk level (ok, warn, critical) and what drives it; poll it to watch | Hyperliquid `/info` directly; wallet and thresholds from Candle | `CANDLE_AGENT_API_KEY` |
+| `candle_perps_thresholds` | The key's stored and effective risk thresholds | `GET /api/v1/agent/keys/self/limits` | `CANDLE_AGENT_API_KEY` |
+| `candle_perps_set_thresholds` | Tighten the key's own risk thresholds (never loosen) | `PUT /api/v1/agent/keys/self/perps-risk` | `CANDLE_AGENT_API_KEY` |
+| `candle_perps_fills` | One page of the wallet's perp fills, read directly from Hyperliquid | Hyperliquid `/info` (`userFillsByTime`); Candle only lists the key's wallets | `CANDLE_AGENT_API_KEY` |
+| `candle_perps_funding` | One page of the wallet's funding payments, read directly from Hyperliquid | Hyperliquid `/info` (`userFunding`); Candle only lists the key's wallets | `CANDLE_AGENT_API_KEY` |
 
 ### Launching with an image file
 
@@ -185,7 +199,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
-forty-two tools:
+fifty-four tools:
 
 - `candle_launch_token`, `candle_get_market`, and `candle_get_feed` hit endpoints that use the
   structured envelope `{ success: false, error: { code, message, ... } }`. Branch on `error.code`.
@@ -324,3 +338,24 @@ writes MOVE REAL FUNDS. Linked/TEE builds return bytes for signing and SDK submi
 Reward claims pay only the recorded owner and resolve the same signature when retried.
 
 Public page editing is on by default for new keys and existing absent-field keys; explicit denial stays off. Only a signed-in Privy session can restore a denied permission. Read keys and hosted Read connections never get `candle_update_profile`, `candle_create_post` or `candle_delete_post`. Discovery refreshes permission and the admin lock; direct calls still enforce both. SDK/CLI/local MCP additions are unreleased source until the next npm release.
+
+## Hyperliquid market reads (local clients)
+
+These are in `@candledottv/mcp` 0.10.19, `@candledottv/cli` 0.11.33 and `@candledottv/agent-sdk` 0.6.3.
+
+A configured Candle agent key of any scope is required; no wallet, signer, or `perps:write` is needed. Without a key, these reads fail with `PERPS_KEY_REQUIRED` before any request. Market data goes directly from your machine to Hyperliquid's public `/info`; only the gate configuration is read from Candle's `/api/v1/agent/perps/config`.
+
+| CLI (all support `--json`) | Local MCP tool | SDK method |
+| --- | --- | --- |
+| `candle perps markets [--sort <metric>] [--limit <1-500>] [--all]` | `candle_perps_markets({ sort?, limit?, all? })` | `client.perpsMarkets(opts)` |
+| `candle perps market <coin>` | `candle_perps_market({ coin })` | `client.perpsMarket(coin)` |
+| `candle perps book <coin> [--depth <1-20>] [--sig-figs <2-5>]` | `candle_perps_book({ coin, depth?, sigFigs? })` | `client.perpsBook(coin, opts)` |
+| `candle perps candles <coin> [--interval <i>] [--count <1-5000>] [--end <time>]` | `candle_perps_candles({ coin, interval?, count?, end? })` | `client.perpsCandles(coin, opts)` |
+
+`markets` defaults to all markets Candle's build gate allows, descending by 24-hour notional volume; `--all` includes refused markets with reasons. `--sort` accepts `volume`, `oi`, `funding`, `change` or `name`. Name sorting is ascending; the other sorts are descending. Funding is hourly (four decimal places for %/h); APR is a simple annualization, not a forecast. OI caps are reported separately: Hyperliquid can reject OI-increasing or overly aggressive orders at the cap even when `candle.tradeable` is true. Tradeability is the build gate at read time, not a promise of execution. On a server/client network mismatch it is `null` (`networkMismatch`), and rows remain visible so you can inspect the selected network.
+
+`market` adds margin tiers, impact prices and size/price rules. `book` defaults to 20 levels per side and reports spread and mid; aggregation passes `nSigFigs` to Hyperliquid. `candles` defaults to `1h` and 100 candles, oldest first. Intervals: `1m 3m 5m 15m 30m 1h 2h 4h 8h 12h 1d 3d 1w 1M`. End time is ISO 8601 or epoch milliseconds, no later than now. The requested window is `[end - count * interval, end]`, using 31 days per `1M` step, trimmed to the newest count. Returned volume is base volume.
+
+Every JSON result carries `network`, epoch-ms `readAt`, `gate: { minOpenInterestUsd, source }`, and `warnings`. Decimals are strings; USD display values use two decimals. The config is read once per SDK client/local MCP configuration (once per CLI command). If unavailable, the OI floor falls back to 1,000,000 USD, labeled `gate.source: "default"` with a warning. Predicted-funding or OI-cap failures produce null fields and warnings; core Hyperliquid failures give retryable `PERPS_UNAVAILABLE`. Unknown or ambiguous coins give `PERPS_MARKET_NOT_FOUND`. The CLI exits 0 on success (including warnings), 1 on runtime failure, 2 on usage error.
+
+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.