Positions Analytics

Access detailed position and transaction data using Merkl States Analytics API

Get User Position History

Fetch historical position data for a user across opportunities (pools, lending markets, etc.):

GET /v1/positions/{userAddress}/{chainId?}

Path Parameters:

  • userAddress (required): The user's wallet address
  • chainId (optional): Chain ID to filter by

Query Parameters:

  • enrichPositions (optional, boolean): Enrich CLAMM positions with formatted token amounts and global state data. Defaults to false
  • includeHistory (optional, boolean): Include history snapshots. Defaults to false
  • includeMerklAPIData (optional, boolean): Include Merkl API data (opportunity ID, APR records). Defaults to false
  • maxTimestamp (optional, numeric): Maximum timestamp to fetch data until
  • protocol (optional, string): Filter by protocol name (e.g., uniswap). Case-insensitive partial match
  • first (optional, numeric, 1–1000): Number of historical snapshots to return. Defaults to 1000
  • after (optional, string): Cursor for pagination. Use the endCursor from the previous response

Examples:

All positions for a user on Ethereum:

GET /v1/positions/0x1234.../1?includeHistory=true

With enrichment:

GET /v1/positions/0x1234.../1?enrichPositions=true&includeHistory=true

Paginate through results:

GET /v1/positions/0x1234.../1?first=50&after=<endCursor>

Get Positions by Identifier

Fetch the latest position for every user in a given pool or token opportunity:

GET /v1/positions/by-identifier/{chainId}/{identifier}

Path Parameters:

  • chainId (required): Chain ID to query
  • identifier (required): Pool address, token address, market ID, or any opportunity identifier

Query Parameters:

  • blockNumber (optional, numeric): Target block number (0 = latest)
  • enrichPositions (optional, boolean): Enrich CLAMM positions with formatted token amounts and global state data. Defaults to false

Example:

GET /v1/positions/by-identifier/1/0xPoolAddress?enrichPositions=true