AiFinPay

@aifinpay/mcp

AiFinPay MCP server for persistent agent identity, Agent Passport resolution, route discovery and non-signing settlement invoices. Canonical domain: aifinpay.io.

Version 2.13.0 is prepared in this checkout, on the published agent 2.9.0 and canonical skill 2.11.0 (AiFinPay/skill 0490615, published 2026-10-22). The separate canonical producer's final immutable source pin is a required handoff, not a moving-branch substitution. The published baseline checked2026-10-04 was MCP2.5.0. Package publication and real registry dependency/lock refresh remain release gates; a source-cohort build does not prove those steps. Owner-enabled v1.4 purchases with payable_fetch are released: on Polygon since 2.2.0, on Base (ETH or USDC) since 2.5.0; site-wide batches with scope: "merchant" since 2.4.1. Since 2.12.1 payments are on by default: a persistent wallet created with init can pay with no payment env at all, within a built-in ceiling of $5 per payment and $20 per 24 hours, and only to merchants registered with AiFinPay. An ephemeral wallet signs nothing, and an unfunded one has nothing to spend. The working limits are the owner's dashboard Controls.

First payment in five steps

Nobody edits the MCP client config to turn payments on. Signing happens only in step 5, only with a persistent, funded wallet, and never above the ceiling.

1. Read the price. GET the resource. The 402 names the merchant (merchant_id), the price per request and the smallest batch ($0.02 for 40 standard requests).
2. Check the setup. Call payment_setup_status. It returns the wallet (persistent or ephemeral), the ceiling and each limit with its source (default or the owner's env), the balance when the RPC answers, funding (what to fund, priced at today's rate), the owner's dashboard Controls in dashboard, and next_step: the first thing still missing.
3. Init. If wallet.persistent is false, run npx @aifinpay/mcp init. Without a terminal it prints one JSON document; copy its env (the passphrase is only there) into the aifinpay server entry of the MCP client config, then call agent_reload in the same connection. No restart: the reload opens the payment journal for the new wallet. Never fund an ephemeral address.
4. Fund and link. Tell the owner addresses.evm and the amount from payment_setup_status's funding: the smallest batch ($0.02) in POL at today's rate plus the gas cap (0.3 POL by default; the SDK refuses before signing if the worst-case fee exceeds it). The rate moves, so never quote a remembered number; if funding carries a rate_error instead of an amount, ask the owner to fund "the batch price in POL at today's rate plus the gas cap" and name no number. Offer the dashboard link too: the owner generates a one-time URL under My Agents → Claim via MCP at https://dash.aifinpay.io and the agent passes it to agent_claim_self; from then on the owner sets the working limits in Controls.
5. Pay. payable_fetch({"url": "https://dev.ratersapp.com/api/agent/genres/list"}) buys the batch on Polygon (splitter v1.4) and returns the content and the receipt summary. Later requests reuse the batch.

Polygon and Base are served on v1.4 today; settlement_routes lists them first, with live: true. Its legacy_v13 section describes the older splitter v1.3 routes, which payable_fetch does not use.

Optional payment overrides

None of these is needed for a first payment, and each one only narrows what the defaults allow. init prints the same reference block:

{

"AIFINPAY_GATEWAY_ORIGINS": "https://merchant.example", "AIFINPAY_MAX_GAS_POL": "0.3" }

