@aifinpay/mcp 2.7.1 → 2.11.0

package/README.md

@@ -4,13 +4,60 @@ AiFinPay MCP server for persistent agent identity, Agent Passport resolution,
 route discovery and non-signing settlement invoices. Canonical domain:
 **aifinpay.io**.
 
-Version **2.7.1** is prepared in this checkout, requiring agent2.5.1 and canonical skill2.8.0.
+Version **2.11.0** is prepared in this checkout, on the published agent 2.8.0
+and canonical skill 2.10.0 (AiFinPay/skill 49c2e2a, published 2026-10-19). The separate canonical producer's final immutable
+source pin is a required handoff, not a moving-branch substitution.
 The published baseline checked2026-10-04 was MCP2.5.0. Package publication and
 real registry dependency/lock refresh remain release gates; a source-cohort
 build does not prove those steps. Owner-enabled v1.4 purchases with `payable_fetch` are
 released: on Polygon since 2.2.0, on Base (ETH or USDC) since 2.5.0; site-wide
-batches with `scope: "merchant"` since 2.4.1. Without payment configuration the server keeps
-its inspection-only tool inventory.
+batches with `scope: "merchant"` since 2.4.1. Without payment configuration the server
+lists every tool, including `payable_fetch`, but signs nothing: `payable_fetch`
+and `payment_setup_status` answer with the setup checklist instead.
+
+## First payment in five steps
+
+Each step is one command or one tool call. Signing happens only in step 5,
+and only once the owner has set every limit in step 4.
+
+1. **Read the price.** `GET` the resource. The `402` names the merchant
+   (`merchant_id`), the price per request and the smallest batch (`$0.10` for
+   200 standard requests).
+2. **Check the setup.** Call `payment_setup_status`. It returns the wallet
+   (persistent or ephemeral), whether payments are enabled, which owner limits
+   are set, the balance when the RPC answers, and `next_step`: the first thing
+   still missing.
+3. **Persistent wallet.** If `wallet.persistent` is false, run
+   `npx @aifinpay/mcp init`. Without a terminal it prints one JSON document;
+   copy its `env` (the passphrase is only there) into the `aifinpay` server
+   entry of the MCP client config, reconnect the server, then call
+   `agent_reload`. Never fund an ephemeral address.
+4. **Fund and enable.** Tell the owner `addresses.evm` and the amount: the
+   batch price in POL plus the gas cap, so about `0.5 POL` for one `$0.10`
+   batch at `$0.20`/POL plus up to `0.3 POL` gas (the SDK refuses before
+   signing if the worst-case fee exceeds the cap). When the owner confirms
+   funding, they add the payment settings to the same `env` and reconnect:
+
+   ```json
+   {
+     "AIFINPAY_PAYMENTS_ENABLED": "1",
+     "AIFINPAY_GATEWAY_ORIGINS": "https://dev.ratersapp.com",
+     "AIFINPAY_GATEWAY_PATH_MODE": "direct",
+     "AIFINPAY_MAX_USD": "0.15",
+     "AIFINPAY_DAILY_USD": "1.00",
+     "AIFINPAY_MAX_GAS_POL": "0.3"
+   }
+   ```
+
+   `payment_setup_status` then reports `ready: true`.
+
+5. **Pay.** `payable_fetch({"url": "https://dev.ratersapp.com/api/agent/genres/list"})`
+   buys the batch on Polygon (splitter v1.4) and returns the content and the
+   receipt summary. Later requests reuse the batch.
+
+Polygon and Base are served on v1.4 today; `settlement_routes` lists them
+first, with `live: true`. Its `legacy_v13` section describes the older
+splitter v1.3 routes, which `payable_fetch` does not use.
 
 ## Enable native paid GET requests
 
@@ -35,6 +82,23 @@ owner. `direct` uses the full path for self-hosted sites; `gateway` uses the
 merchant slug on the hosted gateway. Restart/reconnect the MCP process after
 changing its environment.
 
+## Indexed wallet derivation
+
+The wallet CLI and MCP can use deterministic child wallets from one recovery
+seed. Create an MCP-compatible wallet with
+`npx @aifinpay/wallet new --index 0`; the keystore retains the
+root seed and adds the index as optional metadata without changing existing
+fields. MCP uses that stored index automatically. To select another child in a different MCP
+process, set `AIFINPAY_WALLET_INDEX` to its decimal index; the same variable
+also applies when `SEED_HASH` or an `agents.json` record supplies the seed.
+
+Each chain derives its own indexed key; for example,
+`EVM = SHA-256("aifinpay:evm:v1\0" || decimalIndex || recoverySeed)` and
+`Solana = Ed25519(SHA-256("aifinpay:solana:v1\0" || decimalIndex || recoverySeed))`.
+The decimal UTF-8 index follows that chain's domain NUL separator. Index 0 is
+the first wallet. Indices must be between 0 and 4294967295. With no selected
+index, existing identities retain their current derivation.
+
 `AIFINPAY_MAX_GAS_POL` caps the worst case, not the fee you expect to pay.
 Before signing, the client prices the estimated gas plus 20% at the maximum fee
 per gas the Polygon RPC quotes, and refuses with `V14_GAS_BUDGET_EXCEEDED` if
