Python SDK

Professional Python SDK for ifenpay Agent. One pip install away from autonomous AI payments.

SDK on GitHub View on PyPI

⚡ 1-Minute Setup

Install & Start in Seconds

Production-ready Python SDK with CLI tool included!

Requirement: Docker Desktop

Install from docker.com

Install SDK

pip install ifenpay-agent-sdk

One command installs SDK + CLI tool

Setup Agent

python -m ifenpay_agent_sdk.cli setup

Installs & starts agent automatically

✅ Done! Start Coding:

from ifenpay_agent_sdk import Agent, AgentError

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

# Check balance with auto-receive
balance = agent.check_balance(auto_receive_pending_blocks=True)
print(f"Balance: {balance.balance} NANO")

# Send payment
agent.pay("nano_address", "0.001")

⚙️

Agent Configuration (.env)

The agent uses a .env file for configuration. Located at:

~/.ifenpay/agent/.env

This file is created automatically from .env.example during setup.

Key Settings:

AGENT_MODE - Set to AUTONOMOUS or STRICT

AI_WALLET_PASSWORD - Auto-generated secure password for wallet encryption

NANO_WORK_MODE - CPU or GPU for proof-of-work

💡 Tip: Edit the .env file with your preferred text editor before starting the agent:

nano ~/.ifenpay/agent/.env

Requirement: Docker & Docker Compose

Install: sudo apt install docker.io docker-compose

Install SDK

pip3 install ifenpay-agent-sdk

Works with Python 3.8+

Setup Agent

python3 -m ifenpay_agent_sdk.cli setup

Auto-installs to ~/.ifenpay/agent/

✅ Done! Start Coding:

from ifenpay_agent_sdk import Agent

agent = Agent("http://localhost:7860")
result = agent.pay("nano_address", "0.001")
print(result.amount, result.recipient)

⚙️

Agent Configuration (.env)

The agent uses a .env file for configuration. Located at:

~/.ifenpay/agent/.env

This file is created automatically from .env.example during setup.

Key Settings:

AGENT_MODE - Set to AUTONOMOUS or STRICT

AI_WALLET_PASSWORD - Auto-generated secure password for wallet encryption

NANO_WORK_MODE - CPU or GPU for proof-of-work

💡 Tip: Edit the .env file before starting the agent:

nano ~/.ifenpay/agent/.env

Requirement: Docker Desktop

Install from docker.com or brew install --cask docker

Install SDK

pip3 install ifenpay-agent-sdk

Compatible with M1/M2 Macs

Setup Agent

python3 -m ifenpay_agent_sdk.cli setup

Works on Intel & Apple Silicon

✅ Done! Start Coding:

from ifenpay_agent_sdk import Agent, AgentError

try:
    agent = Agent("http://localhost:7860")
    result = agent.pay("nano_address", "0.001")
except AgentError as e:
    print(f"Error: {e.error_code} - {e.message}")

⚙️

Agent Configuration (.env)

The agent uses a .env file for configuration. Located at:

~/.ifenpay/agent/.env

This file is created automatically from .env.example during setup.

Key Settings:

AGENT_MODE - Set to AUTONOMOUS or STRICT

AI_WALLET_PASSWORD - Auto-generated secure password for wallet encryption

NANO_WORK_MODE - CPU or GPU for proof-of-work

💡 Tip: Edit the .env file before starting the agent:

nano ~/.ifenpay/agent/.env

See SDK Examples Below ↓

Professional Python SDK

Type-safe, well-documented, production-ready

🎯

Type-Safe

Full dataclass support with type hints. IDE autocomplete works perfectly.

result: PaymentResult
result.amount  # str
result.recipient  # str

⚡

Easy Error Handling

Custom AgentError exception with error codes and messages.

try:
    agent.pay("..")
except AgentError as e:
    print(e.error_code)

🛠️

CLI Tool Included

