AI Integration Guide
Enable autonomous Nano payments in your AI agent in minutes.
One binary. Two integration modes. Zero framework lock-in.
Running in 2 Steps
Rust toolchain required. No Docker, no Python, no extra runtime.
Clone
git clone https://github.com/ifenpay/ifenpay-nano-toolset cd ifenpay-nano-toolset
Clone the repository and enter the directory.
Run (Auto Setup + Start)
cargo run --release
# creates .env from .env-example if missing
AI_WALLET_PASSWORD is auto-generated on first run and bound to local wallet encryption. HTTP API on 127.0.0.1:3123, MCP on stdio — both active.
Two Integration Modes
Choose the mode that fits your agent framework. Both expose the same 7 tools.
MCP over stdio
Embedded MCP server. Call initialize, tools/list, and tools/call over stdin/stdout. No HTTP, no ports needed.
- ✅ Native MCP protocol (stdio)
- ✅ Tool schemas auto-exposed via tools/list
- ✅ Works with any MCP-native framework
- ✅ No network port required
HTTP API
Standard REST endpoints on 127.0.0.1:3123. Any language, any framework — if it can make an HTTP request, it works.
- ✅ Plain HTTP GET/POST
- ✅ Consistent success/data/error envelope
- ✅ Python, JS, curl — anything works
- ✅ Lightweight, no SDK required
HTTP API Reference
Base URL: http://127.0.0.1:3123
Response envelope: All responses use {"success": true/false, "data": {...}, "error": null}.
On error: success is false, data is null, and error contains {error, message}.
/wallet/balance
wallet.balance
Returns the current wallet balance and pending amount.
cURL
curl http://127.0.0.1:3123/wallet/balance
Response
{
"success": true,
"data": {
"account": "nano_1abc...",
"balance": "1.5",
"balance_raw": "1500000...",
"pending": "0.0",
"pending_raw": "0"
},
"error": null
}
Python
import requests
r = requests.get("http://127.0.0.1:3123/wallet/balance").json()
print(r["data"]["balance"]) # "1.5"
print(r["data"]["account"]) # "nano_1abc..."
/wallet/send
wallet.send
Send Nano to a recipient address. Sub-second finality.
Request body
{
"recipient_address": "nano_1xyz...",
"amount": "0.1"
}
Response
{
"success": true,
"data": {
"amount": "0.1",
"recipient": "nano_1xyz..."
},
"error": null
}
Python
r = requests.post("http://127.0.0.1:3123/wallet/send", json={
"recipient_address": "nano_1xyz...",
"amount": "0.1"
}).json()
assert r["success"] # True
/payment/request
payment.request
Create a payment request. Returns a transaction_id for status polling.
Request body
{
"receive_address": "nano_1abc...",
"amount": "1.5",
"redirect_url": null
}
Response
{
"success": true,
"data": {
"receive_address": "nano_1abc...",
"amount": "1.5",
"transaction_id": "abc-123-..."
},
"error": null
}
/payment/status/{transaction_id}
payment.status
Check if a payment has been fulfilled. Poll until is_paid is true.
Response
{
"success": true,
"data": {
"success": true,
"message": "Payment confirmed",
"transaction_id": "abc-123-...",
"is_paid": true
},
"error": null
}
Python — poll until paid
import time
txid = "abc-123-..."
while True:
r = requests.get(
f"http://127.0.0.1:3123/payment/status/{txid}"
).json()
if r["data"]["is_paid"]:
print("Payment confirmed")
break
time.sleep(2)
/credits
credits.get
Returns current credit balance and all available topup amounts with Nano prices.
/credits/topup/{credits_amount}
credits.topup
Top up credits. Valid amounts: 10, 50, 100, 500, 1000, 5000, 10000, 50000, 100000. Toolset sends the Nano payment automatically.
curl -X POST http://127.0.0.1:3123/credits/topup/1000
/donate/{amount}
donate.send
Donate Nano to the platform. amount is a decimal string, e.g. "0.05".
curl -X POST http://127.0.0.1:3123/donate/0.05
MCP Integration Guide
The nano-toolset embeds a full MCP server over stdio. It starts automatically with the process — no separate bootstrap needed.
Supported MCP Methods
initializetools/listtools/callAvailable MCP Tools
wallet.balance
wallet.send
payment.request
payment.status
credits.get
credits.topup
donate.send
Response Envelope
All tool responses use the same structure. Branch on success.
Success
{
"success": true,
"data": { ... },
"error": null
}
Error
{
"success": false,
"data": null,
"error": {
"error": "INSUFFICIENT_FUNDS",
"message": "Not enough Nano"
}
}
Minimal MCP Flow
# 1. Initialize — receive server capabilities
initialize
# 2. List tools and cache their input schemas
tools/list
# 3. Call a tool with validated arguments
tools/call {
"name": "wallet.send",
"arguments": {
"recipient_address": "nano_1xyz...",
"amount": "0.05"
}
}
# 4. Parse the envelope and branch on success
response → { "success": true, "data": { ... }, "error": null }
Tool Input Schemas
wallet.send
{
"recipient_address": "nano_...",
"amount": "0.1"
}
payment.request
{
"receive_address": "nano_...",
"amount": "1.5",
"redirect_url": null
}
payment.status
{
"transaction_id": "abc-123-..."
}
credits.topup
{
"credits_amount": 1000
}
donate.send
{
"amount": "0.05"
}
wallet.balance / credits.get
No input fields required.
Example Agent
The ifenpay-agent-example shows a minimal Flask + Ollama agent that calls the nano-toolset. Not production-ready — use it as a reference.
⚠️ Example-only
Minimal reference. No compatibility guarantee, no custom support. Adapt it for your own use case.
What it demonstrates
- ✅ Flask-based agent running in Docker Compose
- ✅ Ollama as the LLM backend
- ✅ Calling nano-toolset over HTTP API (MCP_TOOLSET_BASE_URL)
- ✅ Stateless agent — all wallet state lives in the toolset
Prerequisites
The toolset must be running separately before you start the example agent. The agent does not start the toolset for you.
# 1. Start the toolset
cargo run --release
# Listening on 127.0.0.1:3123
# 2. In a separate terminal, start the example agent
docker compose up --build
# Agent calls http://host.docker.internal:3123
# 3. Verify connectivity
docker exec ifenpay-agent python -c "
import requests
r = requests.get('http://host.docker.internal:3123/wallet/balance', timeout=10)
print(r.status_code, r.text[:200])"
Ready to Enable AI Payments?
One binary. MCP + HTTP API. All 7 payment tools. Zero framework lock-in.