opindex-agent 0.1.0 → 0.2.1

package/README.md

@@ -4,7 +4,7 @@ An agent's own Solana wallet, token risk answers it pays for over x402, and
 swaps it signs itself.
 
 Two ways in. `src/` is a library for an agent that does not speak MCP; `mcp/`
-is the same library behind seven tools for a host that does.
+is the same library behind ten tools for a host that does.
 
 ## Install (as an MCP server)
 
@@ -14,14 +14,19 @@ No configuration is required. Add it to your agent host's MCP config:
 {
   "mcpServers": {
     "opindex": {
-      "command": "node",
-      "args": ["/absolute/path/to/opindex-agent/mcp/server.mjs"]
+      "command": "npx",
+      "args": ["-y", "opindex-agent"]
     }
   }
 }
 ```
 
-Run `npm install` in this directory first.
+That is the whole installation — `npx` fetches the package on first run. To work
+from a clone instead, point `command` at `node` and `args` at
+`/absolute/path/to/opindex-agent/mcp/server.mjs`, and run `npm install` here first.
+
+Then ask your agent to call `agent_wallet`. The key is created on first use, and
+the answer carries the address to fund.
 
 The skill in `skills/opindex-trading/SKILL.md` teaches an agent the order to
 use the tools in. Load it the way your host loads skills; without it the tool

package/mcp/server.mjs

@@ -33,6 +33,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
 import { PublicKey, VersionedTransaction } from '@solana/web3.js';
 import {
   createAssociatedTokenAccountIdempotentInstruction,
@@ -47,9 +48,20 @@ import { wallet } from '../src/wallet.mjs';
 import { connection, returnAddress, rpcSource } from '../src/returns.mjs';
 
 const USDC = new PublicKey('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v');
+
+/**
+ * The version that is actually running, read from the package that shipped it.
+ *
+ * Hosts install this with `npx` or with `npm install -g`, and the second never
+ * updates itself. A stale client looks exactly like a current one from inside
+ * a conversation -- fewer tools, older descriptions -- so `agent_wallet` says
+ * which one this is, and the person can compare it with npm's latest.
+ */
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 const PUBLIC_RPC = 'https://api.mainnet-beta.solana.com';
 
 const mint = z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/, 'a base58 Solana mint address');
+const amountUsd = z.number().int().min(1).max(1_000_000);
 const amountBase = z
   .string()
   .regex(/^[1-9][0-9]*$/, 'base units as a decimal string, no leading zero, non-zero');
@@ -67,11 +79,23 @@ const built = new Map();
 const ok = (value) => ({ content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] });
 const refuse = (value) => ({ content: [{ type: 'text', text: JSON.stringify(value, null, 2) }], isError: true });
 
-/** A paid call to one of the service's HTTP routes, through its MCP pointer. */
-async function paid(tool, args, { method, body } = {}) {
+/**
+ * A paid call to one of the service's HTTP routes, through its MCP pointer.
+ *
+ * The pointer names the route and nothing else: the service writes the mint
+ * into the path and leaves every query parameter out. So `query` is appended
+ * here, after the pointer arrives. Without it an `amount_usd` given to
+ * `assess_token` was dropped on the way, and the answer silently came back
+ * without the exit cost at that size.
+ */
+async function paid(tool, args, { method, body, query } = {}) {
   const pointer = await resolvePointer(tool, args);
+  const url = new URL(pointer.url);
+  for (const [key, value] of Object.entries(query ?? {})) {
+    if (value !== undefined) url.searchParams.set(key, String(value));
+  }
   const payingCall = await payingFetch();
-  const response = await payingCall(pointer.url, {
+  const response = await payingCall(url.toString(), {
     method: method ?? pointer.method,
     ...(body ? { headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) } : {}),
   });
@@ -85,7 +109,7 @@ async function paid(tool, args, { method, body } = {}) {
   return { status: response.status, body: parsed, paid: response.headers.has('payment-response') };
 }
 
-const server = new McpServer({ name: 'opindex', version: '0.1.0' });
+const server = new McpServer({ name: 'opindex', version: VERSION });
 
 // ---------------------------------------------------------------- free tools
 
@@ -98,7 +122,12 @@ server.registerTool(
       'Call this first: it tells you the address to ask your human to fund, and whether the agent is able to pay at all. ' +
       'Fund with USDC before SOL — a USDC transfer creates the token account the payment scheme needs, and the scheme ' +
       'cannot create it. Read `return_address` and check it is your human\'s own wallet: if they funded from an exchange, ' +
-      'it is the exchange\'s hot wallet and returning funds there can lose them.',
+      'it is the exchange\'s hot wallet and returning funds there can lose them. ' +
+      'Before the first trade, ask your human for the limits and the risk: money at risk, size of one trade, the loss ' +
+      'at which you stop, which levels are acceptable (no_flags < caution < unknown < risky) and whether you may ' +
+      'acknowledge them yourself, the most an exit may cost, when to exit, where candidates come from, and whether to ' +
+      'confirm each trade. Say them back and keep to them: this client enforces none of them, and the amount funded ' +
+      'is the only limit anything enforces.',
     inputSchema: {},
     annotations: { readOnlyHint: true, openWorldHint: true },
   },
@@ -131,6 +160,10 @@ server.registerTool(
         ? `derived from the chain: the first USDC transfer in, ${ret.signature}`
         : ret.why,
       rpc: rpcSource(),
+      client_version: VERSION,
+      client_update:
+        'Compare client_version with `npm view opindex-agent version`. Installed globally (command `opindex-mcp`), ' +
+        'it never updates itself: `npm install -g opindex-agent@latest`, then restart the host.',
       note:
         'The agent needs no SOL to pay for answers — the service\'s facilitator pays that network fee. ' +
         'SOL is for the swaps the agent signs itself.',
@@ -178,11 +211,11 @@ for (const [name, tool, price, freshness] of [
         'exit cost and liquidity are what a trade depends on and those are exactly the fields that go stale. ' +
         'The answer carries provenance on every field and `meta.partial` when something could not be measured; ' +
         'an unmeasurable number is null, never a small number.',
-      inputSchema: { mint, amount_usd: z.number().positive().optional() },
+      inputSchema: { mint, amount_usd: amountUsd.optional() },
       annotations: { readOnlyHint: true, openWorldHint: true },
     },
     async ({ mint: m, amount_usd }) => {
-      const { status, body, paid: wasPaid } = await paid(tool, { mint: m, ...(amount_usd ? { amount_usd } : {}) });
+      const { status, body, paid: wasPaid } = await paid(tool, { mint: m }, { query: { amount_usd } });
       if (status !== 200) return refuse({ status, charged: wasPaid, ...body });
       return ok({ ...body, _charged: wasPaid ? price : 'not charged' });
     },
@@ -204,7 +237,9 @@ server.registerTool(
       '  not_built — a named reason; no transaction exists.\n' +
       '  unassessable — the risk could not be established, so nothing was built and nothing was charged.\n' +
       'The raw transaction is deliberately not returned: `submit_swap` takes the `swap_id` so that no transaction from ' +
-      'anywhere else can be submitted through this agent.',
+      'anywhere else can be submitted through this agent.\n' +
+      'Build only within the limits your human set (see `agent_wallet`). If none were set, ask for them before ' +
+      'building: this costs money on every call, refusals included.',
     inputSchema: {
       input_mint: mint,
       output_mint: mint,
@@ -236,6 +271,95 @@ server.registerTool(
   },
 );
 
+// ---------------------------------------------------------- trading data
+//
+// Three routes served from the service's own samples of the tokens it watches.
+// Each answer says how it was sampled and how much of the market it covers;
+// none of them says what to buy.
+const samplesNote =
+  'Served from the service\'s own samples of the chain, about once a minute, not from a transaction feed. ' +
+  '`404 NO_HISTORY` means not sampled yet: free, ask again in a minute. `404 NOT_WATCHED` is free too; do not loop on ' +
+  'it. Data only, not investment advice.';
+
+/** One of the three data routes: paid, and a free 404 is said to be free. */
+async function sampled(tool, args, query, price) {
+  const { status, body, paid: wasPaid } = await paid(tool, args, { query });
+  if (status !== 200) return refuse({ status, charged: wasPaid, ...body });
+  return ok({ ...body, _charged: wasPaid ? price : 'not charged' });
+}
+
+server.registerTool(
+  'screen_tokens',
+  {
+    title: 'Watched tokens that meet your conditions ($0.02, paid from the wallet)',
+    description:
+      'PAID: $0.02 in USDC from this agent\'s wallet, an empty list included. The tokens this service watches that pass ' +
+      'the conditions YOU give, each with why it is included. `meta.coverage` says how many are watched: the list is ' +
+      'not the whole market, and there is no ranking by anyone\'s opinion; `sort` is one measurable field. Use your ' +
+      'human\'s limits as the conditions: `max_level`, `max_exit_cost_bps` at `amount_usd`, `min_liquidity_usd`. ' +
+      'A condition whose value could not be measured is not met. ' +
+      samplesNote,
+    inputSchema: {
+      max_level: z.enum(['no_flags', 'caution']).optional(),
+      min_liquidity_usd: z.number().positive().optional(),
+      max_exit_cost_bps: z.number().int().nonnegative().optional().describe('needs amount_usd'),
+      amount_usd: amountUsd.optional(),
+      min_age_hours: z.number().int().nonnegative().optional(),
+      quote: z.enum(['sol', 'usdc', 'any']).optional(),
+      sort: z
+        .enum(['liquidity', 'price_change_1h', 'price_change_24h', 'flow_1h', 'liquidity_change_24h', 'curve_progress'])
+        .optional(),
+      limit: z.number().int().min(1).max(50).optional(),
+      cursor: z.string().optional().describe('next_cursor of the previous page, with the same conditions'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  },
+  async (query) => sampled('screen_tokens', {}, query, '$0.02'),
+);
+
+server.registerTool(
+  'token_history',
+  {
+    title: 'Sampled price, liquidity and holders of a token ($0.01, paid from the wallet)',
+    description:
+      'PAID: $0.01 in USDC from this agent\'s wallet. Candles, liquidity, reserve flow and holder concentration of one ' +
+      'token over a window, made of samples (`sampling.method: reserve_snapshot`): a minute with no sample has no candle. ' +
+      '`reserve_flow` is classed swap_like, deposit_like, withdrawal_like or quiet: what the reserves looked like, ' +
+      'never trade volume. A paid call on a token nobody watches puts it on watch. ' +
+      samplesNote,
+    inputSchema: {
+      mint,
+      window: z.enum(['1h', '6h', '24h', '7d']).optional(),
+      resolution: z.enum(['1m', '5m', '15m', '1h']).optional(),
+      pool: mint.optional().describe('one pool of this mint, to read that pool rather than the watched one'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  },
+  async ({ mint: m, ...query }) => sampled('token_history', { mint: m }, query, '$0.01'),
+);
+
+server.registerTool(
+  'token_indicators',
+  {
+    title: 'Indicators for one token, and your position in it ($0.01, paid from the wallet)',
+    description:
+      'PAID: $0.01 in USDC from this agent\'s wallet. Numbers with formulas for one watched token: price and liquidity ' +
+      'change, drawdown, volatility, reserve flow, holder and safety changes, and exit cost at `amount_usd`. Give ' +
+      '`entry_price_usd` and `position_base_units` together to get your position; it reads nothing of your wallet. ' +
+      'Read `safety_changes_24h` first when you hold the token. A number that cannot be computed is null, never zero. ' +
+      'This route never puts a token on watch: on `NO_HISTORY` for a token nobody watches, call `token_history` first. ' +
+      samplesNote,
+    inputSchema: {
+      mint,
+      amount_usd: amountUsd.optional(),
+      entry_price_usd: z.number().positive().optional(),
+      position_base_units: amountBase.optional(),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  },
+  async ({ mint: m, ...query }) => sampled('token_indicators', { mint: m }, query, '$0.01'),
+);
+
 // ------------------------------------------------------------ signing tools
 
 server.registerTool(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opindex-agent",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "An agent's Solana wallet, token risk answers paid for over x402, and swaps it signs itself. Library plus an MCP server.",
   "license": "MIT",
   "author": "MONOLITH LABS LTD <info@monolithlabs.uk>",

package/skills/opindex-trading/SKILL.md

@@ -5,29 +5,42 @@ description: Use when trading Solana SPL tokens, or when asked whether a token i
 
 # Trading Solana tokens through opindex
 
-You have a wallet of your own and seven tools. Three are free, three cost USDC
+You have a wallet of your own and ten tools. Two are free reads, six cost USDC
 from that wallet, and two move money. This explains the order to use them in
 and the things that will cost your human money if you get them wrong.
 
 ## What this service does not answer
 
 Before anything else, so you do not build a plan on it: **this service does not
-tell you what to buy or when.**
-
-- **No discovery.** You must already know the mint. There is no screener, no
-  ranking, nothing that says what is moving.
-- **No history.** No candles, no volume, no price change. Every market field is
-  a single point in time, so nothing here shows direction.
-- **No position.** It does not know what you hold, what you paid, or what you
-  are up or down.
-
-What it is: a filter and a cost model. It tells you which tokens not to touch,
-and what leaving one costs at the size you actually hold — which is what sizes
-a position, not what picks it. That is a necessary input to a trade and not a
-sufficient one, so you need a second source for candidates and for timing.
+tell you what to hold or when to act.** It gives you numbers and says how they
+were measured; the decision is yours.
+
+- **Discovery exists only among tokens the service already watches.**
+  `screen` lists the watched tokens that pass the conditions *you* give it, and
+  `meta.coverage` says how many tokens are watched, how many passed and where
+  the set came from. It is not the market: a token missing from a screen may
+  simply not be watched. There is no ranking by our opinion; `sort` is one
+  measurable field.
+- **History is by samples.** `history` and `indicators` come from readings the
+  service takes of a pool about once a minute and of its holders about once an
+  hour. `sampling.method` says so: `reserve_snapshot`. A candle is a candle over
+  samples. A minute with no sample has no candle. There is no transaction feed
+  behind any of it.
+- **Position is by your data.** It does not know what you hold or what you paid.
+  Give `indicators` your `entry_price_usd` and `position_base_units` and it will
+  compute from those two numbers and nothing else; it reads nothing of your
+  wallet.
+
+What it is: a filter, a cost model and a record of how a pool's reserves moved.
+It tells you which tokens not to touch, what leaving one costs at the size you
+actually hold, and what has changed since you looked. That is an input to a
+decision and not the decision, and not a source of candidates beyond the watched
+set or of timing beyond the samples.
 
 If your human expects you to trade profitably using only this, say so plainly
-before you start rather than after.
+before you start rather than after. Then do not stop there: if they still want
+you to trade, the decision is theirs to delegate, and the next step is agreeing
+the limits with them (below), not declining.
 
 ## Start with the wallet, before anything else
 
@@ -48,6 +61,38 @@ Two things in its answer matter more than the balances:
 You need **no SOL to pay for answers** — the service's facilitator pays that
 network fee. You need SOL only for swaps you sign yourself.
 
+## Before the first trade, agree the limits and the risk
+
+Funding you is not a decision about what to do with the money. Before your first
+trade, ask your human for the following, and do not trade until they have
+answered. Ask only for what they have not already said. If they say "you
+decide", propose numbers yourself and have them confirm: a limit they confirmed
+is theirs, one you assumed is not.
+
+1. **Money at risk.** All of the wallet, or how much of it.
+2. **Size of one trade.** In USD, or as a share of the money at risk.
+3. **When to stop.** The loss on the money at risk after which you stop trading
+   and report, instead of trading to win it back.
+4. **Which risk levels are acceptable**, in this service's words: only
+   `no_flags`; or `caution` too, and then whether any factor is still off limits
+   (`freeze_authority_active`, say); `unknown` and `risky` only if they name
+   them. And whether you may acknowledge an allowed level yourself, or must ask
+   each time.
+5. **Exit cost.** The most leaving may cost at the trade's size
+   (`exit_cost_for_amount`) before you will not enter. `null` is unknown and
+   fails this check.
+6. **When to exit a position.** A gain to take, a loss to cut, or a time after
+   which you leave anyway.
+7. **Where candidates come from.** Only mints they give you, or also ones you
+   find, and from where.
+8. **Confirmation.** Ask before each trade, or trade within these limits and
+   report after.
+
+Say the answers back as one short list and keep to it. **These limits are yours
+to keep: the client enforces none of them.** The amount funded is the only limit
+anything enforces, so tell your human that too. If a trade would break a limit,
+do not make it; say which limit and ask. Changing a limit is their call.
+
 ## Never trade on a free answer
 
 `token_identity` is free and may be up to a day stale. That is fine for "what is
@@ -62,15 +107,22 @@ half-cent.
 
 ## Read the verdict properly, not just the level
 
-`heuristic.level` is `no_flags`, `caution`, `unknown` or `risky`. **Read
+`heuristic.level` is `no_flags`, `caution`, `unknown` or `risky`; a factor's `severity` is `risky`, `caution` or `info`. **Read
 `heuristic.factors` even when the level is calm.** A trusted issuer gets a quiet
 level while the facts still say what they say: USDC comes back `no_flags` with
 `mint_authority_active` and `freeze_authority_active` both marked risky, because
 its issuer really can mint and really can freeze your account. The level is not
 a promise; the factors are the evidence.
 
-Two more habits worth having:
+Three more habits worth having:
 
+- **`info` is a fact that, for a mature token, does not raise the level.** Read
+  it if you hold a position: `lp_not_burned`, `metadata_mutable` and
+  `holder_concentration` still say what they say. `heuristic.maturity` shows
+  why the token counted as mature (liquidity, age since this service first saw
+  it, and who holds its LP). A token not yet mature, including every token in
+  the first 30 days of the service seeing it, keeps these as `caution`. The
+  default `screen` filter `max_level=no_flags` now lists mature tokens.
 - **`unknown` outranks `caution`.** An unnamed gap can hide anything, so treat
   it as worse than a named mild finding, never better.
 - **A null is not a small number.** `null` means the service could not measure
@@ -98,10 +150,77 @@ price of the assessment behind it, not a bug. So read the factors before you
 re-send: if you are going to decline the trade anyway, decline it now rather
 than paying twice to arrive there.
 
-**Before you acknowledge, tell your human what you are accepting.** Name the
-factors, not the level. "This token's LP is not burned and a transfer hook can
+**Before you acknowledge, tell your human what you are accepting**, unless they
+already allowed that level in the limits you agreed; then acknowledge and name
+the factors in your report. Either way, name the factors, not the level. "This token's LP is not burned and a transfer hook can
 still be set on it" is a sentence they can judge. "Level: caution" is not.
 
+## How to read `*_like`
+
+`history.reserve_flow` and `indicators.flow` classify each interval between two
+samples by the signs of how both vaults of the pool moved:
+
+- **`swap_like`** — the two moved in opposite directions. At least one swap
+  happened in that minute, and its size is a **net**, not a turnover.
+- **`deposit_like`** — neither shrank (both deltas ≥ 0, not both zero). Looks
+  like liquidity added.
+- **`withdrawal_like`** — neither grew (both deltas ≤ 0, not both zero). Looks
+  like liquidity removed, and may hide swaps.
+- **`quiet`** — neither moved.
+
+The suffix is the point. A minute can hold a swap and a deposit together, so the
+class says what the reserves *looked like*, never what happened. The note on the
+field says the same: deltas of the quote vault, classified by the signs of both
+vault deltas, **not trade volume**. Never turn `quote_net` into a count of
+transactions or a size of activity, and never report it as one.
+
+A hole in the samples is not a `quiet` pool: across a gap no interval exists.
+`sampling.gaps` counts them, and a number that could not be measured is `null`
+with `meta.partial: true`, never zero.
+
+## `404 NO_HISTORY` is free: wait a minute
+
+`history` and `indicators` answer `404 NO_HISTORY` when the service has fewer than
+two samples of that token. It is a client error, **it is not charged**, and it
+is not a failure: it is the start of an answer.
+
+- `history` on a token nobody watches asks the service to start watching it,
+  when the request was a paying one. Ask again in a minute.
+- `indicators` never starts a watch. If it says `NO_HISTORY` for a token that
+  nobody watches, call `history` first, then `indicators`.
+- `404 NOT_WATCHED` means the pool you named is not that token's watched pool, or
+  its watch has ended. Asking again does not change that; do not loop on it.
+- `404 NOT_WATCHED` from all three routes, `screen` included, with "the watcher
+  is not running on this deployment" means that deployment collects nothing.
+  It is free; do not retry it there.
+
+Do not retry faster than once a minute, and do not read a `NO_HISTORY` as "this
+token has no history": it means "not yet sampled".
+
+## Indicators are numbers, not advice
+
+Every answer ends `"disclaimer": "Data only, not investment advice."`, and it
+means it. There is no rating, no action field and no ranking by our opinion.
+What there is, is a number with a formula (`docs/API.md`, "The trading-data
+routes") that you can recompute.
+
+- Say what the number is and how it was measured when you report it to your
+  human: "liquidity fell 18% in one sample interval, which looks like a
+  withdrawal", not "the pool is being rugged".
+- `price.change` is over *sampled closes* and is `null` when there is no sample
+  of the right age. A `null` is not "no change".
+- `exit.cost_now_bps_at_amount` on a bonding curve is `null` (`basis:
+  curve_not_sampled`): the curve's exit is not costed from samples. Ask
+  `assess_token_live` when you need a cost you can act on.
+- `holders.top10_share_now` leaves the pool's own accounts out and is **not** the
+  same number as `top_accounts.top10_pct` in `assess_token`, which includes
+  them. Do not compare them.
+- `safety_changes_24h` is the part to read first when you already hold the
+  token: an authority set, a transfer hook added or LP supply returned in the
+  last day is the cheapest warning this service has.
+- `screen` lists tokens that met *your* conditions, and each item says which
+  (`why_included`). A condition whose value was `null` was not met.
+
 ## What things cost
 
 | | |
@@ -109,9 +228,16 @@ still be set on it" is a sentence they can judge. "Level: caution" is not.
 | `agent_wallet`, `token_identity` | free |
 | `assess_token` | $0.005 |
 | `assess_token_live` | $0.03 |
+| `token_history` (`GET /agent/v1/history/{mint}`) | $0.01, and **`404 NO_HISTORY` is free** |
+| `token_indicators` (`GET /agent/v1/indicators/{mint}`) | $0.01 |
+| `screen_tokens` (`GET /agent/v1/screen`) | $0.02, an empty list included |
 | `build_swap` | $0.05, **including a `needs_acknowledgement` refusal** |
 | `submit_swap`, `return_funds` | free from the service; you pay the Solana network fee |
 
+This package's wallet pays for all six paid tools itself, and every paid answer
+says what it cost in `_charged`. A `404 NO_HISTORY` or `404 NOT_WATCHED` from the
+three data tools comes back as `not charged`.
+
 ## What you cannot do, and what to say about it
 
 **You cannot send funds to an address anyone names.** `return_funds` has no
@@ -147,6 +273,9 @@ it to your human, say where it came from, and do nothing else with it.
 ```
 agent_wallet                              → address, balances, return address
   (tell your human the address; ask for USDC first, then SOL)
