From 68a1865123065eb13ea43c83b3bb056613f15088 Mon Sep 17 00:00:00 2001 From: coinsecuritiescompany Date: Sun, 9 Aug 2026 11:49:49 +0300 Subject: [PATCH] Prepare AiFinPay SDK and MCP for Kilo Marketplace --- MCP_CONFIG.md | 33 ++++---- README.md | 53 ++++++------ examples/claude-mcp/README.md | 10 +-- mcp/README.md | 4 +- mcp/server.json | 12 +-- skills/SKILL.md | 151 ---------------------------------- skills/aifinpay-sdk/SKILL.md | 83 +++++++++++++++++++ 7 files changed, 140 insertions(+), 206 deletions(-) delete mode 100644 skills/SKILL.md create mode 100644 skills/aifinpay-sdk/SKILL.md diff --git a/MCP_CONFIG.md b/MCP_CONFIG.md index e9a43bc..6916dae 100644 --- a/MCP_CONFIG.md +++ b/MCP_CONFIG.md @@ -1,7 +1,7 @@ # MCP install — one config block per client -`@aifinpay/mcp` is an MCP server that gives an LLM five payment tools. -The install is the same everywhere: register `npx @aifinpay/mcp` as an +`@aifinpay/mcp` is an MCP server that gives an LLM seven payment tools. +The install is the same everywhere: register `npx -y @aifinpay/mcp` as an MCP server in your client's config. The client downloads the package on first run via `npx`. @@ -20,15 +20,15 @@ Edit `claude_desktop_config.json`: "mcpServers": { "aifinpay": { "command": "npx", - "args": ["@aifinpay/mcp"] + "args": ["-y", "@aifinpay/mcp"] } } } ``` -Restart Claude Desktop. The five tools (`payable_fetch`, `agent_address`, -`agent_quote`, `pay_with_split`, `quote_split`) show up in the hammer -menu. +Restart Claude Desktop. The seven tools (`agent_call`, `agent_claim_self`, +`payable_fetch`, `agent_address`, `agent_quote`, `pay_with_split`, +`quote_split`) show up in the hammer menu. ## Cursor @@ -39,7 +39,7 @@ Edit `~/.cursor/mcp.json` (create it if missing): "mcpServers": { "aifinpay": { "command": "npx", - "args": ["@aifinpay/mcp"] + "args": ["-y", "@aifinpay/mcp"] } } } @@ -56,7 +56,7 @@ Edit `~/.codeium/windsurf/mcp_config.json`: "mcpServers": { "aifinpay": { "command": "npx", - "args": ["@aifinpay/mcp"] + "args": ["-y", "@aifinpay/mcp"] } } } @@ -74,7 +74,7 @@ In `~/.continue/config.json`, add to `experimental.mcpServers`: "mcpServers": { "aifinpay": { "command": "npx", - "args": ["@aifinpay/mcp"] + "args": ["-y", "@aifinpay/mcp"] } } } @@ -90,7 +90,7 @@ Open the Cline MCP Servers panel → Configure MCP Servers → paste: "mcpServers": { "aifinpay": { "command": "npx", - "args": ["@aifinpay/mcp"] + "args": ["-y", "@aifinpay/mcp"] } } } @@ -102,7 +102,7 @@ Settings → Plugins → Custom MCP → add server with: - name: `aifinpay` - command: `npx` -- args: `@aifinpay/mcp` +- args: `-y @aifinpay/mcp` ## Configuration (optional) @@ -111,7 +111,7 @@ The MCP server reads two environment variables: | Var | Default | Effect | |---|---|---| | `AIFINPAY_AGENT_SECRET` | random (per-process) | base58-encoded Ed25519 secret to reuse across sessions. Persist this if you want the same agent identity / funded address across restarts. | -| `AIFINPAY_MAX_USD` | `0.10` | hard cap per `payable_fetch` call — refuses to settle anything more expensive. | +| `AIFINPAY_MAX_USD` | unset | Hard cap per `agent_call` or `payable_fetch`. Set this explicitly before paid use. | Example with persistent identity and a higher cap: @@ -120,7 +120,7 @@ Example with persistent identity and a higher cap: "mcpServers": { "aifinpay": { "command": "npx", - "args": ["@aifinpay/mcp"], + "args": ["-y", "@aifinpay/mcp"], "env": { "AIFINPAY_AGENT_SECRET": "", "AIFINPAY_MAX_USD": "0.50" @@ -148,10 +148,12 @@ the assistant message. The tx hash is in the tool result. | Tool | Purpose | |---|---| +| `agent_call(provider, ...)` | Call a provider from the AiFinPay directory with automatic payment. | +| `agent_claim_self(magic_link_url)` | Link the agent to an AiFinPay dashboard account. | | `payable_fetch(url, ...)` | Fetch any URL; auto-pay on 402. | | `agent_address()` | Show the agent's EVM/Solana address (for funding). | | `agent_quote(url)` | Preview the cost before paying. | -| `pay_with_split(merchant, amount, order_id, chain)` | Direct B2B split-payment instruction (merchant 98.99% / treasury 1% / IP-creator 0.01%). | +| `pay_with_split(merchant, amount, order_id, chain)` | Prepare a direct on-chain split payment. Confirm the quoted total before paying. | | `quote_split(chain, merchant_amount)` | Pure-view fee breakdown. | ## Troubleshooting @@ -165,7 +167,8 @@ exact base58 string produced by `Agent.new().secret_b58` (Python) or random identity on each start. **Tool refuses to settle (`max_usd_exceeded`).** Raise -`AIFINPAY_MAX_USD`. Defaults are deliberately conservative. +`AIFINPAY_MAX_USD`. It is unset by default, so set it explicitly before +allowing paid calls. **Agent address shows `0x...` zeros.** Means the SDK couldn't derive a key. Check `node -v` is `≥ 18`. diff --git a/README.md b/README.md index 4847c45..73bdd14 100644 --- a/README.md +++ b/README.md @@ -7,9 +7,9 @@ [![Site](https://img.shields.io/badge/site-aifinpay.io-black.svg)](https://aifinpay.io) [![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io) -**Stripe for autonomous AI agents.** One line of code — `agent.pay(url)` — -and your agent settles a real on-chain payment on Polygon or Solana -mainnet, then receives the gated response. Non-custodial. Live since +**Stripe for autonomous AI agents.** One high-level call — +`agent.call(...)` or `agent.fetchPaid(url)` — lets an agent settle a real +on-chain payment and receive the gated response. Non-custodial. Live since 2026. Polygon facilitator compatible. Direct splitter settlement (Node SDK ≥ 1.3.0, `AiFinPayAgent.call()`) also works on Base, Optimism, Unichain, BOT Chain and XRPL EVM (native-token path); the backend-quoted @@ -23,13 +23,13 @@ invoice flow remains Polygon + Solana. ```bash # Python -pip install aifinpay-agent +pip install --pre aifinpay-agent # Node / TypeScript npm install @aifinpay/agent # MCP server (Claude Desktop, Cursor, Windsurf, Continue) -npx @aifinpay/mcp +npx -y @aifinpay/mcp ``` ## One-click MCP for Claude Desktop / Cursor @@ -43,7 +43,7 @@ or Cursor's `~/.cursor/mcp.json`: "mcpServers": { "aifinpay": { "command": "npx", - "args": ["@aifinpay/mcp"] + "args": ["-y", "@aifinpay/mcp"] } } } @@ -61,19 +61,17 @@ Cline) lives in [`MCP_CONFIG.md`](./MCP_CONFIG.md). | Package | Path | Install | Latest | |---|---|---|---| -| **`aifinpay-agent`** (Python) | [`./python`](./python) | `pip install aifinpay-agent` | `1.1.1` | -| **`@aifinpay/agent`** (Node / TypeScript) | [`./node`](./node) | `npm install @aifinpay/agent` | `1.2.1` | -| **`@aifinpay/mcp`** (MCP server) | [`./mcp`](./mcp) | `npx @aifinpay/mcp` | `1.1.1` | +| **`aifinpay-agent`** (Python pre-release) | [`./python`](./python) | `pip install --pre aifinpay-agent` | `0.2.0a2` | +| **`@aifinpay/agent`** (Node / TypeScript) | [`./node`](./node) | `npm install @aifinpay/agent` | `1.8.0` | +| **`@aifinpay/mcp`** (MCP server) | [`./mcp`](./mcp) | `npx -y @aifinpay/mcp` | `1.5.0` | | Go SDK | — | `go get github.com/AiFinPay/sdk/go` | **soon** | | Rust SDK | — | `cargo add aifinpay-sdk` | **soon** | ## What this is -`agent.pay(url)` — one line of Python or TypeScript that pays any -[x402-protected](https://www.x402.org) URL on behalf of an autonomous -AI agent. The SDK auto-detects the facilitator flavor (AiFinPay native, -Coinbase x402, …), signs an Ed25519 challenge, retries the request, and -returns the response. +The Node SDK exposes a chain-opaque `AiFinPayAgent` for named provider calls +and AIFP-1 paid fetches. The legacy `Agent.pay(url)` surface remains available +for existing x402 integrations. Same agent, drop into Claude Desktop's MCP config and the LLM gets seven tools (`payable_fetch`, `agent_address`, `agent_quote`, @@ -106,19 +104,19 @@ invoice = agent.pay_with_split_invoice( ### Node.js / TypeScript ```ts -import { Agent } from "@aifinpay/agent"; +import { AiFinPayAgent } from "@aifinpay/agent"; -const agent = Agent.new(); -console.log("Fund this address:", agent.address); - -const res = await agent.pay("https://api.example.com/v1/data"); +const agent = await AiFinPayAgent.new({ + budgetCaps: { per_call_usd: 0.50, daily_usd: 5 }, +}); -const invoice = await agent.payWithSplitInvoice({ - chain: "polygon", - merchantWallet: "0xMerchant...", - merchantAmount: 10n ** 18n, - orderId: "search-1", +const res = await agent.call({ + provider: "exa", + body: { query: "what is x402" }, }); + +if (!res) throw new Error("AiFinPay call returned no response"); +console.log(await res.json()); ``` ### MCP (Claude Desktop) @@ -128,7 +126,7 @@ const invoice = await agent.payWithSplitInvoice({ "mcpServers": { "aifinpay": { "command": "npx", - "args": ["@aifinpay/mcp"], + "args": ["-y", "@aifinpay/mcp"], "env": { "AIFINPAY_AGENT_SECRET": "", "AIFINPAY_MAX_USD": "0.50" @@ -226,8 +224,9 @@ sdk/ ## Releasing -All three packages are published as stable `1.0.0` on PyPI and npm under -the default (`latest`) tag, with semver-compatible updates from here. +The Node SDK and MCP server are published under npm's stable `latest` tag. +The Python package remains a PyPI pre-release and must be installed with +`--pre` until its stable release. ```bash # Python diff --git a/examples/claude-mcp/README.md b/examples/claude-mcp/README.md index 8917aba..f841481 100644 --- a/examples/claude-mcp/README.md +++ b/examples/claude-mcp/README.md @@ -15,7 +15,7 @@ Zero-code integration. Drop one config block, restart Claude, done. "mcpServers": { "aifinpay": { "command": "npx", - "args": ["@aifinpay/mcp"] + "args": ["-y", "@aifinpay/mcp"] } } } @@ -25,9 +25,9 @@ Zero-code integration. Drop one config block, restart Claude, done. ## Verify it loaded -Click the hammer icon in the chat input. You should see five tools: -`payable_fetch`, `agent_address`, `agent_quote`, `pay_with_split`, -`quote_split`. +Click the hammer icon in the chat input. You should see seven tools: +`agent_call`, `agent_claim_self`, `payable_fetch`, `agent_address`, +`agent_quote`, `pay_with_split`, `quote_split`. ## First conversation @@ -64,7 +64,7 @@ funds. To persist: "mcpServers": { "aifinpay": { "command": "npx", - "args": ["@aifinpay/mcp"], + "args": ["-y", "@aifinpay/mcp"], "env": { "AIFINPAY_AGENT_SECRET": "", "AIFINPAY_MAX_USD": "0.50" diff --git a/mcp/README.md b/mcp/README.md index caa248e..97e123b 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -28,7 +28,7 @@ protocol itself is live across 13 networks — see ## Install ```bash -# Globally — usable as `npx @aifinpay/mcp` from any client config +# Globally — usable as `npx -y @aifinpay/mcp` from any client config # (installs the latest stable — the old @alpha tag is retired, don't use it) npm install -g @aifinpay/mcp ``` @@ -42,7 +42,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: "mcpServers": { "aifinpay": { "command": "npx", - "args": ["@aifinpay/mcp"], + "args": ["-y", "@aifinpay/mcp"], "env": { "AIFINPAY_AGENT_SECRET": "", "AIFINPAY_MAX_USD": "0.50" diff --git a/mcp/server.json b/mcp/server.json index ce32570..39262a1 100644 --- a/mcp/server.json +++ b/mcp/server.json @@ -1,9 +1,9 @@ { "$schema": "https://modelcontextprotocol.io/schemas/server.json", "name": "aifinpay", - "version": "1.0.0", - "description": "Stripe for AI agents. Pay for any HTTP API in stablecoins or native tokens on Polygon and Solana mainnet with one MCP call. Non-custodial, on-chain settlement.", - "vendor": "CoinSecurities (SECCO)", + "version": "1.5.0", + "description": "Non-custodial payment tools for AI agents: wallet addresses, quotes, paid HTTP calls, x402 settlement, receipts, and direct split payments.", + "vendor": "AiFinPay", "license": "MIT", "homepage": "https://aifinpay.io", "repository": "https://github.com/AiFinPay/sdk", @@ -15,19 +15,19 @@ ], "install": { "command": "npx", - "args": ["@aifinpay/mcp"] + "args": ["-y", "@aifinpay/mcp"] }, "claude_desktop_config": { "mcpServers": { "aifinpay": { "command": "npx", - "args": ["@aifinpay/mcp"] + "args": ["-y", "@aifinpay/mcp"] } } }, "env": { "AIFINPAY_AGENT_SECRET": "base58 Ed25519 secret (persistent agent identity; Solana + EVM addresses both derive from it)", - "AIFINPAY_MAX_USD": "hard cap per paid call (agent_call + payable_fetch), default 0.10", + "AIFINPAY_MAX_USD": "hard cap per paid call (agent_call + payable_fetch); unset by default", "AIFINPAY_BASE_URL": "override the AiFinPay backend endpoint, default https://aifinpay.io" }, "tools": [ diff --git a/skills/SKILL.md b/skills/SKILL.md deleted file mode 100644 index 2244b11..0000000 --- a/skills/SKILL.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -name: aifinpay -description: Pay any HTTP API on behalf of an AI agent with one line of code. Settles on-chain in stablecoins (USDC/USDT) or native tokens on Polygon and Solana mainnet. Non-custodial. -license: MIT -homepage: https://aifinpay.io -repository: https://github.com/AiFinPay/sdk -when_to_use: | - Invoke this skill whenever the agent needs to call a paid HTTP API - (search, inference, GPU compute, data feeds, paywalled content) and - the server is x402-protected, i.e. returns HTTP 402 with a payment - challenge. The skill explains how to settle the payment on-chain - via the AiFinPay SDK and retry the request automatically. ---- - -# AiFinPay — payment rail for autonomous agents - -**Stripe for AI agents.** Any HTTP 402 challenge is paid automatically by -the agent's own on-chain wallet, then the original request is retried and -the gated response is returned. Settlement is non-custodial: the -agent's private key signs locally, no AiFinPay-controlled custodian -touches funds at any point. - -## Install - -Pick one: - -```bash -pip install aifinpay-agent # Python -npm install @aifinpay/agent # Node / TypeScript -npx @aifinpay/mcp # MCP server (Claude Desktop / Cursor / Windsurf) -``` - -## First paid call (Python) - -```python -from aifinpay import Agent - -agent = Agent.new() -print("Fund this address with MATIC + USDC:", agent.address) - -resp = agent.pay( - "https://bridge.aifinpay.io/io-net/chat/completions", - body={"model": "meta-llama/Llama-3.3-70B-Instruct", - "messages": [{"role": "user", "content": "Hello"}]}, -) -print(resp.json()["choices"][0]["message"]["content"]) -print("tx hash:", resp.headers.get("x-payment-receipt")) -``` - -Persist `agent.secret_b58` if you want to reuse the identity. Fund the -address once with a few cents of MATIC + USDC on Polygon mainnet — -every subsequent call deducts on-chain. - -## First paid call (Node / TypeScript) - -```ts -import { Agent } from "@aifinpay/agent"; - -const agent = Agent.new(); -console.log("Fund this address:", agent.address); - -const res = await agent.pay( - "https://bridge.aifinpay.io/io-net/chat/completions", - { body: { model: "meta-llama/Llama-3.3-70B-Instruct", - messages: [{ role: "user", content: "Hello" }] } }, -); -console.log((await res.json()).choices[0].message.content); -``` - -## MCP — zero-code (Claude Desktop / Cursor / Windsurf) - -Drop into `claude_desktop_config.json` (or the equivalent file for -your client) and restart: - -```json -{ - "mcpServers": { - "aifinpay": { - "command": "npx", - "args": ["@aifinpay/mcp"] - } - } -} -``` - -The model now has five tools: `payable_fetch`, `agent_address`, -`agent_quote`, `pay_with_split`, `quote_split`. - -Ask the model to *use `agent_address` to show me your wallet address*, -fund it, then ask it to *use `payable_fetch` on -https://bridge.aifinpay.io/io-net/chat/completions with body { … }* -— it will settle on-chain and return the response. - -## How a payment actually settles - -1. The agent's code calls `agent.pay(url)`. -2. The server returns **HTTP 402** with a structured payment block - (`accepts[]` plus an optional `pay_matic` block). -3. The SDK signs an Ed25519 challenge (Solana identity flow) **or** - submits `payMatic` / `payStable` on the Polygon - `AiFinPaySplitter` contract — depending on what the server accepts. -4. The SDK retries the request with the proof header(s). -5. The server verifies on-chain (Polygon facilitator or our indexer), - forwards to the upstream service, returns the response. - -One function call. One on-chain tx. Atomic 99 / 1 split — merchant -98.99 %, AiFinPay treasury 1 %, IP-creator 0.01 %. No custodian holds -funds at any point. - -## Configuration knobs - -| Variable | Default | Effect | -|---|---|---| -| `AIFINPAY_AGENT_SECRET` | random | persistent base58 Ed25519 secret | -| `AIFINPAY_MAX_USD` | `0.10` | hard cap per `payable_fetch` call | -| `AIFINPAY_API` | `https://api.aifinpay.io` | API base URL | -| `AIFINPAY_CHAIN` | `auto` | `polygon`, `solana`, or `auto` | - -## Live partner bridges - -`bridge.aifinpay.io/{io-net,exa,venice}/` — production HTTP 402 -proxies in front of three providers. Hitting any of them without a -payment header returns the 402 challenge inline so the SDK can settle -and retry. - -## Live proofs - -| Provider | Asset | What was bought | Tx | -|---|---|---|---| -| Exa Search | POL | First SDK call via Exa | [`0xeb13c5ed…59c8700`](https://polygonscan.com/tx/0xeb13c5ed59c8700) | -| io.net | POL | Llama-3.3-70B inference, $0.025 | [`0x7c6ca0ff…129f0a`](https://polygonscan.com/tx/0x7c6ca0ff129f0a) | - -## When NOT to use - -- For free APIs — the skill is only relevant when the server returns 402. -- For human-payment flows (Stripe, card, ACH) — AiFinPay is for - autonomous-agent payments, not consumer checkout. -- For chain-only DeFi flows — settlement is the on-chain part; the - goal here is paying an HTTP API, not transferring tokens for their - own sake. - -## Links - -- Site: https://aifinpay.io -- Quick start: https://aifinpay.io/quickstart -- Live demo: https://aifinpay.io/demo/agent-buys-inference -- System status: https://aifinpay.io/status -- SDK source: https://github.com/AiFinPay/sdk -- Manifesto: https://api.aifinpay.io/manifesto.json -- x402 discovery: https://api.aifinpay.io/.well-known/x402.json -- MCP client matrix: https://github.com/AiFinPay/sdk/blob/main/MCP_CONFIG.md diff --git a/skills/aifinpay-sdk/SKILL.md b/skills/aifinpay-sdk/SKILL.md new file mode 100644 index 0000000..a30a739 --- /dev/null +++ b/skills/aifinpay-sdk/SKILL.md @@ -0,0 +1,83 @@ +--- +name: aifinpay-sdk +description: Integrate non-custodial payments into AI agents with the AiFinPay Node SDK. Use for x402 or AIFP-1 paid API calls, provider payments, agent wallets, spend limits, receipts, and pay-per-call workflows. +--- + +# AiFinPay SDK + +Use the stable `@aifinpay/agent` package to give an AI agent a locally +controlled wallet and the ability to pay for APIs, data, content, inference, +and other machine services. + +## Workflow + +1. Inspect the project runtime and package manager. +2. Install the stable package: + + ```bash + npm install @aifinpay/agent + ``` + +3. Use the current chain-opaque API for new integrations: + + ```ts + import { AiFinPayAgent } from "@aifinpay/agent"; + + const agent = await AiFinPayAgent.new({ + budgetCaps: { + per_call_usd: 0.50, + daily_usd: 5, + }, + }); + + const response = await agent.call({ + provider: "exa", + body: { query: "what is x402" }, + }); + + if (!response) throw new Error("AiFinPay call returned no response"); + const data = await response.json(); + ``` + +4. For an AIFP-1 gateway URL, use the paid-fetch surface: + + ```ts + const response = await agent.fetchPaid( + "https://gateway.aifinpay.io/merchant/resource", + ); + ``` + +5. Persist the agent secret using the application's existing secret manager. + Never print, commit, or send a recovery secret to a remote service. +6. Return the transaction reference or receipt with the application result so + operators can reconcile paid calls. + +## Payment safety + +- Set both per-call and daily limits before enabling autonomous payments. +- Obtain explicit user confirmation before a paid call or transfer unless the + user has already approved a specific budget and scope. +- Quote or preview a payment before execution when the chosen flow supports it. +- Reject unknown providers, unexpected chains, and prices above the approved + cap. +- Keep signing local. AiFinPay is non-custodial; private keys must remain under + the agent operator's control. +- Use idempotency keys for retried payment requests. + +## Verification + +After integration: + +1. Run the project tests and the SDK tests relevant to the changed flow. +2. Verify wallet creation without funding it. +3. Verify a quote or dry-run path before making a real payment. +4. For a real payment, use a small approved amount and confirm the returned + receipt or transaction reference. + +## References + +- SDK source and examples: https://github.com/AiFinPay/sdk +- Node package: https://www.npmjs.com/package/@aifinpay/agent +- MCP package: https://www.npmjs.com/package/@aifinpay/mcp +- AIFP-1 protocol: https://github.com/AiFinPay/Protocol-AIFP-1 +- Product site: https://aifinpay.io