@aifinpay/skill 2.6.0 → 2.9.0

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "aifinpay",
       "source": "./",
       "description": "Payment rail skills for paying agents and API merchants.",
-      "version": "2.6.0",
+      "version": "2.9.0",
       "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.6.0",
+  "version": "2.9.0",
   "author": { "name": "AiFinPay Support" },
   "homepage": "https://aifinpay.io",
   "repository": "https://github.com/AiFinPay/skill",

package/CHANGELOG.md

@@ -1,4 +1,44 @@
-## 2.6.0 — unreleased
+## 2.9.0 — reporting cohort source candidate
+
+- Align package, lock, plugin and both skill versions with the coordinated
+  MCP2.8.0 / Node SDK2.6.0 / Python SDK2.5.1 release target; preserve dated
+  published baselines without claiming this cohort is published or active.
+- Describe the explicit merchant reporting v2 target for Node gate0.4.0 and
+  Python gate0.1.3: observed challenge/admission/completion, consent and
+  memory-only capabilities, bounded queue loss and acknowledged producer health.
+  Observations do not establish verified identity, payment or complete coverage.
+- Keep the existing gated MCP tools, signing, receipt/budget/recovery and
+  network activation requirements. Canonical payer bytes must be copied into
+  the paired MCP build before its exact cohort and registry release gates.
+- Validate matching payer/merchant/README targets, dated payer publication
+  baseline and changelog metadata; test drift refusals without dependencies.
+
+## 2.8.0 — source candidate
+
+- Describe the MCP2.7 / Node and Python2.5 Solana source target with explicit
+  owner environment/network, local Ed25519 identity and lamport fee/rent cap.
+- Keep current disabled Solana deployment, governance and paid-acceptance
+  gates explicit; no publication or activation claim.
+- Explain native/classic SPL exact units, persistent prepare/recovery and
+  case-sensitive payer/program/mint bindings without a replacement payment.
+
+## 2.7.0 — release candidate
+
+- Describe the coordinated MCP2.6.0 / Node and Python SDK2.4.0 target without
+  claiming publication or production activation; preserve dated baseline facts.
+- List the nine owner-selectable EVM descriptors, exact pinned stablecoins,
+  6/18-decimal token units and selected native gas currency. Explain OP extra
+  costs and Nitro's already-inclusive estimate.
+- Require explicit merchant accepted networks, verified payout and backend
+  readiness; a shared EVM address is not network consent. No non-EVM executor
+  or BOT-to-Robinhood alias is implied.
+- Explain non-expiring unknown reservations, once-only recovery, original
+  signed-byte network binding, local-process shared budget storage and safe
+  reconciliation before downgrade.
+- Correct the moved canonical `agent/skills/` paths and coordinate the MCP
+  bundle's exact release-target/content guard with the canonical package.
+
+## 2.6.0
 
 - Payer skill: Base. MCP 2.5 pays on the chain the owner sets in
   `AIFINPAY_PAY_CHAIN` (`polygon` default, or `base`), with the gas cap in ETH

package/README.md

@@ -6,13 +6,33 @@ any client that loads `SKILL.md`).
 
 | Skill | Side | File |
 |---|---|---|
