{
  "operationId": "get-token-metadata",
  "method": "GET",
  "path": "/v2/onchain/token/metadata",
  "summary": "Get token metadata",
  "description": "Fetch metadata for a specific token including price, market data, and basic information. Data is fetched from onchain-indexer with fallback to third-party providers.",
  "tags": [
    "Onchain"
  ],
  "parameters": [
    {
      "name": "network",
      "in": "query",
      "required": true,
      "description": "A blockchain network e.g. \"ethereum\", \"optimism\", \"base\", \"arbitrum\"",
      "schema": {
        "enum": [
          "ethereum",
          "optimism",
          "base",
          "arbitrum"
        ],
        "title": "Network",
        "type": "string"
      }
    },
    {
      "name": "address",
      "in": "query",
      "required": true,
      "description": "Token contract address",
      "schema": {
        "example": "0x5a927ac639636e534b678e81768ca19e2c6280b7",
        "pattern": "^0x[a-fA-F0-9]{40}$",
        "type": "string"
      }
    }
  ],
  "requestBody": null,
  "responses": {
    "200": {
      "description": "Success",
      "schema": {
        "properties": {
          "token": {
            "properties": {
              "address": {
                "description": "Token contract address",
                "example": "0x5a927ac639636e534b678e81768ca19e2c6280b7",
                "pattern": "^0x[a-fA-F0-9]{40}$",
                "type": "string"
              },
              "decimals": {
                "description": "Token decimals",
                "example": 6,
                "type": "integer"
              },
              "description": {
                "description": "Token description",
                "example": "USDC is a fully collateralized US dollar stablecoin",
                "nullable": true,
                "type": "string"
              },
              "fdv": {
                "description": "Fully diluted valuation in USD",
                "example": "25000000000",
                "nullable": true,
                "type": "string"
              },
              "holder_count": {
                "description": "Number of token holders",
                "example": 1500000,
                "nullable": true,
                "type": "integer"
              },
              "image_url": {
                "description": "Token logo URL",
                "example": "https://example.com/token.png",
                "nullable": true,
                "type": "string"
              },
              "liquidity": {
                "description": "Total liquidity in USD",
                "example": "500000000",
                "nullable": true,
                "type": "string"
              },
              "market_cap": {
                "description": "Market capitalization in USD",
                "example": "25000000000",
                "nullable": true,
                "type": "string"
              },
              "name": {
                "description": "Token name",
                "example": "USD Coin",
                "type": "string"
              },
              "network": {
                "$ref": "#/components/schemas/Network"
              },
              "price_change_24h_pct": {
                "description": "24-hour price change percentage",
                "example": -1.2,
                "nullable": true,
                "type": "number"
              },
              "price_change_6h_pct": {
                "description": "6-hour price change percentage",
                "example": 0.5,
                "nullable": true,
                "type": "number"
              },
              "price_source": {
                "description": "Source of price data",
                "enum": [
                  "onchain",
                  "coingecko"
                ],
                "example": "onchain",
                "nullable": true,
                "type": "string"
              },
              "price_updated_at": {
                "description": "Timestamp when price data was last updated (milliseconds)",
                "example": 1707177600000,
                "nullable": true,
                "type": "integer"
              },
              "price_usd": {
                "description": "Token price in USD",
                "example": "1.00",
                "nullable": true,
                "type": "string"
              },
              "symbol": {
                "description": "Token symbol",
                "example": "USDC",
                "type": "string"
              },
              "total_supply": {
                "description": "Total token supply",
                "example": "1000000000000",
                "nullable": true,
                "type": "string"
              },
              "volume_24h": {
                "description": "24-hour trading volume in USD",
                "example": "150000000",
                "nullable": true,
                "type": "string"
              },
              "volume_6h": {
                "description": "6-hour trading volume in USD",
                "example": "50000000",
                "nullable": true,
                "type": "string"
              }
            },
            "required": [
              "network",
              "address",
              "name",
              "symbol",
              "decimals",
              "total_supply",
              "image_url",
              "price_usd",
              "market_cap",
              "fdv",
              "liquidity",
              "volume_6h",
              "volume_24h",
              "price_change_6h_pct",
              "price_change_24h_pct",
              "holder_count",
              "description",
              "price_updated_at",
              "price_source"
            ],
            "type": "object"
          }
        },
        "required": [
          "token"
        ],
        "type": "object"
      },
      "example": null
    },
    "400": {
      "description": "Bad Request",
      "schema": {
        "$ref": "#/components/schemas/ErrorRes"
      },
      "example": null
    },
    "404": {
      "description": "Resource not found",
      "schema": {
        "$ref": "#/components/schemas/ErrorRes"
      },
      "example": null
    },
    "500": {
      "description": "Server Error",
      "schema": {
        "$ref": "#/components/schemas/ErrorRes"
      },
      "example": null
    }
  }
}