AI Integration Guide

Enable your AI agents to make autonomous payments in minutes. Complete setup guide from API key to first transaction.

⚡ 2-Minute Setup

Get Started in 3 Steps

It's really this simple!

Requirement: Docker & Docker Compose

Install Docker Desktop from docker.com

1

Install Agent

git clone https://github.com/ifenpay/ifenpay-Agent.git
cd ifenpay-Agent
docker-compose up

Clone repo and run with Docker. Agent starts on localhost:7860

2

Configure

# .env
AGENT_MODE=strict
AI_WALLET_PASSWORD='auto-generated' # Auto-generated
NANO_WORK_USE_GPU=true
NANO_WORK_GPU_VENDOR=nvidia

Edit .env with your settings. AI_WALLET_PASSWORD is auto-generated!

3

Start Coding

requests.post(
  "http://localhost:7860/api/chat/stream",
  json={
    "message": "balance.check true",
    "mode": "strict"
  }
)

Start directly with payments. Wallet auto-managed!

🤖 Open Source AI Agent

ifenpay-Agent: Autonomous Payment Agent

Open-source Flask-based AI agent enabling autonomous AI-to-AI payments through machine-readable strict mode commands. Zero LLM overhead for instant transactions.

7 Strict Mode Commands

Machine-readable responses with automatic AI wallet management

Instant Responses (No LLM Delay)

Direct command execution without natural language processing overhead

Production Ready

Flask API with SSE, automatic wallet management, and comprehensive error handling

strict_mode_example.py
import requests
import uuid

# ifenpay-Agent Strict Mode - Automatic AI Wallet
# Wallet is initialized and cleaned automatically per request
session_id = str(uuid.uuid4())
url = "http://127.0.0.1:7860/api/chat/stream"

# Check balance (wallet auto-initialized, auto-receive pending blocks)
response = requests.post(url, json={
    "message": "balance.check true",  # true = auto-receive pending
    "mode": "strict",
    "session_id": session_id
})
# Response: {"response": "success", "data": {"balance": "0.0", "address": "nano_...", ...}}

# Create payment request
response = requests.post(url, json={
    "message": "payment.request 0.001",
    "mode": "strict",
    "session_id": session_id
})
# Response: {"response": "success", "data": {
#   "amount": "0.001", "transaction_id": "abc-123",
#   "receive_address": "nano_...", "api_key": "xyz789"}}

# Send payment
response = requests.post(url, json={
    "message": "nano.send nano_1ebh... 0.001",
    "mode": "strict",
    "session_id": session_id
})
# Response: {"response": "success", "data": {"amount": "0.001", ...}}

Complete API Documentation

ℹ️

Using ifenpay-Agent with Automatic AI Wallet

Strict mode uses automatic AI wallet management with custodial model. Wallet is initialized and cleaned automatically per request for security. No wallet.create or wallet.unlock needed!

ifenpay_agent_quickstart.py
import requests
import uuid
import json

import uuid
import json

# ifenpay-Agent connection
AGENT_URL = "http://127.0.0.1:7860/api/chat/stream"
session_id = str(uuid.uuid4())

def send_command(message):
    """Send strict mode command to agent"""
    response = requests.post(AGENT_URL, json={
        "message": message,
        "mode": "strict",
        "session_id": session_id
    }, stream=True)
    
    # Parse SSE response
    for line in response.iter_lines():
        if line and line.decode('utf-8').startswith('data:'):
            data = json.loads(line.decode('utf-8')[5:])
            return data

# Step 1: Get wallet info (automatic initialization in strict mode)
print("🔑 Getting wallet info...")
result = send_command("wallet.info")
print(f"   Address: {result['data']['address']}")
# Step 2: Check balance (auto-receive pending blocks)
print("\n💰 Checking balance...")
result = send_command("balance.check true")  # true = auto-receive pending
print(f"   Balance: {result['data']['balance']} NANO")
print(f"   Address: {result['data']['address']}")
# Response: {"response": "success", "data": {"balance": "0.0", "pending": "0.0", "address": "nano_..."}}

# Step 3: Create payment request
print("\n📋 Creating payment request...")
result = send_command("payment.request 0.001")
print(f"   TX ID: {result['data']['transaction_id']}")
# Response: {"response": "success", "data": {"amount": "0.001", "transaction_id": "...", ...}}