-| `aifinpay` | Paying — agent buys x402-gated API access | `skills/aifinpay/SKILL.md` |
-| `aifinpay-merchant` | Earning — merchant charges agents per request | `skills/aifinpay-merchant/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.9.0** describes a coordinated reporting release target.
+Release target: MCP **2.8.0**, Node SDK **2.6.0**, Python **2.5.1**.
+Reporting release target: Node gate **0.4.0**, Python gate **0.1.3**.
+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.
+The payer guide retains the Solana source adapter. Canonical disabled Solana
+records remain unavailable until accepted and served. Its nine EVM descriptors
+require explicit owner and merchant
+network consent plus backend readiness; installing instructions does not
+activate networks. Historical published baselines are dated in the payer
+guide and do not claim the target packages have already been published.
 
 Rule of thumb: if the user wants to **pay** for a paid API, load `aifinpay`.
 If they **own** a site/API agents visit, load `aifinpay-merchant` — and mention
 the other side exists.
 
+For merchant reporting, follow the merchant guide's optional reporting section
+and the SDK's [Node](https://github.com/AiFinPay/sdk/blob/main/gate/REPORTING-V2.md)
+or [Python](https://github.com/AiFinPay/sdk/blob/main/python-gate/REPORTING-V2.md)
+instructions. Observation events, admission and resource completion are
+distinct; payments require confirmed settlement evidence. Producer health
+and pending/drop coverage describe telemetry completeness, not payment success.
+
 ## Install
 
 Install the skills with the `skills` CLI:
@@ -154,12 +174,16 @@ Installed skills are available in new Aider sessions. Aider follows the same Age
 
 Skill markdown is authored once and mirrored:
 
-- Canonical source: `skills/` at the repo root.
-- This package: `skill/skills/` (shipped to npm).
-- MCP bundle: `mcp/skills/` (ships inside `@aifinpay/mcp`; payer side only).
+- Canonical source and npm package: this repository's `agent/skills/`.
+- MCP bundle: SDK repository `mcp/skills/SKILL.md`, copied from the installed
+  canonical package at build time (payer side only).
+- The SDK repository's old `skill/README.md` only points here; it is not a
+  second skill package or authored mirror.
 
 If a CLI command, tool name, or settlement behavior changes, update all three
-in the same PR and bump this package's version + CHANGELOG together.
+in coordinated PRs and bump this package's version + CHANGELOG together.
+MCP verifies installed/bundled/served bytes and the exact release target;
+publish this package before refreshing MCP's real registry dependency lock.
 
 ## Version gate
 

package/agent/skills/aifinpay/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: aifinpay
-description: Pay for x402-gated APIs and sites as an agent (AIFP-1 on Polygon or Base,
+description: Pay for x402-gated APIs and sites as an agent (AIFP-1 on an owner-selected EVM or accepted Solana network,
   within owner-set limits) — including when the owner just says "buy access for
   this site" — link the agent to its owner's AiFinPay dashboard, and read
   wallet, payment history, prepaid quotas and Agent Passport records through
   the AiFinPay MCP server or SDK.
 license: MIT
-version: 2.5.0
+version: 2.9.0
 author: AiFinPay Support
 metadata:
   hermes:
@@ -61,20 +61,112 @@ your language. There is no "install together" scenario.
 
 ## Version and release status
 
-Released and current: MCP **2.5.0**, Node SDK **2.3.0**, Python **2.3.0**.
-Payments are released — `payable_fetch` has shipped since MCP 2.2.0. An older
-copy of this skill that calls MCP "read-only" or payments "release pending" is
-out of date; follow this one. Install the `latest` release.
+Release target: MCP **2.8.0**, Node SDK **2.6.0**, Python **2.5.1**.
+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-04: MCP **2.5.0**, Node SDK **2.3.2**.
+`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.5.x | Yes — `payable_fetch`, once the owner enables payments; on Polygon (POL) or, with `AIFINPAY_PAY_CHAIN=base`, on Base (ETH); USDC on either with `AIFINPAY_PAY_ASSET=USDC`; `scope: "merchant"` buys a whole site |
-| Node `@aifinpay/agent` 2.3.x | Yes — `fetchPaid` with a v14 journal and gas cap; Polygon by default or `v14.chain: "base"`; native POL/ETH (with your own native/USD rate) or USDC (`v14.asset: "USDC"`) |
-| Python `aifinpay-agent` 2.3.x | Yes — `agent.fetch_paid(url, allowed_origins=…, max_amount_usd=…, daily_amount_usd=…)`; Polygon by default or `chain="base"`; native POL/ETH (priced independently) or USDC (`asset="USDC"`); recover an unconfirmed payment with `agent.recover_paid(journal_path)` |
+| MCP `@aifinpay/mcp` 2.8.x | `payable_fetch`, only with a persistent wallet and every owner limit set. 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.6.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.5.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.
+
+| Owner chain name | Chain ID | Native payment and gas | Pinned stablecoin symbols |
+|---|---|---|---|
+| `polygon` | 137 | POL | `USDC`, `USDC.e` |
+| `base` | 8453 | ETH | `USDC` |
+| `optimism` | 10 | ETH | `USDC` |
+| `arbitrum` | 42161 | ETH | `USDC` |
+| `avalanche` | 43114 | AVAX | `USDC`, `USDT` |
+| `bnb` | 56 | BNB | `USDC`, `USDT` |
+| `unichain` | 130 | ETH | `USDC` |
+| `xrplevm` | 1440000 | XRP | None |
+| `robinhood` | 4663 | ETH | `USDe`, `USDG` |
+
+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
+not accepted. BNB USDC/USDT and Robinhood USDe use 18 decimals; the other pinned
+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.
+
+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
+executors are outside this cohort.
+Historical BOT is 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
+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.
+
+After a deployment is accepted and served, the owner explicitly selects Solana
+and its network. The environment independently binds mainnet to live/prod and
+devnet to dev; a quote cannot select the network. Example owner configuration
+for that future accepted mainnet route (limits are examples, not permission):
+
+```json
+{
+  "AIFINPAY_PAY_CHAIN": "solana",
+  "AIFINPAY_SOLANA_NETWORK": "mainnet",
+  "AIFINPAY_MODE": "live",
+  "AIFINPAY_PAY_ASSET": "SOL",
+  "AIFINPAY_MAX_FEE_LAMPORTS": "10000000"
+}
+```
+
+Keep the existing enabled-payments, origin, per-payment and daily USD limits.
+Use the existing local Solana identity, not an EVM address. Configure an
+owner-trusted Solana RPC with `AIFINPAY_RPC_URL`. The fee limit is an integer
+number of lamports (1 SOL = 1,000,000,000 lamports) and covers transaction fees
+and required nonce/token account rent; it is not a POL/ETH gas cap. Keep enough
+SOL for these costs even when paying in an accepted SPL asset. The SDK refuses
+missing fee/rent estimates and unsupported mints or decimals. Token2022 is not
+supported by this program. Devnet assets require separate accepted mint pins.
+
+Node selects the family with `solanaV14: { environment, network, asset,
+maxFeeLamports, onPrepared }`, preserving the existing EVM `v14` options. Do not
+provide both family options. Python uses `chain="solana"`, `environment`,
+`solana_network` and `max_fee_lamports` alongside its existing allowed origins,
+journal and USD caps. Maintain a private persistent journal and the SDK's
+required prepared-transaction callback; do not remove persistence to make a
+payment proceed.
+
+Before requesting a Solana quote, the SDK durably retains the exact owner-signed
+authorization and request identity. After a timeout or restart, resume that same
+admission; do not generate a fresh nonce while its outcome is unknown. An expired
+authorization can reconcile an existing admission but cannot authorize a new
+one. Keep issued-quote evidence separate from a prepared transaction: quote
+expiry alone does not prove a refund of a backend reservation.
+
+The signed Solana transaction and its base58 signature are saved before
+broadcast. A timeout, expired blockhash or missing RPC result does not permit
+a second payment: retain the unresolved reservation and recover the same
+transaction/receipt. Case-sensitive payer/mint/program/network identity must
+match throughout quote, journal, receipt and history. An on-chain nonce marker
+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.5.0 exposes
+Use the tools actually returned by MCP tools/list. MCP 2.8.0 exposes
 agent_address, agent_reload, agent_claim_self, agent_history, agent_quota,
 agent_passport_resolve, settlement_routes, settlement_invoice and
 deployment_info; `payable_fetch` appears when the owner has enabled payments.