Manage agent with simple commands. No manual Docker setup.

python -m ifenpay_agent_sdk.cli setup
python -m ifenpay_agent_sdk.cli status
python -m ifenpay_agent_sdk.cli logs

ai_payment_flow.py

from ifenpay_agent_sdk import Agent, AgentError

# Initialize agent (strict mode for AI-to-AI payments)
agent = Agent(agent_url="http://localhost:7860")

try:
    # 1. Check balance (auto-receives 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}")
    
    # 2. Create payment request (for receiving payments)
    payment_req = agent.request_payment(amount="0.001")
    print(f"\nTransaction ID: {payment_req.transaction_id}")
    print(f"Pay to: {payment_req.receive_address}")
    print(f"Pay EXACTLY: {payment_req.amount} NANO (includes offset)")
    
    # 3. Send payment
    result = agent.pay(
        address="nano_1ebhjnii43rx9fs41njqam86q9uwgcfbap18beoyrpheekw7wniu9e3g6rb3",
        amount="0.001"
    )
    print(f"\n✅ Payment sent!")
    print(f"Hash: {result.hash}")
    
    # 4. Check payment status
    status = agent.check_payment_status(payment_req.transaction_id)
    print(f"\nStatus: {status.get('response')}")
    print(f"Message: {status.get('message')}")
    
    # 5. Get credits info
    credits = agent.get_credits_info()
    print(f"\nCredits: {credits.credits}")
    print(f"10 credits = {credits.price_10} NANO")
    
    # 6. Top up credits
    topup = agent.topup_credits(amount=10)
    print(f"\nToppped up: {topup.topped_up_credits} credits")
    print(f"New balance: {topup.new_credits_balance} credits")
    
    # 7. Donate (sends payment automatically)
    donation = agent.donate(amount="0.001")
    print(f"\n❤️  Donated {donation.amount} NANO")
    
except AgentError as e:
    print(f"❌ Error [{e.error_code}]: {e.message}")

Complete SDK Examples

Check Balance

Check your Nano balance and automatically receive pending blocks

check_balance.py

from ifenpay_agent_sdk import Agent, AgentError

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

try:
    # Check balance (auto-receives 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}")
    
    # Check balance without auto-receive
    balance = agent.check_balance(auto_receive_pending_blocks=False)
    print(f"\n💰 Balance: {balance.balance} NANO")
    print(f"   Pending: {balance.pending} NANO")

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

Send & Receive Payments

Complete payment workflow with error handling

payments.py

from ifenpay_agent_sdk import Agent, AgentError

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

try:
    # Create payment request
    print("📋 Creating payment request...")
    payment_request = agent.request_payment(amount="0.001")
    
    print(f"✅ Payment request created:")
    print(f"   Transaction ID: {payment_request.transaction_id}")
    print(f"   Pay EXACTLY: {payment_request.amount} NANO (includes offset)")
    print(f"   To address: {payment_request.receive_address}")
    
    # Check balance before sending
    balance = agent.check_balance(auto_receive_pending_blocks=True)
    print(f"\n💰 Current balance: {balance.balance} NANO")
    print(f"   Pending: {balance.pending} NANO")
    
    # Send payment
    print(f"\n💸 Sending payment...")
    
    payment = agent.pay(
        address="nano_1ebhjnii43rx9fs41njqam86q9uwgcfbap18beoyrpheekw7wniu9e3g6rb3",
        amount="0.001"
    )
    
    print(f"✅ Payment sent successfully:")
    print(f"   Hash: {payment.hash}")
    
    # Check payment status
    status = agent.check_payment_status(payment_request.transaction_id)
    print(f"\n📊 Payment Status:")
    print(f"   Response: {status.get('response')}")
    print(f"   Message: {status.get('message')}")

