{
 "openapi": "3.1.0",
 "info": {
  "title": "US Bank Risk Metrics API",
  "version": "1.0.0",
  "description": "Pay-per-call (x402, USDC on Base) risk metrics for every FDIC-insured US bank, computed from FDIC Call Report data, with raw inputs and source URLs in every response.",
  "x-guidance": "Find a bank's FDIC cert with GET /v1/banks/search?q=<name> (free). Then GET /v1/banks/{cert} ($0.01) for full metrics, or GET /v1/banks/screen?metric=<id>&top=N ($0.02) to rank all banks. Unpaid calls return HTTP 402 with x402 payment requirements; pay with any x402 client and retry. Try free first: /v1/banks/sample and /v1/free/banks/{cert} (5/day). Only 2xx responses are settled.",
  "license": {
   "name": "Derived data CC-BY-4.0; source FDIC public data"
  },
  "contact": {
   "email": "kv@mail.grokbot.com"
  }
 },
 "servers": [
  {
   "url": "https://bank-risk-api.culturehub-kash.workers.dev"
  }
 ],
 "paths": {
  "/v1/banks/{cert}": {
   "get": {
    "operationId": "banks_lookup",
    "summary": "Bank risk metrics by FDIC cert ($0.01)",
    "description": "Risk metrics for one FDIC-insured US bank by FDIC cert: uninsured deposits, CRE concentration, unrealized securities losses vs tangible equity, loan-to-deposit, NIM, ROA, noncurrent loans, capital ratios, composite risk score; raw FDIC inputs, source URL and 5-quarter history.",
    "tags": [
     "paid"
    ],
    "parameters": [
     {
      "name": "cert",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "example": "628",
      "description": "FDIC certificate number (find via /v1/banks/search?q=)"
     }
    ],
    "x-payment-info": {
     "protocols": [
      {
       "x402": {
        "version": 2,
        "network": "eip155:8453",
        "asset": "USDC",
        "payTo": "0x9f7165394a6a09bf3608d3510645da71867d4eb8"
       }
      }
     ],
     "price": {
      "mode": "fixed",
      "currency": "USD",
      "amount": "0.01"
     }
    },
    "security": [
     {
      "x402": []
     }
    ],
    "responses": {
     "200": {
      "description": "Metrics with provenance",
      "content": {
       "application/json": {
        "example": {
         "dataset": "fdic-banks",
         "cert": 628,
         "name": "JPMORGAN CHASE BANK NA",
         "state": "OHIO",
         "metrics": {
          "risk_score": 54.3,
          "uninsured_deposit_share": 62.5346,
          "cre_concentration": 61.9085,
          "unrealized_loss_to_tangible_equity": 7.1665,
          "loan_to_deposit": 54.4497,
          "nim": 2.8818,
          "roa": 1.5852
         },
         "inputs_thousands_usd": {
          "ASSET": 4091315000,
          "DEP": 2820284000,
          "DEPUNINS": 1392514000,
          "RBC": 326427000
         },
         "provenance": {
          "report_date": "2026-06-30",
          "quarter": "2026Q2",
          "methodology_version": "1.0.0"
         },
         "history": "[5 quarters]"
        }
       }
      }
     },
     "402": {
      "description": "Payment required (x402). PAYMENT-REQUIRED header (v2, base64 JSON) and x402 v1 JSON body."
     },
     "404": {
      "description": "Unknown cert (not charged)"
     }
    }
   }
  },
  "/v1/banks/screen": {
   "get": {
    "operationId": "banks_screen",
    "summary": "Rank all banks by a metric ($0.02)",
    "description": "Rank all ~4,300 FDIC-insured US banks by a risk metric (e.g. cre_concentration, uninsured_deposit_share, unrealized_loss_to_tangible_equity, risk_score); filter by state and minimum assets.",
    "tags": [
     "paid"
    ],
    "parameters": [
     {
      "name": "metric",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "risk_score",
        "uninsured_deposit_share",
        "cre_concentration",
        "construction_concentration",
        "unrealized_loss_to_tangible_equity",
        "htm_adjusted_tangible_equity_ratio",
        "loan_to_deposit",
        "noncurrent_loan_ratio",
        "npa_to_assets",
        "nim",
        "roa",
        "total_rbc_ratio",
        "leverage_ratio",
        "total_assets_usd"
       ]
      }
     },
     {
      "name": "top",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100,
       "default": 25
      }
     },
     {
      "name": "order",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "desc",
        "asc"
       ],
       "default": "desc"
      }
     },
     {
      "name": "state",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "US state name, e.g. Florida"
     },
     {
      "name": "min_assets_usd",
      "in": "query",
      "schema": {
       "type": "number"
      }
     }
    ],
    "x-payment-info": {
     "protocols": [
      {
       "x402": {
        "version": 2,
        "network": "eip155:8453",
        "asset": "USDC",
        "payTo": "0x9f7165394a6a09bf3608d3510645da71867d4eb8"
       }
      }
     ],
     "price": {
      "mode": "fixed",
      "currency": "USD",
      "amount": "0.02"
     }
    },
    "security": [
     {
      "x402": []
     }
    ],
    "responses": {
     "200": {
      "description": "Ranked list",
      "content": {
       "application/json": {
        "example": {
         "metric": "cre_concentration",
         "order": "desc",
         "report_date": "2026-06-30",
         "count": 3,
         "results": [
          {
           "rank": 1,
           "key": "33802",
           "name": "TIOGA-FRANKLIN SAVINGS BANK",
           "state": "PENNSYLVANIA",
           "value": 821.8827
          },
          {
           "rank": 2,
           "key": "58590",
           "name": "NANO BANC",
           "state": "CALIFORNIA",
           "value": 754.533
          },
          {
           "rank": 3,
           "key": "18983",
           "name": "RIVER CITY BANK",
           "state": "CALIFORNIA",
           "value": 649.4332
          }
         ]
        }
       }
      }
     },
     "402": {
      "description": "Payment required (x402). PAYMENT-REQUIRED header (v2, base64 JSON) and x402 v1 JSON body."
     },
     "400": {
      "description": "Invalid metric (not charged)"
     }
    }
   }
  },
  "/v1/banks/search": {
   "get": {
    "operationId": "banks_search",
    "summary": "Find banks by name (free)",
    "security": [],
    "tags": [
     "free"
    ],
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Matches"
     }
    }
   }
  },
  "/v1/banks/sample": {
   "get": {
    "operationId": "banks_sample",
    "summary": "Full sample responses for 3 banks (free)",
    "security": [],
    "tags": [
     "free"
    ],
    "responses": {
     "200": {
      "description": "Sample"
     }
    }
   }
  },
  "/v1/free/banks/{cert}": {
   "get": {
    "operationId": "banks_free_trial",
    "summary": "Free trial of the paid lookup, 5/day/IP",
    "security": [],
    "tags": [
     "free"
    ],
    "parameters": [
     {
      "name": "cert",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Same as paid lookup"
     },
     "429": {
      "description": "Free quota exhausted"
     }
    }
   }
  },
  "/v1/status": {
   "get": {
    "operationId": "status",
    "summary": "Freshness and validation results (free)",
    "security": [],
    "tags": [
     "free"
    ],
    "responses": {
     "200": {
      "description": "Status"
     }
    }
   }
  },
  "/v1/datasets": {
   "get": {
    "operationId": "datasets",
    "summary": "Datasets, routes and prices (free)",
    "security": [],
    "tags": [
     "free"
    ],
    "responses": {
     "200": {
      "description": "Datasets"
     }
    }
   }
  }
 },
 "components": {
  "securitySchemes": {
   "x402": {
    "type": "apiKey",
    "in": "header",
    "name": "PAYMENT-SIGNATURE",
    "description": "x402 payment payload (v2). v1 clients may send X-PAYMENT."
   }
  }
 }
}