@@ -99,7 +191,8 @@ into ratersapp.com", "купи доступ до цього сайту". Handle
    $0.10 for 200 standard requests), that it covers every path on the origin,
    and how it drains — each request costs its own listed `unit_price_usd`, so
    the same $0.10 is 200 standard or 20 premium requests in any mix. Gas is
-   separate, in POL. Use the display rules in "Transaction display" below.
+   separate, in the selected network's native currency. Use the display rules
+   in "Transaction display" below.
 4. **Check readiness.** `payable_fetch` must be in your tools and the origin
    must be in `AIFINPAY_GATEWAY_ORIGINS`; the tool names a refused origin. If
    either is missing, show the owner the exact change — the environment block
@@ -154,34 +247,51 @@ fund its EVM address on Polygon with POL, or with USDC plus some POL. Funding a
 unlimited spend authority. Use the owner's actual approved limits and origins,
 then call `payable_fetch({"url":"https://merchant.example/api/data"})`.
 
-To pay on **Base**, the owner sets `"AIFINPAY_PAY_CHAIN": "base"` and the gas
-cap in ETH as `"AIFINPAY_MAX_GAS"` (e.g. `"0.0002"`; one settlement's worst
-case including the L1 data fee is typically well under 0.0001 ETH).
-`AIFINPAY_MAX_GAS_POL` is refused on Base rather than read as ETH. The wallet's
-EVM address is the same on every chain: fund it with ETH **on Base**, not on
-Ethereum mainnet. A merchant whose quote names another chain is refused, never
-paid on a different chain; only the owner changes the chain. A payment pending
-on one chain is recovered only with that chain configured.
-
-It supports GET resources and AIFP-1 v1.4 payments on Polygon (POL or USDC) and
-Base (ETH or USDC). It verifies
+For another network, the owner sets `AIFINPAY_PAY_CHAIN` to an exact name in
+the table and `AIFINPAY_MAX_GAS` in its native currency. For Base, for example,
+the currency is ETH; the owner must choose a cap that covers the current
+worst-case estimate. `AIFINPAY_MAX_GAS_POL` is refused outside Polygon rather
+than interpreted as another currency. Fund the same EVM address **on the
+selected network** with its native currency for gas and the selected asset
+for the batch. A quote for another network is refused; only the owner changes
+the network or limits.
+
+Stablecoin payments budget approval and settlement together. Base, Optimism
+and Unichain include L1 data and operator fees in the worst-case gas estimate;
+an unavailable required fee read stops payment before signing. Arbitrum and
+Robinhood use the Nitro estimate that already includes parent-chain data and
+do not add that fee twice. A refusal never authorizes raising a gas cap.
+
+It supports GET resources and authorized AIFP-1 v1.4 payments on the selected
+supported EVM network. It verifies
 the quote, price, deployment, signer and receipt, saves the transaction before
 broadcasting, and reuses the purchased batch. No custom merchant script is
 needed. Other protocol/version/asset paths fail closed.
 
