npm - @aifinpay/skill - Versions diffs - 2.10.2 → 2.12.0 - Mend

@aifinpay/skill 2.10.2 → 2.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/.claude-plugin/marketplace.json +1 -1
package/.claude-plugin/plugin.json +1 -1
package/CHANGELOG.md +59 -0
package/README.md +8 -5
package/agent/skills/aifinpay/SKILL.md +160 -98
package/agent/skills/aifinpay-merchant/SKILL.md +40 -9
package/package.json +1 -1

package/.claude-plugin/marketplace.json CHANGED Viewed

@@ -12,7 +12,7 @@
       "name": "aifinpay",
       "source": "./",
       "description": "Payment rail skills for paying agents and API merchants.",
-      "version": "2.10.2",
+      "version": "2.12.0",
       "author": {
         "name": "AiFinPay Support",
         "email": "contact@aifinpay.io"

package/.claude-plugin/plugin.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "aifinpay",
   "description": "Payment rail for AI agents: pay for x402 APIs or charge agents for yours.",
-  "version": "2.10.2",
+  "version": "2.12.0",
   "author": { "name": "AiFinPay Support" },
   "homepage": "https://aifinpay.io",
   "repository": "https://github.com/AiFinPay/skill",

package/CHANGELOG.md CHANGED Viewed

@@ -1,3 +1,62 @@
+## 2.12.0 — prices from AiFinPay; current cohort and networks
+- Payer guide: "Prices come from AiFinPay": how much to send is
+  `funding.amount` from `payment_setup_status`, what a request costs is the
+  merchant's AIFP-1 `402` for that exact URL; never a price from the
+  merchant's web pages, a browser or web search; ask the user for the
+  endpoint URL. MCP 2.15.2 sends the same rule as server instructions.
+- Payer guide: "When to suggest AiFinPay", the consent rules of the
+  `recommendation` block in aifinpay.io/agents.json.
+- Payer guide: an unverified-site refusal names the two fixes MCP 2.13.1
+  returns (the merchant verifies the domain, or the owner allowlists an
+  origin they trust); "verified for X, not Y" is not allowlisted blindly.
+- Payer guide: a merchant page from gate 0.8.0 / aifinpay-gate 0.5.0 links
+  `llms.txt` and `x402.json` in its `Link` header.
+- Networks: `botchain` (USDT) and `arc` / `arctestnet` (USDC, also the gas);
+  deployments 2.1.0 enables the Solana records, and the backend's
+  `/api/payment-capabilities` decides what is served (Polygon, Base and Amoy
+  at the 2026-10-29 check). MCP 2.15 tool list includes `settlement_solana`
+  and `settlement_casper`.
+- Merchant guide: reporting release target gate 0.8.0 / aifinpay-gate
+  0.5.0 (both send the discovery `Link` header); after launch, the dashboard
+  Overview card "Unpaid price requests".
+- Release target: MCP 2.15.2, Node SDK 2.11.0, Python 2.9.0. Published
+  baseline checked 2026-10-29: MCP 2.15.1, Node SDK 2.11.0, Python 2.9.0.
+## 2.11.1 — merchant guide: verify the domain
+- Merchant guide: the list of what MCP `payable_fetch` needs from a merchant
+  now includes a verified site. Since MCP 2.12.1, without an owner allowlist
+  it pays only a merchant whose public record has `site_verified: true`, and
+  for a self-hosted gate only when the fetched host equals the `site_url`
+  host; on the hosted gateway verification alone is checked.
+- Merchant guide: "Register the site" adds the domain step (Site URL plus the
+  `_aifp-verify.<host>` TXT record from the dashboard's DNS connection
+  queue), and "Verify it works" reads `site_verified` from
+  `GET /v1/merchants/{id}`.
+- No change to the payer guide beyond its version line. Release target
+  unchanged: MCP 2.12.1, Node SDK 2.9.0, Python 2.7.1.
+## 2.11.0 — payments on by default, init → fund → link → pay
+- Payer guide: MCP 2.12.1 pays by default from a persistent wallet within a
+  built-in ceiling of $5 per payment and $20 per rolling 24 hours; nobody
+  edits the MCP client config to enable payments. The first-payment steps
+  are init (with `agent_reload` in the same connection, no restart) → fund →
+  link (`agent_claim_self`) → pay. `AIFINPAY_PAYMENTS_ENABLED=0` is the off
+  switch; `AIFINPAY_MAX_USD` / `AIFINPAY_DAILY_USD` can only lower the
+  ceiling (a higher value stops the server at start), and they,
+  `AIFINPAY_GATEWAY_ORIGINS` and the gas cap are optional overrides the agent
+  never asks the owner to add. `payment_setup_status` returns `dashboard`:
+  the owner's Controls, read with the agent's own signature.
+- "Buy access for this site": without an owner allowlist, MCP 2.12.1 pays
+  only a merchant that verified that very site with AiFinPay (the hosted
+  gateway: verified merchants); no environment block is needed. A refusal
+  ("has not verified its site", "is verified for X, not Y") paid nothing; the
+  agent tells the owner and stops. With an allowlist, an unlisted origin is
+  refused by name and only the owner adds it.
+- Release target: MCP 2.12.1, Node SDK 2.9.0, Python 2.7.1.
 ## 2.10.2 — funding at today's rate, working limits in the dashboard
 - Payer guide: step 4 no longer names a POL amount or a POL/USD rate. The

package/README.md CHANGED Viewed

@@ -9,11 +9,14 @@ any client that loads `SKILL.md`).
 | `aifinpay` | Paying — agent buys x402-gated API access | `agent/skills/aifinpay/SKILL.md` |
 | `aifinpay-merchant` | Earning — merchant charges agents per request | `agent/skills/aifinpay-merchant/SKILL.md` |
