zkbcy7ja.nx.link

{
  "parameters": [
    {
      "description": "The blockchain network identifier. Common values include: 1 (Ethereum), 8453 (Base), 137 (Polygon), 56 (BSC), 43114 (Avalanche), 42161 (Arbitrum), 10 (Optimism).",
      "in": "path",
      "name": "chainId",
      "required": true,
      "schema": {
        "description": "The blockchain network identifier. Common values include: 1 (Ethereum), 8453 (Base), 137 (Polygon), 56 (BSC), 43114 (Avalanche), 42161 (Arbitrum), 10 (Optimism).",
        "examples": [
          1,
          8453,
          137,
          56,
          43114,
          42161,
          10
        ],
        "exclusiveMinimum": 0,
        "type": "integer"
      }
    },
    {
      "description": "A valid Ethereum address (0x-prefixed hex string) or ENS name (e.g., vitalik.eth).",
      "in": "path",
      "name": "address",
      "required": true,
      "schema": {
        "description": "A valid Ethereum address (0x-prefixed hex string) or ENS name (e.g., vitalik.eth).",
        "type": "string"
      }
    },
    {
      "description": "Optional token ID for NFT owners. If provided, returns owners of the specific NFT token.",
      "in": "query",
      "name": "tokenId",
      "required": false,
      "schema": {
        "description": "Optional token ID for NFT owners. If provided, returns owners of the specific NFT token.",
        "type": [
          "string",
          "null"
        ]
      }
    },
    {
      "description": "Number of owners to return per page (1-100).",
      "in": "query",
      "name": "limit",
      "required": false,
      "schema": {
        "default": 20,
        "description": "Number of owners to return per page (1-100).",
        "maximum": 100,
        "minimum": 1,
        "type": "integer"
      }
    },
    {
      "description": "Page number for pagination, starting from 1.",
      "in": "query",
      "name": "page",
      "required": false,
      "schema": {
        "default": 1,
        "description": "Page number for pagination, starting from 1.",
        "minimum": 1,
        "type": "integer"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "properties": {
              "result": {
                "properties": {
                  "owners": {
                    "description": "Array of token owners with amounts.",
                    "items": {
                      "properties": {
                        "address": {
                          "description": "Owner wallet address",
                          "type": "string"
                        },
                        "amount": {
                          "description": "Token amount owned as a string",
                          "type": "string"
                        },
                        "tokenId": {
                          "description": "Token ID for NFTs",
                          "type": "string"
                        }
                      },
                      "required": [
                        "address",
                        "amount"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "pagination": {
                    "properties": {
                      "hasMore": {
                        "description": "Whether there are more items available",
                        "type": "boolean"
                      },
                      "limit": {
                        "default": 20,
                        "description": "Number of items per page",
                        "type": [
                          "number",
                          "null"
                        ]
                      },
                      "page": {
                        "default": 1,
                        "description": "Current page number",
                        "type": [
                          "number",
                          "null"
                        ]
                      },
                      "totalCount": {
                        "description": "Total number of items available",
                        "type": [
                          "number",
                          "null"
                        ]
                      }
                    },
                    "type": "object"
                  }
                },
                "required": [
                  "owners",
                  "pagination"
                ],
                "type": "object"
              }
            },
            "required": [
              "result"
            ],
            "type": "object"
          }
        }
      },
      "description": "Token owners retrieved successfully. Returns owners with pagination information. For ERC-20 tokens, `amount` represents token balance. For NFTs, `amount` represents quantity owned (usually '1' for ERC-721, can be >1 for ERC-1155)."
    },
    "400": {
      "description": "Invalid request parameters."
    },
    "401": {
      "description": "Authentication required. The request must include a valid `x-client-id` header for frontend usage or `x-secret-key` for backend usage."
    },
    "404": {
      "description": "Token not found or no owners available."
    },
    "500": {
      "description": "Internal server error."
    }
  }
}