{
  "openapi": "3.1.0",
  "info": {
    "title": "Grokbot x402 tools: Safe Read and x402 Preflight",
    "version": "1.2.0",
    "description": "Pay-per-call tools for AI agents, paid in USDC on Base via x402 v2 (exact scheme, Coinbase CDP facilitator). No account or API key. Responses with status 400 or higher are never settled.",
    "x-guidance": "Use /api/read before putting any public web page into an agent's context: it returns clean main text plus prompt-injection warnings. Use /api/preflight before paying any other x402 endpoint. Use /api/guide ($2) for the full x402 Seller Field Guide as Markdown.",
    "contact": {
      "name": "Grokbot",
      "email": "nickchief@mail.grokbot.com",
      "url": "https://x402-preflight-grokbot.netlify.app"
    }
  },
  "servers": [
    {
      "url": "https://x402-preflight-grokbot.netlify.app"
    }
  ],
  "paths": {
    "/api/read": {
      "get": {
        "operationId": "safeRead",
        "summary": "Fetch a public page: clean text, hash, metadata, prompt-injection risk",
        "description": "SSRF-guarded fetch (DNS resolved and every address checked, socket pinned to the checked address; private, loopback, link-local, CGNAT, multicast and reserved ranges refused; ports 80/443 only; at most 4 redirects, each re-checked; no https-to-http downgrade; 2 MB cap after decompression; 8 s overall timeout; text/html, application/xhtml+xml and text/plain only). Main text via Readability. Injection scan covers visible text, hidden elements, HTML comments, alt/title/aria/meta attributes, invisible Unicode tag characters and base64 payloads.",
        "x-payment-info": {
          "protocol": "x402",
          "x402Version": 2,
          "scheme": "exact",
          "network": "eip155:8453",
          "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "amount": "2000",
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.002000"
          },
          "payTo": "0x6573467528C349Fa9b2AFA6993116fC7bE1D10c1",
          "facilitator": "https://api.cdp.coinbase.com/platform/v2/x402",
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "example": "https://usdc-address-book.netlify.app/"
          }
        ],
        "responses": {
          "200": {
            "description": "Page read",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadResult"
                }
              }
            }
          },
          "400": {
            "description": "Error (not charged)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Payment required. The PAYMENT-REQUIRED header (base64 JSON) carries the x402 v2 offer; retry with a PAYMENT-SIGNATURE header."
          },
          "502": {
            "description": "Error (not charged)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/preflight": {
      "get": {
        "operationId": "x402Preflight",
        "summary": "Check an x402 endpoint before paying it",
        "description": "One unpaid probe of the target. Returns live price in USD, network, canonical-USDC check, payTo, timeout, CDP Bazaar listing mismatches and a pay / caution / do_not_pay verdict. Never signs or pays.",
        "x-payment-info": {
          "protocol": "x402",
          "x402Version": 2,
          "scheme": "exact",
          "network": "eip155:8453",
          "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "amount": "10000",
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.010000"
          },
          "payTo": "0x6573467528C349Fa9b2AFA6993116fC7bE1D10c1",
          "facilitator": "https://api.cdp.coinbase.com/platform/v2/x402",
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "example": "https://gas.apitoll.cloud/v1/base/gas?blocks=20"
          },
          {
            "name": "method",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "GET",
                "POST"
              ],
              "default": "GET"
            }
          },
          {
            "name": "max_usd",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Optional price ceiling in USD"
          }
        ],
        "responses": {
          "200": {
            "description": "Verdict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreflightResult"
                }
              }
            }
          },
          "400": {
            "description": "Error (not charged)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Payment required. The PAYMENT-REQUIRED header (base64 JSON) carries the x402 v2 offer; retry with a PAYMENT-SIGNATURE header."
          }
        }
      }
    },
    "/api/read/sample": {
      "get": {
        "operationId": "safeReadSample",
        "summary": "Free static sample of a /api/read response",
        "responses": {
          "200": {
            "description": "Sample"
          }
        },
        "security": []
      }
    },
    "/api/sample": {
      "get": {
        "operationId": "preflightSample",
        "summary": "Free static sample of a /api/preflight response",
        "responses": {
          "200": {
            "description": "Sample"
          }
        },
        "security": []
      }
    },
    "/api/health": {
      "get": {
        "operationId": "health",
        "summary": "Free health check with prices",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": []
      }
    },
    "/api/guide": {
      "get": {
        "summary": "x402 Seller Field Guide ($2 USDC on Base via x402)",
        "description": "Returns the full guide as Markdown in JSON. Free preview at /guide.html.",
        "responses": {
          "200": {
            "description": "Guide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "title": {
                      "type": "string"
                    },
                    "version": {
                      "type": "integer"
                    },
                    "format": {
                      "type": "string"
                    },
                    "markdown": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required (x402 v2, PAYMENT-REQUIRED header)"
          }
        },
        "x-payment-info": {
          "protocol": "x402",
          "x402Version": 2,
          "scheme": "exact",
          "network": "eip155:8453",
          "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "amount": "2000000",
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "2.000000"
          },
          "payTo": "0x6573467528C349Fa9b2AFA6993116fC7bE1D10c1",
          "facilitator": "https://api.cdp.coinbase.com/platform/v2/x402",
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/preflight/try": {
      "get": {
        "operationId": "preflightDryRun",
        "summary": "Free dry run of x402 Preflight: live pay / caution / do_not_pay verdict for any x402 endpoint, details withheld",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Absolute https URL of the x402 endpoint"
          },
          {
            "name": "method",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "GET",
                "POST"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dry-run verdict"
          },
          "400": {
            "description": "Invalid or refused target"
          }
        },
        "security": []
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "error": {
            "type": "string",
            "description": "e.g. blocked_address, bad_scheme, bad_port, credentials_in_url, internal_host, dns_failed, too_many_redirects, insecure_redirect, unsupported_content_type, too_large, timeout, upstream_status"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Finding": {
        "type": "object",
        "properties": {
          "rule": {
            "type": "string"
          },
          "severity": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high"
            ]
          },
          "where": {
            "type": "string",
            "enum": [
              "main_text",
              "hidden_element",
              "html_comment",
              "attributes",
              "meta_tags"
            ]
          },
          "excerpt": {
            "type": "string"
          }
        }
      },
      "ReadResult": {
        "type": "object",
        "required": [
          "ok",
          "finalUrl",
          "text",
          "contentHash",
          "injection",
          "metadata"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "url": {
            "type": "string"
          },
          "finalUrl": {
            "type": "string"
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "byline": {
            "type": [
              "string",
              "null"
            ]
          },
          "text": {
            "type": "string",
            "description": "Main text, paragraphs separated by blank lines, headings prefixed with #. Max 100,000 chars."
          },
          "contentHash": {
            "type": "string",
            "description": "sha256 of text"
          },
          "rawHash": {
            "type": "string",
            "description": "sha256 of the raw body"
          },
          "injection": {
            "type": "object",
            "properties": {
              "riskScore": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "riskLevel": {
                "type": "string",
                "enum": [
                  "none",
                  "low",
                  "medium",
                  "high"
                ]
              },
              "findings": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Finding"
                }
              },
              "discussesInjection": {
                "type": "boolean",
                "description": "Page is about prompt injection; visible quotes are capped at medium"
              },
              "scanned": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "note": {
                "type": "string"
              }
            }
          },
          "metadata": {
            "type": "object",
            "properties": {
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "siteName": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "author": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "publishedTime": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "modifiedTime": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "lang": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "canonicalUrl": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "image": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "contentType": {
                "type": "string"
              },
              "charset": {
                "type": "string"
              },
              "upstreamStatus": {
                "type": "integer"
              },
              "bytes": {
                "type": "integer"
              },
              "bodyTruncated": {
                "type": "boolean"
              },
              "textTruncated": {
                "type": "boolean"
              },
              "words": {
                "type": "integer"
              },
              "chars": {
                "type": "integer"
              },
              "extraction": {
                "type": "string",
                "enum": [
                  "readability",
                  "body_fallback",
                  "plain"
                ]
              },
              "redirects": {
                "type": "integer"
              },
              "hops": {
                "type": "array"
              },
              "fetchedAt": {
                "type": "string",
                "format": "date-time"
              },
              "elapsedMs": {
                "type": "integer"
              },
              "lastModifiedHeader": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "etag": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        }
      },
      "PreflightResult": {
        "type": "object",
        "properties": {
          "verdict": {
            "type": "string",
            "enum": [
              "pay",
              "caution",
              "do_not_pay",
              "not_x402"
            ]
          },
          "offers": {
            "type": "array"
          },
          "recommendedOffer": {
            "type": [
              "object",
              "null"
            ]
          },
          "bazaar": {
            "type": "object"
          },
          "reasons": {
            "type": "array"
          },
          "warnings": {
            "type": "array"
          },
          "httpStatus": {
            "type": "integer"
          },
          "latencyMs": {
            "type": "integer"
          }
        }
      }
    }
  }
}