Token dashboard indexing example

All requests on this page target the Whitechain Sepolia explorer at https://explorer.testnet.whitechain.io (chain id 1874). The API is public, read-only, and needs no API key. The examples use the real testnet token 0x071c373d58A5290982a0E916D529a27849baE6e0 (USDW, an ERC-20 with 6 decimals). Replace it with the token contract address you want to read. The holder and transfer addresses in the sample responses, such as the example address 0xA439Ad519046CCd7056Ddf74fbaAc99d740Bdf09, are wallets rather than contracts, so they carry no bytecode.

Every request below has a Run this request button. It sends that exact request from your browser to Whitechain Sepolia and prints the live response, so you can compare it with the sample response above it. Each button carries its own input field, so editing the token address in one runner does not change the others. The requests are read-only GET and POST calls with no key and no wallet connection, and nothing you enter leaves your browser except the address in the request.

What you can build

A token dashboard takes one token contract address and reads two Blockscout API surfaces to show:

Metadata: name, symbol, decimals, total supply, and price when the explorer has one.
Two counters: current holders (non-zero balances) and lifetime transfers.
The top holders by balance.
A paginated transfer feed.

API surfaces and base URLs

Surface	Base URL	Use it for
GraphQL API	`https://explorer.testnet.whitechain.io/api/v1/graphql`	The transfer feed and per-address lookups. One POST returns exactly the fields you ask for, with cursor pagination.
REST API v2	`https://explorer.testnet.whitechain.io/api/v2`	Token metadata, the holders list, and the counters.

The split is deliberate. The Blockscout GraphQL schema has no token query, so metadata, holders, and counters come from REST v2. GraphQL owns the transfer feed, where field selection and cursor pagination help most.

Endpoint map

Task	Interface	Request
Name, symbol, decimals, supply, price	REST API	`GET /api/v2/tokens/{hash}`
Holder and transfer counts	REST API	`GET /api/v2/tokens/{hash}/counters`
Top holders	REST API	`GET /api/v2/tokens/{hash}/holders`
Transfer feed (paginated)	GraphQL API	`POST /api/v1/graphql` with `tokenTransfers`
Single address lookup	GraphQL API	`POST /api/v1/graphql` with `address`

Reading metadata, holders, and counters with REST v2

Send GET requests with an accept: application/json header. Responses below are trimmed to the fields a dashboard reads.

Token metadata

Request

curl "https://explorer.testnet.whitechain.io/api/v2/tokens/0x071c373d58A5290982a0E916D529a27849baE6e0" \
  -H "accept: application/json"

Response (trimmed)

{
  "address_hash": "0x071c373d58A5290982a0E916D529a27849baE6e0",
  "name": "USDW",
  "symbol": "USDW",
  "decimals": "6",
  "type": "ERC-20",
  "total_supply": "10000000013605001000",
  "exchange_rate": null
}

Field	Meaning	How to use it
`decimals`	Fractional digits for this token	Divide every raw amount by 10^`decimals`. Here that is 10^6.
`total_supply`	Raw total supply	Divide by 10^`decimals` for the display supply.
`type`	Token standard	`ERC-20`, `ERC-721`, or `ERC-1155`.
`exchange_rate`	USD price, or `null`	Show a price only when it is not `null`.

Counters

Request

curl "https://explorer.testnet.whitechain.io/api/v2/tokens/0x071c373d58A5290982a0E916D529a27849baE6e0/counters" \
  -H "accept: application/json"

Response

{ "token_holders_count": "5", "transfers_count": "31" }

Use token_holders_count for the holders card and transfers_count for the transfers card. Both are strings; parse them before formatting.

Top holders

Request

curl "https://explorer.testnet.whitechain.io/api/v2/tokens/0x071c373d58A5290982a0E916D529a27849baE6e0/holders" \
  -H "accept: application/json"

Response (trimmed to two items)

{
  "items": [
    {
      "address": { "hash": "0xA439Ad519046CCd7056Ddf74fbaAc99d740Bdf09", "is_contract": false },
      "value": "10000000000000000000"
    },
    {
      "address": { "hash": "0x6e057133CFa4a9Ec70c77aaFe29751460FE16307", "name": "UniswapV3Pool", "is_contract": true },
      "value": "2792871783"
    }
  ],
  "next_page_params": null
}

Each item pairs an address with a raw value. Format value against the token decimals from the metadata call, and keep full precision so small balances stay visible. Show address.name (such as UniswapV3Pool) when present, otherwise the raw hash.

Reading the transfer feed with GraphQL

Send POST requests to https://explorer.testnet.whitechain.io/api/v1/graphql with a content-type: application/json body holding a query and its variables. You get back only the fields you request.

