> For the complete documentation index, see [llms.txt](https://hyperliquid-ohlc.gitbook.io/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hyperliquid-ohlc.gitbook.io/api-docs/rest-api/perp-positions/wallet-historical-positions.md).

# Wallet Historical Positions

## Get perp positions history for a wallet

> Retrieve perpetual positions for a specific wallet address with optional token filtering. Defaults to last 7 days of position history. Supports cursor-based pagination.

```json
{"openapi":"3.1.0","info":{"title":"BlockLiquidity API Service","version":"1.0.0"},"servers":[{"url":"https://data.blockliquidity.xyz"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"PerpAssetPositionsHistoryResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/WalletsPerpPositionsHistory"},"type":"array","title":"Data"},"pagination":{"$ref":"#/components/schemas/PaginationInfo"}},"type":"object","required":["data","pagination"],"title":"PerpAssetPositionsHistoryResponse"},"WalletsPerpPositionsHistory":{"properties":{"timestamp":{"type":"integer","title":"Timestamp"},"address":{"type":"string","title":"Address"},"token":{"type":"string","title":"Token"},"szi":{"type":"number","title":"Szi"},"entry_px":{"type":"number","title":"Entry Px"},"position_value":{"type":"number","title":"Position Value"},"unrealized_pnl":{"type":"number","title":"Unrealized Pnl"},"liquidation_px":{"type":"number","title":"Liquidation Px"},"margin_used":{"type":"number","title":"Margin Used"},"cum_funding_since_open":{"type":"number","title":"Cum Funding Since Open"},"leverage":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Leverage"}},"type":"object","required":["timestamp","address","token","szi","entry_px","position_value","unrealized_pnl","liquidation_px","margin_used","cum_funding_since_open"],"title":"WalletsPerpPositionsHistory"},"PaginationInfo":{"properties":{"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"},"has_more":{"type":"boolean","title":"Has More"},"limit":{"type":"integer","title":"Limit"},"start_timestamp":{"type":"integer","title":"Start Timestamp"},"end_timestamp":{"type":"integer","title":"End Timestamp"}},"type":"object","required":["has_more","limit","start_timestamp","end_timestamp"],"title":"PaginationInfo"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/wallets/perp/positions/history":{"get":{"tags":["Wallet Data"],"summary":"Get perp positions history for a wallet","description":"Retrieve perpetual positions for a specific wallet address with optional token filtering. Defaults to last 7 days of position history. Supports cursor-based pagination.","operationId":"get_perp_positions_history_v1_wallets_perp_positions_history_get","parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string","description":"Wallet address","title":"Address"},"description":"Wallet address"},{"name":"token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Token to filter by (e.g., BTC, ETH)","title":"Token"},"description":"Token to filter by (e.g., BTC, ETH)"},{"name":"start_timestamp","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"Start timestamp in Unix milliseconds","title":"Start Timestamp"},"description":"Start timestamp in Unix milliseconds"},{"name":"end_timestamp","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"End timestamp in Unix milliseconds","title":"End Timestamp"},"description":"End timestamp in Unix milliseconds"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Number of records per page","default":100,"title":"Limit"},"description":"Number of records per page"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pagination cursor from previous response","title":"Cursor"},"description":"Pagination cursor from previous response"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerpAssetPositionsHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```