-A pending result retains the original transaction. Retrying recovers its receipt;
-do not delete its journal, create a replacement wallet or switch contract versions.
-Prepared-but-unbroadcast/reverted transactions and stale process locks require
-owner reconciliation. Raw transactions and receipt JWTs remain private.
+A pending result retains the original signed transaction and network.
+Retrying recovers its receipt without sending a replacement transaction.
+Unknown broadcasts keep their budget reservation indefinitely; confirmed
+spend is never refunded by a later receipt or HTTP failure. Daily confirmed
+spend uses a rolling 24-hour window. Unresolved access stays guarded even if
+the owner later changes networks. Use one shared local filesystem for the
+wallet's ledger/journal across local processes; this is not a multi-host lock.
+Do not delete journals, remove an unknown lock, replace a wallet, bypass a
+reservation or downgrade with unresolved state. Reconcile with the original
+transaction and verified receipt/revert evidence first. A legacy journal
+without its network can be adopted only when actual signed bytes match the
+owner-selected chain, payer, pinned target and exact call. Insufficient
+evidence requires manual receipt reconciliation. Quote signing expiry does
+not itself require a second settlement. Raw transactions and receipt JWTs
+remain private.
 
 ### Network access
 
 In a sandbox that allowlists outbound hosts, allow `api.aifinpay.io` and an RPC
