@aifinpay/skill 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 2.3.0 — 2026-09-24
+
+- Payer skill: Python `aifinpay-agent` 2.2.0 pays — `agent.fetch_paid(...)` in
+  POL or USDC, `agent.recover_paid(journal_path)` after an unconfirmed payment.
+  Current versions: MCP 2.3.0, Node 2.2.0, Python 2.2.0.
+- Merchant skill: AiFinPay is not an x402 facilitator (run the gate next to an
+  existing x402 middleware, route by `AIFP-Receipt`); what a Python gate must
+  check; API registration with one `pay_to.evm`, claim, and moving the payout.
+
 ## 2.2.0 — 2026-09-24
 
 - Payer skill: agents can pay in USDC. MCP 2.3.0 `payable_fetch` pays in USDC

package/agent/skills/aifinpay/SKILL.md

@@ -5,7 +5,7 @@ description: Pay for x402-gated APIs and sites as an agent (AIFP-1 on Polygon,
   and read wallet, payment history, prepaid quotas and Agent Passport records
   through the AiFinPay MCP server or SDK.
 license: MIT
-version: 2.2.0
+version: 2.3.0
 author: AiFinPay Support
 metadata:
   hermes:
@@ -41,7 +41,7 @@ metadata:
 wallet, within limits its owner sets, and gets a receipt that unlocks a batch of
 requests. Settlement is non-custodial: the agent's private key signs locally and
 no AiFinPay-controlled custodian touches funds. MCP `payable_fetch` (2.2.0+) and
-Node `fetchPaid` (2.1.0+) execute payments; the Python SDK does not yet.
+Node `fetchPaid` (2.1.0+) and Python `fetch_paid` (2.2.0+) execute payments.
 
 ## Prerequisites — required packages
 
@@ -60,7 +60,7 @@ your language. There is no "install together" scenario.
 
 ## Version and release status
 
-Released and current: MCP **2.3.0**, Node SDK **2.2.0**, Python **2.1.1**.
+Released and current: MCP **2.3.0**, Node SDK **2.2.0**, Python **2.2.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.
@@ -69,7 +69,7 @@ out of date; follow this one. Install the `latest` release.
 |---|---|
 | MCP `@aifinpay/mcp` 2.3.x | Yes — `payable_fetch`, once the owner enables payments; POL, or USDC with `AIFINPAY_PAY_ASSET=USDC` |
 | Node `@aifinpay/agent` 2.2.x | Yes — `fetchPaid` with a v14 journal and gas cap; POL (with your own POL/USD rate) or USDC (`v14.asset: "USDC"`) |
-| Python `aifinpay-agent` | No — use MCP or Node to pay |
+| Python `aifinpay-agent` 2.2.x | Yes — `agent.fetch_paid(url, allowed_origins=…, max_amount_usd=…, daily_amount_usd=…)`; POL (priced independently) or USDC (`asset="USDC"`); recover an unconfirmed payment with `agent.recover_paid(journal_path)` |
 
 # AiFinPay agent workflow
 

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

@@ -5,7 +5,7 @@ description: Turn any website or API into one that charges AI agents to access
   in stablecoins or native tokens on Polygon and Solana. Non-custodial — you
   keep 99%.
 license: MIT
-version: 2.2.0
+version: 2.3.0
 author: AiFinPay Support
 metadata:
   hermes:
@@ -76,6 +76,18 @@ That is it. `aifpGate` returns a 402 with everything an agent needs to pay
 (`how_to_pay`, price, scope). `aifpDiscovery` serves `/.well-known/x402.json` so
 an agent that arrives at just your domain learns which routes cost money.
 
+**Already running x402 (PayAI, Coinbase)?** AiFinPay is not an x402
+facilitator — there is no `/verify` or `/settle` to point your middleware at,
+and swapping a facilitator URL does nothing. Mount the gate next to it and
+route by header: a request carrying `AIFP-Receipt` goes to AiFinPay.
+
+**Python server?** There is no Python gate package yet. A Python gate must
+verify `AIFP-Receipt` as an EdDSA JWT against
+`https://api.aifinpay.io/.well-known/jwks.json` (issuer
+`https://api.aifinpay.io`, `aud` = your `merchant_id`, `scope`/`resource`
+covering the path, `network_mode` live) and meter its `unit_quota` — the same
+checks `@aifinpay/gate` makes.
+
 ### Next.js
 
 `aifpGate` is Express middleware and does not run in `middleware.ts`. Use
@@ -150,6 +162,13 @@ The gate needs a `merchant_id`. Two ways to get one:
    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
    it.
+3. **API (scripts):** `POST https://api.aifinpay.io/v1/merchants` with
+   `{"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. To
+   move the payout later, `PATCH /v1/merchants/{id}` with header
+   `AIFP-Merchant-Secret` and `{"pay_to": {"evm": "0x…"}}`.
 
 ## What the owner must decide
 

package/package.json

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