Let an AI agent buy proxies: a UCP checkout paid from the balance

curl -s https://api.quanticdata.io/.well-known/ucp

{
  "ucp": {
    "version": "2026-08-25",
    "services": { "dev.ucp.shopping": [ { "transport": "rest",
                   "endpoint": "https://api.quanticdata.io/v1/agent/ucp" } ] },
    "capabilities": { "dev.ucp.shopping.checkout": [ { "version": "2026-08-25" } ] },
    "payment_handlers": { "io.quanticdata.balance": [ { "id": "balance",
                   "available_instruments": [ { "type": "account_balance", "currency": "USD" } ] } ] }
  },
  "endpoints": { "checkout_sessions": "https://api.quanticdata.io/v1/agent/ucp/checkout-sessions",
                 "catalog": "https://api.quanticdata.io/v1/public/plans" }
}

curl -s -X POST https://api.quanticdata.io/v1/agent/ucp/checkout-sessions \
  -H "Authorization: Bearer $QD_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-2026-10-26-001" \
  -d '{"line_items":[{"item":{"id":"pln_3e7a"},"quantity":1}],"payment_method":"BALANCE"}'

{
  "id": "chk_7d3f0a9b2c4e1f6a8b9c0d1e",
  "status": "ready_for_complete",
  "totals": [ { "type": "subtotal", "amount": 1200 }, { "type": "total", "amount": 1200 } ],
  "payment": { "instruments": [ { "handler_id": "balance", "type": "account_balance", "selected": true } ] },
  "continue_url": "https://app.quanticdata.io/plans?network=RESIDENTIAL&agent_checkout=chk_…",
  "messages": [ { "code": "balance_available", "content": "The account balance covers this checkout. …" },
                { "code": "vat_rule", "content": "Totals carry 0% VAT (balance or crypto). …" } ]
}

import os, uuid, requests

API = "https://api.quanticdata.io/v1"
H = {"Authorization": f"Bearer {os.environ['QUANTICDATA_API_KEY']}"}

def open_session(plan_id):
    r = requests.post(f"{API}/agent/ucp/checkout-sessions", headers={**H, "Idempotency-Key": str(uuid.uuid4())},
                      json={"line_items": [{"item": {"id": plan_id}, "quantity": 1}], "payment_method": "BALANCE"},
                      timeout=60)
    s = r.json()
    if r.status_code not in (200, 201):
        raise SystemExit(s["messages"][0]["content"])       # UCP error document
    total = next(t["amount"] for t in s["totals"] if t["type"] == "total")
    print(f'session {s["id"]}: {s["status"]}, total {total / 100:.2f} USD')
    return s

session = open_session("pln_3e7a")

curl -s -X POST https://api.quanticdata.io/v1/agent/ucp/checkout-sessions/chk_7d3f0a9b2c4e1f6a8b9c0d1e/complete \
  -H "Authorization: Bearer $QD_API_KEY" -H "Content-Type: application/json" \
  -d '{"payment":{"instruments":[{"handler_id":"balance","type":"account_balance","selected":true}]}}'

{
  "status": "completed",
  "order": { "id": "ord_8c21", "permalink_url": "https://app.quanticdata.io/proxies" },
  "messages": [ { "code": "order_created", "content": "Paid from the account balance. The proxy plan is active: …" } ]
}

def complete(session_id):
    r = requests.post(f"{API}/agent/ucp/checkout-sessions/{session_id}/complete", headers=H,
                      json={"payment": {"instruments": [{"handler_id": "balance", "type": "account_balance", "selected": True}]}},
                      timeout=120)
    s = r.json()
    errors = [m for m in s.get("messages", []) if m["type"] == "error"]
    if s["status"] != "completed":
        # payment_failed: the balance no longer covers it -> hand over; purchase_failed: read content, retry later
        raise RuntimeError(errors[0]["content"] if errors else s["status"])
    return s["order"]["id"]

order_id = complete(session["id"])