@aifinpay/skill 2.11.0 → 2.12.1

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -1,3 +1,48 @@
+## 2.12.1 — capability rows without status fields
+
+- Payer guide: `/api/payment-capabilities` lists only networks that take
+  payments, without `payment_supported` or other status fields; a row without
+  `native` is token-only. The dated 2026-10-29 network snapshot is removed.
+
+## 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

package/README.md

@@ -9,12 +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.11.0** describes MCP 2.12.1, where payments are on by default from
+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.
-Release target: MCP **2.12.1**, Node SDK **2.9.0**, Python **2.7.1**.
-Reporting release target: Node gate **0.4.0**, Python gate **0.1.3**.
+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

@@ -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.11.0
+version: 2.12.1
 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.12.1**, Node SDK **2.9.0**, Python **2.7.1**.
+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.12.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.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.
+`/api/payment-capabilities` lists only the networks it takes payments on, with
+no status fields: a network that is absent is not served, and a row without
+`native` is paid in its listed tokens only. 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,10 +180,11 @@ 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.12.1 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`
+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
@@ -182,6 +197,26 @@ because a quote or invoice was created.
 `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.
 
+## 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
@@ -246,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,
@@ -258,15 +297,20 @@ into ratersapp.com", "купи доступ до цього сайту". Handle
    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 pays only a merchant that verified this very
+   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. If it answers "Not paid: merchant … has not verified
-   its site" or "is verified for X, not Y", nothing was paid: tell the owner
-   the site's AiFinPay merchant has not verified this site, and stop. Do not
-   look for another way to pay it.
+   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
@@ -474,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.)
@@ -526,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

@@ -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.11.0
+version: 2.12.1
 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.12.1**, Node SDK **2.9.0**, Python **2.7.1**.
+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

@@ -1,6 +1,6 @@
 {
   "name": "@aifinpay/skill",
-  "version": "2.11.0",
+  "version": "2.12.1",
   "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": [