Policy Holders

GET /v1/assets/policy/:policyId/holders

Get all addresses holding any asset under a specific policy ID (paginated).

Parameters:

Parameter	Type	Description
policyId	string	56-character hex policy ID

Query Parameters:

Parameter	Type	Default	Description
limit	integer	100	Results per page (1-500)
offset	integer	0	Number of results to skip
order	string	desc	Sort order: asc or desc (by total quantity)

Example Request:

# Top IAG policy holders
curl -X GET "https://api.insight.iagon.com/v1/assets/policy/5d16cc1a177b5d9ba9cfa9793b07e60f1fb70fea1f8aef064415d114/holders?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Smallest holders first
curl -X GET "https://api.insight.iagon.com/v1/assets/policy/5d16cc1a177b5d9ba9cfa9793b07e60f1fb70fea1f8aef064415d114/holders?order=asc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

Content-Type: application/json;charset=utf-8

{
  "success": true,
  "data": [
    {
      "address": "addr1qx...",
      "stake_address": "stake1u9...",
      "quantity": "50000000000000"
    },
    {
      "address": "addr1qy...",
      "stake_address": "stake1u8...",
      "quantity": "25000000000000"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "hasMore": true
  },
  "last_updated": {
    "slot_no": 123456789,
    "block_hash": "abc123...",
    "block_time": "2024-01-15T10:30:00Z"
  }
}

Content-Type: application/json;charset=utf-8

{
  "success": false,
  "error": "Invalid policy ID format. Expected 56 hex characters"
}

Response Fields:

Field	Type	Description
address	string	Bech32 payment address holding policy assets
stake_address	string | null	Associated stake address (if any)
quantity	string	Total amount of all policy assets held

Performance Note

This endpoint aggregates holdings across ALL assets under a policy. For policies with many assets (like large NFT collections), this query can be slow. Consider using smaller page sizes and caching results.

Difference from Asset Holders

• Asset Holders (/v1/assets/:asset/holders) - holders of ONE specific asset
• Policy Holders (/v1/assets/policy/:policyId/holders) - holders of ANY asset under the policy

For NFT collections, Policy Holders shows everyone who owns at least one NFT from the collection.