AI Integration Guide

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

Complete API Documentation

quick_start.py
import requests
import sys

def api_call(method, url, json_data=None, description=""):
    """Make API call with error handling"""
    try:
        response = requests.request(method, url, json=json_data, timeout=35)
        response.raise_for_status()
        return response
    except requests.exceptions.Timeout:
        print(f"โŒ Timeout: {description}")
        sys.exit(1)
    except requests.exceptions.HTTPError as e:
        print(f"โŒ HTTP Error {response.status_code}: {description}")
        print(f"   {response.text}")
        sys.exit(1)
    except Exception as e:
        print(f"โŒ Error: {str(e)}")
        sys.exit(1)

# Step 1: Create API Key
print("๐Ÿ”‘ Creating API key...")
response = api_call("POST", "https://api.x402nano.com/key/create", {}, "Create API Key")
api_key = response.text
print(f"   โœ“ API Key: {api_key[:20]}...")

# Step 2: Create Wallet
print("\n๐Ÿ’ผ Creating wallet...")
response = api_call(
    "POST", "https://api.x402nano.com/wallet/create",
    {
        "password": "SecurePassword123!",
        "password_confirmation": "SecurePassword123!",
        "email": "ai@company.com",
        "api_key": api_key
    },
    "Create Wallet"
)
wallet = response.text
print(f"   โœ“ Wallet created (encrypted)")

# Step 3: Unlock to get wallet details
print("\n๐Ÿ”“ Unlocking wallet...")
response = api_call(
    "POST", "https://api.x402nano.com/wallet/unlock",
    {"encrypted_wallet_string": wallet, "password": "SecurePassword123!"},
    "Unlock Wallet"
)
wallet_data = response.json()
address = wallet_data["address"]
print(f"   โœ“ Address: {address}")

# Step 4: Check balance
print("\n๐Ÿ’ฐ Checking balance...")
response = api_call(
    "POST", f"https://api.x402nano.com/balance/{address}",
    {}, "Get Balance"
)
balance_data = response.json()
print(f"   Balance: {balance_data['balance']} NANO")
print(f"   Pending: {balance_data['pending']} NANO")

# Step 5: Receive pending funds (if any)
if float(balance_data['pending']) > 0:
    print("\n๐Ÿ“จ Receiving pending funds...")
    response = api_call(
        "POST", "https://api.x402nano.com/receive",
        {"encrypted_wallet_string": wallet, "password": "SecurePassword123!"},
        "Receive Funds"
    )
    receive_data = response.json()
    if receive_data.get('success'):
        print(f"   โœ“ Received {receive_data['received']} NANO")
        print(f"   โœ“ New balance: {receive_data['new_balance']} NANO")

# Step 6: Send payment (requires sufficient balance)
print("\n๐Ÿ’ธ Sending payment...")
response = api_call(
    "POST", "https://api.x402nano.com/send",
    {
        "encrypted_wallet_string": wallet,
        "password": "SecurePassword123!",
        "to_address": "nano_3i9iuh88bzkgjnt6usuda5763axrnwpm6hce95gai6kn5to8fb3f3fgmia17",
        "amount": "0.001"  # Amount in Nano, not raw
    },
    "Send Payment"
)
send_data = response.json()
if send_data.get('success'):
    print(f"   โœ“ Sent {send_data['ammount']} NANO")
    print(f"   โœ“ To: {send_data['send_to'][:20]}...")

# Step 7: Make a donation to x402Nano
print("\nโค๏ธ Making donation...")
response = api_call(
    "POST", "https://api.x402nano.com/donate",
    {
        "encrypted_wallet_string": wallet,
        "password": "SecurePassword123!",
        "amount": "0.1"
    },
    "Donate"
)
donate_data = response.json()
if donate_data.get('success'):
    print(f"   โœ“ {donate_data['message']}")

# Step 8: Create merchant transaction
print("\n๐Ÿ›’ Creating merchant transaction...")
response = api_call(
    "POST", "https://api.x402nano.com/transaction/create",
    {
        "receive_address": address,
        "amount": "5.0",
        "metadata": "{\"product\": \"API Access\", \"tier\": \"premium\"}",
        "callback_url": "https://yourapp.com/webhook"
    },
    "Create Transaction"
)
tx_data = response.json()
transaction_id = tx_data['transaction_id']
unique_amount = tx_data['amount']
print(f"   โœ“ Transaction ID: {transaction_id}")
print(f"   โœ“ Unique amount: {unique_amount} NANO")

