# AiFinPay

> Payment infrastructure for AI agents. Merchants publish paid resources over
> HTTP 402; agents use supported clients to buy access and reuse scoped receipts.

## Start here

- [Agent entry point](https://aifinpay.io/agent.txt): current setup and client limits.
- [Public skills](https://github.com/AiFinPay/skill): install with `npx skills add AiFinPay/skill`.
- [Payer skill](https://raw.githubusercontent.com/AiFinPay/skill/main/agent/skills/aifinpay/SKILL.md): instructions for an agent owner buying access.
- [Merchant skill](https://raw.githubusercontent.com/AiFinPay/skill/main/agent/skills/aifinpay-merchant/SKILL.md): instructions for a site or API owner accepting payments.
- [Skill package](https://www.npmjs.com/package/@aifinpay/skill): packaged instructions; installing npm files alone does not register a skill with an assistant.
- [Documentation](https://docs.aifinpay.io): setup, integration and protocol reference.
- [Dashboard](https://dash.aifinpay.io): merchants configure sites and see payments; agent owners link agents and see their balance, payments and receipts.

## Tools and verified availability — 2026-09-23

- Node/TypeScript: `npm install @aifinpay/agent`
- Python: `pip install aifinpay-agent`
- MCP: `npx -y @aifinpay/mcp`
- Persistent wallet setup: `npx @aifinpay/mcp init`
- Merchant gate: `npm install @aifinpay/gate` (Node), `pip install aifinpay-gate` (Python: FastAPI, Starlette, Flask, Django)
- [SDK source and versioned package documentation](https://github.com/AiFinPay/sdk)

`@aifinpay/mcp@2.3.0` is read-only by default: public addresses, wallet reload,
history, quotas, passport resolution, deployment information, settlement route
inspection and non-signing invoices. It registers `payable_fetch` only when the
owner enables payments — `AIFINPAY_PAYMENTS_ENABLED=1` with a persistent wallet
(`npx @aifinpay/mcp init`), per-payment and daily USD limits
(`AIFINPAY_MAX_USD`, `AIFINPAY_DAILY_USD`), a gas cap (`AIFINPAY_MAX_GAS_POL`) and
the exact https origins it may pay (`AIFINPAY_GATEWAY_ORIGINS`). `payable_fetch`
settles AIFP-1 on Polygon (splitter v1.4) only — in native POL by default, or
in USDC when the owner also sets `AIFINPAY_PAY_ASSET=USDC` (the wallet then
needs USDC for the batch and a little POL for gas). "Buy access for this site"
is `payable_fetch` with `scope: "merchant"`: one batch covers every path on the
site, each request at its own listed price; the default `scope: "exact"` buys
one resource. `agent_claim_self`
links the agent to its owner's dashboard (see below). `agent_call`,
`agent_quote`, `pay_with_split` and `quote_split` are not registered. The
server's bundled instructions are the MCP resource `aifinpay://skill`.

A skill copy (bundled or installed) that says MCP is read-only, or that native
payments are "release pending", predates MCP 2.2.0 and is out of date: payments
are released and `payable_fetch` pays once the owner enables it as above.
Update with `npx skills add AiFinPay/skill`.

Python `aifinpay-agent@2.2.1` `agent.fetch_paid(url, allowed_origins=…,
max_amount_usd=…, daily_amount_usd=…, asset="POL"|"USDC")` settles AIFP-1 on
Polygon v1.4 with the same checks as Node, journals each settlement before
sending it, and `agent.recover_paid(journal_path)` obtains the receipt of a
mined payment without paying again.

Node `@aifinpay/agent@2.2.0` `fetchPaid` settles AIFP-1 on Polygon v1.4 — native
POL, or USDC with `v14: { asset: "USDC" }` (exact-amount approval, then settle) —
against its pinned deployment, keeps the signed quote until the receipt is
issued, and recovers a receipt after a mined transaction without paying again.
Legacy v1.2 quotes are not compatible with it. `agent.pay` is a different
protocol path and is not a fallback for a rejected AIFP-1 deployment.

## Network access a paying agent needs

A sandbox that allowlists outbound hosts must allow:
- `api.aifinpay.io` — quotes and receipts;
- a Polygon RPC — MCP and the Node SDK use public endpoints by default;
- for the POL/USD rate, checked independently of the quote to enforce the
  owner's USD limits (POL payments only), MCP 2.3.0 tries the Chainlink POL/USD feed through the
  same Polygon RPC first, then `api.coinbase.com`, then `api.coingecko.com`.
  If none answers, `payable_fetch` stops before paying and nothing is spent.
With the Node SDK, `fetchPaid` takes the rate from your own `nativeUsdPrice`
callback; any independent source works (CoinGecko id `polygon-ecosystem-token`,
not the retired `matic-network`).

## Link the agent to its owner's dashboard

An agent owner can see the agent's balance, payments and receipts, and set a
daily-spend email alert, at https://dash.aifinpay.io → My Agents. Offer this
after creating a wallet. Two ways:
- Claim via MCP: the owner generates a one-time URL there and pastes it to the
  agent, which calls `agent_claim_self`. The URL only lets the agent link
  itself; it is single use and expires after 15 minutes.
- Add agent by address: the dashboard issues a challenge; the agent signs it
  with its EVM key (EIP-191 personal_sign of
  `AiFinPay-claim:polygon:<address>:<nonce>`) and the owner pastes the signature. Hard spending
limits are set in the agent's own configuration (`AIFINPAY_MAX_USD`,
`AIFINPAY_DAILY_USD`), not in the dashboard.

## Accept payments (merchants) — including if you already run x402

AiFinPay is not an x402 facilitator: there is no `/verify`, `/settle` or
`/supported` to point an existing x402 middleware at, and changing a
facilitator URL does not route payments through AiFinPay. Payments use
AIFP-1: your server answers 402 with an AIFP-1 challenge and accepts a request
that carries a valid `AIFP-Receipt`. It can run next to an existing x402
middleware; route by header (`AIFP-Receipt` present → AiFinPay).

1. Register: `POST https://api.aifinpay.io/v1/merchants` with
   `{"name": "...", "pay_to": {"evm": "0x..."}, "settlement_version": "1.4"}`.
   The response shows `merchant_secret` once. One `pay_to.evm` address
   receives on every EVM network — do not send per-network keys such as
   `base`. Change it later with `PATCH /v1/merchants/{id}`
   (header `AIFP-Merchant-Secret`), sending `pay_to.evm` only.
2. Claim it at https://dash.aifinpay.io with that secret, or it belongs to no
   account and does not appear in the dashboard.
3. Register paid routes: `POST /v1/merchants/{id}/resources` with
   `route_pattern`, `type` (required) and `tier`; send `"upsert": true` from
   deploy scripts.
4. Gate the routes: Node `npm install @aifinpay/gate`; Python
   `pip install aifinpay-gate` — `app.add_middleware(AifpGateMiddleware,
   gate=Gate("mrch_…", routes=[Route("/api/*")]))` for FastAPI/Starlette,
   `AifpGateWSGI` for Flask/Django. Both verify the `AIFP-Receipt` locally
   against https://api.aifinpay.io/.well-known/jwks.json and meter its
   `unit_quota`; with more than one worker process, pass a shared Redis store.
5. Browser checkout: `/v1/quote` and `/v1/pay` allow cross-origin requests.
   The payer's own EVM wallet settles on Polygon (chain id 137): in native POL,
   or in USDC with `"asset": "USDC"` in the quote request (the wallet approves
   the exact amount, then settles; it still needs a little POL for gas).

## Discover a merchant

Read `/.well-known/x402.json` on the SAME ORIGIN as the target website. It
lists that merchant's paid paths, tiers, unit prices and receipt scopes, and
points to quote/pay endpoints. Read the merchant's API catalog for HTTP
methods and required parameters. `/llms.txt` should link both catalogs on
the correct deployment origin.

The general AiFinPay skill describes how to use the product; it does not
contain every partner's routes. A self-hosted gate generates discovery from
the resource configuration supplied by the partner. It neither scans the
router nor automatically persists that array in the AiFinPay dashboard.

A protected request returns HTTP 402. With a supported executor, the flow
is quote → authorized settlement → verified quota receipt → retry with
AIFP-Receipt → data. Later covered calls consume quota from the same receipt.
Network gas is separate. The smallest batch is $0.10. A quote is not proof of
payment.

## Payment evidence and usage

Match the confirmed transaction, payer, resource and amount with the receipt
and merchant dashboard. The batch amount is gross paid, not automatically
net merchant revenue. Fees differ by path; `settlement.economics` in
https://api.aifinpay.io/.well-known/x402.json is authoritative:
- AIFP-1 (quote → pay): gross-inclusive — the quoted amount already contains
  the fee; 99% merchant, 1% AiFinPay, 0% creator.
- AIFP-2 (x402-compatible profile): the provider keeps its full price;
  AiFinPay's protocol fee is 0%.
- Legacy B2B bridge v1.2: a separate, older path where the fee is added to
  the payer's total.
Network gas is separate on every path. Always take the amount from the quote.
Hosted quota counters do not represent consumption at an independent
self-hosted gate. Ask that gate for its own usage information.

Keep keys, seed backups, passphrases, raw signed transactions and bearer
receipts private. On a timeout after broadcast, recover the existing payment
before considering another transaction.

## Further reference

- [Public agent flow](https://github.com/AiFinPay/sdk/blob/main/AGENT-FLOW.md)
- [AIFP-1 specification](https://github.com/AiFinPay/Protocol-AIFP-1)
- [AiFinPay discovery](https://api.aifinpay.io/.well-known/x402.json)
- [Receipt verification keys](https://api.aifinpay.io/.well-known/jwks.json)

## Deployment inventory (compatibility metadata)

AiFinPay's implementation spans 13 network surfaces. That is an inventory of
deployed or integrated protocol surfaces, not a list of places an agent can pay
today: payment is enabled only on `payment_enabled_networks` below, in the
released clients described above.

payment_enabled_networks: polygon-mainnet

networks: solana-mainnet, polygon-mainnet, avalanche-c-chain, bnb-mainnet, optimism, arbitrum-one, base-mainnet, unichain, bot-chain, xrpl-evm, near, aptos, casper-mainnet
settlement_networks: polygon-mainnet, solana-mainnet, base-mainnet, optimism, unichain, bot-chain, xrpl-evm
receipt_verifiable_networks: polygon-mainnet
identity_or_read_only_networks: avalanche-c-chain, bnb-mainnet, arbitrum-one, near, aptos, casper-mainnet
public_client_payment_status: released_polygon_v14

These retained inventory fields describe deployed protocol surfaces and backend
receipt verification. They do not enable a client or authorize signing. For the
installed package capabilities, use the version-specific client section above.