• AIFINPAY_GATEWAY_ORIGINS: exact HTTPS origins the agent may pay, comma-separated, no wildcards. Unset, the agent pays only a merchant whose site AiFinPay reports as DNS-verified, on that very site (or through the AiFinPay hosted gateway): the payee comes from the backend-signed quote, never from the 402, and is refused before anything is signed if its verified site is not the host being fetched. Set, an unlisted origin is refused by name and only the owner can add it; the list then decides.
• AIFINPAY_MAX_GAS_POL: worst-case network fee of one payment on Polygon, checked before signing; default 0.3 POL. At ~280 gwei the worst case is ~0.10 POL paying in POL and ~0.21 POL in USDC. Another chain needs AIFINPAY_MAX_GAS in its own currency.
• AIFINPAY_MAX_USD / AIFINPAY_DAILY_USD: lower the built-in ceiling of $5 per payment / $20 per 24 hours. A higher value is refused at start with a message, never silently clipped; raise nothing here, use the dashboard.
• AIFINPAY_GATEWAY_PATH_MODE: unset, inferred per URL (gateway for https://gateway.aifinpay.io, by merchant slug; direct, the full path, for any other site).
• AIFINPAY_PAYMENTS_ENABLED=0: payments off; the server stays read-only.

The env is read when the server starts; restart the aifinpay MCP server after changing it (agent_reload reads only the keystore).

Owner limits: a built-in ceiling, the working limits in the dashboard

The server never signs more than $5 per payment or $20 over any 24 hours (its local journal, checked under the operation lock before any broadcast). That ceiling is not a budget and needs no setting; env can only lower it. The day-to-day limits belong in the dashboard: once the agent is linked with agent_claim_self, the owner manages the per-payment cap, the daily cap, pause and the allowed merchants under Controls at https://dash.aifinpay.io, and the backend enforces that policy on every /v1/quote and /v1/pay for the claimed agent — no env change, no server restart. The ceiling still applies underneath; a payment has to pass both. More than $5 / $20 on an agent key is the Node SDK with its own limits.

payment_setup_status reads those Controls back for a persistent EVM wallet and returns them as dashboard: { linked: true, policy } with the per-payment cap, daily cap, merchant allowlist, expiry and pause; { linked: false } when no owner has claimed the agent yet (its next_step then offers the dashboard link); { linked: "unknown", reason } when the read fails, which blocks nothing because the backend enforces the policy either way. Paused or expired Controls stop the checklist with a next_step that says so. The read is GET /v1/agents/ /policy on the configured backend, signed by the wallet's own key (EIP-191 over ["AiFinPay agent policy read v1", , , ], valid 60 s); it signs no payment and changes nothing. It is not made on payable_fetch's refusal path, for an ephemeral wallet or on Solana.

Indexed wallet derivation

The wallet CLI and MCP can use deterministic child wallets from one recovery seed. Create an MCP-compatible wallet with npx @aifinpay/wallet new --index 0; the keystore retains the root seed and adds the index as optional metadata without changing existing fields. MCP uses that stored index automatically. To select another child in a different MCP process, set AIFINPAY_WALLET_INDEX to its decimal index; the same variable also applies when SEED_HASH or an agents.json record supplies the seed.

Each chain derives its own indexed key; for example, EVM = SHA-256("aifinpay:evm:v1\0" || decimalIndex || recoverySeed) and Solana = Ed25519(SHA-256("aifinpay:solana:v1\0" || decimalIndex || recoverySeed)). The decimal UTF-8 index follows that chain's domain NUL separator. Index 0 is the first wallet. Indices must be between 0 and 4294967295. With no selected index, existing identities retain their current derivation.

AIFINPAY_MAX_GAS_POL caps the worst case, not the fee you expect to pay. Before signing, the client prices the estimated gas plus 20% at the maximum fee per gas the Polygon RPC quotes, and refuses with V14_GAS_BUDGET_EXCEEDED if that exceeds the cap. The worst case follows the gas price: at about 280 gwei (September 2026) it is about 0.10 POL for a POL payment and about 0.21 POL for USDC, which needs a token approval and the settlement. 0.3 covers both at that price; check the current Polygon gas price and raise the cap when it is higher. The fee actually charged is usually a fraction of the cap, but the wallet must hold the batch price plus the worst case before it signs.

To pay in USDC instead of native POL, the owner also sets "AIFINPAY_PAY_ASSET": "USDC". The wallet then needs USDC for the batch and POL for gas: an exact-amount token approval plus the settlement, both within AIFINPAY_MAX_GAS_POL together. Unset or "POL" keeps native POL.

Paying on another chain

AIFINPAY_PAY_CHAIN explicitly picks the chain payable_fetch settles on: polygon by default, or an exact supported name in the capability list below. Only the owner sets it, and a merchant is paid on a chain only if its quote is for that chain; a quote for any other chain is refused, never followed. On Base the batch is paid in ETH (or AIFINPAY_PAY_ASSET: "USDC") and gas is ETH, so the cap is AIFINPAY_MAX_GAS, in ETH:

{

"AIFINPAY_PAY_CHAIN": "base", "AIFINPAY_MAX_GAS": "0.0002" }

AIFINPAY_MAX_GAS is the gas cap in the pay chain's native currency; AIFINPAY_MAX_GAS_POL remains accepted on Polygon and is refused on Base rather than read as ETH (0.3 POL is about $0.04; 0.3 ETH is several hundred dollars). On Base the worst case includes L1 data and operator fees; the owner must set the cap from the current estimate. The wallet's EVM address is the same on every chain, so fund it with ETH on Base, not on Ethereum mainnet. AIFINPAY_RPC_URL optionally replaces the chain's public RPC (https://mainnet.base.org, https://polygon.drpc.org).

A payment still pending on one chain is recovered only with that chain configured; switching chains never re-sends or forgets it.

Call payable_fetch({"url":"https://merchant.example/api/data"}). The tool uses the original signed v1.4 quote, independent fresh native/USD pricing, SDK runtime/signer verification and owner limits. It persists the prepared transaction before sending, verifies the receipt, and reuses the purchased batch. No special merchant script, alternate contract or facilitator fallback is used. GET on the configured chain; EVM receipt payments use live mode and its native currency or the configured stablecoin. The smallest batch is $0.02 plus gas, well inside the $5 per-payment ceiling.

To buy access to a whole site rather than one endpoint, call payable_fetch({"url":"https://merchant.example/api/data","scope":"merchant"}). One batch then covers every path on that merchant, and each request still costs its own listed price, so a premium page drains more of it than a standard API call. The price, the owner limits and the approved origins do not change. When the owner set AIFINPAY_GATEWAY_ORIGINS, an origin missing from it is refused by name; only the owner can add it.

Network access

A sandbox that allowlists outbound hosts must allow api.aifinpay.io (quotes and receipts) and an RPC for the pay chain. The independent native/USD rate uses the pinned Chainlink feed on Polygon/Base, then api.coinbase.com, then api.coingecko.com; other chains use those HTTP price sources. If none provides a valid fresh rate, payable_fetch stops before paying and the error names each host it tried.

Which AI client paid

payable_fetch tells the merchant which AI client is paying: the server maps the clientInfo.name your MCP client sent at initialize to an AIFP-Agent-Framework header on the payment requests (and on recovery of a pending payment).

| windsurf