Merkl Developer Portal logo
get

/v4/analytics/beneficial-owners/allocations

Layered beneficial-owners report for a token

The full report behind the holders mapping, as a nested tree: the asset itself, and every vault/market/gauge holding it, each with its own positions and its own nested children. Reading rule: decomposed: true with childIndexingId means the amount is expanded in that child node; decomposed: false with childIndexingId means a supported node with no active positions, the contract holds the balance (counted in total and holders); decomposed: false with childIndexingId: null is a final holder (EOA or unintegrated contract). A holder mapping to several nodes (singleton) is read in children. A node reachable from more than one parent appears once under EACH parent, same indexingId, each copy holding only the share that flows through its own route. Same at/409 semantics as holders; 403 when any node in the graph holds confidential balances the caller may not read. diagnostics.unresolved lists only nodes whose value is excluded from total; empty nodes are not listed.

Query parameters

chainIdstring (integer) | integer
required

Chain ID

tokenstring
required
atstring (integer) | integer
required

Unix timestamp

Responses

200
Response for status 200
Schema
object
assetobject
required
chainIdnumber
required
addressstring
required
symbolstring
required
decimalsnumber
required
atnumber
required
totalstring
required
rootIndexingIdstring
required
treeobject
required
indexingIdstring
errorobject
reasonstring
required
messagestring
required
descriptionobject | null
protocolstring
namestring
actionstring
tokensobject[]
chainIdnumber
addressstring
symbolstring
diagnosticsobject
required
nodesTraversednumber
required
maxDepthnumber
required
unresolvedobject[]
required
holdsstring | null
protocolstring | null
reasonstring
protocolAmountstring
Example
{
  "asset": {
    "chainId": 0,
    "address": "string",
    "symbol": "string",
    "decimals": 0
  },
  "at": 0,
  "total": "string",
  "rootIndexingId": "string",
  "tree": {
    "indexingId": "string",
    "error": {
      "reason": "string",
      "message": "string"
    },
    "description": {
      "protocol": "string",
      "name": "string",
      "action": "string",
      "tokens": [
        null
      ]
    }
  },
  "diagnostics": {
    "nodesTraversed": 0,
    "maxDepth": 0,
    "unresolved": [
      {
        "holds": "string",
        "protocol": "string",
        "reason": "string",
        "protocolAmount": "string"
      }
    ]
  }
}
409
Response for status 409
Schema
object
typestring
required
default: "/errors/conflict"
titlestring
required
default: "Conflict"
statusnumber
required
default: 409
detailstring
required
error"SNAPSHOT_NOT_INDEXED"
required
messagestring
required
requestednumber
required
availablenumber
required
lagSecondsnumber
required
totalSourcesnumber
required
laggingCountnumber
required
neverIndexedCountnumber
required
laggingSourcesobject[]
required
indexingIdstring
frontiernumber
statusenumunregisteredregistered-no-rangelagging
parentIndexingIdstring
pathstring[]
depthnumber
chainIdnumber
processorTypestring
protocolstring
targetTokenstring
recipientstring
configobject
countsByStatusobject
required
unregisterednumber
required
registeredNoRangenumber
required
laggingnumber
required
truncatedobject
required
unregisteredboolean
required
registeredNoRangeboolean
required
laggingboolean
required
Example
{
  "type": "/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "string",
  "error": "SNAPSHOT_NOT_INDEXED",
  "message": "string",
  "requested": 0,
  "available": 0,
  "lagSeconds": 0,
  "totalSources": 0,
  "laggingCount": 0,
  "neverIndexedCount": 0,
  "laggingSources": [
    {
      "indexingId": "string",
      "frontier": 0,
      "status": "unregistered",
      "parentIndexingId": "string",
      "path": [
        "string"
      ],
      "depth": 0,
      "chainId": 0,
      "processorType": "string",
      "protocol": "string",
      "targetToken": "string",
      "recipient": "string",
      "config": {}
    }
  ],
  "countsByStatus": {
    "unregistered": 0,
    "registeredNoRange": 0,
    "lagging": 0
  },
  "truncated": {
    "unregistered": false,
    "registeredNoRange": false,
    "lagging": false
  }
}