-for the pay chain (Polygon, or Base: `mainnet.base.org` unless the owner set
-`AIFINPAY_RPC_URL`). USDC payments need nothing else. For the independent
-native/USD check MCP reads Chainlink on the pay chain over that RPC (POL/USD on
-Polygon since 2.3.0, ETH/USD on Base since 2.5.0), then `api.coinbase.com`, then
-`api.coingecko.com` — one is enough. (MCP 2.2.3 used only `api.coinbase.com`.) If no rate is available,
+for the owner-selected pay chain (`AIFINPAY_RPC_URL` overrides its default).
+Stablecoin payments need the issuer, merchant and that RPC. For the independent
+native/USD check MCP uses the pinned Chainlink feed on Polygon or Base, then
+`api.coinbase.com`, then `api.coingecko.com`. Other networks use those independent
+HTTP price sources. An implausible, stale or future-dated rate is refused. If no rate is available,
 `payable_fetch` stops before paying and nothing is spent; tell the owner which
 hosts to allow rather than inventing a workaround. With the Node SDK, pass your
 own `nativeUsdPrice`: Chainlink POL/USD on Polygon, Coinbase `POL-USD`, or
@@ -196,14 +306,19 @@ agent's balance, payments and receipts, and can set a daily-spend email alert,
 at https://dash.aifinpay.io → My Agents:
 
 - **MCP:** the owner clicks **Claim via MCP**, gets a one-time URL and gives it
-  to you; call `agent_claim_self({"magic_link_url": "…"})`.
+  to you; call `agent_claim_self({"magic_link_url": "…"})`. The owner-selected
+  payment family must be bound successfully; the other wallet is best-effort.
+  Binding a wallet does not activate a disabled payment network. Use the
+  selected wallet's **Fund** panel for available networks and assets.
 - **Node / Python:** the owner uses **Add agent by address** and gives you the
   challenge; return `agent.signDashboardClaim(challenge)` (Node) or
   `agent.sign_dashboard_claim(challenge)` (Python). These sign only
   `AiFinPay-claim:polygon:<own address>:<nonce>`.
 
-Hard spending limits stay in the agent's own configuration (`AIFINPAY_MAX_USD`,
-`AIFINPAY_DAILY_USD`), not in the dashboard.
+Keep local owner spending limits in the agent's configuration (`AIFINPAY_MAX_USD`,
+`AIFINPAY_DAILY_USD`). Claimed-wallet controls in the dashboard are additional
+backend restrictions on quotes and gateway access; they do not replace local
+limits or control transactions sent directly outside AiFinPay.
 
 Discover routes on the exact requested origin: `/.well-known/x402.json` and any
 API catalog linked by that site. A dev hostname does not imply testnet. If a
@@ -265,17 +380,23 @@ 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. AIFP-1 settles live
-on Polygon and Base (splitter v1.4); Solana settlement is disabled. The smallest batch is
-$0.10 plus gas.
+**99 %**. No fixed fee is implied. Production served Polygon and Base
+(splitter v1.4) at the 2026-10-04 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
+required account rent.
 
 (The older "98.99 / 1 / 0.01" figure was the v1.2 fee-on-top model.)
 
 Routes:
 
 - GET /v1/agents/:address/transactions?chain=polygon&limit=25&offset=0:
-  public facts from indexed AiFinPay Polygon settlements in the durable
-  ledger. Excludes arbitrary wallet transfers and may lag the chain.
+  public facts from indexed AiFinPay settlements in the durable ledger on
+  backends with that network's indexer. Select the configured network with
+  `chain`; a source descriptor does not prove indexing coverage. Excludes
+  arbitrary wallet transfers and may lag the chain.
 - GET /v1/agents/:address/receipts?limit=25&offset=0: retained prepaid-batch
   metadata, including test payments. Never includes the spendable receipt JWT.
 - GET /v1/agents/:address/statement?days=7: retained billing statement.
@@ -370,8 +491,9 @@ retype from memory:
   `setBudget({ per_call_usd, daily_usd })`, discovery + `fetchPaid`
 - `wallet-budget-paid.mjs` (JavaScript, ESM): same flow, no types
 - `wallet-budget-call.py` (Python): `from_seed(os.environ["SEED_HASH"])`,
