@aifinpay/mcp 2.11.4 → 2.12.1

package/README.md

@@ -4,61 +4,50 @@ AiFinPay MCP server for persistent agent identity, Agent Passport resolution,
 route discovery and non-signing settlement invoices. Canonical domain:
 **aifinpay.io**.
 
-Version **2.11.4** is prepared in this checkout, on the published agent 2.9.0
+Version **2.12.1** is prepared in this checkout, on the published agent 2.9.0
 and canonical skill 2.10.2 (AiFinPay/skill 48285cf, 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
-lists every tool, including `payable_fetch`, but signs nothing: `payable_fetch`
-and `payment_setup_status` answer with the setup checklist instead.
+batches with `scope: "merchant"` since 2.4.1. Since 2.12.1 payments are on by
+default: a persistent wallet created with `init` can pay with no payment env at
+all, within a built-in ceiling of $5 per payment and $20 per 24 hours, and only
+to merchants registered with AiFinPay. An ephemeral wallet signs nothing, and
+an unfunded one has nothing to spend. The working limits are the owner's
+dashboard Controls.
 
 ## 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.
+Nobody edits the MCP client config to turn payments on. Signing happens only in
+step 5, only with a persistent, funded wallet, and never above the ceiling.
 
 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, `funding` (what a persistent
-   wallet needs, priced at today's rate) 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 from
+   (persistent or ephemeral), the ceiling and each limit with its source
+   (`default` or the owner's `env`), the balance when the RPC answers,
+   `funding` (what to fund, priced at today's rate), the owner's dashboard
+   Controls in `dashboard`, and `next_step`: the first thing still missing.
+3. **Init.** 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, then call `agent_reload` in the same connection. No restart: the
+   reload opens the payment journal for the new wallet. Never fund an
+   ephemeral address.
+4. **Fund and link.** Tell the owner `addresses.evm` and the amount from
    `payment_setup_status`'s `funding`: the smallest batch (`$0.10`) in POL at
-   today's rate plus the gas cap (the SDK refuses before signing if the
-   worst-case fee exceeds the cap). The rate moves — `$0.10` was 1.08 POL on
-   2026-10-19 — so never quote a remembered number; if `funding` carries a
-   `rate_error` instead of an `amount`, ask the owner to fund "the batch price
-   in POL at today's rate plus the gas cap" and name no number. When the owner
-   confirms funding, they add the payment settings to the same `env` and
-   restart the aifinpay MCP server in the client (`agent_reload` does not read
-   env):
-
-   ```json
-   {
-     "AIFINPAY_PAYMENTS_ENABLED": "1",
-     "AIFINPAY_GATEWAY_ORIGINS": "https://dev.ratersapp.com",
-     "AIFINPAY_GATEWAY_PATH_MODE": "direct",
-     "AIFINPAY_MAX_USD": "5",
-     "AIFINPAY_DAILY_USD": "20",
-     "AIFINPAY_MAX_GAS_POL": "0.3"
-   }
-   ```
-
-   The USD values are a ceiling the owner sets once, not the budget: the
-   working limits live in the dashboard (see "Owner limits" below).
-   `payment_setup_status` then reports `ready: true`.
-
+   today's rate plus the gas cap (0.3 POL by default; the SDK refuses before
+   signing if the worst-case fee exceeds it). The rate moves — `$0.10` was
+   1.08 POL on 2026-10-19 — so never quote a remembered number; if `funding`
+   carries a `rate_error` instead of an `amount`, ask the owner to fund "the
+   batch price in POL at today's rate plus the gas cap" and name no number.
+   Offer the dashboard link too: the owner generates a one-time URL under
+   **My Agents → Claim via MCP** at https://dash.aifinpay.io and the agent
+   passes it to `agent_claim_self`; from then on the owner sets the working
+   limits in Controls.
 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.
@@ -67,40 +56,65 @@ 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
+## Optional payment overrides
 
-Use a persistent wallet created with public `npx @aifinpay/mcp init` or an
-existing configured identity. Keep its passphrase private. The owner adds these
-to the server's `env` (`init` prints the same block):
+None of these is needed for a first payment, and each one only narrows what
+the defaults allow. `init` prints the same reference block:
 
 ```json
 {
-  "AIFINPAY_PAYMENTS_ENABLED": "1",
   "AIFINPAY_GATEWAY_ORIGINS": "https://merchant.example",
-  "AIFINPAY_GATEWAY_PATH_MODE": "direct",
-  "AIFINPAY_MAX_USD": "5",
-  "AIFINPAY_DAILY_USD": "20",
   "AIFINPAY_MAX_GAS_POL": "0.3"
 }
 ```
 
-Limits are examples, not authorization. USD limits cover purchases; gas has its
-own POL cap. Origins are exact HTTPS origins authorized by the
-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.
-
-### Owner limits: a ceiling in env, the working limits in the dashboard
-
-`AIFINPAY_MAX_USD` and `AIFINPAY_DAILY_USD` are the ceiling the SDK requires
-before it signs with the owner's key: set them once, high enough that they do
-not need revisiting (the example `5` per payment and `20` per day is a ceiling,
-not a budget), and leave them. The day-to-day limits belong in the dashboard:
-once the agent is linked with `agent_claim_self`, the owner manages the
-per-payment cap, the daily cap, pause and the allowed sites under **Controls**
-at https://dash.aifinpay.io, and the backend enforces that policy on every
-`/v1/quote` and `/v1/pay` for the claimed agent — no env change, no server
-restart. The env ceiling still applies underneath; a payment has to pass both.
+- `AIFINPAY_GATEWAY_ORIGINS`: exact HTTPS origins the agent may pay,
+  comma-separated, no wildcards. Unset, the agent pays only a merchant whose
+  site AiFinPay reports as DNS-verified, on that very site (or through the
+  AiFinPay hosted gateway): the payee comes from the backend-signed quote, never
+  from the 402, and is refused before anything is signed if its verified site is
+  not the host being fetched. Set, an unlisted origin is refused by name and
+  only the owner can add it; the list then decides.
+- `AIFINPAY_MAX_GAS_POL`: worst-case network fee of one payment on Polygon,
+  checked before signing; default `0.3` POL. At ~280 gwei the worst case is
+  ~0.10 POL paying in POL and ~0.21 POL in USDC. Another chain needs
+  `AIFINPAY_MAX_GAS` in its own currency.
+- `AIFINPAY_MAX_USD` / `AIFINPAY_DAILY_USD`: lower the built-in ceiling of $5
+  per payment / $20 per 24 hours. A higher value is refused at start with a
+  message, never silently clipped; raise nothing here, use the dashboard.
+- `AIFINPAY_GATEWAY_PATH_MODE`: unset, inferred per URL (`gateway` for
+  `https://gateway.aifinpay.io`, by merchant slug; `direct`, the full path,
+  for any other site).
+- `AIFINPAY_PAYMENTS_ENABLED=0`: payments off; the server stays read-only.
+
+The env is read when the server starts; restart the aifinpay MCP server after
+changing it (`agent_reload` reads only the keystore).
+
+### Owner limits: a built-in ceiling, the working limits in the dashboard
+
+The server never signs more than $5 per payment or $20 over any 24 hours (its
+local journal, checked under the operation lock before any broadcast). That
+ceiling is not a budget and needs no setting; env can only lower it. The
+day-to-day limits belong in the dashboard: once the agent is linked with
+`agent_claim_self`, the owner manages the per-payment cap, the daily cap, pause
+and the allowed merchants under **Controls** at https://dash.aifinpay.io, and
+the backend enforces that policy on every `/v1/quote` and `/v1/pay` for the
+claimed agent — no env change, no server restart. The ceiling still applies
+underneath; a payment has to pass both. More than $5 / $20 on an agent key is
+the Node SDK with its own limits.
+
+`payment_setup_status` reads those Controls back for a persistent EVM wallet
+and returns them as `dashboard`: `{ linked: true, policy }` with the per-payment
+cap, daily cap, merchant allowlist, expiry and pause; `{ linked: false }` when
+no owner has claimed the agent yet (its `next_step` then offers the dashboard
+link); `{ linked: "unknown", reason }` when the read fails, which blocks
+nothing because the backend enforces the policy either way. Paused or expired
+Controls stop the checklist with a `next_step` that says so. The read is
+`GET /v1/agents/<address>/policy` on the configured backend, signed by the
+wallet's own key (EIP-191 over `["AiFinPay agent policy read v1", <backend
+origin>, <lowercase address>, <expires_at>]`, valid 60 s); it signs no payment
+and changes nothing. It is not made on `payable_fetch`'s refusal path, for an
+ephemeral wallet or on Solana.
 
 ## Indexed wallet derivation
 
@@ -168,16 +182,16 @@ runtime/signer verification and owner limits. It persists the prepared transacti
 before sending, verifies the receipt, and reuses the purchased batch. No special
 merchant script, alternate contract or facilitator fallback is used. GET on the configured chain; EVM receipt payments use live
 mode only, in its native currency or the configured
-stablecoin; Amoy payment receipts are not supported. The smallest batch is $0.10 plus gas; `AIFINPAY_MAX_USD`
-only has to be at or above the batch you expect to buy.
+stablecoin; Amoy payment receipts are not supported. The smallest batch is $0.10 plus gas, well inside
+the $5 per-payment ceiling.
 
 To buy access to a whole site rather than one endpoint, call
 `payable_fetch({"url":"https://merchant.example/api/data","scope":"merchant"})`.
 One batch then covers every path on that merchant, and each request still costs
 its own listed price, so a premium page drains more of it than a standard API
-call. The price, the owner limits and the approved origins do not change. An
-origin missing from `AIFINPAY_GATEWAY_ORIGINS` is refused by name; only the
-owner can add it.
+call. The price, the owner limits and the approved origins do not change. When
+the owner set `AIFINPAY_GATEWAY_ORIGINS`, an origin missing from it is refused
+by name; only the owner can add it.
 
 ### Network access
 
@@ -219,8 +233,8 @@ origins, signs only the claim challenge for this agent's own address, and moves
 no funds. The owner-selected payment family must be confirmed successfully;
 the second wallet is best-effort. Use the selected wallet's Fund panel for
 available networks and assets; binding does not activate a disabled network.
-Offer this to the owner after `init`: from then on the owner manages the
-agent's working limits under Controls there (see "Owner limits" above).
+Offer this to the owner after `init` (step 4 above): from then on the owner
+manages the agent's working limits under Controls there (see "Owner limits").
 
 Private recovery state for all payment families lives at `AIFINPAY_HOME/payments/<evm-address>/state.json`
 (default home `~/.aifinpay`). State is mode600 in mode700 directories, atomically
@@ -240,7 +254,7 @@ 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.              |
-| `payment_setup_status`   | Read-only setup checklist with the one `next_step`.      |
+| `payment_setup_status`   | Setup checklist, owner's dashboard Controls, `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.    |
@@ -248,11 +262,13 @@ state file in chat. Unconfirmed payments consume the budget conservatively.
 | `settlement_casper`      | Build a non-signing Casper settlement invoice.           |
 | `deployment_info`        | Read deployments: addresses, assets, settlement status.  |
 
-`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
+`payable_fetch` is always listed. It signs only with a persistent wallet, and
+not when the owner set `AIFINPAY_PAYMENTS_ENABLED=0`; otherwise it returns the
+`payment_setup_status` checklist as a tool error and contacts nothing. A
+refused override with payments on by default leaves the server read-only and
+`payment_setup_status` names it; with an explicit `AIFINPAY_PAYMENTS_ENABLED=1`
+the server refuses to start, as before. An env limit above the ceiling stops
+the start in both cases. 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.
 
@@ -355,7 +371,8 @@ passphrase, encrypts the keystore and prints one JSON document:
   "addresses": { "evm": "0x…", "solana": "…", "casper": "account-hash-…" },
   "env": { "AIFINPAY_WALLET_PASSPHRASE": "<generated>" },
   "passphrase_note": "…",
-  "payment_env_example": { "AIFINPAY_PAYMENTS_ENABLED": "1", "…": "…" },
+  "payments": "Payments are on by default within a built-in ceiling of $5 per payment and $20 per 24 hours, …",
+  "optional_env_example": { "AIFINPAY_GATEWAY_ORIGINS": "https://merchant.example", "AIFINPAY_MAX_GAS_POL": "0.3" },
   "next_step": "Put \"env\" into the aifinpay server entry of the MCP client config …"
 }
 ```
@@ -431,9 +448,12 @@ snapshot. Verify `agent_address` against the wallet you intend to use.
 | ---------------------------- | --------------------- | ------------------------------------------------------------------------------------- |
 | `AIFINPAY_BASE_URL`          | `https://aifinpay.io` | Backend URL. Unset, `payable_fetch` quotes and verifies at `https://api.aifinpay.io`. |
 | `AIFINPAY_TIMEOUT_MS`        | `30000`               | Request timeout.                                                                      |
-| `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_PAYMENTS_ENABLED`  | on                    | Optional override: `0` turns payments off.                                            |
+| `AIFINPAY_MAX_USD`           | `5`                   | Optional override: lowers the per-payment ceiling; a higher value is refused.         |
+| `AIFINPAY_DAILY_USD`         | `20`                  | Optional override: lowers the 24-hour ceiling; a higher value is refused.             |
+| `AIFINPAY_GATEWAY_ORIGINS`   | verified merchant sites | Optional allowlist: comma-separated exact HTTPS origins the agent may pay. |
+| `AIFINPAY_GATEWAY_PATH_MODE` | inferred per URL      | `gateway` (merchant slug) or `direct` (full path); unset: the hosted gateway by slug. |
+| `AIFINPAY_MAX_GAS_POL`       | `0.3`                 | Optional override: gas cap per payment on Polygon, in POL.                            |
 | `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.                                                          |
@@ -465,16 +485,17 @@ The programmatic equivalents of identity environment options are `seedHash`,
 - AIFINPAY_MODE=dev: expose dev_payment_quote; requires a separate dev base URL.
 
 - AIFINPAY_TIMEOUT_MS: SDK request timeout.
-- AIFINPAY_MAX_USD: per-payment USD cap for payable_fetch; required with payments.
+- AIFINPAY_MAX_USD: lowers the $5 per-payment ceiling of payable_fetch (optional).
 - AIFINPAY_TRUSTED_HOSTS: exact hosts allowed to bypass the DNS pre-check.
 - AIFINPAY_ALLOW_PRIVATE_FETCH=1: explicit local-development network access.
   Never enable this on the public hosted MCP.
 
-For a self-hosted AIFP-1 gateway, set `AIFINPAY_GATEWAY_ORIGINS` to exact HTTPS
-origins. `AIFINPAY_GATEWAY_PATH_MODE=direct` makes the process use each request's
-full pathname as its AIFP-1 resource identity; `gateway` uses the merchant slug.
-The mode is process-wide, does not broaden the trusted-origin allowlist, and
-does not enable the retired signing tools in the production RC.
+A self-hosted AIFP-1 gateway needs no setting: unset, the path mode is
+`direct` (each request's full pathname is its AIFP-1 resource identity) for any
+origin other than `https://gateway.aifinpay.io`, which uses the merchant slug.
+`AIFINPAY_GATEWAY_PATH_MODE` forces one mode for every origin; it does not
+broaden an owner's `AIFINPAY_GATEWAY_ORIGINS` allowlist and does not enable the
+retired signing tools in the production RC.
 
 Dev quoting does not bypass wallet signatures, issuer verification or
 receipt metering. See the bundled skill for backend prerequisites. The low-level SDK has an Amoy

package/bin/aifinpay-mcp.js

@@ -27,7 +27,7 @@
  *   AIFINPAY_AGENT_SECRET   legacy base58 secret — overrides the legacy keystore
  *   AIFINPAY_BASE_URL       default https://aifinpay.io
  *   AIFINPAY_TIMEOUT_MS     default 30000
- *   AIFINPAY_MAX_USD        hard cap per single payment (no default)
+ *   AIFINPAY_MAX_USD        lowers the built-in $5-per-payment ceiling (never raises it)
  */
 import {
   readFileSync,
@@ -91,10 +91,16 @@ Env (all optional):
   AIFINPAY_TIMEOUT_MS     default 30000
   AIFINPAY_HOME           default ~/.aifinpay
 
-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;
-the payment_setup_status tool says which of them is still missing.
+Payments (payable_fetch) are on by default, within a built-in ceiling of $5 per
+payment and $20 per 24 hours, only from a persistent wallet (init), and only to
+merchants registered with AiFinPay; an unfunded wallet spends nothing. The
+working limits are the dashboard Controls (https://dash.aifinpay.io) once the
+agent is claimed. Optional overrides, all narrowing:
+  AIFINPAY_PAYMENTS_ENABLED=0   turn payments off
+  AIFINPAY_MAX_USD, AIFINPAY_DAILY_USD   lower the ceiling (higher is refused)
+  AIFINPAY_GATEWAY_ORIGINS      exact https origins it may pay; unset, any https site
+  AIFINPAY_MAX_GAS_POL          gas cap per payment on Polygon (default 0.3)
+The payment_setup_status tool says what is still missing before a first payment.
 `);
   process.exit(0);
 }
@@ -178,7 +184,8 @@ if (arg === "init") {
 
   const { loadConfigFromEnv } = await import("../dist/config.js");
   const { loadWalletIdentity } = await import("../dist/identity.js");
-  const { PAYMENT_ENV, lockedKeystoreStep } = await import("../dist/tools/payment-setup-status.js");
+  const { PAYMENT_OVERRIDES, PAYMENTS_DEFAULT_NOTE, lockedKeystoreStep } =
+    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. An agent cannot ask
@@ -225,7 +232,7 @@ if (arg === "init") {
   // 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.';
+    '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: payments then work without a restart), 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
@@ -239,7 +246,8 @@ if (arg === "init") {
         source: selected.source,
         addresses: addressesOf(agent),
         env: { ...homeEnv, ...indexEnv },
-        payment_env_example: PAYMENT_ENV,
+        payments: PAYMENTS_DEFAULT_NOTE,
+        optional_env_example: PAYMENT_OVERRIDES,
         next_step: nextStep,
       },
       `Using ${selected.source}${selected.derivationIndex === undefined ? "" : ` (index ${selected.derivationIndex})`}; no replacement wallet created.\n` +
@@ -347,7 +355,8 @@ if (arg === "init") {
               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,
+        payments: PAYMENTS_DEFAULT_NOTE,
+        optional_env_example: PAYMENT_OVERRIDES,
         next_step: nextStep,
       },
       ""
@@ -389,10 +398,8 @@ if (arg === "init") {
       `  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 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` +
+      `Add this to your MCP client config and connect/reconnect this MCP server\n` +
+      `(or call agent_reload in one that is already connected):\n\n` +
       JSON.stringify(
         {
           mcpServers: {
@@ -420,31 +427,32 @@ if (arg === "init") {
       `keystore. If this server is already connected, call agent_reload after init.\nA new conversation is not required by this server.\n\n` +
       `Back up ${KEYSTORE}. It is the only copy. The derivation is not\n` +
       `BIP-39, so no standard wallet can recover this from a phrase.\n\n` +
-      `To let it pay, add these to "env" above, then reconnect the server:\n\n` +
-      JSON.stringify(PAYMENT_ENV, null, 2) +
-      `\n\n` +
-      `  AIFINPAY_GATEWAY_ORIGINS    exact HTTPS origins it may pay, comma-separated;\n` +
-      `                              replace the example. No wildcards.\n` +
-      `  AIFINPAY_GATEWAY_PATH_MODE  "direct" for a site that runs its own AiFinPay\n` +
-      `                              paywall, "gateway" for gateway.aifinpay.io.\n` +
-      `  AIFINPAY_MAX_USD            per payment, a ceiling set once (the smallest\n` +
-      `                              batch is $0.10; the example is not a budget).\n` +
-      `  AIFINPAY_DAILY_USD          total over any 24 hours, the same kind of ceiling.\n` +
-      `                              Day-to-day limits: dashboard Controls, once the\n` +
-      `                              agent is claimed (see below).\n` +
-      `  AIFINPAY_MAX_GAS_POL        worst-case network fee of one payment, checked\n` +
-      `                              before signing. It follows Polygon's gas price:\n` +
-      `                              at ~280 gwei it is ~0.10 POL paying in POL and\n` +
-      `                              ~0.21 POL paying in USDC. A lower cap refuses\n` +
-      `                              the payment; raise it when gas is higher.\n\n` +
-      `Fund the EVM address on Polygon with the batch price at today's rate plus the\n` +
-      `gas cap, in POL; payment_setup_status prices it.\n` +
-      `To pay in USDC, also set "AIFINPAY_PAY_ASSET": "USDC" and hold USDC for the\n` +
-      `batch plus POL up to the gas cap. Check the balance before funding or paying.\n\n` +
-      `See its balance, payments and receipts in your dashboard:\n` +
+      `Payments are on: payable_fetch pays at most $5 per payment and $20 per 24\n` +
+      `hours (a built-in ceiling, not a budget), only to merchants registered with\n` +
+      `AiFinPay. It holds nothing yet, so it can spend nothing. To let it pay, fund\n` +
+      `the EVM address on Polygon with the batch price at today's rate plus the gas\n` +
+      `cap, in POL; payment_setup_status prices it (the smallest batch is $0.10).\n` +
+      `To pay in USDC, set "AIFINPAY_PAY_ASSET": "USDC" and hold USDC for the batch\n` +
+      `plus POL up to the gas cap. Check the balance before funding or paying.\n\n` +
+      `Set the working limits in your dashboard:\n` +
       `  https://dash.aifinpay.io → My Agents → Claim via MCP, then give the\n` +
       `  one-time URL to the agent (tool agent_claim_self). Controls there set the\n` +
-      `  working limits; the env values above stay as the ceiling.\n`
+      `  per-payment cap, daily cap, pause and allowed merchants, enforced on every\n` +
+      `  quote and payment; the ceiling above still applies underneath.\n\n` +
+      `Optional env, for reference (none of it is needed for a first payment):\n\n` +
+      JSON.stringify(PAYMENT_OVERRIDES, null, 2) +
+      `\n\n` +
+      `  AIFINPAY_GATEWAY_ORIGINS    exact HTTPS origins it may pay, comma-separated,\n` +
+      `                              no wildcards. Unset, any https site: the money\n` +
+      `                              still goes only where AiFinPay's signed quote says.\n` +
+      `  AIFINPAY_MAX_GAS_POL        worst-case network fee of one payment, checked\n` +
+      `                              before signing; default 0.3 POL. It follows\n` +
+      `                              Polygon's gas price: at ~280 gwei it is ~0.10 POL\n` +
+      `                              paying in POL and ~0.21 POL paying in USDC.\n` +
+      `  AIFINPAY_MAX_USD, AIFINPAY_DAILY_USD   lower the ceiling; a higher value\n` +
+      `                              is refused. Raise nothing here: use Controls.\n` +
+      `  AIFINPAY_PAYMENTS_ENABLED   "0" turns payments off.\n` +
+      `Env is read when the server starts; after changing it, restart the server.\n`
   );
   process.exit(0);
 }

package/dist/config.d.ts

@@ -19,8 +19,16 @@ export interface McpConfig {
     baseUrl?: string;
     /** Request timeout in ms. */
     timeoutMs?: number;
-    /** Owner opt-in; never accepted from tool arguments. */
+    /** On unless the owner sets AIFINPAY_PAYMENTS_ENABLED=0; never accepted from tool arguments.
+     *  An unfunded wallet spends nothing, and the built-in ceiling below bounds a funded one. */
     paymentsEnabled?: boolean;
+    /** Payments are on because AIFINPAY_PAYMENTS_ENABLED is unset. A refused payment setting
+     *  then leaves the server running read-only, with payment_setup_status naming the refusal;
+     *  an explicit =1 (or a programmatic paymentsEnabled) stops the server, as it always did. */
+    paymentsByDefault?: boolean;
+    /** Names of the limit variables the owner set in env to lower the built-in ceiling;
+     *  payment_setup_status reports each limit's source from this. */
+    ownerOverrides?: string[];
     dailyAmountUsd?: number;
     /** Chain payable_fetch settles on: "polygon" (default), another supported EVM chain, or "solana". Set by
      *  the owner only; never inferred from a quote or a tool argument. */
@@ -40,20 +48,24 @@ export interface McpConfig {
     payAsset?: string;
     /** Hard cap on a single payment to prevent runaway agents. */
     maxAmountUsd?: number;
-    /** Gateway origins this agent may settle against.
+    /** Optional allowlist of gateway origins this agent may settle against.
      *
-     *  The SDK has always supported this (parseGatewayUrl in @aifinpay/agent) and
-     *  this wrapper never exposed it, so a self-hosted merchant was unreachable:
-     *  payable_fetch reached the 402 and then refused with "dev.ratersapp.com is
-     *  not a known AiFinPay gateway; allowed: https://gateway.aifinpay.io".
-     *  Observed in an external E2E run on 2026-08-27.
+     *  Unset (the default since 2.12.1), payable_fetch accepts the https origin
+     *  of the URL it is given, and pays only if the merchant in the backend-signed
+     *  quote has a DNS-verified site that is that origin's host (any verified
+     *  merchant on the AiFinPay hosted gateway) — see ../merchant-site.ts. The
+     *  402 never decides who is paid; the ceiling below and the owner's dashboard
+     *  Controls still apply.
+     *  Before 2.12.1 this variable was required, and an unlisted origin was
+     *  refused by name (observed in an external E2E run on 2026-08-27).
      *
-     *  Set by the OPERATOR, exact origins only, never a wildcard. The refusal it
-     *  relaxes is not paranoia: a 402 is unauthenticated, so paying an
-     *  unrecognised host means paying whoever answered. Naming a host here is a
-     *  statement that you know who that is. */
+     *  Set by the OPERATOR, exact https origins only, never a wildcard, it
+     *  narrows that default: an origin not listed is refused before any quote.
+     *  Naming a host here is a statement that you know who that is. */
     gatewayOrigins?: string[];
-    /** AIFP-1 resource identity: merchant slug or full direct request path. */
+    /** AIFP-1 resource identity: merchant slug or full direct request path.
+     *  Unset, payable_fetch infers it per URL: the hosted gateway
+     *  (https://gateway.aifinpay.io) uses the slug, any other origin the path. */
     gatewayPathMode?: "gateway" | "direct";
     /** Hosts whose DNS pre-check is skipped, exact names only.
      *
@@ -70,6 +82,19 @@ export interface McpConfig {
     logFn?: (level: "info" | "warn" | "error", msg: string) => void;
 }
 export declare function loadConfigFromEnv(): McpConfig;
-/** Signing is available only after the owner configures all spending boundaries. */
+/** Built-in spending ceiling (owner decision 2026-10-20): $5 per payment, $20 per
+ *  24 h. The env values can only lower it; a higher value is refused so a
+ *  pasted config cannot raise the ceiling above what the dashboard Controls
+ *  are meant to manage. */
+export declare const DEFAULT_MAX_USD = 5;
+export declare const DEFAULT_DAILY_USD = 20;
+/** Gas cap per payment on Polygon when the owner sets none: the worst case at
+ *  ~280 gwei is ~0.10 POL paying in POL and ~0.21 POL in USDC, so 0.3 POL
+ *  (~$0.06) leaves room without being a budget. Another chain still needs
+ *  AIFINPAY_MAX_GAS in its own currency: choosing the chain is explicit anyway. */
+export declare const DEFAULT_MAX_GAS_POL = "0.3";
+/** Signing is available only while payments are on and every spending boundary is set:
+ *  the per-payment and daily USD ceiling, a gas cap, and an exact https allowlist when
+ *  the owner chose to set one. */
 export declare function validatePaymentConfig(config: McpConfig): bigint;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"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;iGAC6F;IAC7F,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;iGAE6F;IAC7F,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;sEACkE;IAClE,cAAc,CAAC,EAAE,MAAM,EAAE,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;;;;;;;;;;;;;uEAamE;IACnE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B;;kFAE8E;IAC9E,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,CAqC7C;AA4ED;;;2BAG2B;AAC3B,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC;;;mFAGmF;AACnF,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAUzC;;kCAEkC;AAClC,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAsF/D"}