> ## Documentation Index > Fetch the complete documentation index at: https://docs.datadash.xyz/llms.txt > Use this file to discover all available pages before exploring further. # User Position > Lifetime per-position trading stats for a wallet, bought/sold shares and USD, entry/exit prices, realized and unrealized PnL. One row per (wallet, position token); see positions/all for the event-grouped portfolio view. ## OpenAPI ````yaml /openapi.json post /api/v1/user-position openapi: 3.0.3 info: title: DataDash Analytics API version: 1.0.0 servers: [] security: - ApiKeyAuth: [] - BearerAuth: [] paths: /api/v1/user-position: post: tags: - Positions summary: User Position description: >- Lifetime per-position trading stats for a wallet, bought/sold shares and USD, entry/exit prices, realized and unrealized PnL. One row per (wallet, position token); see positions/all for the event-grouped portfolio view. operationId: listUserPosition requestBody: content: application/json: schema: properties: filter: $ref: '#/components/schemas/UserPositionFilter' orderBy: description: >- Sort keys in priority order; the first is the primary sort. Defaults to the table's configured ranking when omitted. items: properties: direction: default: asc enum: - asc - desc type: string field: enum: - userId - positionId - marketId - eventId - tagIds - seriesId - totalBoughtShares - totalBoughtUsd - totalSoldShares - totalSoldUsd - currentlyHeldShares - avgBuyingPrice - avgSellingPrice - realizedPnl - totalBuyCost - realizedPnlPercentage - realizedAvgBuyingPrice - totalTrades - firstTradeTimestamp - latestTradeTimestamp - unrealizedUsd - positionSize type: string required: - field type: object type: array page: $ref: '#/components/schemas/PageInput' searchKey: description: 'Free-text search over: User (prefix match/full-text search).' type: string required: - page type: object required: true responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/UserPositionRow' type: array description: List of User Position rows '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- invalid request (malformed body, unknown field, or failed validation) '401': content: application/json: schema: $ref: '#/components/schemas/Error' description: missing or invalid credentials '403': content: application/json: schema: $ref: '#/components/schemas/Error' description: credentials lack access to this resource '500': content: application/json: schema: $ref: '#/components/schemas/Error' description: internal error components: schemas: UserPositionFilter: description: Filters to apply, combined with AND. Use a group for OR. items: $ref: '#/components/schemas/UserPositionFilterNode' minItems: 1 type: array PageInput: properties: limit: minimum: 1 type: integer offset: minimum: 0 type: integer required: - limit type: object UserPositionRow: properties: avgBuyingPrice: description: Average buying price per share format: double title: Avg Buying Price type: number avgSellingPrice: description: Average selling price per share format: double title: Avg Selling Price type: number currentlyHeldShares: description: Shares currently held format: double title: Currently Held Shares type: number eventId: description: Prediction event ID format: int32 title: Event type: integer firstTradeTimestamp: description: Timestamp of the first trade format: date-time title: First Trade Time type: string latestTradeTimestamp: description: Timestamp of the latest trade format: date-time title: Latest Trade Time type: string marketId: description: Prediction market ID format: int32 title: Market type: integer positionId: description: The position bought/sold in a market. format: int32 title: Position type: integer positionSize: description: Size of Position format: double title: Position Size type: number realizedAvgBuyingPrice: description: Average buying price per share for sold shares format: double title: Realized Avg Buying Price type: number realizedPnl: description: Realized profit and loss format: double title: Realized PnL type: number realizedPnlPercentage: description: Realized PnL as a percentage format: float title: Realized PnL Percentage type: number seriesId: description: Series identifier format: int32 title: Series type: integer tagIds: description: Tags associated with the event items: format: int32 type: integer title: Category type: array totalBoughtShares: description: Total shares bought format: double title: Total Bought Shares type: number totalBoughtUsd: description: Total USD spent buying format: double title: Total Bought USD type: number totalBuyCost: description: Total cost basis for sold shares format: double title: Realized Buy Cost type: number totalSoldShares: description: Total shares sold format: double title: Total Sold Shares type: number totalSoldUsd: description: Total USD received from selling format: double title: Total Sold USD type: number totalTrades: description: Total number of trades done by the user for this position. format: int32 title: Total Trades type: integer unrealizedUsd: description: Unrealized USD value aka unrealized value format: double title: Unrealized USD type: number userId: description: User wallet address title: User type: string type: object Error: properties: code: description: machine-readable error code type: string message: description: human-readable description type: string required: - code - message type: object UserPositionFilterNode: description: A single condition, or a group combining conditions with AND/OR. oneOf: - $ref: '#/components/schemas/UserPositionCondition' - $ref: '#/components/schemas/UserPositionFilterGroup' UserPositionCondition: description: >- A single field condition. in/notIn take an array of values; matches/notMatches take one search term. oneOf: - $ref: '#/components/schemas/UserPositionNumericCondition' - $ref: '#/components/schemas/UserPositionIdCondition' - $ref: '#/components/schemas/UserPositionAddressCondition' - $ref: '#/components/schemas/UserPositionTimeCondition' UserPositionFilterGroup: description: >- A group of conditions and nested groups, combined with the group's operator. properties: filters: items: oneOf: - $ref: '#/components/schemas/UserPositionCondition' - $ref: '#/components/schemas/UserPositionFilterInnerGroup' minItems: 1 type: array operator: enum: - AND - OR type: string required: - operator - filters type: object UserPositionNumericCondition: properties: field: enum: - totalBoughtShares - totalBoughtUsd - totalSoldShares - totalSoldUsd - currentlyHeldShares - avgBuyingPrice - avgSellingPrice - realizedPnl - totalBuyCost - realizedAvgBuyingPrice - totalTrades - unrealizedUsd - positionSize type: string operator: enum: - eq - neq - lt - lte - gt - gte type: string value: oneOf: - format: double type: number - items: format: double type: number minItems: 1 type: array required: - field - operator - value type: object UserPositionIdCondition: properties: field: enum: - positionId - marketId - eventId - tagIds - seriesId type: string operator: enum: - in - notIn type: string value: oneOf: - format: int32 type: integer - items: format: int32 type: integer minItems: 1 type: array required: - field - operator - value type: object UserPositionAddressCondition: description: inCohort/notInCohort take cohort ids instead of addresses. properties: field: enum: - userId type: string operator: enum: - in - notIn - matches - notMatches - inCohort - notInCohort type: string value: oneOf: - type: string - items: type: string minItems: 1 type: array required: - field - operator - value type: object UserPositionTimeCondition: description: >- last takes {unit, length}; between takes {from, to}; since takes a date or {range}. properties: field: enum: - firstTradeTimestamp - latestTradeTimestamp type: string operator: enum: - last - between - since type: string value: oneOf: - description: 'last: a trailing window' properties: length: minimum: 1 type: integer unit: enum: - day - week - month - quarter - year type: string required: - unit - length type: object - description: 'between: a fixed range' properties: from: format: date type: string to: format: date type: string required: - from - to type: object - description: 'since: an open-ended range from a calendar unit' properties: range: enum: - week - month - quarter - year type: string required: - range type: object - description: 'since: an open-ended range from a date' format: date type: string required: - field - operator - value type: object UserPositionFilterInnerGroup: description: >- A nested group. Its members must be conditions, which bounds grouping at two levels. properties: filters: items: $ref: '#/components/schemas/UserPositionCondition' minItems: 1 type: array operator: enum: - AND - OR type: string required: - operator - filters type: object securitySchemes: ApiKeyAuth: description: API key issued for programmatic access. in: header name: X-Api-Key type: apiKey BearerAuth: bearerFormat: JWT description: User access token. scheme: bearer type: http ````