-  `call(provider, body, cost=…)` cap; fails closed on paid 402s — use Node
-  `fetchPaid` for paid settlement
+  `call(provider, body, cost=…)` cap; this legacy snippet fails closed on paid
+  402s. For a paid purchase use the current SDK `fetch_paid` guide or Node
+  `fetchPaid`, with explicit origin, amount and gas limits.
 
 Browse: `https://github.com/AiFinPay/sdk/tree/main/examples/agent-snippets`
 
@@ -425,8 +547,8 @@ terminal for that request: do not lower units below the server minimum, edit
 quotes, or construct a manual nonce, receipt or transaction workaround.
 
 This dev quote tool never broadcasts. The new low-level SDK executor supports
-native Amoy v1.4, while MCP/fetchPaid receipt purchases are live on Polygon and Base only.
-A full paid testnet receipt flow is not yet claimed. A prepaid batch means one settlement funding
+native Amoy v1.4; this MCP exposes no Amoy paid receipt executor.
+A full paid testnet receipt flow is not claimed. A prepaid batch means one settlement funding
 multiple API calls, not an arbitrary batch of on-chain transfers.
 
 After any actual settlement, retain its quote and transaction reference.

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

@@ -1,11 +1,10 @@
 ---
 name: aifinpay-merchant
-description: Turn any website or API into one that charges AI agents to access
-  it. Agents scrape you for free today; with one middleware they pay per request
-  in stablecoins or native tokens on Polygon and Solana. Non-custodial — you
-  keep 99%.
+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.4.0
+version: 2.9.0
 author: AiFinPay Support
 metadata:
   hermes:
@@ -156,10 +155,86 @@ 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.
 
