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": {
      "budget_usd": {
        "default": 1,
        "description": "Max USDC the agent will pay the downstream tool per call",
        "type": "number"
      },
      "chain": {
        "default": "",
        "description": "Optional chain filter: 'base', 'arbitrum', 'arbitrum-stack'. Empty = all chains.",
        "type": "string"
      },
      "need": {
        "description": "What the agent needs, e.g. 'dex pair liquidity', 'crypto prices'",
        "type": "string"
      }
    },
    "required": [
      "need"
    ],
    "type": "object"
  },
  "output": {
    "budget_usd": "1",
    "catalog": {
      "after_vetting": 114,
      "biggest_factory": {
        "listings": 72,
        "pay_to": "0x2bb72231eed3"
      },
      "real_providers": 41,
      "scanned": 117,
      "sybil_collapsed": 73,
      "unique_wallets": 38
    },
    "chain": null,
    "need": "dex pair liquidity",
    "recommendation": {
      "calls30d": 3246,
      "evidence": [
        {
          "metric": "delivery_rate",
          "n": 12,
          "observed_at": "2026-09-30T13:05:00Z",
          "ref": "/s/otto-example-dex-1a2b3c",
          "source": "agentpay-prober",
          "type": "delivery",
          "value": 1
        },
        {
          "metric": "unique_payers_30d",
          "observed_at": "2026-10-01T12:00:00Z",
          "ref": null,
          "source": "coinbase-bazaar",
          "type": "third-party",
          "value": 200
        }
      ],
      "flags": [],
      "name": "Otto AI",
      "network": "eip155:8453",
      "pay_to": "0x0e84ddedaae6a7",
      "payers30d": 200,
      "price_usd": "0.001",
      "quality": 3851,
      "ready_to_pay": {
        "accepts": {
          "network": "eip155:8453",
          "scheme": "exact"
        },
        "network": "eip155:8453",
        "price_usd": "0.001",
        "url": "https://otto.example/dex"
      },
      "url": "https://otto.example/dex"
    },
    "survivors": [],
    "vetting": "swept 17 queries → 117 listings → collapsed 73 sybil listings → 41 real providers"
  }
}