# Step 9: Pay the transaction
print("\n๐Ÿ’ณ Paying transaction...")
response = api_call(
    "POST", "https://api.x402nano.com/transaction/pay",
    {
        "transaction_id": transaction_id,
        "amount": unique_amount,
        "encrypted_wallet_string": wallet,
        "password": "SecurePassword123!"
    },
    "Pay Transaction"
)
pay_data = response.json()
print(f"   โœ“ Payment successful!")

# Step 10: Check transaction status
print("\n๐Ÿ” Checking transaction status...")
response = api_call(
    "POST", f"https://api.x402nano.com/transaction/status/{transaction_id}",
    {}, "Get Transaction Status"
)
status_data = response.json()
print(f"   โœ“ Status: {status_data['message']}")
print(f"   โœ“ Is Paid: {status_data['is_paid']}")
print(f"   โœ“ Metadata: {status_data['metadata']}")

print("\nโœ… Complete integration demo finished!")

Error Handling

โš ๏ธ HTTP Status Codes

200 Success - Request processed successfully
400 Bad Request - Invalid parameters or missing required fields
401 Unauthorized - Invalid API key
429 Rate Limited - Too many requests
500 Server Error - Internal error, retry with exponential backoff

๐Ÿ” Common Error Responses

// Invalid Address
{
  "error": "invalid_address",
  "message": "The receive address is invalid or does not exist"
}

// Insufficient Balance
{
  "error": "insufficient_balance",
  "message": "Insufficient funds to complete transaction"
}

// Invalid Password
{
  "error": "invalid_password",
  "message": "Failed to decrypt wallet with provided password"
}

// Transaction Not Found
{
  "error": "invalid_transaction_id",
  "message": "Invalid transaction ID"
}

// Amount Mismatch
{
  "error": "amount_mismatch",
  "message": "Amount does not match the created transaction amount. Amount should be 9.990000123456789."
}

// Metadata Too Large
{
  "error": "metadata_too_large",
  "message": "Metadata must be less than 4KB"
}

// Invalid Metadata
{
  "error": "invalid_metadata",
  "message": "Metadata must be valid JSON"
}

โœ… Best Practices

โฑ๏ธ
Set Timeouts:

Use 35 second timeout for transaction status (long-polling), 10 seconds for other endpoints

๐Ÿ”„
Implement Retries:

Retry on 500/503 errors with exponential backoff (1s, 2s, 4s, 8s)

โœ”๏ธ
Validate Responses:

Always check success field and HTTP status codes

๐Ÿ’พ
Store Wallet Safely:

Encrypted wallet string is safe to store, but password must be kept secret

๐Ÿ“Š
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

โฒ๏ธ Rate Limiting

The API has rate limits to ensure fair usage:

Per API Key
100 req/min
All endpoints
Burst Allowed
20 req/sec
Short bursts only

โ„น๏ธ If rate limited (429), wait and retry with exponential backoff. Contact support for higher limits.

Advanced Features

Webhooks

โš ๏ธ

Security Warning

Only configure webhooks if your firewall is properly configured. Webhooks expose your server to incoming HTTP requests.

Get instant notifications when payments are received:

  • โœ“ Real-time payment alerts
  • โœ“ HMAC-SHA256 signature verification
  • โœ“ Custom metadata support (4KB JSON)
  • โœ“ Automatic retries on failure

Payment Requests

Create payment transactions with unique amounts:

  • โœ“ Unique amounts prevent conflicts
  • โœ“ Auto-expiring (60 minutes)
  • โœ“ Long-polling confirmation (30s)
  • โœ“ PostgreSQL audit trail

Security

Enterprise-grade security built-in:

  • โœ“ AES-256 wallet encryption
  • โœ“ HTTPS-only communication
  • โœ“ No private key exposure
  • โœ“ Rate limiting & DDoS protection

OpenAPI Schema

Machine-readable API specification:

  • โœ“ Import into Postman/Insomnia
  • โœ“ Generate client libraries
  • โœ“ Perfect for AI agents
  • โœ“ Always up-to-date

Need Help?

Full documentation, code examples, and community support available