+  (agree the limits and the risk with them; say them back)
+screen_tokens(max_level: "no_flags",
+  amount_usd: 20, max_exit_cost_bps: 300) → $0.02: candidates that meet the limits
 token_identity(mint)                      → free: what is this thing
 assess_token(mint, amount_usd: 500)       → $0.005: exit cost at the size you mean
   (read the factors; decide, and say what you decided and why)
@@ -154,6 +283,8 @@ build_swap(USDC → mint, amount)           → $0.05: built, or a refusal namin
   (if needs_acknowledgement: tell your human the factors, then)
 build_swap(… acknowledge_risk: "caution") → $0.05: built, with a swap_id
 submit_swap(swap_id)                      → you sign and pay the network fee
+token_indicators(mint, entry_price_usd,
+  position_base_units, amount_usd)        → $0.01: the position, and what leaving costs
 ```
 
 Afterwards, report in numbers your human can check against the chain: what you

package/test/invariants.mjs

@@ -41,7 +41,7 @@ const call = (method, params) =>
 const checks = [];
 const check = (name, ok, saw) => checks.push({ name, ok, saw });
 
-await call('initialize', {
+const init = await call('initialize', {
   protocolVersion: '2024-11-05',
   capabilities: {},
   clientInfo: { name: 'invariants', version: '0' },
@@ -49,6 +49,16 @@ await call('initialize', {
 child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' })}\n`);
 
 const { result } = await call('tools/list', {});