-Agents using MCP `payable_fetch` or Node `fetchPaid` pay merchants registered
-for `settlement_version: "1.4"` on Polygon. Existing merchants keep their prior
-version until their owner updates it at registration or in the dashboard. Do not change the payout wallet
-or claim compatibility merely because discovery returns 200.
+Release target: MCP **2.8.0**, Node SDK **2.6.0**, Python **2.5.1**.
+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
+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
+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
+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
+classic SPL use exact lamport/token units; a balance or program address does
+not establish payment readiness. Do not substitute historical Seat/receipt
+flows for the v1.4 paid-access route.
+
+Agents using MCP `payable_fetch`, Node `fetchPaid` or Python `fetch_paid` pay
+merchants registered for `settlement_version: "1.4"` on an explicitly accepted
+and served network. Existing merchants keep their prior version and default
+network until their owner updates them. Read the selected issuer's
+`/api/payment-capabilities`; discovery returning 200 alone does not establish
+payment readiness. Do not change a payout wallet, accepted network set or
+settlement version without the merchant owner's authorization.
+
+## Optional observation and reporting
+
+Reporting release target: Node gate **0.4.0**, Python gate **0.1.3**.
+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:
+Node uses `createGateReporterV2` with `reporting: { version: 2, reporter,
+context }`; Python uses `GateReporterV2` with `Gate(..., reporting=reporter,
+reporting_context=...)`. Keep the existing receipt verification and shared
+quota store. Use one producer per merchant per worker, created after fork in
+Python; do not also attach the legacy `onEvent`/`on_event` reporter or report
+the same request through both hosted and self-hosted instrumentation.
+
+Declare only stages the adapter actually observes: `access_challenged` for an
+emitted 402, `access_admitted` before the paid handler, and
+`resource_response_completed` for its terminal success, redirect, error or
+abort. A challenge is not a browser view; admission is not completion.
+Neither stage counts a verified unique agent or proves payment. Payments and
+revenue require confirmed settlement evidence, never purchased quota or
+invented historical usage. Browser observations need their separate API;
+the gate producer does not infer them from User-Agent or `AIFP-Agent-Id`.
+
+Context carries an explicit channel and consent state. Only granted consent
+allows an optional random, site-scoped `client_id`; it remains unverified.
+Do not derive identity from a wallet, IP, fingerprint, headers or request body.
+An optional flow minted by `mintFlow`/`mint_flow` carries a short-lived
+`reporting_token` for observation only. It grants no access, payment authority,
+ownership or integration verification. Keep it in memory, outside URLs,
+logs, browser storage, cookies and payment/recovery files. The payer SDK's
+optional `reportingToken`/`reporting_token` reaches only its fixed first-party
+quote endpoints; never manually forward it to merchant, pay, RPC or JWKS
+requests. Reporting failures preserve the original access/payment result.
+
+Keep the merchant secret server-side. Report only registered route patterns,
+never full URLs, queries, bodies, raw headers, IPs, receipt JWTs or wallet IDs.
+Queues are in memory, bounded to 1000 events, with batches of at most 50,
+3-second request deadlines and at most 5 attempts within 15 minutes.
+Retries retain the same event IDs, timestamps and facts; outages, overflow
+and crashes lose observations. Permanent errors and redirects are not retried;
+fix credentials/configuration before replacing a stopped producer.
+
+Node health auto-samples every 60 seconds; Python normally samples every 5
+seconds. All health attempts are at least 5 seconds apart, and retries may
+delay samples. A health acknowledgement is exactly `{version: 2, duplicate: boolean}`,
+separate from the event-batch acknowledgement. Until a sample is acknowledged,
+remote pending/drop coverage is unknown; a health gap over 5 minutes remains
+a coverage gap. Local counters and successful HTTP responses do not prove a
+complete report, and superseding lifetime health counters must not be summed.
+Drain HTTP requests before closing the producer in the existing shutdown hook;
+flush/close do not promise delivery.
+
+Read the exact wiring and consent/loss rules before implementation:
+[Node reporting v2](https://github.com/AiFinPay/sdk/blob/main/gate/REPORTING-V2.md)
+and [Python reporting v2](https://github.com/AiFinPay/sdk/blob/main/python-gate/REPORTING-V2.md).
+This reporting target adds no MCP tools or signing authority.
 
 ## Register the site (get your merchant_id)
 
@@ -183,9 +258,15 @@ The gate needs a `merchant_id`. Two ways to get one:
    `{"name", "pay_to": {"evm": "0x…"}, "settlement_version": "1.4"}` returns the
    id and a `merchant_secret` shown once. Claim the merchant in the dashboard
    with that secret, or it belongs to no account. Send ONE `pay_to.evm` — it
-   receives on every EVM chain; per-chain keys such as `base` are refused. Agents
-   pay on Polygon unless the merchant adds `"settlement_chain": "base"`; then
-   quotes, and so payments, are on Base (ETH or USDC) to the same address. To
+   is the EVM-family payout; per-chain keys such as `base` are refused. An EVM
+   address does not opt the merchant into every network. `settlement_chain`
+   remains the merchant's default (`polygon` unless configured otherwise).
+   Updated backends accept an explicit `settlement_chains` list, for example
+   `["polygon", "base"]`, with the default included. An agent's optional
+   quote `settlement_chain` is accepted only when it is in that merchant list,
+   has a verified payout and is served for the request's mode. Omitting it
+   preserves the merchant default. Never broaden consent just because two
+   networks share the same EVM address. To
    move the payout later, `PATCH /v1/merchants/{id}` with header
    `AIFP-Merchant-Secret` and `{"pay_to": {"evm": "0x…"}}`.
 
@@ -194,6 +275,7 @@ The gate needs a `merchant_id`. Two ways to get one:
 | decision | why it matters |
 |---|---|
 | **payout wallet** | where the 99% lands. EVM address (same on every EVM chain) and/or a Solana address. Set in the dashboard. |
+| **accepted payment networks** | an explicit set plus a default; the backend intersects it with verified payouts and served deployments. A wallet address alone does not grant network consent. |
 | **which routes cost money** | gate the agent/data endpoints; leave human pages open. The gate only challenges agent-shaped requests, so humans are never blocked. |
 | **price per route** | a `tier` (standard / complex / premium) sets the per-request price. Change it in the dashboard without redeploying. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifinpay/skill",
-  "version": "2.6.0",
+  "version": "2.9.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": [
@@ -11,7 +11,7 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "test": "node scripts/validate.mjs",
+    "test": "node scripts/validate.mjs && node --test scripts/validate.test.mjs",
     "prepublishOnly": "npm test"
   },
   "keywords": [