{
  "openapi": "3.1.0",
  "info": {
    "title": "Hood Incinerator API",
    "version": "1.0.0",
    "summary": "Read burn data and compose unsigned token burns on EVM chains.",
    "description": "Public, keyless, read-only API for Hood Incinerator (0XdEaD.io). Every endpoint reads live chain data. The build-burn endpoint returns an unsigned transaction batch for the asset owner's wallet to approve — the API never signs, never holds keys, and never asks for a seed phrase. Burns are irreversible.",
    "contact": {
      "name": "Hood Incinerator",
      "url": "https://0xdead.io/agents"
    }
  },
  "servers": [
    {
      "url": "https://0xdead.io/api/public/v1"
    }
  ],
  "paths": {
    "/chains": {
      "get": {
        "operationId": "listChains",
        "summary": "Supported chains, app fees and the dead address",
        "responses": {
          "200": {
            "description": "Chain list"
          }
        }
      }
    },
    "/token": {
      "get": {
        "operationId": "getToken",
        "summary": "Token supply and how much is already burned",
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "chain",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "robinhood"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Token facts"
          },
          "400": {
            "description": "Bad input"
          }
        }
      }
    },
    "/leaderboard": {
      "get": {
        "operationId": "getLeaderboard",
        "summary": "Tokens ranked by percentage of supply burned",
        "parameters": [
          {
            "name": "chain",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "robinhood"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked rows"
          }
        }
      }
    },
    "/points": {
      "get": {
        "operationId": "getPoints",
        "summary": "Incinerator Points for a wallet, or the scoring model",
        "parameters": [
          {
            "name": "wallet",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Points"
          }
        }
      }
    },
    "/compare": {
      "get": {
        "operationId": "compareBurnMethods",
        "summary": "Routing through the terminal versus a hand-sent transfer",
        "description": "Deterministic cost and artifact comparison: the exact extra fee, signature count, and the verifiable outputs routing produces (leaderboard row, Incinerator Points, supply receipt, proof post, machine-readable record). Supply arithmetic is included when a token and amount are given. No price or success-rate claim is made.",
        "parameters": [
          {
            "name": "chain",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "robinhood"
            }
          },
          {
            "name": "address",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "amount",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "burner",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Comparison"
          },
          "400": {
            "description": "Bad input"
          }
        }
      }
    },
    "/stats": {
      "get": {
        "operationId": "getTerminalStats",
        "summary": "Measured terminal usage, recounted from public explorer records",
        "description": "App-fee payments, distinct wallets, distinct contracts burned, routed burns and summed supply share removed, with the explorer URLs and match rule needed to reproduce every figure independently.",
        "parameters": [
          {
            "name": "chain",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "robinhood"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Measured stats"
          }
        }
      }
    },
    "/build-burn": {
      "post": {
        "operationId": "buildBurn",
        "summary": "Compose an unsigned burn (transfer to 0x…dEaD plus the app fee)",
        "description": "Returns an EIP-5792 wallet_sendCalls batch, individual transactions, an EIP-681 URI, a pre-filled burn console URL and the share post. Nothing is signed or broadcast.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "address",
                  "amount"
                ],
                "properties": {
                  "address": {
                    "type": "string",
                    "description": "ERC-20 contract to burn."
                  },
                  "amount": {
                    "type": "string",
                    "description": "Decimal amount, \"25%\", or \"max\"."
                  },
                  "burner": {
                    "type": "string",
                    "description": "Signing wallet, if known."
                  },
                  "chain": {
                    "type": "string",
                    "default": "robinhood"
                  },
                  "ref": {
                    "type": "string",
                    "description": "Optional attribution label."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Unsigned burn plan"
          },
          "400": {
            "description": "Bad input"
          }
        }
      }
    }
  }
}