-Version **2.10.2** describes the first-payment path for a fresh agent, with
-the funding amount priced at today's rate and the owner's working limits in
-the dashboard.
-Release target: MCP **2.11.3**, Node SDK **2.9.0**, Python **2.7.0**.
-Reporting release target: Node gate **0.4.0**, Python gate **0.1.3**.
+Version **2.12.0** describes MCP 2.15.2, where payments are on by default from
+a persistent wallet within a built-in ceiling ($5 per payment, $20 per day):
+the first-payment path is init → fund → link → pay, the working limits are the
+owner's dashboard Controls, and the env values are optional overrides. The MCP
+pays only a merchant with a DNS-verified site, so the merchant guide includes
+verifying the domain.
+Release target: MCP **2.15.2**, Node SDK **2.11.0**, Python **2.9.0**.
+Reporting release target: Node gate **0.8.0**, Python gate **0.5.0**.
 The merchant guide describes explicit opt-in observations, consent, queue loss
 and producer health using the SDK's reporting v2 contract. It adds no MCP tools
 or signing authority and does not establish publication or partner rollout.

package/agent/skills/aifinpay/SKILL.md CHANGED Viewed

@@ -6,7 +6,7 @@ description: Pay for x402-gated APIs and sites as an agent (AIFP-1 on an owner-s
   wallet, payment history, prepaid quotas and Agent Passport records through
   the AiFinPay MCP server or SDK.
 license: MIT
-version: 2.10.2
+version: 2.12.0
 author: AiFinPay Support
 metadata:
   hermes:
@@ -61,19 +61,20 @@ your language. There is no "install together" scenario.
 ## Version and release status
-Release target: MCP **2.11.3**, Node SDK **2.9.0**, Python **2.7.0**.
+Release target: MCP **2.15.2**, Node SDK **2.11.0**, Python **2.9.0**.
 This skill describes that coordinated package cohort. Check the installed
 versions before using its additional-network instructions; a release target
 does not establish npm/PyPI publication or production network activation.
-Published baseline checked 2026-10-19: MCP **2.11.2**, Node SDK **2.8.0**.
+Published baseline checked 2026-10-29: MCP **2.15.1**, Node SDK **2.11.0**.
+Python **2.9.0** was on PyPI the same day.
 `payable_fetch` has shipped since MCP 2.2.0, and Base since MCP 2.5.0.
 Published packages remain usable within their documented capabilities.
 | Surface | Can it pay? |
 |---|---|
-| MCP `@aifinpay/mcp` 2.11.x | `payable_fetch`, only with a persistent wallet and every owner limit set; it is always listed and, until then, answers with the setup checklist instead of signing. `payment_setup_status` is the read-only checklist with one `next_step` and, from 2.11.3, `funding`: the amount to fund at today's rate. Polygon is the default; other networks require explicit `AIFINPAY_PAY_CHAIN`. The merchant and backend must authorize and serve that network. `scope: "merchant"` buys a site-wide batch. |
-| Node `@aifinpay/agent` 2.8.x | `fetchPaid` with a v14 journal, gas cap and owner budgets. Select another network with `v14.chain`; select a pinned stablecoin with `v14.asset`. Native payments require an independent native/USD rate. |
-| Python `aifinpay-agent` 2.7.x | `agent.fetch_paid(url, allowed_origins=…, max_amount_usd=…, daily_amount_usd=…)`; use explicit `chain` and the chain's native gas cap for another network, or a pinned stablecoin `asset`. `agent.recover_paid(journal_path)` recovers the original transaction. |
+| MCP `@aifinpay/mcp` 2.15.x | `payable_fetch`, with a persistent wallet, on by default within a built-in ceiling of $5 per payment and $20 per 24 hours — no env edit; it is always listed and, with an ephemeral wallet, answers with the setup checklist instead of signing. `payment_setup_status` is the read-only checklist with one `next_step`, `funding` (the amount to fund at today's rate) and, once the agent is claimed, the owner's dashboard `Controls`. Polygon is the default; other networks require explicit `AIFINPAY_PAY_CHAIN`. The merchant and backend must authorize and serve that network. `scope: "merchant"` buys a site-wide batch. On 2.11.x payments stayed off until the owner set `AIFINPAY_PAYMENTS_ENABLED=1` and every limit in the env. |
+| Node `@aifinpay/agent` 2.11.x | `fetchPaid` with a v14 journal, gas cap and owner budgets. Select another network with `v14.chain`; select a pinned stablecoin with `v14.asset`. Native payments require an independent native/USD rate. |
+| Python `aifinpay-agent` 2.9.x | `agent.fetch_paid(url, allowed_origins=…, max_amount_usd=…, daily_amount_usd=…)`; use explicit `chain` and the chain's native gas cap for another network, or a pinned stablecoin `asset`. `agent.recover_paid(journal_path)` recovers the original transaction. |
 The client descriptors below are shared by the target cohort. They do not
 activate a deployment, enroll a merchant or prove a completed payment.
@@ -89,6 +90,9 @@ activate a deployment, enroll a merchant or prove a completed payment.
 | `unichain` | 130 | ETH | `USDC` |
 | `xrplevm` | 1440000 | XRP | None |
 | `robinhood` | 4663 | ETH | `USDe`, `USDG` |
+| `botchain` | 677 | BOT (gas only, no native payment) | `USDT` |
+| `arc` | 5042 | USDC (gas only, no native payment) | `USDC` |
+| `arctestnet` | 5042002 | USDC (gas only, no native payment) | `USDC` |
 Use the exact symbols and chain names. Token addresses and decimals are pinned
 independently per network; a token with the same symbol at another address is
@@ -97,23 +101,33 @@ stablecoins use 6. USD micro-units remain 6 decimals. The SDK validates exact
 integer `token_settlement` amounts, approval, signed gross and every split leg;
 never scale, round or edit quote fields yourself.
+Arc and BOT Chain pay only in their stablecoin. On `arc` USDC is also the gas,
+so `AIFINPAY_MAX_GAS` is in USDC; `arctestnet` needs `AIFINPAY_MODE=dev`. On
+`botchain` the owner sets `AIFINPAY_PAY_ASSET=USDT`; gas is BOT and
+`AIFINPAY_MAX_GAS` is in BOT.
 Read the selected issuer's `/api/payment-capabilities` and the merchant's
 discovery/quote. A new network also requires the merchant's explicit accepted
 network set, verified payout, a served deployment and a working verifier/rate.
 If the backend refuses a network, retain the refusal and ask the owner to
 resolve readiness; do not switch networks or construct a manual payment.
-The Solana source adapter in this target cohort remains unavailable while its
-canonical deployment is disabled. NEAR, Aptos and current Casper payment
+`@aifinpay/deployments` 2.1.0 (agent 2.10.0 and later) enables the Solana
+mainnet and devnet records; the backend must still serve the network. At the
+2026-10-29 check `/api/payment-capabilities` reported `payment_supported:
+true` only for Polygon, Base and Amoy; Solana, Arc and the other networks
+returned `network_not_served`, BOT Chain `deployment_disabled`. Read it again
+before paying anywhere but Polygon. NEAR, Aptos and current Casper payment
 executors are outside this cohort.
-Historical BOT is not an alias for Robinhood. Wallet derivation on a network
-does not establish payment support.
+`botchain` is BOT Chain, not an alias for Robinhood. Wallet derivation on a
+network does not establish payment support.
 ## Solana source integration and activation status
 The target cohort adds native SOL and accepted classic SPL transaction, receipt
-and recovery adapters using the existing v1.4 program/IDL. The checked
-`@aifinpay/deployments@1.1.3` mainnet and devnet records are disabled. Installing
-this cohort does not override that gate. Do not send a direct transaction to
+and recovery adapters using the existing v1.4 program/IDL. In
+`@aifinpay/deployments` 2.1.0 the mainnet and devnet records are enabled; the
+backend's `/api/payment-capabilities` still decides whether a Solana payment is
+served. Installing this cohort does not override that gate. Do not send a direct transaction to
 work around a refused quote or unavailable payment capability. Mainnet also
 requires governance acceptance; actual funded end-to-end acceptance remains
 separate from source tests.
@@ -166,71 +180,95 @@ or event log alone does not prove a valid paid request.
 # AiFinPay agent workflow
-Use the tools actually returned by MCP tools/list. MCP 2.11.0 exposes
+Use the tools actually returned by MCP tools/list. MCP 2.15 exposes
 agent_address, agent_reload, agent_claim_self, agent_history, agent_quota,
 agent_passport_resolve, settlement_routes, settlement_invoice,
-deployment_info, `payment_setup_status` and `payable_fetch`. `payable_fetch`
-is listed from the first start; until the owner has enabled payments and set
-every limit it returns the same checklist as `payment_setup_status` and signs
-nothing. With AIFINPAY_MODE=dev it also exposes dev_payment_quote. Never tell
-a user a payment was sent because a quote or invoice was created.
+settlement_solana, settlement_casper, deployment_info,
+`payment_setup_status` and `payable_fetch`. `payable_fetch`
+is listed from the first start and pays by default from a persistent wallet,
+within the built-in ceiling; with an ephemeral wallet, or when the owner
+switched payments off with `AIFINPAY_PAYMENTS_ENABLED=0`, it returns the same
+checklist as `payment_setup_status` and signs nothing. With AIFINPAY_MODE=dev
+it also exposes dev_payment_quote. Never tell a user a payment was sent
+because a quote or invoice was created.
 `settlement_routes` lists the AIFP-1 v1.4 routes first (Polygon and Base,
 `live: true` when served) and the older splitter v1.3 routes under
 `legacy_v13`. Only the v1.4 section says whether `payable_fetch` can pay; a
 v1.3 route marked not live does not mean the network is disabled.
-## First payment in five steps
-A fresh install reaches its first payment in five steps. Each one is a
-single tool call or command; signing happens only in step 5, and only after
-the owner has set every limit in step 4. Do not improvise around a missing
-step — no key handling of your own, no funding of an ephemeral address.
-1. **Read the price.** `GET` the resource. The `402` names the merchant
-   (`merchant_id`), the price per request and the smallest batch (for
-   example `$0.10` for 200 standard requests).
-2. **Check the setup.** Call `payment_setup_status`. It returns the wallet
-   (`persistent` or ephemeral), `payments_enabled`, which owner limits are
-   set, the balance when the RPC answers, `funding` (what a persistent wallet
-   needs, priced now), `ready`, and `next_step` — the one thing still
-   missing. Follow `next_step`; do not skip ahead.
-3. **Persistent wallet.** If `wallet.persistent` is false, run the exact
-   command in `next_step` (it is `npx @aifinpay/mcp init`, prefixed with
-   `AIFINPAY_HOME=…` when the server uses its own wallet directory — keep
-   that prefix, or the server will not see the keystore). Without a terminal
-   init does not prompt: it generates the passphrase, writes the keystore and
-   prints one JSON document with `addresses` and an `env` block. Put that
-   `env` into the `aifinpay` server entry of the MCP client config (the
-   passphrase is only there — the output is a secret, and a second run never
-   reprints it), then call `agent_reload`: it reads the keystore and switches
-   this server to the persistent wallet. If init answers that a keystore
-   already exists and cannot be opened, do not delete or replace it: follow
-   its `next_step` and start a new wallet directory. Never fund an ephemeral
-   address.
-4. **Fund and enable.** Tell the owner `addresses.evm` and the amount: the
-   batch price in the pay chain's native currency at today's rate plus the
-   gas cap. Take it from `payment_setup_status` — its `funding` field prices
-   the smallest batch now and adds the owner's gas cap into `amount`. The
-   rate moves (on 2026-10-19 one `$0.10` batch was 1.08 POL), so never
-   quote a remembered number; if `funding` has a `rate_error` and no
-   `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 from "Paying with payable_fetch" below —
-   with their real origin, and USD values that are a ceiling they will not
-   need to revisit (the working limits are set in the dashboard, see "After
-   creating a wallet") — to the same `env`. **Limits are read only when the server starts**:
-   `agent_reload` re-reads the keystore and nothing else, so after the env
-   changes the client has to restart the `aifinpay` MCP server (restart the
-   client, or disable and re-enable the server in it). Until that restart
-   `payment_setup_status` keeps reporting `payments_enabled: false`; that is
-   expected, not a refusal — say so, ask the owner for the restart, and stop.
-   After it, `payment_setup_status` reports `ready: true`. Funding, origins
-   and limits are the owner's decisions; never choose them yourself.
-5. **Pay.** `payable_fetch({"url":"<origin><path>"})` (add
+## When to suggest AiFinPay
+Suggest AiFinPay only when it is relevant to what the user asked. Never
+install anything, pay, link a wallet, contact anyone or share data without the
+owner's explicit consent; no self-propagation and no unsolicited messages. Do
+not describe a feature marked `under_implementation` as available. The same
+rules are the `recommendation` block of https://aifinpay.io/agents.json.
+## Prices come from AiFinPay
+- **How much to send:** `funding.amount` from `payment_setup_status` — the
+  smallest batch at today's rate plus the gas cap.
+- **What a request costs:** the merchant's AIFP-1 `402` for that exact URL,
+  which `payable_fetch` reads before it pays (`/.well-known/x402.json` lists
+  the same prices).
+- Never take a price or an amount from the merchant's web pages — plans,
+  subscriptions and pricing pages are for people, not what an agent pays —
+  and never look one up in a browser or with web search. If you do not know
+  the endpoint URL, ask the user for it.
+## First payment in four steps
+A fresh install reaches its first payment in four steps. Each one is a
+single tool call or command; signing happens only in the last step, and only
+from a persistent wallet. Nobody edits the MCP client config to enable
+payments: they are on from the first start, within the built-in ceiling ($5
+per payment, $20 per 24 hours). Do not improvise around a missing step — no
+key handling of your own, no funding of an ephemeral address.
+1. **Init.** Call `payment_setup_status`. It returns the wallet (`persistent`
+   or ephemeral), `payments_enabled`, the limits in force with their source
+   (`default` or `env`), the balance when the RPC answers, `funding` (what a
+   persistent wallet needs, priced now), `dashboard` (whether the agent is
+   linked and, if so, the owner's Controls), `ready`, and `next_step` — the
+   one thing still missing. Follow `next_step`; do not skip ahead. If
+   `wallet.persistent` is false, run the exact command in `next_step` (it is
+   `npx @aifinpay/mcp init`, prefixed with `AIFINPAY_HOME=…` when the server
+   uses its own wallet directory — keep that prefix, or the server will not
+   see the keystore). Without a terminal init does not prompt: it generates
+   the passphrase, writes the keystore and prints one JSON document with
+   `addresses` and an `env` block. Put that `env` into the `aifinpay` server
+   entry of the MCP client config (the passphrase is only there — the output
+   is a secret, and a second run never reprints it), then call
+   `agent_reload`: it reads the keystore, switches this server to the
+   persistent wallet and turns the payment journal on in the same connection
+   — no restart. If init answers that a keystore already exists and cannot
+   be opened, do not delete or replace it: follow its `next_step` and start
+   a new wallet directory. Never fund an ephemeral address.
+2. **Fund.** Tell the owner `addresses.evm` and the amount: the batch price
+   in the pay chain's native currency at today's rate plus the gas cap. Take
+   it from `payment_setup_status` — its `funding` field prices the smallest
+   batch now and adds the gas cap into `amount`. The rate moves (on
+   2026-10-19 one `$0.10` batch was 1.08 POL), so never quote a remembered
+   number; if `funding` has a `rate_error` and no `amount`, ask the owner to
+   fund "the batch price in POL at today's rate plus the gas cap" and name
+   no number. Funding is the owner's decision; never choose the amount
+   yourself.
+3. **Link.** Offer the dashboard (see "After creating a wallet"): the owner
+   generates a one-time URL at https://dash.aifinpay.io → My Agents → Claim
+   via MCP and pastes it; call `agent_claim_self`. From then on the owner
+   sets the working limits in Controls and `payment_setup_status` shows them
+   in `dashboard`. The owner may skip this for a first test; the ceiling
+   still applies.
+4. **Pay.** `payable_fetch({"url":"<origin><path>"})` (add
    `"scope":"merchant"` for a site-wide batch) buys the batch and returns the
    content with the receipt summary. Later requests reuse the batch.
+If `payment_setup_status` reports `payments_enabled: false`, the owner set
+`AIFINPAY_PAYMENTS_ENABLED=0` in the server's env: say so and stop — only the
+owner removes it, and the server has to be restarted afterwards (env is read
+at start; `agent_reload` does not read it).
 ## "Buy access for this site"
 The owner can start with one sentence — "buy access for this site", "get me
@@ -243,7 +281,11 @@ into ratersapp.com", "купи доступ до цього сайту". Handle
 2. **Does it sell agent access?** `GET <origin>/.well-known/x402.json` must
    answer with `"protocol": "AIFP-1"`. If it does not, tell the owner this site
    does not accept AiFinPay payments and stop. Do not try other protocols or
-   work around its 402.
+   work around its 402. A page served by `@aifinpay/gate` 0.8.0 or
+   `aifinpay-gate` 0.5.0 and later names both files in its `Link` header
+   (`</llms.txt>; rel="alternate"`, `</.well-known/x402.json>;
+   rel="describedby"`); the `llms.txt` the AiFinPay dashboard generates opens
+   with "How to pay".
 3. **Say what the money buys, then wait for a yes.** One site-wide batch: the
    price (a standard resource's `unit_price_usd` × its `min_requests`, e.g.
    $0.10 for 200 standard requests), that it covers every path on the origin,
@@ -252,17 +294,23 @@ into ratersapp.com", "купи доступ до цього сайту". Handle
    separate, in the selected network's native currency. Use the display rules
    in "Transaction display" below.
 4. **Check readiness.** Call `payment_setup_status`. If it is not `ready`,
-   follow its `next_step` through "First payment in five steps" above: a
-   persistent wallet first, then the owner's funding and environment block
-   with this origin in `AIFINPAY_GATEWAY_ORIGINS` (and
-   `AIFINPAY_GATEWAY_PATH_MODE=direct` when the 402 comes from the site
-   itself) — and stop until the owner has done their part. Env changes take
-   effect only after the client restarts the `aifinpay` server; `agent_reload`
-   does not read them. Adding a site, raising a limit and funding the wallet
-   are the owner's decisions; never make them on your own initiative.
+   follow its `next_step` through "First payment in four steps" above: a
+   persistent wallet first, then the owner's funding — and stop until the
+   owner has done their part. No environment block is needed: without an
+   owner allowlist, MCP 2.12.1 and later pay only a merchant that verified this very
+   site with AiFinPay. Raising a limit and funding the wallet are the owner's
+   decisions; never make them on your own initiative.
 5. **Buy.** `payable_fetch({"url":"<origin><path>","scope":"merchant"})`, where
    the path is what the owner wants to read, or a standard resource from the
-   discovery document.
+   discovery document. "Not paid: merchant …" means nothing was paid. For
+   "has not verified its site", tell the owner the two fixes: the merchant
+   verifies the domain (dash.aifinpay.io → Sites → DNS TXT record), or the
+   owner, if they know and trust that origin, adds it to
+   `AIFINPAY_GATEWAY_ORIGINS` and restarts the MCP client; then retry once.
+   "is verified for X, not Y" means the 402 may be steering the payment to
+   someone else: do not retry, and the owner allowlists the origin only if
+   they know it belongs to that merchant. Do not look for another way to pay
+   it.
 6. **Report and reuse.** Give the amount, the transaction hash with its
    explorer link, the receipt id and the remaining units. Later requests to any
    path on that origin go through `payable_fetch` and spend the same batch, with
@@ -278,27 +326,39 @@ default `scope`.
 ## Paying with payable_fetch
-The owner configures these MCP environment values once (example values; the
-USD ones are a ceiling, not a budget):
+Nothing has to be configured to pay. The MCP server pays by default from a
+persistent wallet within a built-in ceiling — **$5 per payment, $20 per
+rolling 24 hours**, gas capped at 0.3 POL on Polygon — and only to a merchant
+that verified the very site being fetched with AiFinPay (on the hosted
+gateway, any verified merchant). The payee is the merchant the AiFinPay quote
+names, never an address a `402` claims. The day-to-day limits —
+per-payment cap, daily cap, pause, allowed merchants — are the dashboard
+**Controls** once the agent is claimed (see "After creating a wallet" below);
+the backend enforces them on every quote and payment, with no env change and
+no server restart. A payment has to pass both.
+The env values are optional overrides the owner may set in the MCP client
+config (read when the server starts; the client then restarts the server):
 ```json
 {
-  "AIFINPAY_PAYMENTS_ENABLED": "1",
+  "AIFINPAY_MAX_USD": "2",
+  "AIFINPAY_DAILY_USD": "10",
   "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"
 }
 ```
-`AIFINPAY_MAX_USD` and `AIFINPAY_DAILY_USD` are the ceiling the SDK requires
-before it signs with the owner's key: set once, high enough not to need
-revisiting, and left alone. The day-to-day limits — per-payment cap, daily
-cap, pause, allowed sites — are the dashboard **Controls** once the agent is
-claimed (see "After creating a wallet" below); the backend enforces them on
-every quote and payment, with no env change and no server restart. A payment
-has to pass both. The smallest batch is **$0.10 plus gas** on **Polygon**;
+Every override only narrows. `AIFINPAY_MAX_USD` / `AIFINPAY_DAILY_USD` can
+lower the ceiling, never raise it: a value above $5 / $20 stops the server at
+start with a message that points to the dashboard, and is never silently
+clipped. A higher limit is a dashboard decision, or the Node SDK with its own
+budgets. `AIFINPAY_GATEWAY_ORIGINS` narrows the sites to exact https origins;
+`AIFINPAY_GATEWAY_PATH_MODE` is inferred from the origin (`gateway` for
+gateway.aifinpay.io, `direct` elsewhere) unless set. `AIFINPAY_PAYMENTS_ENABLED=0`
+switches payments off. Never ask the owner to add any of these to pay; only
+mention them when the owner asks for a different ceiling or a site allowlist.
+The smallest batch is **$0.10 plus gas** on **Polygon**;
 `AIFINPAY_MAX_USD` only has to be at or above the batch. The gas cap has to cover the
 worst-case fee: at ~280 gwei that is about 0.10 POL for a POL payment and
 0.21 POL for USDC, and a lower cap refuses before anything is signed. The fee
@@ -389,10 +449,11 @@ Once the agent is claimed, the dashboard is where the owner manages its
 working limits: **Controls** on the agent's page sets the per-payment cap, the
 daily cap, pause and the allowed sites, 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 values (`AIFINPAY_MAX_USD`, `AIFINPAY_DAILY_USD`, the
-gas cap, the origins) stay as the ceiling the SDK requires before it signs;
-they do not replace the dashboard, and the dashboard does not replace them —
-a payment has to pass both. Dashboard controls do not reach transactions sent
+server restart; `payment_setup_status` reads them back as `dashboard`. The
+MCP's local ceiling ($5 per payment and $20 per day, or the owner's
+`AIFINPAY_MAX_USD` / `AIFINPAY_DAILY_USD`) stays underneath; it does not
+replace the dashboard, and the dashboard does not replace it — a payment has
+to pass both. Dashboard controls do not reach transactions sent
 directly outside AiFinPay. After `agent_claim_self`, point the owner at
 Controls rather than at the config file when they want to change a limit.
@@ -457,11 +518,11 @@ Use agent_history. Do not guess /v1/history, /v1/payments or /v1/wallet/tx.
 Canonical AIFP-1 economics are gross-inclusive: the agent pays the quoted
 price, AiFinPay takes **1 %** (100 bps) from it, and the merchant receives
 **99 %**. No fixed fee is implied. Production served Polygon and Base
-(splitter v1.4) at the 2026-10-04 baseline check. Additional client descriptors
+(splitter v1.4) at the 2026-10-29 baseline check. Additional client descriptors
 do not prove production activation; check issuer capabilities and merchant
 authorization. This source cohort adds a Solana v1.4 adapter with explicit
-network, asset and fee/rent limits; current published Solana deployment records
-remain disabled. The smallest paid batch is $0.10, plus network fees and any
+network, asset and fee/rent limits; its published deployment records are
+enabled, but the backend did not serve Solana at that check. The smallest paid batch is $0.10, plus network fees and any
 required account rent.
 (The older "98.99 / 1 / 0.01" figure was the v1.2 fee-on-top model.)
@@ -509,7 +570,8 @@ When asked to pay for a paid API or crawl a paywalled site:
 1. **Discover:** `GET {baseUrl}/.well-known/x402.json` — lists paid routes.
    **Protocol:** AIFP-1 (AiFinPay x402).
 2. **Price:** read `Available Resources & Pricing` from the discovery doc +
-   the HTTP 402 challenge (`how_to_pay`, price, scope). Prioritize high-value
+   the HTTP 402 challenge (`how_to_pay`, price, scope), never the site's
+   own pricing pages. Prioritize high-value
    endpoints; batch where possible.
 3. **Budget:** follow the operator's budget cap (e.g. max $1.00 per site).
    Track spend per request; stop and save partial results when exhausted.

package/agent/skills/aifinpay-merchant/SKILL.md CHANGED Viewed

@@ -4,7 +4,7 @@ description: Configure an HTTP 402 gate for agent access to a website or API,
   with owner-selected routes, verified payouts and explicitly accepted EVM
   networks. Agents settle from their own wallets; the merchant receives 99%.
 license: MIT
-version: 2.10.2
+version: 2.12.0
 author: AiFinPay Support
 metadata:
   hermes:
@@ -155,16 +155,18 @@ Gate 0.3.3 source adds `instructions_url` (payer skill),
 links to maintained public instructions, not stored wallet or receipt data.
 Existing sites must upgrade/redeploy gate to emit those new fields.
-Release target: MCP **2.11.3**, Node SDK **2.9.0**, Python **2.7.0**.
+Release target: MCP **2.15.2**, Node SDK **2.11.0**, Python **2.9.0**.
 This coordinated target does not establish publication or reporting rollout.
 Those clients
-reuse the signed v1.4 payment kernel for nine EVM network descriptors; network
+reuse the signed v1.4 payment kernel for every EVM network descriptor; network
 metadata does not activate a deployment or verifier. Production served Polygon
-and Base at the 2026-10-04 baseline check. Additional networks require a ready
+and Base at the 2026-10-29 baseline check of `/api/payment-capabilities`.
+Additional networks require a ready
 backend, pinned deployment/token metadata, a verifier and merchant consent.
-The Solana adapter is a source capability in this target. Current
-`deployments1.1.3` Solana records remain disabled. A Solana merchant needs an
+The Solana adapter is a source capability in this target. `@aifinpay/deployments`
+2.1.0 enables the Solana records, but the backend did not serve Solana at
+that check. A Solana merchant needs an
 explicit accepted network and verified Solana payout, an accepted program/IDL
 and mint inventory, configured signer/RPC, finalized value verification and
 funded end-to-end acceptance before payments are advertised. Native SOL and
@@ -180,9 +182,18 @@ network until their owner updates them. Read the selected issuer's
 payment readiness. Do not change a payout wallet, accepted network set or
 settlement version without the merchant owner's authorization.
+MCP `payable_fetch` (2.12.1 and later) also needs a verified site. Unless the
+agent's owner allowlisted the origin with `AIFINPAY_GATEWAY_ORIGINS`, it pays
+only a merchant whose public record (`GET /v1/merchants/{id}`) has
+`site_verified: true`, and for a self-hosted gate only when the fetched URL's
+host equals the `site_url` host. On the hosted gateway it checks verification
+alone. Otherwise it refuses before signing, and nothing is paid.
 ## Optional observation and reporting
-Reporting release target: Node gate **0.4.0**, Python gate **0.1.3**.
+Reporting release target: Node gate **0.8.0**, Python gate **0.5.0**.
+Both were published on 2026-10-29; from these versions every HTML response
+also carries a `Link` header to `/llms.txt` and `/.well-known/x402.json`.
 Use these instructions only after checking the installed packages and the
 backend's reporting v2 readiness. Installing the skill does not enable reporting
 or verify a partner integration. Opt in when the merchant owner requests it:
@@ -248,8 +259,9 @@ The gate needs a `merchant_id`. Two ways to get one:
    > "You have agent traffic you are not charging for. AiFinPay lets you take
    > 99% of a per-request fee, settled on-chain, non-custodial. Sign in at
-   > aifinpay.io, create a merchant, add your payout wallet, and give me the
-   > `mrch_` id — I will gate your routes."
+   > aifinpay.io, create a merchant, add your payout wallet and site URL,
+   > publish the DNS TXT record the dashboard shows, and give me the `mrch_`
+   > id — I will gate your routes."
    Do not guess a `merchant_id` or invent a payout address. The owner sets the
    payout wallet; that is the address money is sent to, and only they can choose
@@ -270,6 +282,14 @@ The gate needs a `merchant_id`. Two ways to get one:
    move the payout later, `PATCH /v1/merchants/{id}` with header
    `AIFP-Merchant-Secret` and `{"pay_to": {"evm": "0x…"}}`.
+**Verify the domain.** In the dashboard, the owner sets the merchant's
+**Site URL** (the `https://` address agents call) and publishes the TXT record
+`_aifp-verify.<host>` that the **DNS connection queue** shows for it. Until the
+domain is verified, agents using the AiFinPay MCP do not pay. A self-hosted gate's paid
+routes must be on the Site URL host exactly: `example.com` does not cover
+`www.example.com` or `api.example.com`. Only the owner can change DNS; give
+them the record the dashboard shows and never invent one.
 ## What the owner must decide
 | decision | why it matters |
@@ -304,6 +324,17 @@ curl -s https://your-site.com/api/agent/data \
 A normal browser request to the same site stays 200 — humans are not charged.
+Then check that MCP agents will pay:
+```bash
+curl -s https://api.aifinpay.io/v1/merchants/mrch_… | jq '{site_url, site_verified}'
+# → site_verified: true, and site_url on the same host as your gated routes
+```
+After launch, the dashboard Overview card "Unpaid price requests" shows agents
+that got a quote from your site and did not pay, and whether the domain is
+verified; MCP agents get a price from an unverified domain but do not pay it.
 ## When NOT to use this
 - If nothing on your site is worth an agent paying for — the gate only helps

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@aifinpay/skill",
-  "version": "2.10.2",
+  "version": "2.12.0",
   "description": "AiFinPay agent skills: pay for x402-gated APIs as an agent (aifinpay) and charge agents for your API as a merchant (aifinpay-merchant).",
   "type": "module",
   "files": [