# AiFinPay — start here
# Canonical: https://aifinpay.io/agent.txt

## Choose your role
Agent owner buying access: install the aifinpay skill.
Website/API owner charging for access: install the aifinpay-merchant skill.

Install for your assistant:
  npx skills add AiFinPay/skill
Package: https://www.npmjs.com/package/@aifinpay/skill
Source: https://github.com/AiFinPay/skill
Payer instructions: https://raw.githubusercontent.com/AiFinPay/skill/main/agent/skills/aifinpay/SKILL.md
Merchant instructions: https://raw.githubusercontent.com/AiFinPay/skill/main/agent/skills/aifinpay-merchant/SKILL.md

Skills are instructions, not executors. npm install @aifinpay/skill downloads
files but does not by itself register them in your assistant. Installed skill
copies must be updated; the MCP bundled copy belongs to its package version.

## Connect tools
MCP: npx -y @aifinpay/mcp
Persistent wallet setup: npx @aifinpay/mcp init
Node/TypeScript application: npm install @aifinpay/agent
Python application: pip install aifinpay-agent
MCP includes its SDK dependency. Choose the surface your runtime uses.
Keep keys, passphrases and bearer receipts local and out of chats and logs.
Read the skill for wallet encryption and client configuration.

## Payment availability — checked 2026-09-24
MCP 2.4.0 is read-only by default. It registers payable_fetch only when the
owner sets AIFINPAY_PAYMENTS_ENABLED=1 with a persistent wallet, USD limits
(AIFINPAY_MAX_USD, AIFINPAY_DAILY_USD), a gas cap (AIFINPAY_MAX_GAS_POL) and
exact payable origins (AIFINPAY_GATEWAY_ORIGINS). It pays AIFP-1 on native
Polygon v1.4 only: in POL, or in USDC with AIFINPAY_PAY_ASSET=USDC (USDC for the
batch plus 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. agent_call and agent_quote are not registered.
Node 2.2.0 fetchPaid pays AIFP-1 on Polygon v1.4 in POL, or in USDC with
v14.asset = "USDC"; a v1.2 quote is not
compatible. Wallet creation, funding or installing the skill does not enable
payments by itself. Do not treat agent.pay as a fallback for a rejected route.
Python aifinpay-agent 2.2.1 fetch_paid pays AIFP-1 on Polygon v1.4 in POL or
USDC (asset="USDC"), with per-payment and daily USD limits.
A skill copy saying MCP is read-only or payments are "release pending" is out
of date — update it with npx skills add AiFinPay/skill.
The smallest batch is $0.10 plus network gas.
13 network surfaces are deployed or integrated; payment is enabled on Polygon
only. A contract address or old transaction does not mean a route is open.

## Fees — by path; settlement.economics in /.well-known/x402.json is authoritative
AIFP-1: gross-inclusive, the quote already contains the fee — 99% merchant,
1% AiFinPay. AIFP-2 (x402-compatible): the provider keeps its full price,
AiFinPay fee 0%. Legacy bridge v1.2 (older, separate path): the fee is added to the payer's
total. Gas is separate.

## Network access for paying
Allow api.aifinpay.io and a Polygon RPC. For POL payments MCP 2.3.0 checks POL/USD
independently of the quote: Chainlink over that RPC first, then
api.coinbase.com, then api.coingecko.com. If all are blocked, payable_fetch
stops before paying and nothing is spent.

## After creating a wallet
Tell the owner they can link the agent at https://dash.aifinpay.io → My Agents:
either Claim via MCP (the owner pastes a one-time URL, the agent calls
agent_claim_self; the URL only links the agent, single use, 15 minutes), or
Add agent by address (the agent signs the dashboard's challenge, EIP-191,
AiFinPay-claim:polygon:<address>:<nonce>, with its EVM key). The owner then
sees balance, payments and receipts and can set a daily-spend alert.
Hard limits stay in the agent's config (AIFINPAY_MAX_USD, AIFINPAY_DAILY_USD).

## Discover a target website
1. Read /.well-known/x402.json on the SAME ORIGIN as the requested website.
2. Read its API catalog for methods and required parameters.
3. Inspect the protected route's HTTP 402, price, minimum batch and scope.
4. Check the quoted deployment against the installed client's supported routes.
5. Agree on resource, batch price and separate gas budget before payment.
A site's /llms.txt should link these catalogs on the correct origin.

## Protocol flow, with a supported executor
HTTP 402 -> quote -> authorized settlement -> verified quota receipt ->
retry with AIFP-Receipt -> data. Reuse the receipt within its scope and quota.
A quote or invoice is not proof of payment. Recover an existing transaction
before attempting another payment after a timeout.

## Dashboard
https://dash.aifinpay.io — merchants register sites and inspect payments;
agent owners link agents and watch their spend.
https://docs.aifinpay.io — integration and product documentation.