{
  "openapi": "3.1.0",
  "info": {
    "title": "GoDegen.fun Public API",
    "version": "1.0.0",
    "summary": "Read market data, user state, referrals, and promo slots for GoDegen.fun.",
    "description": "Public HTTP API for the GoDegen.fun Base memecoin launchpad. Read endpoints are unauthenticated. Creator social updates require an EIP-191 signature from the authorized wallet. Promo bids are on-chain USDC transactions. The backend never holds private keys. WebSocket realtime events are served at /ws with Socket.io; see https://godegen.fun/llms-full.txt for event names and subscription payloads.",
    "contact": {
      "name": "GoDegen.fun",
      "url": "https://godegen.fun",
      "email": "security@godegen.fun"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://github.com/Fernarc/GoDegen/blob/main/LICENSE"
    }
  },
  "externalDocs": {
    "description": "Product documentation",
    "url": "https://godegen.fun/docs"
  },
  "servers": [
    {
      "url": "https://godegen.fun",
      "description": "Production"
    },
    {
      "url": "http://127.0.0.1:8080",
      "description": "Local backend"
    }
  ],
  "tags": [
    {
      "name": "System",
      "description": "Health and runtime configuration."
    },
    {
      "name": "Market",
      "description": "Global stats, bootstrap data, and the trade tape."
    },
    {
      "name": "Tokens",
      "description": "Token discovery, charts, holders, and social metadata."
    },
    {
      "name": "Users",
      "description": "User positions, balances, referrals, and leaderboard."
    },
    {
      "name": "Promo",
      "description": "Promo slot state and on-chain bidding."
    },
    {
      "name": "Assets",
      "description": "Token logo uploads, IPFS metadata, R2 fallback, and partner token lists."
    },
    {
      "name": "Builders",
      "description": "Builder verification through a signed, single-use code placed in a public GitHub README."
    },
    {
      "name": "Creators",
      "description": "Creator verification through a short code placed in an X bio. Checks run at 30 and 60 seconds."
    }
  ],
  "paths": {
    "/api/v1/health": {
      "get": {
        "tags": [
          "System"
        ],
        "operationId": "getHealth",
        "summary": "Service health",
        "responses": {
          "200": {
            "description": "Service is healthy.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "description": "Service is degraded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/ready": {
      "get": {
        "tags": [
          "System"
        ],
        "operationId": "getReady",
        "summary": "Indexer readiness",
        "responses": {
          "200": {
            "description": "Ready to serve.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Ready"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "description": "Not ready.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Ready"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/config": {
      "get": {
        "tags": [
          "System"
        ],
        "operationId": "getConfig",
        "summary": "Public protocol configuration",
        "responses": {
          "200": {
            "description": "Chain, fee, Uxp, decay, and promo configuration.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Config"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/stats": {
      "get": {
        "tags": [
          "Market"
        ],
        "operationId": "getStats",
        "summary": "Global market and reward stats",
        "responses": {
          "200": {
            "description": "Global stats.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Stats"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/bootstrap": {
      "get": {
        "tags": [
          "Market"
        ],
        "operationId": "getBootstrap",
        "summary": "Initial client payload",
        "description": "Tokens, stats, leaderboard, recent trades, config, and server time in one response.",
        "responses": {
          "200": {
            "description": "Bootstrap payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Bootstrap"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/tokens": {
      "get": {
        "tags": [
          "Tokens"
        ],
        "operationId": "listTokens",
        "summary": "List tokens",
        "parameters": [
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "trending",
                "new",
                "gainers",
                "sniper",
                "marketcap"
              ],
              "default": "trending"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "live"
              ],
              "default": "all"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 40
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100000,
              "default": 0
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Name, ticker, slug, or contract address search.",
            "schema": {
              "type": "string",
              "maxLength": 512
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated token list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenPage"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/tokens/{id}": {
      "get": {
        "tags": [
          "Tokens"
        ],
        "operationId": "getToken",
        "summary": "Get a token by address or slug",
        "parameters": [
          {
            "$ref": "#/components/parameters/TokenId"
          }
        ],
        "responses": {
          "200": {
            "description": "Token with top holders.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Token"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/tokens/{id}/trades": {
      "get": {
        "tags": [
          "Tokens"
        ],
        "operationId": "listTokenTrades",
        "summary": "Token trade tape",
        "parameters": [
          {
            "$ref": "#/components/parameters/TokenId"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "before",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "beforeLogIndex",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Trades in reverse chronological order.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Trade"
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/tokens/{id}/candles": {
      "get": {
        "tags": [
          "Tokens"
        ],
        "operationId": "listTokenCandles",
        "summary": "Token candles",
        "parameters": [
          {
            "$ref": "#/components/parameters/TokenId"
          },
          {
            "name": "interval",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "1s",
                "1m",
                "5m",
                "15m",
                "1h",
                "4h",
                "1d"
              ],
              "default": "1m"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 2000,
              "default": 300
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Candles in ascending time order.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Candle"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/api/v1/tokens/{id}/holders": {
      "get": {
        "tags": [
          "Tokens"
        ],
        "operationId": "listTokenHolders",
        "summary": "Token holder ranking",
        "parameters": [
          {
            "$ref": "#/components/parameters/TokenId"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Holder ranking.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Holder"
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/creators/challenge": {
      "post": {
        "tags": [
          "Creators"
        ],
        "operationId": "createCreatorChallenge",
        "summary": "Start creator verification",
        "description": "Requires an EIP-191 signature from the wallet. Accepts a handle, @handle, x.com link, or twitter.com link. Returns a short code to place in the X bio. The signature also authorises the automatic checks, so the wallet is not asked to sign again.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatorChallengeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Challenge with the code and expiry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatorVerification"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/v1/creators/verify": {
      "post": {
        "tags": [
          "Creators"
        ],
        "operationId": "verifyCreatorProfile",
        "summary": "Check the X bio for the code",
        "description": "The frontend calls this at 30 seconds and again at 60 seconds. `proof` is the signature returned with the challenge. A missing code returns 422; an expired code returns 410. Each attempt allows at most two checks.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatorVerifyRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verified creator record.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatorVerification"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "410": {
            "description": "The code expired."
          },
          "422": {
            "description": "The bio does not contain the code yet."
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/v1/creators/reserve": {
      "post": {
        "tags": [
          "Creators"
        ],
        "operationId": "reserveCreatorProfile",
        "summary": "Hold a verified profile for one launch",
        "description": "Reserves the profile for ten minutes so two tabs cannot spend it. Requires the challenge proof.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatorProfileActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reserved profile.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatorProfile"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/api/v1/creators/confirm": {
      "post": {
        "tags": [
          "Creators"
        ],
        "operationId": "confirmCreatorProfile",
        "summary": "Bind the profile to the launched token",
        "description": "Called after the launch transaction confirms. A profile can bind to one token only.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatorConfirmRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bound profile.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatorProfile"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/api/v1/creators/release": {
      "post": {
        "tags": [
          "Creators"
        ],
        "operationId": "releaseCreatorProfile",
        "summary": "Free a launch reservation",
        "description": "Called when a launch fails or is cancelled, so the profile can be used again.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatorProfileActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reservation released."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/creators/{address}": {
      "get": {
        "tags": [
          "Creators"
        ],
        "operationId": "getCreatorStatus",
        "summary": "Creator verification status",
        "description": "Returns the verified X handle, any open challenge, the checks used today, and whether X verification is configured.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Address"
          }
        ],
        "responses": {
          "200": {
            "description": "Creator verification status for the wallet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatorStatus"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/api/v1/builders/challenge": {
      "post": {
        "tags": [
          "Builders"
        ],
        "operationId": "createBuilderChallenge",
        "summary": "Create a builder verification code",
        "description": "Requires an EIP-191 signature from the wallet. Returns a short single-use code that expires after 30 minutes. The builder pastes the code into a public GitHub README on the default branch, then calls `/builders/verify`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BuilderChallengeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification challenge with the code and expiry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BuilderVerification"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/builders/verify": {
      "post": {
        "tags": [
          "Builders"
        ],
        "operationId": "verifyBuilderRepository",
        "summary": "Verify the repository README",
        "description": "Requires a second EIP-191 signature from the same wallet. The backend fetches the README from the repository's default branch and looks for the code. The repository must be public, and the code can be removed from the README after verification.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BuilderVerifyRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verified builder record.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BuilderVerification"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "410": {
            "description": "The code expired."
          },
          "422": {
            "description": "The README does not contain the code yet."
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/builders/reserve": {
      "post": {
        "tags": [
          "Builders"
        ],
        "operationId": "reserveBuilderProfile",
        "summary": "Hold a verified repository for one launch",
        "description": "Reserves the repository for ten minutes so two tabs cannot spend it. Requires the challenge proof.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BuilderProfileActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reserved repository.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BuilderProfile"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/api/v1/builders/confirm": {
      "post": {
        "tags": [
          "Builders"
        ],
        "operationId": "confirmBuilderProfile",
        "summary": "Bind the repository to the launched token",
        "description": "A repository can bind to one token only.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BuilderConfirmRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bound repository.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BuilderProfile"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/api/v1/builders/release": {
      "post": {
        "tags": [
          "Builders"
        ],
        "operationId": "releaseBuilderProfile",
        "summary": "Free a launch reservation",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BuilderProfileActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reservation released."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/builders/{address}": {
      "get": {
        "tags": [
          "Builders"
        ],
        "operationId": "getBuilderStatus",
        "summary": "Builder verification status",
        "description": "Returns whether the wallet is a verified builder and any pending challenge.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Address"
          }
        ],
        "responses": {
          "200": {
            "description": "Verification status for the wallet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BuilderStatus"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/api/v1/tokens/{id}/socials": {
      "post": {
        "tags": [
          "Tokens"
        ],
        "operationId": "updateTokenSocials",
        "summary": "Update creator social links",
        "description": "Requires an EIP-191 signature from the token creator. Missing links can be added at any time. Existing links can be changed once every 30 days.",
        "parameters": [
          {
            "$ref": "#/components/parameters/TokenId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SocialUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Token"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/trades": {
      "get": {
        "tags": [
          "Market"
        ],
        "operationId": "listRecentTrades",
        "summary": "Recent global trades",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recent trades.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Trade"
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/users/{address}": {
      "get": {
        "tags": [
          "Users"
        ],
        "operationId": "getUser",
        "summary": "Get user state",
        "parameters": [
          {
            "$ref": "#/components/parameters/Address"
          }
        ],
        "responses": {
          "200": {
            "description": "Balances, positions, referral summary, and activity.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/api/v1/users/{address}/trades": {
      "get": {
        "tags": [
          "Users"
        ],
        "operationId": "listUserTrades",
        "summary": "Recent user trades",
        "parameters": [
          {
            "$ref": "#/components/parameters/Address"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Trades by the user.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Trade"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/api/v1/users/{address}/referrals": {
      "get": {
        "tags": [
          "Users"
        ],
        "operationId": "listReferrals",
        "summary": "Referred wallets with all-time volume",
        "description": "Returns every wallet bound to the referrer, newest first. Volume is the referred wallet lifetime total, not a recent trade window.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Address"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Rows to return. Defaults to 100, maximum 500.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Rows to skip. Defaults to 0.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Referral rows.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Referral"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/api/v1/referrals/validate/{value}": {
      "get": {
        "tags": [
          "Users"
        ],
        "operationId": "validateReferral",
        "summary": "Validate a referral code or registered referrer address",
        "description": "Returns the resolved referrer only when the code exists or the address already has a referral code. The app calls this before sending a binding transaction.",
        "parameters": [
          {
            "name": "value",
            "in": "path",
            "required": true,
            "description": "Eight-character referral code or 0x referrer address.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Valid referral.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferralValidation"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/referrals/{address}": {
      "get": {
        "tags": [
          "Users"
        ],
        "operationId": "listReferralsByAddress",
        "summary": "Referred wallets with all-time volume",
        "description": "Alias of /api/v1/users/{address}/referrals.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Address"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Rows to return. Defaults to 100, maximum 500.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Rows to skip. Defaults to 0.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Referral rows.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Referral"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/api/v1/referrals/code/{address}": {
      "get": {
        "tags": [
          "Users"
        ],
        "operationId": "getReferralCode",
        "summary": "Get a wallet's referral code",
        "parameters": [
          {
            "$ref": "#/components/parameters/Address"
          }
        ],
        "responses": {
          "200": {
            "description": "Stable referral code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferralCode"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/api/v1/referrals/resolve/{code}": {
      "get": {
        "tags": [
          "Users"
        ],
        "operationId": "resolveReferralCode",
        "summary": "Resolve a referral code",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 64
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Resolved code and address.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferralCode"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/leaderboard": {
      "get": {
        "tags": [
          "Users"
        ],
        "operationId": "getLeaderboard",
        "summary": "Staker leaderboard",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Leaderboard rows.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/LeaderboardEntry"
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/promo": {
      "get": {
        "tags": [
          "Promo"
        ],
        "operationId": "getPromoState",
        "summary": "Current promo state",
        "responses": {
          "200": {
            "description": "Five UTC promo slots, the current phase, and optional wallet contributions.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PromoState"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        },
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "description": "Optional wallet address used to return per-slot contribution totals.",
            "schema": {
              "type": "string",
              "pattern": "^0x[a-fA-F0-9]{40}$"
            }
          }
        ]
      }
    },
    "/api/v1/token-assets": {
      "post": {
        "tags": [
          "Assets"
        ],
        "operationId": "uploadTokenAsset",
        "summary": "Upload a token logo and create immutable metadata",
        "description": "Multipart upload. The backend validates PNG, JPEG, or WebP magic bytes, rejects other attachments including ZIP and SVG, enforces a 1.1 MB hard limit, normalizes the image to a 512px PNG, uploads it to R2 and Lighthouse IPFS, and returns the metadata URI for the factory.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "logo",
                  "wallet",
                  "timestamp",
                  "nonce",
                  "signature",
                  "name",
                  "ticker"
                ],
                "properties": {
                  "logo": {
                    "type": "string",
                    "format": "binary"
                  },
                  "wallet": {
                    "type": "string",
                    "pattern": "^0x[a-fA-F0-9]{40}$"
                  },
                  "timestamp": {
                    "type": "integer",
                    "format": "int64"
                  },
                  "nonce": {
                    "type": "string",
                    "minLength": 8,
                    "maxLength": 64
                  },
                  "signature": {
                    "type": "string",
                    "pattern": "^0x[a-fA-F0-9]{130}$"
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 32
                  },
                  "ticker": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9]{2,10}$"
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "socials": {
                    "type": "string",
                    "description": "JSON object with optional x, telegram, and website strings."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Logo and metadata stored.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenAssetUpload"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "description": "The logo exceeds the 1.1 MB upload limit."
          },
          "415": {
            "description": "Unsupported file type."
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/v1/token-assets/confirm": {
      "post": {
        "tags": [
          "Assets"
        ],
        "operationId": "confirmTokenAsset",
        "summary": "Bind an uploaded logo to a launched token",
        "description": "Confirms that the upload belongs to the indexed token metadata URI and creator wallet. If the indexer has not caught up yet, the backend keeps the upload in confirming state and reconciles it automatically.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TokenAssetConfirmRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Confirmation accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenAssetConfirm"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/token-list": {
      "get": {
        "tags": [
          "Assets"
        ],
        "operationId": "getTokenList",
        "summary": "Public Uniswap token list",
        "description": "Confirmed GoDegen tokens with R2 primary logos, IPFS fallback URLs, metadata URIs, and launchpad extensions. Also available through the frontend at /tokenlist.json.",
        "responses": {
          "200": {
            "description": "Current token list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenList"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/admin/token-assets": {
      "get": {
        "tags": [
          "Assets"
        ],
        "operationId": "exportTokenAssets",
        "summary": "Partner asset export",
        "description": "Full confirmed asset registry for partnerships and bulk handoffs. Requires the server-side asset admin bearer token.",
        "security": [
          {
            "AdminBearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Full asset export.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminTokenAssets"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "TokenId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "Token contract address or slug.",
        "schema": {
          "type": "string"
        }
      },
      "Address": {
        "name": "address",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^0x[a-fA-F0-9]{40}$"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The signature or authorization is invalid.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "The requested resource was not found.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Conflict": {
        "description": "The request conflicts with current state.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "The service is not configured or temporarily unavailable.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Rate limit exceeded.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "retryAt": {
                "type": "integer",
                "format": "int64"
              }
            }
          }
        }
      },
      "Health": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "degraded"
            ]
          },
          "redis": {
            "type": "boolean"
          },
          "database": {
            "type": "object",
            "additionalProperties": true
          },
          "indexer": {
            "type": "object",
            "additionalProperties": true
          },
          "uptime": {
            "type": "number"
          }
        }
      },
      "Ready": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "ready": {
            "type": "boolean"
          },
          "indexer": {
            "type": "object",
            "additionalProperties": true
          },
          "cluster": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "Config": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "chainId",
          "totalSupply",
          "tradeFeeBps",
          "feeSplit"
        ],
        "properties": {
          "chainId": {
            "type": "integer"
          },
          "totalSupply": {
            "type": "integer"
          },
          "initialMcOptions": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "tradeFeeBps": {
            "type": "integer",
            "description": "130 = 1.30%."
          },
          "feeSplit": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "platform": {
                "type": "integer"
              },
              "creator": {
                "type": "integer"
              },
              "referrer": {
                "type": "integer"
              },
              "stakersWithReferrer": {
                "type": "integer"
              },
              "stakersWithoutReferrer": {
                "type": "integer"
              }
            }
          },
          "uxpZones": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "quickFlipSeconds": {
            "type": "integer"
          },
          "rektMinHoldSeconds": {
            "type": "integer"
          },
          "decayActiveBps": {
            "type": "integer"
          },
          "decayInactiveBps": {
            "type": "integer"
          },
          "minDecayTradeUsd": {
            "type": "number"
          },
          "promoSlotsAddress": {
            "type": [
              "string",
              "null"
            ],
            "description": "Deployed GoDegenPromoSlots address."
          }
        }
      },
      "Socials": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "x": {
            "type": "string"
          },
          "telegram": {
            "type": "string"
          },
          "website": {
            "type": "string"
          }
        }
      },
      "Holder": {
        "type": "object",
        "required": [
          "address",
          "balance",
          "share"
        ],
        "properties": {
          "address": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "balance": {
            "type": "number"
          },
          "share": {
            "type": "number"
          },
          "uxp": {
            "type": "number"
          },
          "isCreator": {
            "type": "boolean"
          },
          "isYou": {
            "type": "boolean"
          }
        }
      },
      "Token": {
        "type": "object",
        "required": [
          "slug",
          "address",
          "curve",
          "name",
          "ticker",
          "creator",
          "createdAt",
          "mc",
          "price"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "address": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$"
          },
          "curve": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$"
          },
          "name": {
            "type": "string"
          },
          "ticker": {
            "type": "string"
          },
          "emoji": {
            "type": "string"
          },
          "avatarUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "gradient": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "creator": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$"
          },
          "createdAt": {
            "type": "integer",
            "format": "int64"
          },
          "initialMc": {
            "type": "number"
          },
          "mc": {
            "type": "number"
          },
          "price": {
            "type": "number"
          },
          "progress": {
            "type": "number"
          },
          "rate": {
            "type": "number",
            "enum": [
              1,
              0.5,
              0.25
            ]
          },
          "volume24h": {
            "type": "number"
          },
          "volume24hUsd": {
            "type": "number"
          },
          "holders": {
            "type": "integer"
          },
          "change24h": {
            "type": "number"
          },
          "sparkline": {
            "type": "array",
            "items": {
              "type": "number"
            }
          },
          "socials": {
            "$ref": "#/components/schemas/Socials"
          },
          "totalSupply": {
            "type": "number"
          },
          "lastTradeAt": {
            "type": "integer",
            "format": "int64"
          },
          "holdersList": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Holder"
            }
          },
          "isNew": {
            "type": "boolean"
          },
          "metadataURI": {
            "type": "string"
          },
          "poolId": {
            "type": [
              "string",
              "null"
            ]
          },
          "volumeEth": {
            "type": "number"
          },
          "volumeUsd": {
            "type": "number"
          },
          "trades": {
            "type": "integer"
          },
          "trades24h": {
            "type": "integer"
          },
          "uxpMinted": {
            "type": "number"
          },
          "initialEthReserve": {
            "type": "number"
          },
          "priceEth": {
            "type": "number"
          },
          "avatarFallbackUrl": {
            "type": "string"
          }
        }
      },
      "TokenPage": {
        "type": "object",
        "required": [
          "data",
          "nextCursor"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Token"
            }
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ]
          },
          "total": {
            "type": "integer"
          }
        }
      },
      "Trade": {
        "type": "object",
        "required": [
          "id",
          "slug",
          "side",
          "trader",
          "ethAmount",
          "tokenAmount",
          "timestamp",
          "txHash"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "side": {
            "type": "string",
            "enum": [
              "buy",
              "sell"
            ]
          },
          "trader": {
            "type": "string"
          },
          "ethAmount": {
            "type": "number"
          },
          "tokenAmount": {
            "type": "number"
          },
          "price": {
            "type": "number"
          },
          "uxp": {
            "type": "number"
          },
          "timestamp": {
            "type": "integer",
            "format": "int64"
          },
          "txHash": {
            "type": "string"
          },
          "logIndex": {
            "type": "integer"
          },
          "blockNumber": {
            "type": "integer"
          },
          "referrer": {
            "type": [
              "string",
              "null"
            ]
          },
          "preconfirmed": {
            "type": "boolean"
          }
        }
      },
      "Candle": {
        "type": "object",
        "required": [
          "time",
          "interval",
          "open",
          "high",
          "low",
          "close",
          "volume"
        ],
        "properties": {
          "time": {
            "type": "integer",
            "format": "int64"
          },
          "interval": {
            "type": "string",
            "enum": [
              "1s",
              "1m",
              "5m",
              "15m",
              "1h",
              "4h",
              "1d"
            ]
          },
          "open": {
            "type": "number"
          },
          "high": {
            "type": "number"
          },
          "low": {
            "type": "number"
          },
          "close": {
            "type": "number"
          },
          "volume": {
            "type": "number"
          },
          "volumeUsd": {
            "type": "number"
          },
          "trades": {
            "type": "integer"
          }
        }
      },
      "Stats": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "ethUsd",
          "totalVolume",
          "totalTrades",
          "totalFees"
        ],
        "properties": {
          "ethUsd": {
            "type": "number"
          },
          "ethDistributedToday": {
            "type": "number"
          },
          "stakerFees24h": {
            "type": "number"
          },
          "participantFees24h": {
            "type": "number"
          },
          "totalStakedUxp": {
            "type": "number"
          },
          "stakers": {
            "type": "integer"
          },
          "totalUxpSupply": {
            "type": "number"
          },
          "totalVolume24h": {
            "type": "number"
          },
          "totalTrades24h": {
            "type": "integer"
          },
          "totalVolume": {
            "type": "number"
          },
          "totalFees": {
            "type": "number"
          },
          "totalTrades": {
            "type": "integer"
          },
          "totalTokens": {
            "type": "integer"
          },
          "totalTraders": {
            "type": "integer"
          },
          "platformFees": {
            "type": "number"
          },
          "creatorFees": {
            "type": "number"
          },
          "referrerFees": {
            "type": "number"
          },
          "stakerFees": {
            "type": "number"
          },
          "updatedAt": {
            "type": "integer",
            "format": "int64"
          },
          "stakers24h": {
            "type": "integer",
            "description": "Distinct wallets that staked Uxp in the last 24 hours."
          }
        }
      },
      "Position": {
        "type": "object",
        "required": [
          "token",
          "slug",
          "ticker",
          "name",
          "balance",
          "valueUsd"
        ],
        "properties": {
          "token": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "ticker": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "balance": {
            "type": "number"
          },
          "avgEntryPrice": {
            "type": "number"
          },
          "lastBuyAt": {
            "type": "integer",
            "format": "int64"
          },
          "valueUsd": {
            "type": "number"
          }
        }
      },
      "User": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "address",
          "stakedUxp",
          "pendingUxp",
          "uxpBalance",
          "claimableEth"
        ],
        "properties": {
          "address": {
            "type": "string"
          },
          "stakedUxp": {
            "type": "number"
          },
          "pendingUxp": {
            "type": "number"
          },
          "uxpBalance": {
            "type": "number"
          },
          "claimableEth": {
            "type": "number"
          },
          "lastActiveTradeTime": {
            "type": "integer",
            "format": "int64"
          },
          "decayStartedAt": {
            "type": "integer",
            "format": "int64"
          },
          "lastDecayAt": {
            "type": "integer",
            "format": "int64"
          },
          "todayActive": {
            "type": "boolean"
          },
          "todayBurnBps": {
            "type": "integer"
          },
          "nextBurnAt": {
            "type": "integer",
            "format": "int64"
          },
          "holdings": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            }
          },
          "lastBuyAt": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "avgEntryPrice": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            }
          },
          "referredBy": {
            "type": [
              "string",
              "null"
            ]
          },
          "referredByCode": {
            "type": [
              "string",
              "null"
            ]
          },
          "referralCode": {
            "type": "string"
          },
          "referrals": {
            "type": "integer"
          },
          "referralEarningsEth": {
            "type": "number",
            "description": "Lifetime referral ETH earned from referred wallets."
          },
          "referralEarningsUxp": {
            "type": "number",
            "description": "Lifetime referral Uxp earned from referred wallets."
          },
          "claimedTotal": {
            "type": "number"
          },
          "positions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Position"
            }
          },
          "createdTokens": {
            "type": "integer"
          },
          "creatorEarningsEth": {
            "type": "number",
            "description": "Lifetime creator ETH earned from trades on tokens launched by this wallet."
          },
          "stakerEarningsEth": {
            "type": "number",
            "description": "Lifetime staking ETH checkpointed for this wallet."
          },
          "claimableCreatorEth": {
            "type": "number",
            "description": "Creator ETH currently claimable."
          },
          "claimableReferrerEth": {
            "type": "number",
            "description": "Referral ETH currently claimable."
          },
          "claimableStakerEth": {
            "type": "number",
            "description": "Staking ETH currently claimable, including checkpointed and pending staker rewards."
          }
        }
      },
      "LeaderboardEntry": {
        "type": "object",
        "required": [
          "address",
          "stakedUxp",
          "share",
          "rewards24h"
        ],
        "properties": {
          "address": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "stakedUxp": {
            "type": "number"
          },
          "share": {
            "type": "number"
          },
          "rewards24h": {
            "type": "number"
          },
          "isYou": {
            "type": "boolean"
          }
        }
      },
      "Referral": {
        "type": "object",
        "description": "A wallet that bound to the referrer through a referral code.",
        "required": [
          "address",
          "joinedAt",
          "volumeEth",
          "volumeUsd"
        ],
        "properties": {
          "address": {
            "type": "string",
            "description": "Referred wallet address."
          },
          "joinedAt": {
            "type": "integer",
            "format": "int64",
            "description": "Unix timestamp in milliseconds when the wallet bound."
          },
          "volumeEth": {
            "type": "number",
            "description": "All-time traded volume for the referred wallet in ETH."
          },
          "volumeUsd": {
            "type": "number",
            "description": "All-time traded volume for the referred wallet in USD."
          }
        }
      },
      "ReferralCode": {
        "type": "object",
        "required": [
          "address",
          "code"
        ],
        "properties": {
          "address": {
            "type": "string"
          },
          "code": {
            "type": "string"
          }
        }
      },
      "ReferralValidation": {
        "type": "object",
        "required": [
          "valid",
          "address",
          "code"
        ],
        "properties": {
          "valid": {
            "type": "boolean",
            "description": "Always true on a 200 response."
          },
          "address": {
            "type": "string",
            "description": "Checksummed referrer address."
          },
          "code": {
            "type": "string",
            "description": "Canonical referral code for the address."
          }
        }
      },
      "PromoState": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "enabled",
          "ready",
          "promoAddress",
          "usdcAddress",
          "factoryAddress",
          "now",
          "phase",
          "dayId",
          "auctionStart",
          "auctionEnd",
          "displayEnd",
          "schedule",
          "slots",
          "activeCount"
        ],
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "ready": {
            "type": "boolean"
          },
          "promoAddress": {
            "type": [
              "string",
              "null"
            ]
          },
          "usdcAddress": {
            "type": [
              "string",
              "null"
            ]
          },
          "factoryAddress": {
            "type": [
              "string",
              "null"
            ]
          },
          "now": {
            "type": "integer",
            "format": "int64"
          },
          "phase": {
            "type": "string",
            "enum": [
              "bidding",
              "display"
            ],
            "description": "Bidding is 00:00-12:00 UTC; display is 12:00-24:00 UTC."
          },
          "dayId": {
            "type": "integer",
            "description": "UTC day index (floor(unixSeconds / 86400))."
          },
          "auctionStart": {
            "type": "integer",
            "format": "int64"
          },
          "auctionEnd": {
            "type": "integer",
            "format": "int64"
          },
          "displayEnd": {
            "type": "integer",
            "format": "int64"
          },
          "schedule": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "slots",
              "minBidUsd",
              "minIncrementUsd",
              "bidSeconds",
              "displaySeconds",
              "cycleSeconds"
            ],
            "properties": {
              "slots": {
                "type": "integer"
              },
              "minBidUsd": {
                "type": "number"
              },
              "minIncrementUsd": {
                "type": "number"
              },
              "bidSeconds": {
                "type": "integer"
              },
              "displaySeconds": {
                "type": "integer"
              },
              "cycleSeconds": {
                "type": "integer"
              }
            }
          },
          "slots": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PromoSlot"
            }
          },
          "activeCount": {
            "type": "integer"
          }
        }
      },
      "Bootstrap": {
        "type": "object",
        "required": [
          "tokens",
          "stats",
          "leaderboard",
          "recentTrades",
          "config",
          "serverTime"
        ],
        "properties": {
          "tokens": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Token"
            }
          },
          "stats": {
            "$ref": "#/components/schemas/Stats"
          },
          "leaderboard": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LeaderboardEntry"
            }
          },
          "recentTrades": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Trade"
            }
          },
          "config": {
            "$ref": "#/components/schemas/Config"
          },
          "serverTime": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "SocialUpdateRequest": {
        "type": "object",
        "required": [
          "socials",
          "timestamp",
          "nonce",
          "signature"
        ],
        "properties": {
          "socials": {
            "$ref": "#/components/schemas/Socials"
          },
          "timestamp": {
            "type": "integer",
            "format": "int64"
          },
          "nonce": {
            "type": "string",
            "minLength": 8,
            "maxLength": 64
          },
          "signature": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{130}$"
          }
        }
      },
      "BuilderChallengeRequest": {
        "type": "object",
        "required": [
          "address",
          "repo",
          "timestamp",
          "nonce",
          "signature"
        ],
        "properties": {
          "address": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$"
          },
          "repo": {
            "type": "string",
            "maxLength": 140,
            "description": "GitHub repository as owner/repo or a github.com URL."
          },
          "timestamp": {
            "type": "integer",
            "format": "int64"
          },
          "nonce": {
            "type": "string",
            "minLength": 8,
            "maxLength": 64
          },
          "signature": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{130}$"
          }
        }
      },
      "BuilderVerifyRequest": {
        "type": "object",
        "required": [
          "address",
          "id",
          "proof"
        ],
        "properties": {
          "address": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$"
          },
          "id": {
            "type": "string",
            "description": "Verification id returned by the challenge endpoint."
          },
          "proof": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{130}$",
            "description": "The signature from the challenge call."
          }
        }
      },
      "BuilderProfile": {
        "type": "object",
        "required": [
          "id",
          "repo",
          "verifiedAt",
          "tokenAddress",
          "boundAt",
          "reservedUntil"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "repo": {
            "type": "string"
          },
          "verifiedAt": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          },
          "tokenAddress": {
            "type": "string",
            "nullable": true
          },
          "boundAt": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          },
          "reservedUntil": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          }
        }
      },
      "BuilderProfileActionRequest": {
        "type": "object",
        "required": [
          "address",
          "id",
          "proof"
        ],
        "properties": {
          "address": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$"
          },
          "id": {
            "type": "string"
          },
          "proof": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{130}$"
          }
        }
      },
      "BuilderConfirmRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/BuilderProfileActionRequest"
          },
          {
            "type": "object",
            "required": [
              "tokenAddress"
            ],
            "properties": {
              "tokenAddress": {
                "type": "string",
                "pattern": "^0x[a-fA-F0-9]{40}$"
              }
            }
          }
        ]
      },
      "BuilderVerification": {
        "type": "object",
        "required": [
          "id",
          "address",
          "repo",
          "code",
          "status",
          "createdAt",
          "expiresAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "repo": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "example": "GDX-7K2M9-Q4V3N"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "verified",
              "expired",
              "revoked"
            ]
          },
          "createdAt": {
            "type": "integer",
            "format": "int64"
          },
          "expiresAt": {
            "type": "integer",
            "format": "int64"
          },
          "verifiedAt": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          }
        }
      },
      "BuilderStatus": {
        "type": "object",
        "required": [
          "profiles",
          "challenge",
          "attemptsToday",
          "dailyLimit"
        ],
        "properties": {
          "profiles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BuilderProfile"
            }
          },
          "challenge": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BuilderVerification"
              }
            ],
            "nullable": true
          },
          "attemptsToday": {
            "type": "integer"
          },
          "dailyLimit": {
            "type": "integer"
          }
        }
      },
      "CreatorChallengeRequest": {
        "type": "object",
        "required": [
          "address",
          "handle",
          "timestamp",
          "nonce",
          "signature"
        ],
        "properties": {
          "address": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$"
          },
          "handle": {
            "type": "string",
            "maxLength": 300,
            "description": "Handle, @handle, x.com link, or twitter.com link."
          },
          "timestamp": {
            "type": "integer",
            "format": "int64"
          },
          "nonce": {
            "type": "string",
            "minLength": 8,
            "maxLength": 64
          },
          "signature": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{130}$"
          }
        }
      },
      "CreatorVerifyRequest": {
        "type": "object",
        "required": [
          "address",
          "id",
          "proof"
        ],
        "properties": {
          "address": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$"
          },
          "id": {
            "type": "string",
            "description": "Verification id returned by the challenge endpoint."
          },
          "proof": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{130}$",
            "description": "The signature from the challenge call."
          }
        }
      },
      "CreatorVerification": {
        "type": "object",
        "required": [
          "id",
          "address",
          "platform",
          "handle",
          "externalId",
          "code",
          "status",
          "createdAt",
          "expiresAt",
          "checks"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "platform": {
            "type": "string",
            "enum": [
              "x"
            ]
          },
          "handle": {
            "type": "string"
          },
          "externalId": {
            "type": "string",
            "description": "Stable X numeric id, used so a username change cannot break the proof."
          },
          "code": {
            "type": "string",
            "example": "GDX-7K2M9Q4V"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "verified",
              "expired",
              "revoked"
            ]
          },
          "createdAt": {
            "type": "integer",
            "format": "int64"
          },
          "expiresAt": {
            "type": "integer",
            "format": "int64"
          },
          "verifiedAt": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          },
          "checks": {
            "type": "integer"
          }
        }
      },
      "CreatorProfileActionRequest": {
        "type": "object",
        "required": [
          "address",
          "id",
          "proof"
        ],
        "properties": {
          "address": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$"
          },
          "id": {
            "type": "string"
          },
          "proof": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{130}$"
          }
        }
      },
      "CreatorConfirmRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CreatorProfileActionRequest"
          },
          {
            "type": "object",
            "required": [
              "tokenAddress"
            ],
            "properties": {
              "tokenAddress": {
                "type": "string",
                "pattern": "^0x[a-fA-F0-9]{40}$"
              }
            }
          }
        ]
      },
      "CreatorProfile": {
        "type": "object",
        "required": [
          "id",
          "handle",
          "externalId",
          "verifiedAt",
          "tokenAddress",
          "boundAt",
          "reservedUntil"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "handle": {
            "type": "string"
          },
          "externalId": {
            "type": "string"
          },
          "verifiedAt": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          },
          "tokenAddress": {
            "type": "string",
            "nullable": true,
            "description": "Set once the profile launches its coin."
          },
          "boundAt": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          },
          "reservedUntil": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          }
        }
      },
      "CreatorStatus": {
        "type": "object",
        "required": [
          "profiles",
          "challenge",
          "attemptsToday",
          "dailyLimit",
          "configured"
        ],
        "properties": {
          "profiles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CreatorProfile"
            }
          },
          "challenge": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CreatorVerification"
              }
            ],
            "nullable": true
          },
          "attemptsToday": {
            "type": "integer"
          },
          "dailyLimit": {
            "type": "integer"
          },
          "configured": {
            "type": "boolean"
          }
        }
      },
      "TokenAssetUpload": {
        "type": "object",
        "required": [
          "uploadId",
          "chainId",
          "metadataUri",
          "logoFallbackUrl",
          "logoCid",
          "logoSha256",
          "expiresAt",
          "logoCanonicalUrl",
          "logoCdnUrl"
        ],
        "properties": {
          "uploadId": {
            "type": "string"
          },
          "chainId": {
            "type": "integer"
          },
          "metadataUri": {
            "type": "string"
          },
          "metadataCid": {
            "type": [
              "string",
              "null"
            ]
          },
          "logoFallbackUrl": {
            "type": "string"
          },
          "logoCid": {
            "type": "string"
          },
          "logoSha256": {
            "type": "string"
          },
          "expiresAt": {
            "type": "integer",
            "format": "int64"
          },
          "logoCanonicalUrl": {
            "type": "string"
          },
          "logoCdnUrl": {
            "type": "string"
          }
        }
      },
      "TokenAsset": {
        "type": "object",
        "required": [
          "chainId",
          "tokenAddress",
          "creator",
          "name",
          "ticker",
          "decimals",
          "logoFallbackUrl",
          "logoCid",
          "logoSha256",
          "r2Key",
          "txHash",
          "createdAt",
          "updatedAt",
          "logoCanonicalUrl",
          "logoCdnUrl"
        ],
        "properties": {
          "chainId": {
            "type": "integer"
          },
          "tokenAddress": {
            "type": "string"
          },
          "creator": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "ticker": {
            "type": "string"
          },
          "decimals": {
            "type": "integer"
          },
          "description": {
            "type": "string"
          },
          "logoFallbackUrl": {
            "type": "string"
          },
          "logoCid": {
            "type": "string"
          },
          "logoSha256": {
            "type": "string"
          },
          "metadataCid": {
            "type": [
              "string",
              "null"
            ]
          },
          "metadataUri": {
            "type": [
              "string",
              "null"
            ]
          },
          "r2Key": {
            "type": "string"
          },
          "txHash": {
            "type": "string"
          },
          "createdAt": {
            "type": "integer",
            "format": "int64"
          },
          "updatedAt": {
            "type": "integer",
            "format": "int64"
          },
          "logoCanonicalUrl": {
            "type": "string"
          },
          "logoCdnUrl": {
            "type": "string"
          }
        }
      },
      "TokenAssetConfirmRequest": {
        "type": "object",
        "required": [
          "uploadId",
          "wallet",
          "tokenAddress",
          "txHash"
        ],
        "properties": {
          "uploadId": {
            "type": "string"
          },
          "wallet": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$"
          },
          "tokenAddress": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$"
          },
          "txHash": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{64}$"
          }
        }
      },
      "TokenAssetConfirm": {
        "type": "object",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "confirmed",
              "confirming"
            ]
          },
          "asset": {
            "$ref": "#/components/schemas/TokenAsset"
          }
        }
      },
      "TokenListEntry": {
        "type": "object",
        "required": [
          "chainId",
          "address",
          "name",
          "symbol",
          "decimals",
          "logoURI",
          "extensions"
        ],
        "properties": {
          "chainId": {
            "type": "integer"
          },
          "address": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "symbol": {
            "type": "string"
          },
          "decimals": {
            "type": "integer"
          },
          "logoURI": {
            "type": "string"
          },
          "extensions": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "TokenList": {
        "type": "object",
        "required": [
          "name",
          "timestamp",
          "version",
          "tokens"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "version": {
            "type": "object",
            "required": [
              "major",
              "minor",
              "patch"
            ],
            "properties": {
              "major": {
                "type": "integer"
              },
              "minor": {
                "type": "integer"
              },
              "patch": {
                "type": "integer"
              }
            }
          },
          "logoURI": {
            "type": "string"
          },
          "keywords": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "tokens": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TokenListEntry"
            }
          }
        }
      },
      "AdminTokenAssets": {
        "type": "object",
        "required": [
          "generatedAt",
          "count",
          "assets"
        ],
        "properties": {
          "generatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "count": {
            "type": "integer"
          },
          "assets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TokenAsset"
            }
          }
        }
      },
      "PromoSlot": {
        "type": "object",
        "required": [
          "slot",
          "bidder",
          "tokenAddress",
          "token",
          "amountUsd",
          "contributionUsd",
          "extraCostUsd",
          "minimumBidUsd",
          "priorityPct",
          "active",
          "leading"
        ],
        "properties": {
          "slot": {
            "type": "integer",
            "minimum": 0,
            "maximum": 4
          },
          "bidder": {
            "type": [
              "string",
              "null"
            ]
          },
          "tokenAddress": {
            "type": [
              "string",
              "null"
            ]
          },
          "token": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Token"
              },
              {
                "type": "null"
              }
            ]
          },
          "amountUsd": {
            "type": "number"
          },
          "contributionUsd": {
            "type": "number",
            "description": "The wallet's previous total bid for this UTC day and slot."
          },
          "extraCostUsd": {
            "type": "number",
            "description": "The extra amount the wallet pays to reach the current minimum total."
          },
          "minimumBidUsd": {
            "type": "number"
          },
          "priorityPct": {
            "type": "number",
            "description": "Relative live tape exposure for this slot."
          },
          "active": {
            "type": "boolean",
            "description": "True whenever the current bid is on the tape: during bidding for the current leader, and during the live window for the final winner."
          },
          "leading": {
            "type": "boolean",
            "description": "True during the 00:00-12:00 UTC bidding phase when the current leader is on the tape."
          }
        }
      }
    },
    "securitySchemes": {
      "AdminBearer": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "security": []
}