@@ -104,6 +168,24 @@ then `api.coingecko.com`; other chains use those HTTP price sources.
 If none provides a valid fresh rate, `payable_fetch` stops before paying and
 the error names each host it tried.
 
+### Which AI client paid
+
+`payable_fetch` tells the merchant which AI client is paying: the server maps the
+`clientInfo.name` your MCP client sent at initialize to an `AIFP-Agent-Framework`
+header on the payment requests (and on recovery of a pending payment).
+
+| `clientInfo.name`          | `AIFP-Agent-Framework` |
+| -------------------------- | ---------------------- |
+| `claude-ai`, `claude-code` | `claude`               |
+| `cursor`, `cursor-vscode`  | `cursor`               |
+| `windsurf`                 | `windsurf`             |
+| `chatgpt`, `openai`        | `chatgpt`              |
+| `gemini`                   | `gemini`               |
+| `perplexity`               | `perplexity`           |
+
+Names are matched exactly. Any other client sends no header; the server never
+guesses. Nothing in the payment, limits or receipts depends on it.
+
 ## Link the agent to its owner's dashboard
 
 The owner sees the agent's balance, payments and receipts at
@@ -133,18 +215,31 @@ state file in chat. Unconfirmed payments consume the budget conservatively.
 | `agent_reload`           | Reload local wallet files in the current MCP connection. |
 | `agent_quota`            | Read the agent's quota.                                  |
 | `agent_passport_resolve` | Resolve the global Agent Passport identity.              |
-| `settlement_routes`      | Read the available verified settlement routes.           |
+| `payment_setup_status`   | Read-only setup checklist with the one `next_step`.      |
+| `settlement_routes`      | Splitter v1.4 routes (live now) first, then legacy v1.3. |
 | `settlement_invoice`     | Prepare a non-signing settlement invoice.                |
 | `agent_history`          | Read indexed settlements or retained receipt batches.    |
 | `settlement_solana`      | Build a non-signing Solana settlement invoice.           |
 | `settlement_casper`      | Build a non-signing Casper settlement invoice.           |
 | `deployment_info`        | Read deployments: addresses, assets, settlement status.  |
 
-`payable_fetch` is registered when the owner sets `AIFINPAY_PAYMENTS_ENABLED=1`
-with a persistent wallet. With payments enabled and any owner limit missing or
-invalid, the server refuses to start rather than hiding the tool. It accepts
-only `url`, `max_amount_usd` and `scope`; `max_amount_usd` can lower the owner's
-per-payment cap for one call, never raise it. `dev_payment_quote` is registered
+`payable_fetch` is always listed. It signs only with a persistent wallet,
+`AIFINPAY_PAYMENTS_ENABLED=1` and every owner limit; before that it returns the
+`payment_setup_status` checklist as a tool error and contacts nothing. With
+payments enabled and any owner limit missing or invalid, the server refuses to
+start rather than hiding the tool. It accepts
+only `url`, `max_amount_usd`, `scope` and `expected_merchant_id`; `max_amount_usd`
+can lower the owner's per-payment cap for one call, never raise it.
+
+Each gateway site (origin + slug) is pinned to the merchant this wallet first
+paid it as. The agent SDK keeps these pins under `~/.aifinpay/merchant-pins`, or
+`AIFINPAY_STATE_DIR/merchant-pins`; `AIFINPAY_HOME` does not move them. When a
+site answers as another merchant, `payable_fetch` stops before any quote and
+names both merchant ids. Nothing is paid, and the agent cannot approve the change
+itself. Once the owner confirms the new merchant, a call with
+`expected_merchant_id` set to it pays and re-pins the site. There is no blanket
+"allow any merchant change" argument. A `410 gateway_retired` site is terminal:
+the tool says not to retry. `dev_payment_quote` is registered
 only with `AIFINPAY_MODE=dev`. Legacy `agent_call`, `agent_quote`,
 `pay_with_split` and `quote_split` remain unregistered.
 
@@ -170,6 +265,41 @@ Invalid or ambiguous configured inputs fail; they never generate a replacement
 wallet. With no configured wallet at all the server has an ephemeral identity:
 **do not fund it**.
 