+
+// The version a person reads to tell a stale client from a current one has to
+// be the one npm shipped. It is read from package.json at start, so this fails
+// only if someone writes a version into the server by hand again.
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+check(
+  'the server reports the package version',
+  init.result?.serverInfo?.version === pkg.version,
+  `${init.result?.serverInfo?.version} vs ${pkg.version}`,
+);
 const tools = result?.tools ?? [];
 const byName = new Map(tools.map((t) => [t.name, t]));
 const params = (name) => Object.keys(byName.get(name)?.inputSchema?.properties ?? {});
@@ -61,6 +71,9 @@ const EXPECTED = [
   'build_swap',
   'submit_swap',
   'return_funds',
+  'screen_tokens',
+  'token_history',
+  'token_indicators',
 ];
 check('every tool is present', EXPECTED.every((n) => byName.has(n)), tools.map((t) => t.name).join(', '));
 
@@ -101,7 +114,7 @@ for (const name of ['submit_swap', 'return_funds']) {
 
 // The paid tools have to say so in words a model will read, because being
 // charged without warning is the complaint that ends an integration.
-for (const name of ['assess_token', 'assess_token_live', 'build_swap']) {
+for (const name of ['assess_token', 'assess_token_live', 'build_swap', 'screen_tokens', 'token_history', 'token_indicators']) {
   check(`${name} says it is paid`, (byName.get(name)?.description ?? '').includes('PAID'), 'description');
 }
 
@@ -124,7 +137,14 @@ check('the skill mentions every tool', missingFromSkill.length === 0, missingFro
 // the skill proves nothing about a document that mentions prices in several
 // places: a wrong price in the table passes while the right one still stands
 // in a worked example below.
-const PRICES = { assess_token: '$0.005', assess_token_live: '$0.03', build_swap: '$0.05' };
+const PRICES = {
+  assess_token: '$0.005',
+  assess_token_live: '$0.03',
+  build_swap: '$0.05',
+  screen_tokens: '$0.02',
+  token_history: '$0.01',
+  token_indicators: '$0.01',
+};
 const expectedPrices = new Set(Object.values(PRICES));
 
 for (const [tool, price] of Object.entries(PRICES)) {
@@ -155,7 +175,6 @@ check(
 // starts with `./` — and says so in a warning that prints the normalised path,
 // which is the valid form, so the message points at a string that is fine.
 // That cost one failed publish; it costs nothing to pin.
-const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 const bins = Object.entries(pkg.bin ?? {});
 check('the package declares an executable', bins.length > 0, JSON.stringify(pkg.bin));
 for (const [name, target] of bins) {