get

/v4/analytics/positions/{userAddress}/{chainId}

Get user position history

Fetch historical position data for a user across opportunities.

Auth: a valid x-api-key developer key, or an authenticated JWT identity (cookie or Bearer) — both grant the same read access.

Response:
- data[chainId][identifier][indexingId]: Wrapped positions grouped by chain ID → identifier → indexingId. Each positionGroup carries shared metadata (protocol, action, stateType, globalStates, tokens) and a positions map keyed by positionId.
- latest is reported as of the indexing checkpoint: its (blockNumber, blockTimestamp) are advanced to how far indexing has completed (state unchanged through there), never beyond it — so the state is never presented as more current than what's indexed.
- globalStates (present when enrichment runs): at the positionGroup level it holds series descriptors only (type, indexingId). The value applied to a snapshot lives on that snapshot's own globalStates[key] = { blockTimestamp, value } — the series row at-or-before the snapshot's timestamp (carry-forward) — so each snapshot (latest + each history entry) is self-describing.
- pagination.positionCount: Number of positions returned
- pagination.totalHistorySnapshots: Total history snapshots (when > 0)
- pagination.pageInfo: Cursor-based pagination info (when applicable)

Examples:
- All positions on chain 1: GET /v4/analytics/positions/0xUserAddress/1
- With history: GET /v4/analytics/positions/0xUserAddress/1?includeHistory=true
- With enrichment: GET /v4/analytics/positions/0xUserAddress/1?enrichPositions=true
- With USD display values: GET /v4/analytics/positions/0xUserAddress/1?includeDisplay=true
- With Merkl API data: GET /v4/analytics/positions/0xUserAddress/1?includeMerklAPIData=true
- Filter by protocol: GET /v4/analytics/positions/0xUserAddress/1?protocol=uniswap
- Filter by identifier: GET /v4/analytics/positions/0xUserAddress/1?identifier=0xPoolAddress

Path parameters

userAddressstring
required
chainIdnumber | string
required

Query parameters

enrichPositionsboolean
required
default: false
includeHistoryboolean
required
default: false
includeDisplayboolean
required
default: false
includeMerklAPIDataboolean
required
default: false
minTimestampnumber | string
dailyboolean
required
default: false
firstnumber | stringdefault: 1000
protocolstring
identifierstring
indexingIdsstring[]
afterstring

Responses

200
Response for status 200
Schema
object
dataobject
required
Wrapped positions keyed by chainId, then identifier, then indexingId
paginationobject
required
positionCountnumber
required
Actual number of items returned
totalHistorySnapshotsnumberTotal number of history snapshots
pageInfoobject
endCursorstringCursor for the next page
hasMoreHistoryboolean
required
Whether there are more results available
Example
{
  "data": {},
  "pagination": {
    "positionCount": 0,
    "totalHistorySnapshots": 0,
    "pageInfo": {
      "endCursor": "string",
      "hasMoreHistory": false
    }
  }
}
get
https://analytics.merkl.xyz/v4/analytics/positions/{userAddress}/{chainId}
Merkl Analytics API
curl -X GET "https://analytics.merkl.xyz/v4/analytics/positions/{userAddress}/{chainId}"
Fill the required path parameters userAddress, chainId to send.