except AgentError as e:
    print(f"❌ Error [{e.error_code}]: {e.message}")
    
    # Handle specific errors
    if e.error_code == "INSUFFICIENT_BALANCE":
        print("💡 Tip: Fund your wallet first!")
    elif e.error_code == "INVALID_ADDRESS":
        print("💡 Tip: Check the recipient address format")

API Credits Management

Check and top up API credits for platform service costs (NANO transactions = 0 fees)

credits_management.py

from ifenpay_agent_sdk import Agent, AgentError

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

try:
    # Get credits info
    print("💳 Checking API credits...")
    credits = agent.get_credits_info()
    
    print(f"\n📊 Credits Status:")
    print(f"   Available: {credits.credits} credits")
    print(f"\n💰 Pricing:")
    print(f"   10 credits  = {credits.price_10} NANO")
    print(f"   50 credits  = {credits.price_50} NANO")
    print(f"   100 credits = {credits.price_100} NANO")
    
    # Top up credits (sends payment automatically)
    credits_to_buy = 10
    print(f"\n🔋 Topping up {credits_to_buy} credits...")
    
    topup = agent.topup_credits(amount=credits_to_buy)
    
    print(f"✅ Credits topped up:")
    print(f"   Added: {topup.topped_up_credits} credits")
    print(f"   New Balance: {topup.new_credits_balance} credits")
    
    # Donate to support development (sends payment automatically)
    print("\n❤️  Support ifenpay Development:")
    donation = agent.donate(amount="0.001")
    print(f"   ✅ Donated {donation.amount} NANO")
    print(f"   Thank you for your support! 🙏")

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

CLI Tool Commands

Manage ifenpay Agent from command line

⚙️ Setup (Install + Start)

python -m ifenpay_agent_sdk.cli setup

One command to install and start agent (checks Docker, clones repo, starts containers)

📊 Check Status

python -m ifenpay_agent_sdk.cli status

Shows agent installation status and running state

▶️ Start / Stop Agent

python -m ifenpay_agent_sdk.cli start
python -m ifenpay_agent_sdk.cli stop

Control agent Docker containers

📋 View Logs

python -m ifenpay_agent_sdk.cli logs

Tail agent logs in real-time (Ctrl+C to exit)

🔄 Automatic Updates

python -m ifenpay_agent_sdk.cli update       # Update both SDK and Agent
python -m ifenpay_agent_sdk.cli update-sdk   # Update SDK only
python -m ifenpay_agent_sdk.cli update-agent # Update Agent only

Keep your SDK and Agent up to date (updates are checked automatically on start)

📦 Install Only

python -m ifenpay_agent_sdk.cli install

Install agent without starting (useful for custom configuration)

💡

Note for Windows Users

If the CLI command doesn't work, use python -m ifenpay_agent_sdk.cli instead of ifenpay-agent

Resources & Links

📦

SDK Repository

View source code, examples, and documentation on GitHub

🐍

PyPI Package

Official Python package on PyPI - pip install ready

🤖

Agent Backend

ifenpay-Agent repository with Flask API and strict mode

💬

Discord Community

Get help, share projects, and discuss AI payments

❤️ Support ifenpay

Donation Address

💝 Your Support Helps Us:

Python SDK

Install & Start in Seconds

Install SDK

Setup Agent

✅ Done! Start Coding:

Agent Configuration (.env)

Key Settings:

Install SDK

Setup Agent

✅ Done! Start Coding:

Agent Configuration (.env)

Key Settings:

Install SDK

Setup Agent

✅ Done! Start Coding:

Agent Configuration (.env)

Key Settings:

Professional Python SDK

Type-Safe

Easy Error Handling

CLI Tool Included

Complete SDK Examples

Check Balance

Send & Receive Payments

API Credits Management

CLI Tool Commands

⚙️ Setup (Install + Start)

📊 Check Status

▶️ Start / Stop Agent

📋 View Logs

🔄 Automatic Updates

📦 Install Only

Resources & Links

SDK Repository

PyPI Package

Agent Backend

Discord Community