@aifinpay/skill 2.1.0 → 2.3.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.
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,19 @@
|
|
|
1
|
+
## 2.3.0 — 2026-09-24
|
|
2
|
+
|
|
3
|
+
- Payer skill: Python `aifinpay-agent` 2.2.0 pays — `agent.fetch_paid(...)` in
|
|
4
|
+
POL or USDC, `agent.recover_paid(journal_path)` after an unconfirmed payment.
|
|
5
|
+
Current versions: MCP 2.3.0, Node 2.2.0, Python 2.2.0.
|
|
6
|
+
- Merchant skill: AiFinPay is not an x402 facilitator (run the gate next to an
|
|
7
|
+
existing x402 middleware, route by `AIFP-Receipt`); what a Python gate must
|
|
8
|
+
check; API registration with one `pay_to.evm`, claim, and moving the payout.
|
|
9
|
+
|
|
10
|
+
## 2.2.0 — 2026-09-24
|
|
11
|
+
|
|
12
|
+
- Payer skill: agents can pay in USDC. MCP 2.3.0 `payable_fetch` pays in USDC
|
|
13
|
+
when the owner sets `AIFINPAY_PAY_ASSET=USDC` (USDC for the batch plus a little
|
|
14
|
+
POL for gas); Node 2.2.0 `fetchPaid` with `v14: { asset: "USDC" }`. Current
|
|
15
|
+
versions: MCP 2.3.0, Node 2.2.0, Python 2.1.1 (does not pay).
|
|
16
|
+
|
|
1
17
|
## 2.1.0 — 2026-09-23
|
|
2
18
|
|
|
3
19
|
- Payer skill: payments are released. MCP `payable_fetch` (2.2.0+) and Node
|
|
@@ -5,7 +5,7 @@ description: Pay for x402-gated APIs and sites as an agent (AIFP-1 on Polygon,
|
|
|
5
5
|
and read wallet, payment history, prepaid quotas and Agent Passport records
|
|
6
6
|
through the AiFinPay MCP server or SDK.
|
|
7
7
|
license: MIT
|
|
8
|
-
version: 2.
|
|
8
|
+
version: 2.3.0
|
|
9
9
|
author: AiFinPay Support
|
|
10
10
|
metadata:
|
|
11
11
|
hermes:
|
|
@@ -41,7 +41,7 @@ metadata:
|
|
|
41
41
|
wallet, within limits its owner sets, and gets a receipt that unlocks a batch of
|
|
42
42
|
requests. Settlement is non-custodial: the agent's private key signs locally and
|
|
43
43
|
no AiFinPay-controlled custodian touches funds. MCP `payable_fetch` (2.2.0+) and
|
|
44
|
-
Node `fetchPaid` (2.1.0+)
|
|
44
|
+
Node `fetchPaid` (2.1.0+) and Python `fetch_paid` (2.2.0+) execute payments.
|
|
45
45
|
|
|
46
46
|
## Prerequisites — required packages
|
|
47
47
|
|
|
@@ -60,20 +60,20 @@ your language. There is no "install together" scenario.
|
|
|
60
60
|
|
|
61
61
|
## Version and release status
|
|
62
62
|
|
|
63
|
-
Released and current: MCP **2.
|
|
63
|
+
Released and current: MCP **2.3.0**, Node SDK **2.2.0**, Python **2.2.0**.
|
|
64
64
|
Payments are released — `payable_fetch` has shipped since MCP 2.2.0. An older
|
|
65
65
|
copy of this skill that calls MCP "read-only" or payments "release pending" is
|
|
66
66
|
out of date; follow this one. Install the `latest` release.
|
|
67
67
|
|
|
68
68
|
| Surface | Can it pay? |
|
|
69
69
|
|---|---|
|
|
70
|
-
| MCP `@aifinpay/mcp` 2.
|
|
71
|
-
| Node `@aifinpay/agent` 2.
|
|
72
|
-
| Python `aifinpay-agent` |
|
|
70
|
+
| MCP `@aifinpay/mcp` 2.3.x | Yes — `payable_fetch`, once the owner enables payments; POL, or USDC with `AIFINPAY_PAY_ASSET=USDC` |
|
|
71
|
+
| 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"`) |
|
|
72
|
+
| 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)` |
|
|
73
73
|
|
|
74
74
|
# AiFinPay agent workflow
|
|
75
75
|
|
|
76
|
-
Use the tools actually returned by MCP tools/list. MCP 2.
|
|
76
|
+
Use the tools actually returned by MCP tools/list. MCP 2.3.0 exposes
|
|
77
77
|
agent_address, agent_reload, agent_claim_self, agent_history, agent_quota,
|
|
78
78
|
agent_passport_resolve, settlement_routes, settlement_invoice and
|
|
79
79
|
deployment_info; `payable_fetch` appears when the owner has enabled payments.
|
|
@@ -95,14 +95,18 @@ The owner configures these MCP environment values (example limits only):
|
|
|
95
95
|
}
|
|
96
96
|
```
|
|
97
97
|
|
|
98
|
-
The smallest batch is **$0.10 plus gas
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
98
|
+
The smallest batch is **$0.10 plus gas** on **Polygon**; keep `AIFINPAY_MAX_USD`
|
|
99
|
+
a little above the batch you expect to buy. It is paid in **POL** by default.
|
|
100
|
+
To pay in **USDC** instead, the owner also sets `"AIFINPAY_PAY_ASSET": "USDC"`:
|
|
101
|
+
the wallet then needs USDC for the batch plus a little POL (about 0.05) for gas,
|
|
102
|
+
because the tool approves exactly the batch amount and then settles — two
|
|
103
|
+
transactions, both within `AIFINPAY_MAX_GAS_POL`. Use an existing persistent
|
|
104
|
+
wallet or create one with `npx @aifinpay/mcp init` (a passphrase is required);
|
|
105
|
+
fund its EVM address on Polygon with POL, or with USDC plus some POL. Funding a wallet does not establish
|
|
102
106
|
unlimited spend authority. Use the owner's actual approved limits and origins,
|
|
103
107
|
then call `payable_fetch({"url":"https://merchant.example/api/data"})`.
|
|
104
108
|
|
|
105
|
-
It supports GET resources and
|
|
109
|
+
It supports GET resources and Polygon AIFP-1 v1.4 payments in POL or USDC. It verifies
|
|
106
110
|
the quote, price, deployment, signer and receipt, saves the transaction before
|
|
107
111
|
broadcasting, and reuses the purchased batch. No custom merchant script is
|
|
108
112
|
needed. Other protocol/version/asset paths fail closed.
|
|
@@ -115,7 +119,8 @@ owner reconciliation. Raw transactions and receipt JWTs remain private.
|
|
|
115
119
|
### Network access
|
|
116
120
|
|
|
117
121
|
In a sandbox that allowlists outbound hosts, allow `api.aifinpay.io` and a
|
|
118
|
-
Polygon RPC. For the independent POL/USD check
|
|
122
|
+
Polygon RPC. USDC payments need nothing else. For the independent POL/USD check
|
|
123
|
+
on POL payments MCP 2.3.0 reads Chainlink on
|
|
119
124
|
Polygon over that RPC, then `api.coinbase.com`, then `api.coingecko.com` — one
|
|
120
125
|
is enough. (MCP 2.2.3 used only `api.coinbase.com`.) If no rate is available,
|
|
121
126
|
`payable_fetch` stops before paying and nothing is spent; tell the owner which
|
|
@@ -5,7 +5,7 @@ description: Turn any website or API into one that charges AI agents to access
|
|
|
5
5
|
in stablecoins or native tokens on Polygon and Solana. Non-custodial — you
|
|
6
6
|
keep 99%.
|
|
7
7
|
license: MIT
|
|
8
|
-
version: 2.
|
|
8
|
+
version: 2.3.0
|
|
9
9
|
author: AiFinPay Support
|
|
10
10
|
metadata:
|
|
11
11
|
hermes:
|
|
@@ -76,6 +76,18 @@ That is it. `aifpGate` returns a 402 with everything an agent needs to pay
|
|
|
76
76
|
(`how_to_pay`, price, scope). `aifpDiscovery` serves `/.well-known/x402.json` so
|
|
77
77
|
an agent that arrives at just your domain learns which routes cost money.
|
|
78
78
|
|
|
79
|
+
**Already running x402 (PayAI, Coinbase)?** AiFinPay is not an x402
|
|
80
|
+
facilitator — there is no `/verify` or `/settle` to point your middleware at,
|
|
81
|
+
and swapping a facilitator URL does nothing. Mount the gate next to it and
|
|
82
|
+
route by header: a request carrying `AIFP-Receipt` goes to AiFinPay.
|
|
83
|
+
|
|
84
|
+
**Python server?** There is no Python gate package yet. A Python gate must
|
|
85
|
+
verify `AIFP-Receipt` as an EdDSA JWT against
|
|
86
|
+
`https://api.aifinpay.io/.well-known/jwks.json` (issuer
|
|
87
|
+
`https://api.aifinpay.io`, `aud` = your `merchant_id`, `scope`/`resource`
|
|
88
|
+
covering the path, `network_mode` live) and meter its `unit_quota` — the same
|
|
89
|
+
checks `@aifinpay/gate` makes.
|
|
90
|
+
|
|
79
91
|
### Next.js
|
|
80
92
|
|
|
81
93
|
`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:
|
|
|
150
162
|
Do not guess a `merchant_id` or invent a payout address. The owner sets the
|
|
151
163
|
payout wallet; that is the address money is sent to, and only they can choose
|
|
152
164
|
it.
|
|
165
|
+
3. **API (scripts):** `POST https://api.aifinpay.io/v1/merchants` with
|
|
166
|
+
`{"name", "pay_to": {"evm": "0x…"}, "settlement_version": "1.4"}` returns the
|
|
167
|
+
id and a `merchant_secret` shown once. Claim the merchant in the dashboard
|
|
168
|
+
with that secret, or it belongs to no account. Send ONE `pay_to.evm` — it
|
|
169
|
+
receives on every EVM chain; per-chain keys such as `base` are refused. To
|
|
170
|
+
move the payout later, `PATCH /v1/merchants/{id}` with header
|
|
171
|
+
`AIFP-Merchant-Secret` and `{"pay_to": {"evm": "0x…"}}`.
|
|
153
172
|
|
|
154
173
|
## What the owner must decide
|
|
155
174
|
|
package/package.json
CHANGED