> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trusset.org/llms.txt
> Use this file to discover all available pages before exploring further.

# List Token Holders

> Retrieve all holders of a specific stock token

Returns a paginated list of addresses holding a given stock token, along with the total holder count.

## Path Parameters

<ParamField path="tokenAddress" type="string" required>
  Address of the stock token contract.
</ParamField>

## Query Parameters

<ParamField query="limit" type="integer" default="100">
  Maximum number of holders to return. Capped at 500.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">Request status.</ResponseField>

<ResponseField name="data" type="object">
  <Expandable>
    <ResponseField name="holders" type="object[]">Array of holder records.</ResponseField>
    <ResponseField name="total" type="integer">Total number of holders for this token.</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.trusset.org/stocks/api/fetch/holders/0x1234...?limit=50" \
    -H "X-API-Key: trusset_abc123xy_secret..."
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    `https://api.trusset.org/stocks/api/fetch/holders/${tokenAddress}?limit=50`,
    {
      headers: { 'X-API-Key': 'trusset_abc123xy_secret...' }
    }
  );
  const { data } = await response.json();
  console.log(`${data.total} total holders`);
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "holders": [
        {
          "address": "0xAbC123dEf456789012345678901234567890AbCd",
          "balance": "5000"
        },
        {
          "address": "0x9876543210fedcba9876543210fedcba98765432",
          "balance": "1500"
        }
      ],
      "total": 2
    },
    "metadata": {
      "requestId": "550e8400-e29b-41d4-a716-446655440000",
      "timestamp": "2025-06-15T12:00:00.000Z",
      "instanceId": "inst_abc123"
    }
  }
  ```
</ResponseExample>