# Step 4: Send payment (requires balance)
print("\n💸 Sending payment...")
recipient = "nano_1ebhjnii43rx9fs41njqam86q9uwgcfbap18beoyrpheekw7wniu9e3g6rb3"
result = send_command(f"nano.send {recipient} 0.001")
print(f"   Amount: {result['data']['amount']} NANO")
# Response: {"response": "success", "data": {"amount": "0.001", "recipient": "nano_..."}}

# Step 5: Check credits info
print("\n💳 Checking credits...")
result = send_command("credits.info")
print(f"   Credits: {result['data']['available_credits']}")
# Response: {"response": "success", "data": {"available_credits": 0, "price_10": "0.005", ...}}

# Step 6: Top up credits
print("\n🔋 Requesting credit top-up...")
result = send_command("credits.topup 10")
print(f"   Pay {result['data']['nano_amount']} NANO")
# Response: {"response": "success", "data": {"nano_amount": "0.005", "payment_address": "nano_..."}}

# Step 7: Donate
print("\n❤️  Getting donation address...")
result = send_command("donate.nano 0.1")
print(f"   Address: {result['data']['donate_address']}")
# Response: {"response": "success", "data": {"donate_address": "nano_...", "amount": "0.1"}}

print("\n✅ All commands tested successfully!")

Error Handling

⚠️ Error Code Format

All errors follow the format: ERROR_CODE: Description

WALLET_* Wallet-related errors (creation, unlock, not found)
SEND_* Transaction sending errors (insufficient balance, validation)
PAYMENT_* Payment request/status errors
BALANCE_* Balance check errors
CREDITS_* Credits and top-up errors

🔍 Common Error Responses

// Wallet Not Found
WALLET_NOT_FOUND: Wallet 'MyWallet' does not exist

// Wrong Password
WALLET_WRONG_PASSWORD: Incorrect password for wallet

// Insufficient Balance
SEND_INSUFFICIENT_BALANCE: Insufficient balance to complete transaction

// Invalid Parameters
SEND_INVALID_PARAMS: Usage: nano.send <address> <amount>

// No Active Wallet
SEND_NO_WALLET: No active wallet found. Use wallet.unlock first

// Validation Error
SEND_VALIDATION_ERROR: Invalid NANO address format

// Payment Not Found
PAYMENT_STATUS_NOT_FOUND: Transaction ID not found or not paid

// Manual Password Override (rarely occurs - password is auto-generated)
WALLET_CONFIG_ERROR: AI_WALLET_PASSWORD is not strong enough (needs uppercase, lowercase, digits, special chars)

✅ Best Practices

🔍
Parse Error Codes:

Extract ERROR_CODE prefix for programmatic error handling

🔐
Auto-Generated Security:

AI_WALLET_PASSWORD is automatically generated with high-entropy secure random strings (uppercase, lowercase, digits, special chars)

🔓
Wallet Management:

In natural/hybrid mode, use wallet.unlock before payments. In strict mode, wallet is automatically managed.

📝
Session IDs:

Use unique session IDs (UUID) for each AI agent to maintain separate wallet states

📊
Log All Transactions:

Keep local records of transaction IDs, amounts, and timestamps for auditing

🧪
Test Before Production:

Start with small amounts (0.001 NANO) to verify integration

PoW Performance:

Receive blocks: ~1-5s | Send blocks: ~30-90s (depending on hardware)

Installation & Configuration

Docker Installation

Deploy with Docker (recommended):

git clone https://github.com/ifenpay/ifenpay-Agent.git
cd ifenpay-Agent
docker-compose up
  • ✓ Auto-configured environment
  • ✓ GPU support included
  • ✓ Runs on port 7860

Configuration

Edit .env:

  • AGENT_MODE: "strict" for AI-to-AI
  • AI_WALLET_PASSWORD: Auto-generated by init script
  • NANO_WORK_MODE: "opencl" (GPU) or "cpu"
  • LLM_BACKEND: "ollama" (local) recommended

Security Features

Built-in security mechanisms:

  • ✓ Session-based wallet isolation
  • ✓ Automatic password management
  • ✓ API key verification for payments
  • ✓ No private key exposure

OpenAPI Specification

Machine-readable API docs:

  • ifenpay-agent-openapi.yaml
  • ✓ Import into Postman/Insomnia
  • ✓ Perfect for AI agents
  • ✓ Complete endpoint documentation

Need Help?

Full documentation, code examples, and community support available