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
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
Use 35 second timeout for transaction status (long-polling), 10 seconds for other endpoints
Retry on 500/503 errors with exponential backoff (1s, 2s, 4s, 8s)
Always check success field and HTTP status codes
Encrypted wallet string is safe to store, but password must be kept secret
Keep local records of transaction IDs, amounts, and timestamps for auditing
Start with small amounts (0.001 NANO) to verify integration
โฒ๏ธ Rate Limiting
The API has rate limits to ensure fair usage:
โน๏ธ 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