# Positions

## POST /positions/{pubkey}/by-filter

> Get paginated positions for a user that match the specified filter

```json
{"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"position","description":"Get positions created by users for Saturn swap pools"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/positions/{pubkey}/by-filter":{"post":{"tags":["position"],"description":"Get paginated positions for a user that match the specified filter","operationId":"get_positions_by_filter","parameters":[{"name":"pubkey","in":"path","description":"User's pubkey as hex string","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PositionSearchFilter"}}},"required":true},"responses":{"200":{"description":"Paginated positions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginationResponse_Vec_PositionResult"}}}},"400":{"description":"Invalid pubkey format"}}}}},"components":{"schemas":{"PositionSearchFilter":{"type":"object","properties":{"name":{"type":["array","null"],"items":{"type":"string"}},"min_liquidity":{"type":["integer","null"],"format":"int32"},"offset":{"type":["integer","null"],"format":"int32"},"limit":{"type":["integer","null"],"format":"int32"}}},"PaginationResponse_Vec_PositionResult":{"type":"object","required":["response","offset"],"properties":{"response":{"type":"array","items":{"type":"object","required":["position","state","historicalGainPct","totalIncrementToken0Amount","totalIncrementToken1Amount"],"properties":{"position":{"$ref":"#/components/schemas/Position"},"state":{"$ref":"#/components/schemas/PositionState"},"historicalGainPct":{"type":"string"},"totalIncrementToken0Amount":{"type":"integer"},"totalIncrementToken1Amount":{"type":"integer"},"estimatedApy24h":{"type":["string","null"]},"estimatedApy7d":{"type":["string","null"]}}}},"offset":{"type":"integer","format":"int32"}}},"Position":{"type":"object","required":["id","poolId","owner"],"properties":{"id":{"type":"string"},"poolId":{"type":"string"},"owner":{"type":"string"}}},"PositionState":{"type":"object","required":["positionId","blockHeight","liquidity","incrementToken0Amount","incrementToken1Amount"],"properties":{"positionId":{"type":"string"},"blockHeight":{"type":"string"},"liquidity":{"type":"string"},"incrementToken0Amount":{"type":"integer"},"incrementToken1Amount":{"type":"integer"}}}}}}
```

## GET /position/{id}

> Get position details

```json
{"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"position","description":"Get positions created by users for Saturn swap pools"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/position/{id}":{"get":{"tags":["position"],"description":"Get position details","operationId":"get_position_by_id","parameters":[{"name":"id","in":"path","description":"Position pubkey as hex string","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Position details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PositionDetails"}}}},"400":{"description":"Invalid pubkey format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Position not found","content":{"text/plain":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"PositionDetails":{"type":"object","required":["position","state"],"properties":{"position":{"$ref":"#/components/schemas/Position"},"state":{"$ref":"#/components/schemas/PositionState"}}},"Position":{"type":"object","required":["id","poolId","owner"],"properties":{"id":{"type":"string"},"poolId":{"type":"string"},"owner":{"type":"string"}}},"PositionState":{"type":"object","required":["positionId","blockHeight","liquidity","incrementToken0Amount","incrementToken1Amount"],"properties":{"positionId":{"type":"string"},"blockHeight":{"type":"string"},"liquidity":{"type":"string"},"incrementToken0Amount":{"type":"integer"},"incrementToken1Amount":{"type":"integer"}}},"ApiError":{"oneOf":[{"type":"object","required":["DBError"],"properties":{"DBError":{"type":"string"}}},{"type":"object","required":["NotFound"],"properties":{"NotFound":{"type":"string"}}},{"type":"object","required":["InvalidPubkey"],"properties":{"InvalidPubkey":{"type":"string"}}}]}}}}
```

## GET /position/{pubkey}/{pool\_id}

> Get details for a user's position in the specified pool

```json
{"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"position","description":"Get positions created by users for Saturn swap pools"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/position/{pubkey}/{pool_id}":{"get":{"tags":["position"],"description":"Get details for a user's position in the specified pool","operationId":"get_position_by_pubkey_and_pool","parameters":[{"name":"pubkey","in":"path","description":"User's pubkey as hex string","required":true,"schema":{"type":"string"}},{"name":"pool_id","in":"path","description":"Pool ID as a hex string","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of positions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PositionResult"}}}},"400":{"description":"Invalid pubkey format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Position not found for specified pool","content":{"text/plain":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"PositionResult":{"type":"object","required":["position","state","historicalGainPct","totalIncrementToken0Amount","totalIncrementToken1Amount"],"properties":{"position":{"$ref":"#/components/schemas/Position"},"state":{"$ref":"#/components/schemas/PositionState"},"historicalGainPct":{"type":"string"},"totalIncrementToken0Amount":{"type":"integer"},"totalIncrementToken1Amount":{"type":"integer"},"estimatedApy24h":{"type":["string","null"]},"estimatedApy7d":{"type":["string","null"]}}},"Position":{"type":"object","required":["id","poolId","owner"],"properties":{"id":{"type":"string"},"poolId":{"type":"string"},"owner":{"type":"string"}}},"PositionState":{"type":"object","required":["positionId","blockHeight","liquidity","incrementToken0Amount","incrementToken1Amount"],"properties":{"positionId":{"type":"string"},"blockHeight":{"type":"string"},"liquidity":{"type":"string"},"incrementToken0Amount":{"type":"integer"},"incrementToken1Amount":{"type":"integer"}}},"ApiError":{"oneOf":[{"type":"object","required":["DBError"],"properties":{"DBError":{"type":"string"}}},{"type":"object","required":["NotFound"],"properties":{"NotFound":{"type":"string"}}},{"type":"object","required":["InvalidPubkey"],"properties":{"InvalidPubkey":{"type":"string"}}}]}}}}
```

## GET /positions/{pubkey}

> Get a list of positions owned by the user

```json
{"openapi":"3.1.0","info":{"title":"Saturn Indexer API","version":"0.1.0"},"tags":[{"name":"position","description":"Get positions created by users for Saturn swap pools"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local testing"}],"paths":{"/positions/{pubkey}":{"get":{"tags":["position"],"description":"Get a list of positions owned by the user","operationId":"get_positions_by_pubkey","parameters":[{"name":"pubkey","in":"path","description":"User's pubkey as hex string","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of positions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PositionResult"}}}}},"400":{"description":"Invalid pubkey format"}}}}},"components":{"schemas":{"PositionResult":{"type":"object","required":["position","state","historicalGainPct","totalIncrementToken0Amount","totalIncrementToken1Amount"],"properties":{"position":{"$ref":"#/components/schemas/Position"},"state":{"$ref":"#/components/schemas/PositionState"},"historicalGainPct":{"type":"string"},"totalIncrementToken0Amount":{"type":"integer"},"totalIncrementToken1Amount":{"type":"integer"},"estimatedApy24h":{"type":["string","null"]},"estimatedApy7d":{"type":["string","null"]}}},"Position":{"type":"object","required":["id","poolId","owner"],"properties":{"id":{"type":"string"},"poolId":{"type":"string"},"owner":{"type":"string"}}},"PositionState":{"type":"object","required":["positionId","blockHeight","liquidity","incrementToken0Amount","incrementToken1Amount"],"properties":{"positionId":{"type":"string"},"blockHeight":{"type":"string"},"liquidity":{"type":"string"},"incrementToken0Amount":{"type":"integer"},"incrementToken1Amount":{"type":"integer"}}}}}}
```