{
  "openapi": "3.1.0",
  "info": {
    "title": "ToolMint HUD FMR + Income Limits JSON",
    "version": "0.1.1",
    "description": "HUD Fair Market Rents and Income Limits by US county for AI agents. Pay per call with USDC on Base via x402. This product uses the HUD User Data API but is not endorsed or certified by HUD User.",
    "x-guidance": "Find a county's FIPS with free GET /counties/{state} (e.g. LA). Then GET /fmr/county/{fips} for rents, /il/county/{fips} for income limits, or /county/{fips} for both. Optional ?year=. Unpaid calls receive HTTP 402 with x402 payment requirements (USDC on Base). 4xx/5xx are not charged.",
    "contact": {
      "email": "toolmint.dev@gmail.com",
      "name": "ToolMint"
    }
  },
  "paths": {
    "/health": {
      "get": {
        "operationId": "health",
        "summary": "Liveness",
        "security": [],
        "responses": {
          "200": {
            "description": "ok"
          }
        }
      }
    },
    "/counties/{state}": {
      "get": {
        "operationId": "hud_counties",
        "summary": "Counties + FIPS for a state (free)",
        "security": [],
        "parameters": [
          {
            "name": "state",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{2}$"
            }
          },
          {
            "name": "updated",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                2025
              ]
            },
            "description": "2025 = county codes updated for Income Limits 2025"
          }
        ],
        "responses": {
          "200": {
            "description": "County list"
          },
          "400": {
            "description": "Bad state (code bad_input)"
          },
          "503": {
            "description": "Rate limited (code rate_limited, Retry-After) or not configured"
          }
        }
      }
    },
    "/fmr/county/{fips}": {
      "get": {
        "operationId": "hud_fmr_county",
        "summary": "Fair Market Rents for a county",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.010000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ],
          "network": "eip155:8453",
          "payTo": "0xfbF7413bcB3a604936775C96FDbe0b0C9c9E37F5",
          "asset": "USDC",
          "scheme": "exact",
          "amountAtomic": "10000"
        },
        "parameters": [
          {
            "name": "fips",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^(\\d{5}|\\d{10})$"
            },
            "description": "5-digit county FIPS (e.g. 22015 Bossier Parish, LA) or 10-digit HUD id"
          },
          {
            "name": "year",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 2017,
              "maximum": 2027
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized HUD data with provenance, attribution and terms"
          },
          "400": {
            "description": "Bad parameters, code bad_input (rejected before payment; not charged)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment Required"
          },
          "404": {
            "description": "No HUD data for that county/year, code not_found (not charged)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal error, code internal (not charged)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Upstream error, code upstream_error (not charged)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Not configured / payment init / rate limited (codes not_configured, payment_unavailable, rate_limited; Retry-After on rate limits; not charged)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/il/county/{fips}": {
      "get": {
        "operationId": "hud_il_county",
        "summary": "Income Limits for a county",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.010000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ],
          "network": "eip155:8453",
          "payTo": "0xfbF7413bcB3a604936775C96FDbe0b0C9c9E37F5",
          "asset": "USDC",
          "scheme": "exact",
          "amountAtomic": "10000"
        },
        "parameters": [
          {
            "name": "fips",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^(\\d{5}|\\d{10})$"
            },
            "description": "5-digit county FIPS (e.g. 22015 Bossier Parish, LA) or 10-digit HUD id"
          },
          {
            "name": "year",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 2017,
              "maximum": 2027
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized HUD data with provenance, attribution and terms"
          },
          "400": {
            "description": "Bad parameters, code bad_input (rejected before payment; not charged)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment Required"
          },
          "404": {
            "description": "No HUD data for that county/year, code not_found (not charged)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal error, code internal (not charged)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Upstream error, code upstream_error (not charged)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Not configured / payment init / rate limited (codes not_configured, payment_unavailable, rate_limited; Retry-After on rate limits; not charged)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/county/{fips}": {
      "get": {
        "operationId": "hud_fmr_il_county",
        "summary": "FMR + Income Limits for a county",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.020000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ],
          "network": "eip155:8453",
          "payTo": "0xfbF7413bcB3a604936775C96FDbe0b0C9c9E37F5",
          "asset": "USDC",
          "scheme": "exact",
          "amountAtomic": "20000"
        },
        "parameters": [
          {
            "name": "fips",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^(\\d{5}|\\d{10})$"
            },
            "description": "5-digit county FIPS (e.g. 22015 Bossier Parish, LA) or 10-digit HUD id"
          },
          {
            "name": "year",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 2017,
              "maximum": 2027
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized HUD data with provenance, attribution and terms"
          },
          "400": {
            "description": "Bad parameters, code bad_input (rejected before payment; not charged)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment Required"
          },
          "404": {
            "description": "No HUD data for that county/year, code not_found (not charged)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal error, code internal (not charged)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Upstream error, code upstream_error (not charged)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Not configured / payment init / rate limited (codes not_configured, payment_unavailable, rate_limited; Retry-After on rate limits; not charged)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}