AiFinPay — financial rails for AI agents

AiFinPay provides payment and monetization infrastructure for autonomous AI agents.

• Agent side: identity, wallet discovery, payment history, route discovery, quotas and settlement preparation.
• Merchant side: HTTP 402 paywalls and per-request monetization for AI traffic.
• Non-custodial design: private keys remain with the agent/operator. Public MCP tools do not expose seeds or private keys.

Canonical domain: https://aifinpay.io

Current package versions

Package lines are versioned independently. The package manifests in this repository and the corresponding npm/PyPI registries are the source of truth.

Install

# MCP
npx @aifinpay/mcp

# Node / TypeScript SDK
npm install @aifinpay/agent

# Python SDK
pip install aifinpay-agent

# Merchant paywall
npm install @aifinpay/gate

# Agent skills
npm install @aifinpay/skill

MCP: current production surface

The current @aifinpay/mcp source exposes the following production tools:

With AIFINPAY_MODE=dev, an additional dev_payment_quote tool is available for dev-only quote inspection.

The public MCP surface does not sign or broadcast payments. Creating an invoice or quote is not a completed payment.

Legacy tools such as payable_fetch, agent_call, agent_quote, pay_with_split, quote_split and agent_claim_self are not registered by the current production MCP server.

MCP client configuration

{
  "mcpServers": {
    "aifinpay": {
      "command": "npx",
      "args": ["-y", "@aifinpay/mcp"]
    }
  }
}

For a persistent local identity, initialize the keystore once:

npx @aifinpay/mcp init

Then use agent_reload and agent_address to verify the selected public wallet. Do not paste seeds or private keys into chat, issues, logs or shared configuration.

Full client setup: MCP_CONFIG.md

SDK payment status

The SDK surfaces have different execution status. Do not treat them as interchangeable.

Node / TypeScript

@aifinpay/agent includes the AIFP-1 fetchPaid path. The 2.3.0 source candidate adds explicitly selected Base v1.4 (ETH or pinned USDC) alongside default Polygon v1.4. Paid execution validates the selected chain, pinned deployment/profile, token and RPC before signing; native payments also require a fresh independent price. Legacy Polygon v1.3 still requires its separately reviewed settlement pin. Source support does not activate a production route or publish a package.

See node/README.md and node/PAYMENT_RECEIPTS.md.

Python

The Python package pays AIFP-1 merchants with AiFinPayAgent.fetch_paid (Polygon v1.4, POL or USDC). The 2.3.0 source candidate also supports explicit chain="base" with ETH or pinned USDC and a required gas budget in wei. Its legacy paid call() settlement path stays disabled. MCP's current payment configuration remains Polygon; these source changes do not add a Base MCP setting.

See python/README.md.

Economics

Current protocol economics documented in the v2 line:

• AIFP-1: payer pays the quoted gross amount; merchant receives 99%; AiFinPay receives 1%; creator/referral receives 0%.
• AIFP-2 / x402: provider receives 100%; AiFinPay protocol fee is currently 0%.

Older 98.99% / 1% / 0.01% examples belong to a retired fee model and must not be used as current economics.

Merchant monetization

For a site or API that wants to monetize AI-agent traffic:

npm install @aifinpay/gate

The merchant package can return HTTP 402 challenges, expose discovery metadata and meter paid access. See gate/README.md. Python servers (FastAPI, Starlette, Flask, Django) use pip install aifinpay-gate, the same gate as ASGI/WSGI middleware — see python-gate/README.md and the aifinpay-merchant skill in skill/skills/aifinpay-merchant/SKILL.md.

Deployment status

Deployment addresses and program IDs are registry data; they are not, by themselves, proof that settlement is enabled. Use deployment_info or the deployment registry and check settlementEnabled / status before presenting a network as active.

Solana

The old Solana program 5g9zWHF1Vv6GiGpA2ZbJQbSCDZd5hAk9AyvabRJvKFx2 was closed and is not the current program.

The current registry contains the redeployed v1.4.1 programs below, both currently disabled for settlement:

Canonical registry source: deployments/registry/splitter/solana/deployments.json

Historical mainnet evidence

These are historical transactions only. They do not certify the current release, fee model or current production readiness.

Repository layout

sdk/
├── node/          @aifinpay/agent
├── python/        aifinpay-agent
├── mcp/           @aifinpay/mcp
├── mcp-http/      Streamable HTTP wrapper
├── skill/         @aifinpay/skill
├── gate/          merchant HTTP 402 paywall
├── wallet/        lightweight agent wallet / keystore
├── deployments/   deployment registry
└── examples/      integrations and reference examples

Security rules

• Never print, log or publish a seed, private key, keystore JSON or signing secret.
• Public addresses and transaction hashes are safe to display.
• Do not infer production readiness from a contract address, program ID, quote or invoice alone.
• Retain the original quote, transaction reference and idempotency context when recovering from a settlement error to avoid accidental duplicate payment attempts.

Links

• Website: https://aifinpay.io
• Documentation: https://aifinpay.io/docs
• Quick start: QUICKSTART.md
• MCP configuration: MCP_CONFIG.md
• Issues: https://github.com/AiFinPay/sdk/issues
• MCP specification: https://modelcontextprotocol.io
• x402: https://www.x402.org

License

MIT — see LICENSE.