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": {
      "side": {
        "default": "long",
        "description": "Trade direction (funding carry is side-aware)",
        "enum": [
          "long",
          "short"
        ],
        "type": "string"
      },
      "size_usd": {
        "default": 10000,
        "description": "Intended position size in USD (drives the slippage check)",
        "type": "number"
      },
      "symbol": {
        "description": "Asset to check, e.g. 'ETH', 'BTC', 'SOL'",
        "type": "string"
      },
      "token_address": {
        "description": "Optional ERC-20 contract address for the GoPlus security scan. Auto-resolved for major tokens; required for a full verdict on tokens the resolver doesn't know (otherwise security reads 'unknown' and caps the verdict at caution)",
        "type": "string"
      }
    },
    "required": [
      "symbol"
    ],
    "type": "object"
  },
  "output": {
    "factors": {
      "carry": {
        "annualized_pct": 67.9,
        "level": "caution",
        "median_funding_pct": 0.062,
        "reason": "longs paying elevated funding"
      },
      "crowding": {
        "level": "ok",
        "long_short_ratio": 1.4,
        "oi_change_24h_pct": 3.2,
        "reason": "positioning unremarkable"
      },
      "liquidity": {
        "bucket_usd": 50000,
        "level": "ok",
        "reason": "fills within 0.011% of best ask",
        "slippage_pct": 0.011
      },
      "security": {
        "level": "skipped",
        "reason": "no token_address provided"
      }
    },
    "side": "long",
    "size_usd": 50000,
    "symbol": "ETH",
    "verdict": "caution"
  }
}