Get Token With Holders

Retrieve a list of all holders for a specific token, including their balances and current value in USD.

GETapi.metal.build/token/:tokenAddress

List all holders

This endpoint returns a list of all addresses holding your token, along with their balances and current values.

Response attributes

Name
id
Type
string
Description
The id of the token.
Name
address
Type
string
Description
The contract address of the token.
Name
name
Type
string
Description
The name of the token.
Name
symbol
Type
string
Description
The ticker symbol of the token.
Name
totalSupply
Type
number
Description
Total token supply.
Name
startingAppSupply
Type
number
Description
Available supply for distribution.
Name
remainingAppSupply
Type
number
Description
Remaining supply for distribution.
Name
merchantSupply
Type
number
Description
The amount allocated to the merchant.
Name
merchantAddress
Type
string
Description
The address of the merchant.
Name
price
Type
number
Description
Current price of the token in USD.
Will return null if no liquidity has been created for the token.
Name
lpInfo
Type
object
Description
- Name
  nftId
  Type
  string
  Description
  Uniswap V3 Position Id
- Name
  liquidityPoolAddress
  Type
  string
  Description
  Liquidity Pool Address
Will return null if no liquidity has been created for the token.
Name
createdAt
Type
string
Description
The timestamp when the token was created.
Name
holders
Type
array
Description
Array of holder objects, each containing:
Holder value will return null if no liquidity has been created for the token.
{ id: "string", address: "string", balance: "number", value: "number", }

Request

GET

api.metal.build/token/:tokenAddress

const response = await fetch(
  'https://api.metal.build/token/0x1234567890abcdef1234567890abcdef12345678',
  {
    headers: {
      'x-api-key': 'YOUR_SECRET_API_KEY',
    },
  }
)

const holders = await response.json()

Response

{
  id: "0x1234567890abcdef1234567890abcdef12345678",
  address: "0x1234567890abcdef1234567890abcdef12345678",
  name: "Test Token",
  symbol: "TEST",
  totalSupply: 1000000000,
  startingAppSupply: 1000000000,
  remainingAppSupply: 499965000,
  merchantSupply: 100000000,
  merchantAddress: "0x1234567890abcdef1234567890abcdef12345678",
  price: 0.015,
  lpInfo: {
    nftId: "2234135",
    liquidityPoolAddress: "0x46D4702D9A0dD7602b0a4f6571347751D456A86e"
  },
  createdAt: "2025-02-24T21:00:03.520Z",
  holders: [
    {
      id: "0xabcdef1234567890abcdef1234567890abcdef12",
      address: "0xabcdef1234567890abcdef1234567890abcdef12",
      balance: 1000000,
      value: 7.50,
    },
    {
      id: "0x7890abcdef1234567890abcdef1234567890abcd",
      address: "0x7890abcdef1234567890abcdef1234567890abcd",
      balance: 2000000,
      value: 15.00,
    },
    {
      id: "0x3456789012345678901234567890123456789012",
      address: "0x3456789012345678901234567890123456789012",
      balance: 500000,
      value: 3.75,
    }
  ]
}