agentpay.tools

{
  "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": 500,
      "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": {
    "properties": {
      "agent_address": {
        "description": "Paying agent's wallet address",
        "type": "string"
      },
      "label": {
        "description": "Optional session label",
        "type": "string"
      },
      "max_spend": {
        "description": "Budget cap in USDC, e.g. '0.10'",
        "type": "string"
      }
    },
    "type": "object"
  },
  "output": {
    "agent_address": "G...",
    "created_at": "2026-05-27T00:00:00Z",
    "gateway_url": "https://agentpay.tools",
    "max_spend": "0.10",
    "receipt": {
      "amount_usdc": "0.01",
      "network": "base",
      "tx_hash": "0x..."
    },
    "session_id": "uuid",
    "tools_endpoint": "https://agentpay.tools/tools"
  }
}