{
  "openapi": "3.1.0",
  "info": {
    "title": "Empire Builder API",
    "version": "1.0.0",
    "description": "HTTP API for Empire Builder. An \"Empire\" is a community treasury (an ERC-4337 SmartVault on Base chain 8453 or Arbitrum chain 42161) paired with an identity called an \"Empire ID\". All write operations are live on mainnet; there is no testnet or sandbox. Most reads are open GETs; writes require an API key (`x-api-key` header or `api_key` query) and frequently an EIP-191 signature in the request body. The Empire ID (often spelled `tokenAddress`, `baseToken`, or `empire_id`) is identity (an ERC-20 address, an `fid<digits>` value, or a custom slug) and is never interchangeable with the on-chain SmartVault address (`empireAddress` / `treasuryAddress`). See https://www.empirebuilder.world/skill/SKILL.md for full signing workflows and on-chain details.",
    "contact": {
      "name": "Empire Builder",
      "url": "https://www.empirebuilder.world"
    }
  },
  "servers": [
    { "url": "https://www.empirebuilder.world", "description": "Production (mainnet, canonical host)" }
  ],
  "tags": [
    { "name": "Empires", "description": "Empire discovery and metadata" },
    { "name": "Leaderboards", "description": "Read and create leaderboards" },
    { "name": "Distributions", "description": "Prepare and record treasury payouts and burns" },
    { "name": "Boosters", "description": "Reward multipliers" },
    { "name": "Staking", "description": "Native staking activation and staking boosters" },
    { "name": "Deploy", "description": "Token config and empire lifecycle" },
    { "name": "Airdrops", "description": "Launch airdrops" }
  ],
  "security": [
    { "ApiKeyHeader": [] }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Partner/read/write API key."
      },
      "ApiKeyQuery": {
        "type": "apiKey",
        "in": "query",
        "name": "api_key",
        "description": "Alternative to the x-api-key header."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "description": "Human-readable error message." }
        },
        "required": ["error"]
      },
      "SignatureFields": {
        "type": "object",
        "description": "EIP-191 personal-sign fields. The signer field name is route-specific: `signer` for distribute-prepare, `signerAddress` for leaderboard/booster creates, `owner` for deploy flows.",
        "properties": {
          "signature": { "type": "string", "description": "0x-prefixed EIP-191 signature." },
          "message": { "type": "string", "description": "The exact plain-text message that was signed." },
          "signer": { "type": "string", "description": "Recovered signer address (used by distribute-prepare; must equal vault owner())." },
          "signerAddress": { "type": "string", "description": "Recovered signer address (used by leaderboard/booster creates; must be an empire guardian)." }
        }
      },
      "Empire": {
        "type": "object",
        "description": "An empire row. Shape is illustrative; resolve canonical fields from the live response.",
        "properties": {
          "empire_id": { "type": "string", "description": "Empire ID (ERC-20 address, fid<digits>, or custom slug)." },
          "name": { "type": "string" },
          "owner": { "type": "string", "description": "Owner wallet address." },
          "empire_address": { "type": "string", "description": "On-chain SmartVault treasury address." },
          "co_emperors": { "type": "array", "items": { "type": "string" } }
        }
      },
      "EmpireIdParam": {
        "type": "string",
        "description": "Empire ID: an ERC-20 address (0x + 40 hex), an `fid` + digits value, or a custom alphanumeric slug."
      },
      "PrepareTransaction": {
        "type": "object",
        "description": "A single vault executeBatch transaction to broadcast.",
        "properties": {
          "chainId": { "type": "integer", "examples": [8453, 42161] },
          "batchIndex": { "type": "integer", "description": "0-based index within that chain's batches; broadcast ascending." },
          "contractAddress": { "type": "string", "description": "SmartVault address (same as treasuryAddress)." },
          "value": { "type": "string", "description": "Native ETH to send, as a string integer (wei). Always \"0\"." },
          "functionName": { "type": "string", "examples": ["executeBatch"] },
          "calls": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "target": { "type": "string" },
                "value": { "type": "string" },
                "data": { "type": "string" }
              }
            }
          },
          "data": { "type": "string", "description": "Full ABI-encoded calldata for executeBatch(calls)." }
        }
      },
      "LeaderboardCreate": {
        "type": "object",
        "description": "Base body for leaderboard create endpoints. Specific types add fields (e.g. erc20Address, csv rows, channel name). See the agent skill for per-type schemas.",
        "properties": {
          "tokenAddress": { "$ref": "#/components/schemas/EmpireIdParam" },
          "applyBoosters": { "type": "boolean" },
          "signature": { "type": "string" },
          "message": { "type": "string" },
          "signerAddress": { "type": "string" }
        },
        "required": ["tokenAddress", "signature", "message", "signerAddress"]
      }
    },
    "responses": {
      "BadRequest": { "description": "Bad parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unauthorized": { "description": "API key or signature invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Forbidden": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "NotFound": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "ServerError": { "description": "Server error — retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "parameters": {
      "EmpireIdPath": {
        "name": "empire_id",
        "in": "path",
        "required": true,
        "schema": { "$ref": "#/components/schemas/EmpireIdParam" },
        "description": "Empire ID."
      }
    }
  },
  "paths": {
    "/api/top-empires": {
      "get": {
        "tags": ["Empires"],
        "summary": "Top empires by ranking",
        "security": [],
        "responses": {
          "200": { "description": "List of top empires.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Empire" } } } } },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/api/empires": {
      "get": {
        "tags": ["Empires"],
        "summary": "List empires",
        "security": [],
        "responses": {
          "200": { "description": "Empires.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Empire" } } } } },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/api/empires/{empire_id}": {
      "get": {
        "tags": ["Empires"],
        "summary": "Get a single empire by Empire ID",
        "security": [],
        "parameters": [{ "$ref": "#/components/parameters/EmpireIdPath" }],
        "responses": {
          "200": { "description": "Empire row (use empire_address as the on-chain SmartVault).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empire" } } } },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/empires/search": {
      "get": {
        "tags": ["Empires"],
        "summary": "Search empires",
        "security": [],
        "parameters": [{ "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query." }],
        "responses": {
          "200": { "description": "Matching empires.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Empire" } } } } }
        }
      }
    },
    "/api/empires/owner/{wallet}": {
      "get": {
        "tags": ["Empires"],
        "summary": "Empires owned by a wallet",
        "security": [],
        "parameters": [{ "name": "wallet", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Owner wallet address." }],
        "responses": {
          "200": { "description": "Empires owned by the wallet.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Empire" } } } } }
        }
      }
    },
    "/api/empires/ranking": {
      "get": {
        "tags": ["Empires"],
        "summary": "Empire rankings",
        "security": [],
        "responses": { "200": { "description": "Ranking data.", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/empire-airdrop-total": {
      "get": {
        "tags": ["Empires"],
        "summary": "Total airdropped across empires",
        "security": [],
        "responses": { "200": { "description": "Aggregate airdrop totals.", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/leaderboards": {
      "get": {
        "tags": ["Leaderboards"],
        "summary": "Leaderboards for an empire",
        "security": [],
        "parameters": [{ "name": "tokenAddress", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/EmpireIdParam" }, "description": "Empire ID." }],
        "responses": { "200": { "description": "Leaderboards.", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/leaderboards/{id}": {
      "get": {
        "tags": ["Leaderboards"],
        "summary": "Get a leaderboard by id",
        "security": [],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Leaderboard id (\"main\" or UUID)." }],
        "responses": { "200": { "description": "Leaderboard.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    },
    "/api/leaderboards/{type}": {
      "post": {
        "tags": ["Leaderboards"],
        "summary": "Create a leaderboard of the given type",
        "description": "Create a leaderboard. The path segment is the type, e.g. tokenHoldersLeaderboards, stakersLeaderboards, nftLeaderboards, apiLeaderboards, csvLeaderboards, farTokenLeaderboards, tipnLeaderboards, farcasterCastLeaderboards, farcasterChannelLeaderboards, farcasterInteractionLeaderboards, quotientLeaderboards. Requires API key + signature; signerAddress must be the empire owner or a co-emperor. Type-specific fields are documented in the agent skill.",
        "parameters": [{ "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": ["tokenHoldersLeaderboards", "stakersLeaderboards", "nftLeaderboards", "apiLeaderboards", "csvLeaderboards", "farTokenLeaderboards", "tipnLeaderboards", "farcasterCastLeaderboards", "farcasterChannelLeaderboards", "farcasterInteractionLeaderboards", "quotientLeaderboards"] } }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaderboardCreate" } } } },
        "responses": { "200": { "description": "Created leaderboard.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }
      }
    },
    "/api/leaderboards/refresh/{type}": {
      "patch": {
        "tags": ["Leaderboards"],
        "summary": "Refresh leaderboards of a type",
        "parameters": [{ "name": "type", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Leaderboard type suffix." }],
        "responses": { "200": { "description": "Refreshed.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      }
    },
    "/api/leaderboards/delete": {
      "post": {
        "tags": ["Leaderboards"],
        "summary": "Delete a leaderboard",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } },
        "responses": { "200": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      }
    },
    "/api/distribute-prepare": {
      "post": {
        "tags": ["Distributions"],
        "summary": "Prepare treasury payout batches",
        "description": "Reads a leaderboard and returns executeBatch transactions for the vault owner() to broadcast. The `signer` must equal the vault owner(); co-signers must use the product UI instead.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "treasuryAddress": { "type": "string", "description": "SmartVault address." },
                  "baseToken": { "$ref": "#/components/schemas/EmpireIdParam" },
                  "selectedTokenAddresses": { "type": "array", "items": { "type": "string" } },
                  "distributionMode": { "type": "string", "enum": ["even", "weighted", "raffle"] },
                  "raffleWinnerCount": { "type": "integer", "description": "Only for raffle mode." },
                  "leaderboardId": { "type": "string", "description": "\"main\" or a custom UUID." },
                  "distributePercentage": { "type": "number" },
                  "recipientCount": { "type": "integer" },
                  "signature": { "type": "string" },
                  "message": { "type": "string" },
                  "signer": { "type": "string", "description": "Must equal vault owner()." }
                },
                "required": ["treasuryAddress", "baseToken", "selectedTokenAddresses", "distributionMode", "leaderboardId", "signature", "message", "signer"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Prepared transactions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/PrepareTransaction" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/api/store-distribution": {
      "post": {
        "tags": ["Distributions"],
        "summary": "Record confirmed distribution transactions",
        "description": "Anchors a distribution record to mined executeBatch transactions. baseToken here is the Empire ID, not the vault address.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "transactionHashes": { "type": "array", "items": { "type": "object", "properties": { "hash": { "type": "string" }, "chainId": { "type": "integer" } }, "required": ["hash", "chainId"] } },
                  "empireAddress": { "type": "string", "description": "SmartVault address." },
                  "baseToken": { "$ref": "#/components/schemas/EmpireIdParam" },
                  "distributionMode": { "type": "string" },
                  "leaderboardType": { "type": "string" },
                  "leaderboardNumber": { "type": "integer" },
                  "empireDisplayName": { "type": "string" }
                },
                "required": ["transactionHashes", "empireAddress", "baseToken"]
              }
            }
          }
        },
        "responses": { "200": { "description": "Stored." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      }
    },
    "/api/store-burn": {
      "post": {
        "tags": ["Distributions"],
        "summary": "Record a burn transaction",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "transactionHash": { "type": "string" },
                  "empireAddress": { "type": "string" },
                  "chainId": { "type": "integer", "examples": [8453, 42161] }
                },
                "required": ["transactionHash", "empireAddress", "chainId"]
              }
            }
          }
        },
        "responses": { "200": { "description": "Stored." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      }
    },
    "/api/distribution-records/{empireAddress}": {
      "get": {
        "tags": ["Distributions"],
        "summary": "Distribution records for an empire vault",
        "security": [],
        "parameters": [{ "name": "empireAddress", "in": "path", "required": true, "schema": { "type": "string" }, "description": "SmartVault address." }],
        "responses": { "200": { "description": "Records.", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/rewards/recipients/{txHash}": {
      "get": {
        "tags": ["Distributions"],
        "summary": "Recipients decoded from a distribution tx",
        "security": [],
        "parameters": [{ "name": "txHash", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Recipients.", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/empire-rewards/{token}": {
      "get": {
        "tags": ["Distributions"],
        "summary": "Reward totals for an empire",
        "security": [],
        "parameters": [{ "name": "token", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EmpireIdParam" } }],
        "responses": { "200": { "description": "Reward totals.", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/get-token-config": {
      "post": {
        "tags": ["Deploy"],
        "summary": "Generate a Clanker v4 token config",
        "description": "Generates a tokenConfig object (and optional airdrop tree) for client-side deployment. API key only; no signature.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "symbol": { "type": "string" },
                  "imageUrl": { "type": "string" },
                  "creatorAddress": { "type": "string" },
                  "vaultPercentage": { "type": "number" },
                  "vaultDays": { "type": "integer" },
                  "poolType": { "type": "string" },
                  "feeType": { "type": "string" },
                  "initialMarketCap": { "type": "number" },
                  "enableDevBuy": { "type": "boolean" },
                  "devBuyAmount": { "type": "number" },
                  "enableAirdrop": { "type": "boolean" },
                  "airdropEntries": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "amount": { "type": "number" } } } },
                  "airdropLockupDays": { "type": "integer", "description": "Must be >= 1 when enableAirdrop is true." },
                  "airdropVestingDays": { "type": "integer" }
                },
                "required": ["name", "symbol", "imageUrl", "creatorAddress"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Token config.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "tokenConfig": { "type": "object" }, "airdropTree": { "type": ["object", "null"] } } } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/deploy-empire": {
      "post": {
        "tags": ["Deploy"],
        "summary": "Register an empire (deploy SmartVaults)",
        "description": "Fresh-deploy flow: provide txHash of the Clanker deploy. Attach flow: omit txHash and provide signature + message verified against owner. Never send tokenType (rejected with 400).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "baseToken": { "type": "string", "description": "Deployed/existing ERC-20 address." },
                  "name": { "type": "string" },
                  "owner": { "type": "string" },
                  "txHash": { "type": "string", "description": "Required for the fresh-deploy flow." },
                  "chainId": { "type": "integer", "examples": [8453, 42161] },
                  "clankerVersion": { "type": "string", "examples": ["clanker_v4"] },
                  "tokenInfo": { "type": "object", "properties": { "symbol": { "type": "string" }, "name": { "type": "string" }, "logoURI": { "type": "string" } } },
                  "signature": { "type": "string", "description": "Required when txHash is omitted." },
                  "message": { "type": "string", "description": "Required when txHash is omitted." },
                  "empireMetadata": { "type": "object" }
                },
                "required": ["baseToken", "name", "owner"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Empire registered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "empireAddress": { "type": "string" }, "treasuryAddress": { "type": "string" }, "empire": { "$ref": "#/components/schemas/Empire" } } } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/deploy-empire-tokenless": {
      "post": {
        "tags": ["Deploy"],
        "summary": "Create a tokenless empire",
        "description": "Creates a SmartVault-backed empire without an ERC-20 base token. Requires API key + EIP-191 signature by owner; the message must match the exact template (Farcaster or custom mode).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "mode": { "type": "string", "enum": ["farcaster", "custom"] },
                  "owner": { "type": "string" },
                  "name": { "type": "string", "description": "<= 100 chars." },
                  "logoUri": { "type": "string" },
                  "signature": { "type": "string" },
                  "message": { "type": "string", "description": "Exact template text." },
                  "fid": { "type": "integer", "description": "Required when mode is farcaster; must match Neynar FID for owner." }
                },
                "required": ["mode", "owner", "name", "signature", "message"]
              }
            }
          }
        },
        "responses": { "200": { "description": "Empire created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empire" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      }
    },
    "/api/store-airdrop": {
      "post": {
        "tags": ["Airdrops"],
        "summary": "Register a launch airdrop",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tokenAddress": { "type": "string" },
                  "tokenName": { "type": "string" },
                  "tokenSymbol": { "type": "string" },
                  "creatorAddress": { "type": "string" },
                  "airdropEntries": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "amount": { "type": "number" } } } },
                  "lockupDays": { "type": "integer" },
                  "vestingDays": { "type": "integer" },
                  "totalAmount": { "type": "number" },
                  "deploymentTxHash": { "type": "string" },
                  "merkleRoot": { "type": "string" },
                  "airdropContractAddress": { "type": "string" }
                },
                "required": ["tokenAddress", "tokenName", "creatorAddress", "airdropEntries", "deploymentTxHash"]
              }
            }
          }
        },
        "responses": { "200": { "description": "Stored." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      }
    },
    "/api/airdrops/{tokenAddress}": {
      "get": {
        "tags": ["Airdrops"],
        "summary": "Airdrops for a token",
        "parameters": [{ "name": "tokenAddress", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Airdrops.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      }
    },
    "/api/boosters/{empire_id}": {
      "get": {
        "tags": ["Boosters"],
        "summary": "List boosters for an empire",
        "security": [],
        "parameters": [{ "$ref": "#/components/parameters/EmpireIdPath" }],
        "responses": { "200": { "description": "Boosters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "boosters": { "type": "array", "items": { "type": "object" } } } } } } } }
      },
      "post": {
        "tags": ["Boosters"],
        "summary": "Add a booster",
        "description": "Requires API key plus either signature auth (signature + message + signer, guardian) or transaction auth (txHash from the mint.club create flow).",
        "parameters": [{ "$ref": "#/components/parameters/EmpireIdPath" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } },
        "responses": { "200": { "description": "Added." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }
      },
      "delete": {
        "tags": ["Boosters"],
        "summary": "Remove a booster",
        "parameters": [{ "$ref": "#/components/parameters/EmpireIdPath" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureFields" } } } },
        "responses": { "200": { "description": "Removed." }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      }
    },
    "/api/empires/activate-staking": {
      "get": {
        "tags": ["Staking"],
        "summary": "Staking activation status",
        "security": [],
        "parameters": [{ "name": "tokenAddress", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/EmpireIdParam" } }],
        "responses": { "200": { "description": "Status.", "content": { "application/json": { "schema": { "type": "object" } } } } }
      },
      "post": {
        "tags": ["Staking"],
        "summary": "Activate native staking for an empire",
        "description": "Guardian-signed. Auto-creates a stakers leaderboard.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureFields" } } } },
        "responses": { "200": { "description": "Activated." }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      }
    },
    "/api/staking-boosters/{empire_id}": {
      "get": {
        "tags": ["Staking"],
        "summary": "List staking boosters",
        "security": [],
        "parameters": [{ "$ref": "#/components/parameters/EmpireIdPath" }],
        "responses": { "200": { "description": "Staking boosters.", "content": { "application/json": { "schema": { "type": "object" } } } } }
      },
      "post": {
        "tags": ["Staking"],
        "summary": "Add a staking booster",
        "parameters": [{ "$ref": "#/components/parameters/EmpireIdPath" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } },
        "responses": { "200": { "description": "Added." }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      },
      "delete": {
        "tags": ["Staking"],
        "summary": "Remove a staking booster",
        "parameters": [{ "$ref": "#/components/parameters/EmpireIdPath" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureFields" } } } },
        "responses": { "200": { "description": "Removed." }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      }
    }
  }
}