+### Embed an external EVM wallet
+
+An embedding host can pass a viem `WalletClient` directly to `createServer`.
+This is programmatic-only; `npx @aifinpay/mcp` and environment variables cannot
+carry a wallet client. Keep the existing local identity configured for Solana
+and other identity surfaces. When supplied, the client account becomes the EVM
+payment identity and the payment journal is keyed to that address. Its chain
+must match the owner-selected `AIFINPAY_PAY_CHAIN` (Polygon by default); the
+SDK refuses a mismatch rather than switching providers or falling back to the
+local EVM key.
+
+```ts
+import { createServer, loadConfigFromEnv } from "@aifinpay/mcp";
+import type { EvmWalletClient } from "@aifinpay/agent";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// Constructed by the host from its chosen external signer/provider.
+declare const walletClient: EvmWalletClient;
+
+const { server } = await createServer({
+  ...loadConfigFromEnv(),
+  evmWalletClient: walletClient,
+});
+await server.connect(new StdioServerTransport());
+```
+
+The host must provide a viem `LocalAccount` with `signTransaction`, bound to
+the selected chain. v1.4 persists exact signed transaction bytes before the
+SDK broadcasts them through its verified RPC; JSON-RPC/send-only and smart
+account clients are refused rather than bypassing durable recovery. MCP still
+applies its configured spending limits, runtime and route checks, receipt
+verification, and recovery. Changing the injected account while payment
+recovery is pending requires reconciliation and reconnecting; it is not a
+tool-level wallet switch.
+
 ## Initialize and connect
 
 A quote or invoice is not a completed payment. `payable_fetch` pays only with the
@@ -184,7 +314,33 @@ AIFINPAY_WALLET_PASSPHRASE='<a long passphrase>' npx @aifinpay/mcp init
 The keystore is encrypted at rest and the MCP server needs the same
 `AIFINPAY_WALLET_PASSPHRASE` to load it. For a disposable test wallet only,
 `npx @aifinpay/mcp init --plaintext` writes it unencrypted (mode 600); without
