# GET /v4/analytics/positions/{userAddress}

_Merkl Analytics API_

> 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

- `userAddress` (string) _(required)_
- `chainId` (string | number) _(required)_

### Query parameters

- `enrichPositions` (boolean) _(required)_
- `includeHistory` (boolean) _(required)_
- `includeDisplay` (boolean) _(required)_
- `includeMerklAPIData` (boolean) _(required)_
- `minTimestamp` (string | number)
- `daily` (boolean) _(required)_
- `first` (string | number)
- `protocol` (string)
- `identifier` (string)
- `indexingIds` (array)
- `after` (string)

## Responses

- **200** Response for status 200

## Example request

```bash
curl -X GET "https://analytics.merkl.xyz/v4/analytics/positions/{userAddress}?enrichPositions=<enrichPositions>&includeHistory=<includeHistory>&includeDisplay=<includeDisplay>&includeMerklAPIData=<includeMerklAPIData>&daily=<daily>" \
  -H "x-api-key: YOUR_API_KEY"
```