Code Examples

Ready-to-use code snippets for common integration scenarios

🐍

Python SDK Examples

These examples use the ifenpay Python SDK - the easiest way to integrate Nano payments for AI applications.

View Full SDK Docs GitHub Repository

Check Balance

Basic

Check your wallet balance. In strict mode, the wallet is automatically initialized per request. Optionally auto-receive pending blocks.

Python
from ifenpay_agent_sdk import Agent, AgentError

# Initialize the agent (connects to Docker agent)
agent = Agent(agent_url="http://localhost:7860")

try:
    # Check balance and auto-receive pending blocks
    balance = agent.check_balance(auto_receive_pending_blocks=True)
    
    print(f"Balance: {balance.balance} NANO")
    print(f"Pending: {balance.pending} NANO")
    print(f"Address: {balance.address}")
    
except AgentError as e:
    print(f"❌ Error [{e.error_code}]: {e.message}")

💡 Tip: Set auto_receive_pending_blocks=True to automatically process incoming payments.

Make a Payment

Common

Send Nano to any destination address. No wallet unlock needed - automatic in strict mode.

Python
from ifenpay_agent_sdk import Agent, AgentError

agent = Agent(agent_url="http://localhost:7860")

try:
    # Send payment (wallet initialized automatically)
    result = agent.pay(
        address="nano_1ebhjnii43rx9fs41njqam86q9uwgcfbap18beoyrpheekw7wniu9e3g6rb3",
        amount="0.001"  # 0.001 NANO
    )
    
    print(f"✅ Payment sent!")
    print(f"Transaction Hash: {result.hash}")
    
except AgentError as e:
    print(f"❌ Error [{e.error_code}]: {e.message}")

⚠️ Important: Always verify the destination address before sending payments.

Payment Requests (AI-to-AI)

AI Payments

Create payment requests for AI-to-AI transactions. The amount includes a unique offset for payment matching.

Python
from ifenpay_agent_sdk import Agent, AgentError

agent = Agent(agent_url="http://localhost:7860")

try:
    # Create payment request
    payment_req = agent.request_payment(amount="0.001")
    
    print(f"Transaction ID: {payment_req.transaction_id}")
    print(f"Pay to: {payment_req.receive_address}")
    print(f"⚠️  EXACT Amount: {payment_req.amount} NANO (with offset)")
    
    # Check payment status later
    status = agent.check_payment_status(payment_req.transaction_id)
    print(f"Status: {status.get('response')}")
    
except AgentError as e:
    print(f"❌ Error [{e.error_code}]: {e.message}")

⚠️ Critical: The payer MUST send the exact amount from payment_req.amount (includes unique offset). Don't use the originally requested amount.

Credits System

Credits

Check available credits and pricing. Top up credits by paying with Nano.

Python
from ifenpay_agent_sdk import Agent, AgentError

agent = Agent(agent_url="http://localhost:7860")

try:
    # Get credit info and pricing
    credits = agent.get_credits_info()
    
    print(f"Available Credits: {credits.credits}")
    print(f"10 credits = {credits.price_10} NANO")
    print(f"1000 credits = {credits.price_1000} NANO")
    
    # Top up credits
    topup = agent.topup_credits(amount=10)
    print(f"✅ Topped up {topup.topped_up_credits} credits")
    
except AgentError as e:
    print(f"❌ Error [{e.error_code}]: {e.message}")

Error Handling

Important

Always wrap SDK calls in try-except blocks to handle AgentError exceptions gracefully.

Python
from ifenpay_agent_sdk import Agent, AgentError

agent = Agent(agent_url="http://localhost:7860")

try:
    # Try to send payment
    result = agent.pay(
        address="nano_1ebhjnii43rx9fs41njqam86q9uwgcfbap18beoyrpheekw7wniu9e3g6rb3",
        amount="0.001"
    )
    print(f"✅ Success: {result.hash}")
    
except AgentError as e:
    # AgentError provides error_code and message
    print(f"❌ Error [{e.error_code}]: {e.message}")
    
    # Handle specific error codes
    if e.error_code == "insufficient_balance":
        print("💰 Need to add funds to wallet")
    elif e.error_code == "invalid_address":
        print("⚠️  Check the destination address")
    elif e.error_code == "connection_error":
        print("🔌 Agent not running? Check Docker container")

🤖 Complete AI-to-AI Payment Flow

Advanced

Complete example showing how two AI agents can transact autonomously using payment requests.

ai_to_ai_payment.py
from ifenpay_agent_sdk import Agent, AgentError
from decimal import Decimal

# AI Agent 1 (Receiver) - requests payment
receiver = Agent(agent_url="http://localhost:7860")

try:
    # Check balance first
    balance = receiver.check_balance(auto_receive_pending_blocks=True)
    print(f"Receiver Balance: {balance.balance} NANO")
    print(f"Receiver Address: {balance.address}")
    
    # Create payment request
    payment_req = receiver.request_payment(amount="0.001")
    print(f"\n📝 Payment Request Created:")
    print(f"   Transaction ID: {payment_req.transaction_id}")
    print(f"   Pay to: {payment_req.receive_address}")
    print(f"   ⚠️  EXACT Amount: {payment_req.amount} NANO (with offset)")
    
    # AI Agent 2 (Payer) - sends payment
    payer = Agent(agent_url="http://localhost:7860")
    
    # Check payer has sufficient balance
    payer_balance = payer.check_balance()
    if Decimal(payer_balance.balance) < Decimal(payment_req.amount):
        print(f"❌ Insufficient balance for payment")
    else:
        # Send payment using EXACT amount from request
        result = payer.pay(
            address=payment_req.receive_address,
            amount=payment_req.amount  # CRITICAL: Use exact amount with offset
        )
        print(f"\n✅ Payment sent!")
        print(f"   Hash: {result.hash}")
        
        # Check payment status
        status = receiver.check_payment_status(payment_req.transaction_id)
        print(f"\n📊 Payment Status: {status.get('response')}")
        
        # Receiver checks updated balance
        new_balance = receiver.check_balance(auto_receive_pending_blocks=True)
        print(f"\n💰 Receiver New Balance: {new_balance.balance} NANO")

except AgentError as e:
    print(f"❌ Error [{e.error_code}]: {e.message}")

Need More Examples?

Check out our GitHub repository for more real-world examples and use cases

View GitHub Examples Ask in Discord