-either, `init` refuses rather than create an unencrypted wallet you might fund.
+either, `init` on a terminal refuses rather than create an unencrypted wallet
+you might fund.
+
+Without a terminal on stdin (an agent's subprocess), or with
+`AIFINPAY_NONINTERACTIVE=1`, `init` never prompts. It generates a 192-bit
+passphrase, encrypts the keystore and prints one JSON document:
+
+```json
+{
+  "keystore": "/home/me/.aifinpay/agent.json",
+  "created": true,
+  "encrypted": true,
+  "source": "legacy-keystore",
+  "addresses": { "evm": "0x…", "solana": "…", "casper": "account-hash-…" },
+  "env": { "AIFINPAY_WALLET_PASSPHRASE": "<generated>" },
+  "passphrase_note": "…",
+  "payment_env_example": { "AIFINPAY_PAYMENTS_ENABLED": "1", "…": "…" },
+  "next_step": "Put \"env\" into the aifinpay server entry of the MCP client config …"
+}
+```
+
+The passphrase appears only inside `env`, because the caller must put it in
+the client config and there is no other channel; a process that captures that
+output captures the passphrase, so treat the output as a secret. A second run
+keeps the wallet and prints a placeholder instead of the passphrase. If the
+keystore exists and `AIFINPAY_WALLET_PASSPHRASE` is unset, `init` prints one
+line naming the variable and exits with status 2.
 
 Select the wallet in this order: `SEED_HASH` → `./aifinpay/agents.json` →
 legacy `AIFINPAY_AGENT_SECRET` → `~/.aifinpay/agent.json`.
@@ -247,7 +403,7 @@ snapshot. Verify `agent_address` against the wallet you intend to use.
 | `AIFINPAY_MAX_USD`           | —                     | Per-payment USD cap for `payable_fetch`; required when payments are enabled.          |
 | `AIFINPAY_GATEWAY_ORIGINS`   | —                     | Comma-separated exact HTTPS origins the agent may pay; required with payments.        |
 | `AIFINPAY_GATEWAY_PATH_MODE` | `gateway`             | Use `gateway` for merchant-slug identity or `direct` for full request-path identity.  |
-| `AIFINPAY_PAY_CHAIN`         | `polygon`             | Owner-selected payment chain; see the2.7.1 source capability list.                    |
+| `AIFINPAY_PAY_CHAIN`         | `polygon`             | Owner-selected payment chain; see the2.8.1 source capability list.                    |
 | `AIFINPAY_MAX_GAS`           | —                     | Gas cap per payment in the pay chain's native currency (POL, ETH, AVAX, BNB, XRP).    |
 | `AIFINPAY_RPC_URL`           | chain's public RPC    | HTTPS RPC for the pay chain.                                                          |
 | `AIFINPAY_CLAIM_ORIGINS`     | AiFinPay dashboards   | Exact origins `agent_claim_self` may link the agent to.                               |
@@ -297,14 +453,14 @@ executor; this MCP does not expose Amoy paid receipt purchases.
 
 MIT.
 
-## Additional EVM networks in the 2.7.1 source candidate
+## Additional EVM networks in the 2.8.1 source candidate
 
 Owner `AIFINPAY_PAY_CHAIN` accepts polygon, base, optimism, arbitrum, avalanche,
 bnb, unichain, xrplevm and robinhood. `AIFINPAY_MAX_GAS` is in the selected native
 POL/ETH/AVAX/BNB/XRP currency; the legacy POL cap applies only on Polygon. Assets
 must be pinned for that chain, including BNB 18-decimal USDC/USDT and Robinhood
 18-decimal USDe/6-decimal USDG. XRPL EVM has native XRP only. Metadata comes from
-agent 2.5.1; the backend must still authorize and serve that merchant/network.
+agent 2.6.1; the backend must still authorize and serve that merchant/network.
 Source support does not activate networks in production. Pending journals retain
 the original chain and are recovered without another settlement. A legacy
 missing-chain journal is adopted only when the owner-configured chain and the
@@ -312,13 +468,14 @@ actual signed transaction's chain ID, payer, pinned target and exact call agree.
 Insufficient evidence requires manual receipt reconciliation. A later quote
 expiry does not invalidate receipt recovery for an existing payment.
 
-Release order: publish reviewed canonical skill2.8.0 and agent2.5.1, refresh MCP
+Release order after final release gates: publish reviewed canonical skill2.9.0 and agent2.6.1, refresh MCP
 dependencies and lock from those real registry releases, pass standalone MCP
-CI, then publish MCP2.7.1. Source-cohort validation requires fresh source-packed
-agent2.5.1 and skill2.8.0. The existing registry entries remain until publication;
+CI, then publish MCP2.8.0. This candidate requires fresh source-packed
+agent2.6.0 and skill2.9.0, plus the exact Python2.5.1 release target. The existing
+registry agent2.5.0 / skill2.8.0 entries remain until publication;
 no npm integrity/resolution is fabricated. An old2.3.x agent cannot build the
 new descriptor/helper imports, and old skill2.6.0 cannot satisfy the exact
-release-target guard. Hosted source CI uses `scripts/check-mcp-source-cohort.mjs`: a byte-preserving fixed registry bootstrap and genuine same-commit Node plus fully pinned canonical skill packages in disposable directories. Exact package bytes, versions, bundled skill and full tests must pass; the registry publication guard must still refuse this source cohort. Standalone release CI requires the refreshed real registry lock. Never publish the candidate with the old registry dependency lock.
+release-target guard. Hosted source CI uses `scripts/check-mcp-source-cohort.mjs`: a byte-preserving patched registry bootstrap and genuine same-commit Node plus fully pinned canonical skill packages in disposable directories. The Node producer's authoritative source lock seeds the genuine runtime; it is separate resolution evidence, since npm excludes it from the tarball. Exact package bytes, versions, bundled skill, high/critical audits and full tests must pass; the registry publication guard must still refuse a source cohort lacking a matching real registry lock. Standalone release CI requires the refreshed real registry lock. Never publish the candidate with the old registry dependency lock.
 
 Use one shared local filesystem for a wallet's ledger/journal and reconcile
 pending transactions before downgrading. Node 2.4 reservations never expire for

package/bin/aifinpay-mcp.js

@@ -75,16 +75,26 @@ if (arg === "--help" || arg === "-h" || arg === "help") {
 Run init once. It writes ${KEYSTORE} with mode 600 and the server picks
 it up automatically — you do not have to put the secret in a config file.
 
+Without a terminal on stdin (an agent's subprocess), or with
+AIFINPAY_NONINTERACTIVE=1, init never prompts: it generates the passphrase
+itself, encrypts the keystore and prints one JSON document with the keystore
+path, the public addresses and the exact "env" block for the MCP client config.
+
 Env (all optional):
-  SEED_HASH              32-byte hex seed; highest priority\n  AIFINPAY_AGENTS_FILE    default ./aifinpay/agents.json; second priority\n  AIFINPAY_AGENT_ID       select one record when the file has multiple agents\n  AIFINPAY_AGENT_SECRET   legacy base58 secret; after project wallet sources
+  SEED_HASH              32-byte hex seed; highest priority
+  AIFINPAY_AGENTS_FILE   project agents file (default ./aifinpay/agents.json)
+  AIFINPAY_AGENT_ID      select one record when the file has multiple agents
+  AIFINPAY_AGENT_SECRET  legacy base58 secret; after project wallet sources
+  AIFINPAY_WALLET_INDEX  child index derived from the selected seed
   AIFINPAY_WALLET_PASSPHRASE  opens an encrypted keystore; the server needs it too
   AIFINPAY_BASE_URL       default https://aifinpay.io
   AIFINPAY_TIMEOUT_MS     default 30000
   AIFINPAY_HOME           default ~/.aifinpay
 
-Payments (payable_fetch) are off until the owner sets all of
+Payments (payable_fetch) sign nothing until the owner sets all of
 AIFINPAY_PAYMENTS_ENABLED=1, AIFINPAY_GATEWAY_ORIGINS, AIFINPAY_MAX_USD,
-AIFINPAY_DAILY_USD and AIFINPAY_MAX_GAS_POL. init prints an example block.
+AIFINPAY_DAILY_USD and AIFINPAY_MAX_GAS_POL. init prints an example block;
+the payment_setup_status tool says which of them is still missing.
 `);
   process.exit(0);
 }
@@ -96,7 +106,14 @@ if (arg === "--version" || arg === "-v" || arg === "version") {
 
 // ── init ──────────────────────────────────────────────────────────────────
 
-const PASSPHRASE = process.env.AIFINPAY_WALLET_PASSPHRASE || null;
+const PASSPHRASE_ENV = "AIFINPAY_WALLET_PASSPHRASE";
+let PASSPHRASE = process.env[PASSPHRASE_ENV] || null;
+// An agent's subprocess has no terminal on stdin. Nothing here may wait for a
+// human then: a 2026-10-19 agent run hung 167 s on a passphrase it could not
+// type and invented its own key handling instead. In this mode init generates
+// the passphrase itself and prints JSON the agent can act on.
+const NONINTERACTIVE = process.env.AIFINPAY_NONINTERACTIVE === "1" || !process.stdin.isTTY;
+let GENERATED_PASSPHRASE = false;
 
 // Optional at-rest encryption. Mode 600 keeps the keystore from OTHER users; it
 // does nothing against malware running as YOU — the threat the OSINT write-up of
@@ -126,7 +143,7 @@ function encryptSecret(secretB58) {
   };
 }
 function decryptSecret(store) {
-  if (!PASSPHRASE) throw new Error(`${KEYSTORE} is encrypted but AIFINPAY_WALLET_PASSPHRASE is not set.`);
+  if (!PASSPHRASE) throw new Error(`${KEYSTORE} is encrypted but ${PASSPHRASE_ENV} is not set.`);
   const key = scryptSync(PASSPHRASE, Buffer.from(store.salt, "base64"), 32, {
     N: 1 << 15,
     r: 8,
@@ -156,52 +173,97 @@ function readKeystore() {
   return typeof parsed?.secretB58 === "string" ? parsed : null;
 }
 
-// The owner settings that register payable_fetch, as init prints them. README
-// "Enable native paid GET requests" shows the same block; a test keeps the two
-// equal and starts a server with it. The gas cap is a worst case at the current
-// Polygon gas price, not the fee: 0.05 POL refused every payment at ~280 gwei.
-const PAYMENT_ENV = {
-  AIFINPAY_PAYMENTS_ENABLED: "1",
-  AIFINPAY_GATEWAY_ORIGINS: "https://merchant.example",
-  AIFINPAY_GATEWAY_PATH_MODE: "direct",
-  AIFINPAY_MAX_USD: "0.15",
-  AIFINPAY_DAILY_USD: "1.00",
-  AIFINPAY_MAX_GAS_POL: "0.3",
-};
-
 if (arg === "init") {
   const { Agent, AiFinPayAgent } = await import("@aifinpay/agent");
 
   const { loadConfigFromEnv } = await import("../dist/config.js");
   const { loadWalletIdentity } = await import("../dist/identity.js");
-  const selected = loadWalletIdentity(loadConfigFromEnv());
+  const { PAYMENT_ENV } = await import("../dist/tools/payment-setup-status.js");
+  const config = loadConfigFromEnv();
+  // A keystore that cannot be opened is reported in one line that names the
+  // variable, never as a stack trace — and never replaced.
+  const failKeystore = (error) => {
+    const line =
+      !PASSPHRASE && existsSync(KEYSTORE)
+        ? `${KEYSTORE} exists and is encrypted; set ${PASSPHRASE_ENV} to the passphrase used at init (it is not set in this environment).`
+        : error.message;
+    if (NONINTERACTIVE)
+      process.stdout.write(
+        JSON.stringify({ error: line, keystore: KEYSTORE, ...(PASSPHRASE ? {} : { missing_env: PASSPHRASE_ENV }) }) +
+          "\n"
+      );
+    else process.stderr.write(line + "\n");
+    process.exit(2);
+  };
+  let selected;
+  try {
+    selected = loadWalletIdentity(config);
+  } catch (error) {
+    failKeystore(error);
+  }
+  const plaintext = process.argv.includes("--plaintext");
+  const addressesOf = (agent) => ({ evm: agent.evmAddress, solana: agent.solanaAddress, casper: agent.casperAddress });
+  const indexEnv =
+    selected?.derivationIndex === undefined ? {} : { AIFINPAY_WALLET_INDEX: String(selected.derivationIndex) };
+  // Non-interactive stdout is one JSON document and nothing else, so the
+  // caller can parse it. The same facts, as prose, go to a terminal.
+  const emit = (json, text) => process.stdout.write(NONINTERACTIVE ? JSON.stringify(json, null, 2) + "\n" : text);
+  const nextStep =
+    'Put "env" into the aifinpay server entry of the MCP client config and reconnect the server (or call agent_reload in an already connected one), then call payment_setup_status: it names the next step up to the first payment.';
+
   if (selected && selected.source !== "legacy-keystore") {
     const agent = selected.seedHash
-      ? await AiFinPayAgent.fromSeed(selected.seedHash)
+      ? await AiFinPayAgent.fromSeed(selected.seedHash, { derivationIndex: selected.derivationIndex })
       : await AiFinPayAgent.fromSolanaSecret(selected.secretB58);
-    process.stdout.write(
-      `Using ${selected.source}; no replacement wallet created.\n` +
+    emit(
+      {
+        keystore: null,
+        created: false,
+        encrypted: null,
+        source: selected.source,
+        addresses: addressesOf(agent),
+        env: indexEnv,
+        payment_env_example: PAYMENT_ENV,
+        next_step: nextStep,
+      },
+      `Using ${selected.source}${selected.derivationIndex === undefined ? "" : ` (index ${selected.derivationIndex})`}; no replacement wallet created.\n` +
         `EVM ${agent.evmAddress}\nSolana ${agent.solanaAddress}\nCasper ${agent.casperAddress}\n` +
         `Keep your configured seed backed up privately. Call agent_reload in an already connected MCP server.\n`
     );
     process.exit(0);
   }
 
-  let store = readKeystore();
+  const openExistingKeystore = () => {
+    try {
+      return readKeystore();
+    } catch (error) {
+      failKeystore(error);
+    }
+  };
+  let store = openExistingKeystore();
   let freshlyCreated = false;
   // A new wallet is encrypted at rest unless the owner asks otherwise, by name.
   // It used to be written in plaintext whenever AIFINPAY_WALLET_PASSPHRASE was
   // unset — which is the default — so the documented one-liner produced an
   // unencrypted key for a wallet people then funded. Existing keystores are
   // untouched; only creating a new plaintext one needs the flag.
-  if (!store && !PASSPHRASE && !process.argv.includes("--plaintext")) {
-    process.stderr.write(
-      `No wallet at ${KEYSTORE}, and none will be created unencrypted by default.\n\n` +
-        `  Encrypted (recommended):  AIFINPAY_WALLET_PASSPHRASE='<a long passphrase>' npx @aifinpay/mcp init\n` +
-        `  Disposable test wallet:   npx @aifinpay/mcp init --plaintext\n\n` +
-        `Keep the passphrase: an encrypted wallet cannot be recovered without it.\n`
-    );
-    process.exit(2);
+  if (!store && !PASSPHRASE && !plaintext) {
+    if (NONINTERACTIVE) {
+      // 192 random bits. The passphrase is printed once, inside the env block
+      // below, because the caller has to put it in the client config and there
+      // is no other channel; this is the trade-off of a wallet created by a
+      // process that cannot be asked anything.
+      PASSPHRASE = randomBytes(24).toString("base64url");
+      GENERATED_PASSPHRASE = true;
+    } else {
+      process.stderr.write(
+        `No wallet at ${KEYSTORE}, and none will be created unencrypted by default.\n\n` +
+          `  Encrypted (recommended):  AIFINPAY_WALLET_PASSPHRASE='<a long passphrase>' npx @aifinpay/mcp init\n` +
+          `  Disposable test wallet:   npx @aifinpay/mcp init --plaintext\n\n` +
+          `Keep the passphrase: an encrypted wallet cannot be recovered without it.\n`
+      );
+      process.exit(2);
+    }
   }
   if (!store) {
     mkdirSync(HOME, { recursive: true, mode: 0o700 });
@@ -228,7 +290,9 @@ if (arg === "init") {
         freshlyCreated = true;
       } catch (error) {
         if (error.code !== "EEXIST") throw error;
-        store = readKeystore();
+        // The other process won; a passphrase generated here opens nothing.
+        if (GENERATED_PASSPHRASE) PASSPHRASE = null;
+        store = openExistingKeystore();
         if (!store) throw new Error(`Existing ${KEYSTORE} is unreadable; refusing to replace it.`);
       }
     } finally {
@@ -236,6 +300,44 @@ if (arg === "init") {
       if (ownsTemporary) unlinkSync(temporary);
     }
   }
+  const agent = selected?.seedHash
+    ? await AiFinPayAgent.fromSeed(selected.seedHash, { derivationIndex: selected.derivationIndex })
+    : await AiFinPayAgent.fromSolanaSecret(store.secretB58);
+  // The server cannot open an encrypted keystore without the passphrase, so a
+  // config block without it does not start.
+  const encrypted = freshlyCreated ? Boolean(PASSPHRASE) : Boolean(store.encrypted);
+
+  if (NONINTERACTIVE) {
+    emit(
+      {
+        keystore: KEYSTORE,
+        created: freshlyCreated,
+        encrypted,
+        source: "legacy-keystore",
+        addresses: addressesOf(agent),
+        env: {
+          ...(encrypted
+            ? {
+                [PASSPHRASE_ENV]: GENERATED_PASSPHRASE
+                  ? PASSPHRASE
+                  : `<the ${PASSPHRASE_ENV} already set in this environment>`,
+              }
+            : {}),
+          ...indexEnv,
+        },
+        ...(GENERATED_PASSPHRASE
+          ? {
+              passphrase_note: `${PASSPHRASE_ENV} was generated for this wallet and appears only here, inside env. The wallet cannot be opened or recovered without it.`,
+            }
+          : {}),
+        payment_env_example: PAYMENT_ENV,
+        next_step: nextStep,
+      },
+      ""
+    );
+    process.exit(0);
+  }
+
   if (freshlyCreated) {
     process.stdout.write(
       PASSPHRASE
@@ -265,26 +367,25 @@ if (arg === "init") {
     );
   }
 
-  const agent = await AiFinPayAgent.fromSolanaSecret(store.secretB58);
-  // The server cannot open an encrypted keystore without the passphrase, so a
-  // config block without it does not start.
-  const encrypted = freshlyCreated ? Boolean(PASSPHRASE) : Boolean(store.encrypted);
-
   process.stdout.write(
-    `Your agent's addresses — the EVM one is the same on every EVM chain:\n\n` +
+    `Your agent's addresses${selected?.derivationIndex === undefined ? "" : ` (index ${selected.derivationIndex})`} — the EVM one is the same on every EVM chain:\n\n` +
       `  EVM     ${agent.evmAddress}\n` +
       `  Solana  ${agent.solanaAddress}\n` +
       `  Casper  ${agent.casperAddress}\n\n` +
       `Add this to your MCP client config and connect/reconnect this MCP server.\n` +
-      `As printed it cannot pay; payable_fetch appears once you add the payment\n` +
-      `settings further down:\n\n` +
+      `As printed it cannot pay: payable_fetch is listed but signs nothing until\n` +
+      `you add the payment settings further down (payment_setup_status says what\n` +
+      `is still missing):\n\n` +
       JSON.stringify(
         {
           mcpServers: {
             aifinpay: {
               command: "npx",
               args: ["-y", `@aifinpay/mcp@${VERSION}`],
-              env: encrypted ? { AIFINPAY_WALLET_PASSPHRASE: "<the passphrase you used for init>" } : {},
+              env: {
+                ...(encrypted ? { AIFINPAY_WALLET_PASSPHRASE: "<the passphrase you used for init>" } : {}),
+                ...indexEnv,
+              },
             },
           },
         },

package/dist/client-framework.d.ts

@@ -0,0 +1,3 @@
+import type { AgentFramework } from "@aifinpay/agent";
+export declare function frameworkForClient(name: unknown): AgentFramework | undefined;
+//# sourceMappingURL=client-framework.d.ts.map

package/dist/client-framework.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-framework.d.ts","sourceRoot":"","sources":["../src/client-framework.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAqBtD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAE5E"}

package/dist/client-framework.js

@@ -0,0 +1,22 @@
+/**
+ * MCP `clientInfo.name`, as the client sent it at initialize, → the
+ * AIFP-Agent-Framework the backend records. Exact names only: a client not
+ * listed here sends no header rather than a guess. Entries are the names the
+ * product owner listed plus `cursor-vscode`, which Cursor is reported to send;
+ * confirm new ones against real initialize payloads before adding them.
+ */
+const CLIENT_FRAMEWORKS = new Map([
+    ["claude-ai", "claude"],
+    ["claude-code", "claude"],
+    ["cursor", "cursor"],
+    ["cursor-vscode", "cursor"],
+    ["windsurf", "windsurf"],
+    ["chatgpt", "chatgpt"],
+    ["openai", "chatgpt"],
+    ["gemini", "gemini"],
+    ["perplexity", "perplexity"],
+]);
+export function frameworkForClient(name) {
+    return typeof name === "string" ? CLIENT_FRAMEWORKS.get(name) : undefined;
+}
+//# sourceMappingURL=client-framework.js.map

package/dist/client-framework.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-framework.js","sourceRoot":"","sources":["../src/client-framework.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAyB;IACxD,CAAC,WAAW,EAAE,QAAQ,CAAC;IACvB,CAAC,aAAa,EAAE,QAAQ,CAAC;IACzB,CAAC,QAAQ,EAAE,QAAQ,CAAC;IACpB,CAAC,eAAe,EAAE,QAAQ,CAAC;IAC3B,CAAC,UAAU,EAAE,UAAU,CAAC;IACxB,CAAC,SAAS,EAAE,SAAS,CAAC;IACtB,CAAC,QAAQ,EAAE,SAAS,CAAC;IACrB,CAAC,QAAQ,EAAE,QAAQ,CAAC;IACpB,CAAC,YAAY,EAAE,YAAY,CAAC;CAC7B,CAAC,CAAC;AAEH,MAAM,UAAU,kBAAkB,CAAC,IAAa;IAC9C,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC5E,CAAC"}

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+import type { EvmWalletClient } from "@aifinpay/agent";
 /** Runtime configuration loaded from env. */
 export interface McpConfig {
     /** Legacy base58 secret, after SEED_HASH and the project agents file. */
@@ -8,6 +9,10 @@ export interface McpConfig {
     agentId?: string;
     walletHome?: string;
     walletPassphrase?: string;
+    /** Child wallet number from a seed or indexed wallet keystore. */
+    walletIndex?: number;
+    /** Programmatic external EVM signer supplied by an embedding MCP host. */
+    evmWalletClient?: EvmWalletClient;
     /** Dev environment. EVM payments stay live-only; Solana requires explicit devnet. */
     devMode?: boolean;
     /** Custom AiFinPay backend URL. Defaults to production. */

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,6CAA6C;AAC7C,MAAM,WAAW,SAAS;IACxB,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qFAAqF;IACrF,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,wDAAwD;IACxD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;0EACsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACrC,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;yFACqF;IACrF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;+CAW2C;IAC3C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B,2EAA2E;IAC3E,eAAe,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAEvC;;;;;;;;;8CAS0C;IAC1C,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB,qDAAqD;IACrD,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACjE;AAED,wBAAgB,iBAAiB,IAAI,SAAS,CA+B7C;AAgED,oFAAoF;AACpF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAkF/D"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGvD,6CAA6C;AAC7C,MAAM,WAAW,SAAS;IACxB,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,qFAAqF;IACrF,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,wDAAwD;IACxD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;0EACsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACrC,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;yFACqF;IACrF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;+CAW2C;IAC3C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B,2EAA2E;IAC3E,eAAe,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAEvC;;;;;;;;;8CAS0C;IAC1C,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB,qDAAqD;IACrD,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACjE;AAED,wBAAgB,iBAAiB,IAAI,SAAS,CAgC7C;AA4ED,oFAAoF;AACpF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAkF/D"}

package/dist/config.js

@@ -23,6 +23,7 @@ export function loadConfigFromEnv() {
         agentId: process.env.AIFINPAY_AGENT_ID || undefined,
         walletHome: process.env.AIFINPAY_HOME || undefined,
         walletPassphrase: process.env.AIFINPAY_WALLET_PASSPHRASE || undefined,
+        walletIndex: parseWalletIndex(process.env.AIFINPAY_WALLET_INDEX),
         agentSecretB58: process.env.AIFINPAY_AGENT_SECRET || undefined,
         baseUrl: process.env.AIFINPAY_BASE_URL || undefined,
         timeoutMs: process.env.AIFINPAY_TIMEOUT_MS ? Number(process.env.AIFINPAY_TIMEOUT_MS) : undefined,
@@ -32,6 +33,18 @@ export function loadConfigFromEnv() {
         trustedHosts: splitList(process.env.AIFINPAY_TRUSTED_HOSTS),
     };
 }
+function parseWalletIndex(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!/^(0|[1-9][0-9]*)$/.test(raw)) {
+        throw new Error("AIFINPAY_WALLET_INDEX must be a non-negative integer");
+    }
+    const index = Number(raw);
+    if (!Number.isSafeInteger(index) || index > 0xffffffff) {
+        throw new Error("AIFINPAY_WALLET_INDEX must be between 0 and 4294967295");
+    }
+    return index;
+}
 function parseSolanaNetwork(raw) {
     if (raw === undefined)
         return undefined;