Get Holder

Retrieve holder information, such as wallet address and token balances.

GETapi.metal.build/holder/:userId?publicKey=:publicKey

Get Holder

This endpoint returns the wallet address, token balances, presale allocations and other relevant information for a specific holder.

Your public API key can be found here.

Response attributes

Name
id
Type
string
Description
The id of the holder. This is the same as userId which you made the request with.
Name
address
Type
string
Description
The address of the holder.
Name
totalValue
Type
number
Description
Total value of all token holdings in USD (including active tokens, locked tokens, and presales).

Name

tokens

Type

array

Description

Array of active (unlocked) token objects, each containing:

[{
  "id": "string",
  "address": "string", 
  "name": "string",
  "symbol": "string",
  "balance": "number",
  "value": "number",
  "status": "active",
  "type": "token"
}]

Name

presales

Type

array

Description

Array of presale participation objects, each containing:

[{
  "id": "string",
  "address": "string",
  "name": "string",
  "symbol": "string", 
  "balance": "number", // Expected tokens to receive
  "value": "number", // USDC invested
  "status": "pending",
  "type": "presale",
  "metadata": {
    "presaleId": "string",
    "progress": "number", // Percentage complete
    "endDate": "string" // ISO date
  }
}]

Name

locks

Type

array

Description

Array of locked token objects, each containing:

[{
  "id": "string",
  "address": "string",
  "name": "string", 
  "symbol": "string",
  "balance": "number", // Locked amount
  "value": "number",
  "status": "locked",
  "type": "lock",
  "unlockDate": "string" // ISO date when tokens unlock
}]

Request

GET

api.metal.build/holder/:userId?publicKey=:publicKey

const response = await fetch(
  'https://api.metal.build/holder/holder_789?publicKey=YOUR_PUBLIC_API_KEY'
  )

const balances = await response.json()

Response

{
  "id": "holder_789",
  "address": "0xabcdef1234567890abcdef1234567890abcdef12",
  "totalValue": 326.12,
  "tokens": [
    {
      "id": "0x1234567890abcdef1234567890abcdef12345678",
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "name": "Community Token",
      "symbol": "COMM",
      "balance": 50.25,
      "value": 75.37,
      "status": "active",
      "type": "token"
    },
    {
      "id": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "name": "USDC",
      "symbol": "USDC",
      "balance": 100.50,
      "value": 100.50,
      "status": "active",
      "type": "token"
    }
  ],
  "presales": [
    {
      "id": "81ce774a-ebaf-4d19-ba77-b1dbb41bc5d1",
      "address": "presale-81ce774a-ebaf-4d19-ba77-b1dbb41bc5d1",
      "name": "Future Token",
      "symbol": "FUT",
      "balance": 1000,
      "value": 50,
      "status": "pending",
      "type": "presale",
      "metadata": {
        "presaleId": "81ce774a-ebaf-4d19-ba77-b1dbb41bc5d1",
        "progress": 75.5,
        "endDate": "2024-03-01T00:00:00.000Z"
      }
    }
  ],
  "locks": [
    {
      "id": "0x1234567890abcdef1234567890abcdef12345678-locked",
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "name": "Locked Token",
      "symbol": "LOCK",
      "balance": 500,
      "value": 100.25,
      "status": "locked",
      "type": "lock",
      "unlockDate": "2024-04-01T00:00:00.000Z"
    }
  ]
}

Get Single Token Balance

Retrieve detailed balance information for a specific token holder, including their balance and its current value in USD.

GETapi.metal.build/holder/:holderAddress/token/:tokenAddress

Get Single Token Balance

This endpoint returns the balance and value information for a specific token holder. To retrieve the user's holderAddress you can use Get Holder.

Response attributes

Name
name
Type
string
Description
The name of the token.
Name
symbol
Type
string
Description
The token's symbol.
Name
id
Type
string
Description
The token's contract address.
Name
address
Type
string
Description
The token's contract address (same as id).
Name
balance
Type
number
Description
The holder's token balance.
Name
value
Type
number
Description
The holder's token balance in USD.
Will return null if no liquidity has been created for the token.

Request

GET

api.metal.build/holder/:holderAddress/token/:tokenAddress

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

const holder = await response.json()

Response

{
  name: "TestToken",
  symbol: "TT",
  id: "0xde522f429bde9776417985c6ebcdc9de872fd5c4",
  address: "0xde522f429bde9776417985c6ebcdc9de872fd5c4",
  balance: 2000000,
  value: 15.00
}