The transfers query

Request

curl "https://explorer.testnet.whitechain.io/api/v1/graphql" \
  -H "content-type: application/json" \
  -d '{
    "query": "query Transfers($token: AddressHash!, $first: Int!, $after: String) { tokenTransfers(tokenContractAddressHash: $token, first: $first, after: $after) { edges { node { amount fromAddressHash toAddressHash transactionHash tokenIds } } pageInfo { hasNextPage endCursor } } }",
    "variables": { "token": "0x071c373d58A5290982a0E916D529a27849baE6e0", "first": 8, "after": null }
  }'

Response (trimmed to one edge)

{
  "data": {
    "tokenTransfers": {
      "edges": [
        {
          "node": {
            "amount": "207128221",
            "fromAddressHash": "0x6e057133CFa4a9Ec70c77aaFe29751460FE16307",
            "toAddressHash": "0xE637dc119ADAEb23e72f689183Cf6F60a52773Aa",
            "transactionHash": "0xb97ceb21417fe4a7d94162f99b3f2d8c5f7bc3b5ca54ac0b45fadb15c05c3b57",
            "tokenIds": null
          }
        }
      ],
      "pageInfo": { "hasNextPage": true, "endCursor": "WyIyNjE3MzMwIiwxXQ==" }
    }
  }
}

Field	Meaning	How to use it
`amount`	Raw amount moved	Divide by the token `decimals`. Here `207128221` is 207.128221 USDW.
`fromAddressHash` / `toAddressHash`	Sender and recipient	Render both; a mint shows `from` as the zero address `0x0000000000000000000000000000000000000000`.
`transactionHash`	The transaction the transfer belongs to	Link to `/tx/{hash}` on the explorer.
`tokenIds`	NFT ids, or `null`	`null` for ERC-20. Set for ERC-721 and ERC-1155.

The GraphQL server caps operation complexity at 100, and tokenTransfers costs about 11 per item, so request 8 at a time (first: 8). Explore the full schema at the GraphQL API docs.

Address lookup

Use the address query when you need one address’s native balance and whether it holds contract code, for example to annotate a holder row.

Request

curl "https://explorer.testnet.whitechain.io/api/v1/graphql" \
  -H "content-type: application/json" \
  -d '{
    "query": "query AddressLookup($hash: AddressHash!) { address(hash: $hash) { hash fetchedCoinBalance contractCode } }",
    "variables": { "hash": "0xA439Ad519046CCd7056Ddf74fbaAc99d740Bdf09" }
  }'

Response

{
  "data": {
    "address": {
      "hash": "0xA439Ad519046CCd7056Ddf74fbaAc99d740Bdf09",
      "fetchedCoinBalance": "177504708847852442",
      "contractCode": null
    }
  }
}

A null contractCode means the address is a wallet, not a contract. fetchedCoinBalance is the native balance in wei; divide by 10^18 for WBT.

Pagination

The transfer feed pages with an opaque cursor. Read pageInfo.hasNextPage and pageInfo.endCursor from a response, then send that endCursor back as the after variable to fetch the next page. Stop when hasNextPage is false. Do not build or parse the cursor yourself; treat it as opaque.

Errors

GraphQL always returns HTTP 200. On failure the body has an errors array instead of (or alongside) data, so check for errors before reading data. An operation above the complexity cap returns such an error, which is why the page requests 8 transfers at a time. REST v2 returns HTTP 422 with an errors array for a malformed token address or parameter, where each entry carries a title, a source.pointer naming the bad field, and a detail string.

Load sequence

For a full dashboard, issue the three REST reads (metadata, counters, holders) and the first GraphQL transfers page in parallel; none depend on another. Then fetch further transfer pages on demand with the cursor. Refetch everything when the user enters a different token address.

Wallet

Dapps

Deploy

Bridge

Block Explorer

Ecosystem

Token dashboard indexing example

What you can build

API surfaces and base URLs

Endpoint map

Reading metadata, holders, and counters with REST v2

Token metadata

Counters

Top holders

Reading the transfer feed with GraphQL

The transfers query

Address lookup

Errors

Load sequence

​What you can build

​API surfaces and base URLs

​Endpoint map

​Reading metadata, holders, and counters with REST v2

​Token metadata

​Counters

​Top holders

​Reading the transfer feed with GraphQL

​The transfers query

​Address lookup

​Pagination

​Errors

​Load sequence

​Related

What you can build

API surfaces and base URLs

Endpoint map

Reading metadata, holders, and counters with REST v2

Token metadata

Counters

Top holders

Reading the transfer feed with GraphQL

The transfers query

Address lookup

Pagination

Errors

Load sequence

Related