AI Agent Playbook

Build autonomous payment agents with a predictable execution model. Same 7 tools via MCP over stdio or HTTP API.

Integration Guide Code Examples

Agent Lifecycle

1. Inspect State

Read wallet.balance before deciding the next payment action.

2. Create Intent

Create a request with payment.request and store transaction_id.

3. Execute Transfer

Use wallet.send and capture response fields for audit and retries.

4. Verify Outcome

Poll payment.status until is_paid is true.

HTTP Pattern

Framework-agnostic flow with deterministic envelope handling.

import requests, time
BASE = "http://127.0.0.1:3123"

def call(method, path, **kwargs):
    resp = getattr(requests, method)(f"{BASE}{path}", **kwargs).json()
    if not resp["success"]:
        raise ValueError(resp["error"]["error"])
    return resp["data"]

balance = call("get", "/wallet/balance")
request = call("post", "/payment/request", json={
    "receive_address": balance["account"],
    "amount": "0.001"
})

for _ in range(20):
    status = call("get", f"/payment/status/{request['transaction_id']}")
    if status["is_paid"]:
        break
    time.sleep(2)

MCP Pattern

Use MCP when your framework already supports stdio tools.

# 1) initialize
# 2) tools/list
# 3) tools/call (payment.request)

{
  "name": "payment.request",
  "arguments": {
    "receive_address": "nano_...",
    "amount": "0.01",
    "redirect_url": null
  }
}

# Always branch on envelope:
# success=true  -> use data
# success=false -> use error.error + error.message

Production Checklist

  • ✅ Validate required arguments before each tool call.
  • ✅ Treat error.error as machine key for routing logic.
  • ✅ Add retries only for transient connectivity failures.
  • ✅ Do not retry input/validation errors without changing payload.
  • ✅ Persist transaction_id for reconciliation and idempotency logic.
  • ✅ Keep AI_WALLET_PASSWORD stable after wallet creation; it is bound to local wallet encryption.

Build Your First Autonomous Payment Agent

Start with the playbook, then plug in your own business rules.

Integration Guide API Reference