HTTP API Examples

Ready-to-run code for every nano-toolset endpoint

[INFO]

Prerequisites

nano-toolset must be running: cargo run --release in the ifenpay-nano-toolset directory.

HTTP API listens on http://127.0.0.1:3123 by default. Install requests for Python examples: pip install requests

Example 1: Check Wallet Balance

GET /wallet/balance

Retrieve the current wallet balance and address. Useful as a health check and to verify funds before sending.

Python requests 
import requests

# GET /wallet/balance
resp = requests.get("http://127.0.0.1:3123/wallet/balance").json()

if resp["success"]:
    data = resp["data"]
    print(f"Address: {data['account']}")
    print(f"Balance: {data['balance']} NANO")
    print(f"Raw:     {data['balance_raw']}")
else:
    print(f"Error: {resp['error']['message']}")
Example Response
{
  "success": true,
  "data": {
        "account": "nano_3abc...",
        "balance": "1.5",
        "pending": "0.0",
        "balance_raw": "1500000000000000000000000000000"
  },
  "error": null
}

Example 2: Send Nano

POST /wallet/send

Send Nano to a recipient address. The toolset handles block creation, signing and broadcasting. Amount is in NANO (not raw).

Python requests 
import requests

# POST /wallet/send
payload = {
    "recipient_address": "nano_1abc...",
    "amount": "0.001",  # NANO
}
resp = requests.post("http://127.0.0.1:3123/wallet/send", json=payload).json()

if resp["success"]:
    data = resp["data"]
    print(f"Sent! Amount: {data['amount']} to {data['recipient']}")
else:
    print(f"Error: {resp['error']['error']} - {resp['error']['message']}")
Example Response
{
  "success": true,
  "data": {
    "amount": "0.001",
    "recipient": "nano_1abc..."
  },
  "error": null
}

Example 3: Create & Poll Payment Request

POST /payment/request GET /payment/status/{id}

Create a payment request and poll for confirmation. Ideal for AI-to-AI payments or any scenario where you need to verify receipt.

Python requests + polling 
import requests, time

# Step 1: Create payment request
payload = {
    "receive_address": "nano_1abc...",
    "amount": "0.01",
    "redirect_url": "https://example.com/thanks",  # optional
}
resp = requests.post("http://127.0.0.1:3123/payment/request", json=payload).json()

if not resp["success"]:
    raise Exception(resp["error"]["message"])

tx_id = resp["data"]["transaction_id"]
amount = resp["data"]["amount"]  # payer should send this exact amount
print(f"tx: {tx_id} - send {amount} to {resp['data']['receive_address']}")

# Step 2: Poll for payment confirmation
for _ in range(30):
    status = requests.get(f"http://127.0.0.1:3123/payment/status/{tx_id}").json()
    state = status["data"]["is_paid"]
    if state:
        print("Payment confirmed!")
        break
    time.sleep(5)
else:
    print("Timeout: Timed out waiting for payment")

Example 4: Credits System

GET /credits POST /credits/topup/{n}

Check your ifenpay service credits balance and top up. Credits power the payment request infrastructure. Valid top-up amounts: 10, 50, 100, 500, 1000, 5000, 10000, 50000, 100000.

Python requests 
import requests

# Check credits
resp = requests.get("http://127.0.0.1:3123/credits").json()
credits = resp["data"]["credits"]
print(f"Current credits: {credits}")

# Top up credits (valid amounts: 10,50,100,500,1000,...)
if credits < 50:
    topup = requests.post("http://127.0.0.1:3123/credits/topup/100").json()
    if topup["success"]:
        print(f"Topped up! New balance: {topup['data']['new_credits_balance']}")
    else:
        print(f"Top-up failed: {topup['error']['message']}")
Credits Response
{
  "success": true,
  "data": {
    "topped_up_credits": 100,
    "new_credits_balance": 950
  },
  "error": null
}

Example 5: Error Handling

All API responses follow the same envelope. Check success first, then inspect error.error for the error code and error.message for a human-readable description.

Python - robust error handling pattern 
import requests

def call_toolset(method, path, **kwargs):
    url = f"http://127.0.0.1:3123{path}"
    resp = getattr(requests, method)(url, **kwargs).json()
    if not resp["success"]:
        err = resp["error"]
        raise ValueError(f"[{err['error']}] {err['message']}")
    return resp["data"]

# Usage
try:
    data = call_toolset("get", "/wallet/balance")
    print(f"Balance: {data['balance']} NANO")
except ValueError as e:
    print(f"API error: {e}")
except requests.exceptions.ConnectionError:
    print("nano-toolset is not running (cargo run --release)")
INSUFFICIENT_FUNDS

Not enough funds

INVALID_ADDRESS

Bad Nano address

INVALID_NUMBER_FORMAT

Amount format error

INVALID_TRANSACTION_ID

Unknown tx_id

INVALID_CREDITS_AMOUNT

Need more credits

REQUEST_ERROR

Unexpected server error

Example 6: Complete AI-to-AI Payment Flow

Agent A requests payment -> Agent B verifies -> Agent B sends -> Agent A confirms

End-to-end example combining all toolset capabilities. Agent A creates a payment request, Agent B polls and sends Nano, Agent A verifies receipt.

Python - full AI-to-AI flow 
import requests, time

BASE = "http://127.0.0.1:3123"  # both agents use same toolset in this example

# -- Agent A: request payment -----------------------------------------
balance_a = requests.get(f"{BASE}/wallet/balance").json()["data"]
print(f"Agent A address: {balance_a['account']}")

req = requests.post(f"{BASE}/payment/request", json={
    "receive_address": balance_a["account"],
    "amount": "0.001",
}).json()

if not req["success"]:
    raise Exception(f"Request failed: {req['error']['message']}")

tx_id = req["data"]["transaction_id"]
print(f"Agent A created payment request: {tx_id}")

# -- Agent B: check balance, then send -------------------------------
bal_b = requests.get(f"{BASE}/wallet/balance").json()["data"]
if float(bal_b["balance"]) >= 0.001:
    send = requests.post(f"{BASE}/wallet/send", json={
        "recipient_address": balance_a["account"],
        "amount": "0.001",
    }).json()
    print(f"Agent B sent. Recipient: {send['data']['recipient']}")

# -- Agent A: poll for confirmation ----------------------------------
for _ in range(20):
    status = requests.get(f"{BASE}/payment/status/{tx_id}").json()["data"]
    if status["is_paid"]:
        print("Agent A confirmed payment received")
        break
    time.sleep(3)

Start Building

Run nano-toolset, call the HTTP API, integrate with your agent.

Quick Start Guide API Reference GitHub ->