A stateful, multi-chain spending session for AI agents

[
  {
    "scheme": "exact",
    "network": "eip155:8453",
    "payTo": "0xE8B25A72dD6aeF69515452a61AD231C7DF2843b7",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "10000",
    "maxTimeoutSeconds": 300
  }
]

{
  "bazaar": {
    "description": "A stateful, multi-chain spending session for AI agents: a hard USDC budget cap across every tool call, with a verifiable receipt and running ledger per payment. Not a one-shot budget check — persistent spend governance with a full audit trail. USDC on Base (standard x402) or Stellar (via the AgentPay SDK).",
    "info": {
      "errors": [
        {
          "body": {
            "error": "<summary>",
            "reason": "<machine-readable reason>"
          },
          "retry": "Re-request the challenge and pay again",
          "status": 402,
          "when": "No payment attached (this challenge), or the attached payment failed verification: wrong amount/recipient, memo mismatch, expired, or already used (replay)"
        },
        {
          "body": {
            "detail": [
              {
                "loc": [
                  "body"
                ],
                "msg": "<what is wrong>",
                "type": "<error type>"
              }
            ]
          },
          "retry": "Fix the body and retry with a fresh payment",
          "status": 422,
          "when": "Request body present but malformed (invalid JSON or wrong field types) WITH a payment header attached — checked BEFORE settlement, so the payment is never consumed. An unpaid malformed request gets the 402, not a 422"
        },
        {
          "body": {
            "detail": "Tool '<name>' not found"
          },
          "status": 404,
          "when": "Unknown tool name"
        },
        {
          "body": {
            "error": "Rate limit exceeded"
          },
          "retry": "Back off and retry after a minute",
          "status": 429,
          "when": "Rate limited (per-IP and per-wallet limits)"
        },
        {
          "body": {
            "error": "Tool execution failed",
            "payment_status": "refund_pending",
            "tool": "<name>"
          },
          "status": 502,
          "when": "Payment settled on-chain but tool execution failed — the payment is marked refund_pending automatically; you are not charged for a failed call"
        },
        {
          "body": {
            "detail": "<what is unavailable>"
          },
          "retry": "Retry shortly",
          "status": 503,
          "when": "Tool temporarily unavailable, or the gateway cannot persist the challenge (fail-closed)"
        }
      ],
      "input": {
        "body": {
          "agent_address": "0x0000000000000000000000000000000000000000",
          "label": "session",
          "max_spend": "0.10"
        },
        "bodyType": "json",
        "method": "POST",
        "type": "http"
      },
      "output": {
        "example": {
          "created_at": "2026-05-29T00:00:00Z",
          "gateway_url": "https://agentpay.tools",
          "max_spend": "0.10",
          "receipt": {
            "amount_usdc": "0.01",
            "network": "eip155:8453",
            "tx_hash": "0xee85d8dd374b5d1cb40bfa441086af557d356acc2bb4d5819f56331fce42adee"
          },
          "session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
          "tools_endpoint": "https://agentpay.tools/tools"
        },
        "type": "json"
      }
    },
    "schema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "properties": {
        "input": {
          "properties": {
            "body": {
              "properties": {
                "agent_address": {
                  "description": "Paying agent's EVM wallet address",
                  "type": "string"
                },
                "label": {
                  "description": "Optional human-readable session label",
                  "type": "string"
                },
                "max_spend": {
                  "description": "Hard budget cap in USDC, e.g. '0.10'",
                  "type": "string"
                }
              },
              "required": [
                "agent_address"
              ],
              "type": "object"
            },
            "bodyType": {
              "type": "string"
            },
            "method": {
              "type": "string"
            },
            "type": {
              "type": "string"
            }
          },
          "required": [
            "type",
            "method",
            "body"
          ],
          "type": "object"
        }
      },
      "type": "object"
    }
  }
}

curl "https://agentpay.tools/v1/session/create"
# -> 402 Payment Required, accepts[] lists how to pay
# retry with a PAYMENT-SIGNATURE (or PAYMENT header) once paid

const res = await fetch("https://agentpay.tools/v1/session/create");
if (res.status === 402) {
  const { accepts } = await res.json();
  // pay one of accepts[] via an x402 client, then retry with the payment header
}

import httpx
res = httpx.get("https://agentpay.tools/v1/session/create")
if res.status_code == 402:
    accepts = res.json()["accepts"]
    # pay one of accepts[] via an x402 client, then retry with the payment header