@aifinpay/sdk-monorepo

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	Current source version	Install
aifinpay-agent (Python)	2.1.0	pip install aifinpay-agent
@aifinpay/agent (Node / TypeScript)	2.0.1	npm install @aifinpay/agent
@aifinpay/mcp	2.1.0	npx @aifinpay/mcp
@aifinpay/mcp-http	2.0.2	Streamable HTTP wrapper
@aifinpay/skill	2.0.9	npm install @aifinpay/skill
@aifinpay/gate	0.3.2	npm install @aifinpay/gate
@aifinpay/wallet	1.1.0	npm install @aifinpay/wallet
@aifinpay/deployments	1.1.2	deployment registry package

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:

Tool	Purpose
agent_address	Read the current EVM, Solana and Casper public addresses.
agent_reload	Reload configured local wallet files without starting a new conversation.
agent_quota	Read the agent's quota.
agent_history	Read indexed AiFinPay payment history or retained receipt history.
agent_passport_resolve	Resolve a public Agent Passport identity and verified wallet bindings.
settlement_routes	Read currently runtime-verified AIFP-1 / AIFP-2 settlement routes.
settlement_invoice	Build and validate a non-signing EVM settlement invoice.
settlement_solana	Build and validate a non-signing Solana settlement invoice.
settlement_casper	Build and validate a non-signing Casper settlement invoice.
deployment_info	Read deployment addresses, program IDs and settlement status across supported ecosystems.

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 reviewed AIFP-1 fetchPaid path. Paid execution is gated by runtime checks, including the reviewed Polygon v1.3 deployment/profile and a fresh trusted native/USD price. A quote, invoice or matching runtime hash alone is not proof that a route is production-enabled.

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

Python

The Python package supports identity and related SDK functions, but its legacy paid call() settlement path is disabled and it does not currently expose the Node fetchPaid executor.

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 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:

Network	Program ID	Settlement status	Reason
Devnet	8dty5bD738Z9TzEkDu8vLSnhpJNWtEGMUEcYaKCUTY6y	Disabled	Backend receipt verification is not implemented.
Mainnet	724Ut31i4ecY4dJ25z8HuZetu3A43xtNkPdk4JdbsfdD	Disabled	Backend receipt verification is not implemented and upgrade authority is not multisig.

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.

Provider	Asset	Historical use	Transaction
Exa Search	POL	SDK call via Exa	0xeb13c5eddf645b3e5b5e5db82d8b19d301a4c0c8593f6e7dce9cd4c3359c8700
io.net	POL	Llama-3.3-70B inference, $0.025	0x7c6ca0ffcf75b1ca3ade4800fb896c4bb08bc5f1a91916dc2cf4918f16129f0a

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.