> ## Documentation Index > Fetch the complete documentation index at: https://api.polymarketanalytics.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Profit & Loss > Retrieves realized profit and loss (PnL) for a given wallet address over a specified time range and aggregation interval. You may optionally filter results to a single market using `condition_id`. Unlike Polymarket’s dashboard, which displays unrealized PnL, this API reports realized gains only, calculated from confirmed sell transactions or fully settled (closed) markets. **Platform:** Polymarket\ **Endpoint:** `POST /v2/semantic/retrieve/parameterized`\ **Authentication:** Bearer token ## Query parameters All requests use `agent_id` `569` (Profit & Loss). Set filters inside `params` in the playground — all values must be strings. | Parameter | Type | Description | | - | - | - | | `granularity` | String | Aggregation interval: `1d`, `3d`, `1w`, `1m`, or `all`. | | `wallet` | String | Wallet address (for example, `"0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd"`). | | `start_time` | String | Start of the time range (for example, `"2026-02-10"`). | | `end_time` | String | End of the time range (for example, `"2026-02-28"`). | ## Example Request ```bash cURL theme={null} curl --request POST \ --url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \ --header 'Authorization: Bearer YOUR_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "agent_id": 569, "params": { "granularity": "1d", "wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd", "start_time": "2026-02-10", "end_time": "2026-02-28" }, "pagination": { "limit": 10, "offset": 0 }, "formatter_config": { "format_type": "raw" } }' ``` ```python Python theme={null} import requests response = requests.post( "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized", headers={"Authorization": "Bearer YOUR_TOKEN"}, json={ "agent_id": 569, "params": { "granularity": "1d", "wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd", "start_time": "2026-02-10", "end_time": "2026-02-28" }, "pagination": { "limit": 10, "offset": 0 }, "formatter_config": { "format_type": "raw" } } ) print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch("https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized", { method: "POST", headers: { "Authorization": "Bearer YOUR_TOKEN", "Content-Type": "application/json" }, body: JSON.stringify({ "agent_id": 569, "params": { "granularity": "1d", "wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd", "start_time": "2026-02-10", "end_time": "2026-02-28" }, "pagination": { "limit": 10, "offset": 0 }, "formatter_config": { "format_type": "raw" } }) }); const data = await response.json(); ``` ## Example Response ```json theme={null} { "timestamp": "", "params": { "condition_id": "ALL", "end_time": "2026-02-28", "granularity": "1d", "start_time": "2026-02-10", "wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd" }, "pagination": { "limit": 200, "offset": 0, "has_more": true }, "data": { "results": [ { "date": "2026-02-19T00:00:00Z", "invested": "830494.18", "losses": 0, "pnl": "0.00", "proxy_wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd", "trades": 3342, "win_rate": "0.00", "wins": 0 }, { "date": "2026-02-20T00:00:00Z", "invested": "241245.70", "losses": 18, "pnl": "-302209.22", "proxy_wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd", "trades": 406, "win_rate": "0.49", "wins": 2 } ] } } ``` ## Response fields | Field | Type | Description | | - | - | - | | `date` | String (ISO 8601) | Date for which the performance metrics are aggregated | | `proxy_wallet` | String | Wallet address for which performance is calculated | | `invested` | String (Decimal) | Total amount invested during the period | | `pnl` | String (Decimal) | Net profit and loss for the period (negative values indicate a loss) | | `trades` | Integer | Total number of trades executed during the period | | `wins` | Integer | Number of profitable trades | | `losses` | Integer | Number of losing trades | | `win_rate` | String (Decimal) | Proportion of winning trades (0–1 or percentage, depending on client interpretation) | ## OpenAPI ````yaml /api-reference/polymarket-profit-and-loss.openapi.json POST /api/v2/semantic/retrieve/parameterized openapi: 3.1.0 info: title: Falcon API — Profit & Loss version: 1.0.0 servers: - url: https://narrative.agent.heisenberg.so description: Production security: - bearerAuth: [] paths: /api/v2/semantic/retrieve/parameterized: post: tags: - Polymarket summary: Profit & Loss description: >- Retrieves realized profit and loss for a wallet over a time range and aggregation interval. operationId: polymarketProfitAndLoss requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PolymarketProfitAndLossRequest' examples: default: summary: Daily PnL for a wallet value: agent_id: 569 params: granularity: 1d wallet: '0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd' start_time: '2026-02-10' end_time: '2026-02-28' pagination: limit: 10 offset: 0 formatter_config: format_type: raw responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/PolymarketProfitAndLossResponse' '400': description: Bad request — check params '401': description: Unauthorized — check your Bearer token x-codeSamples: - lang: curl label: cURL source: |- curl --request POST \ --url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \ --header 'Authorization: Bearer YOUR_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "agent_id": 569, "params": { "granularity": "1d", "wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd", "start_time": "2026-02-10", "end_time": "2026-02-28" }, "pagination": { "limit": 10, "offset": 0 }, "formatter_config": { "format_type": "raw" } }' - lang: python label: Python source: |- import requests response = requests.post( "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized", headers={"Authorization": "Bearer YOUR_TOKEN"}, json={ "agent_id": 569, "params": { "granularity": "1d", "wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd", "start_time": "2026-02-10", "end_time": "2026-02-28", }, "pagination": {"limit": 10, "offset": 0}, "formatter_config": {"format_type": "raw"}, }, ) print(response.json()) - lang: javascript label: JavaScript source: |- const response = await fetch( "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized", { method: "POST", headers: { Authorization: "Bearer YOUR_TOKEN", "Content-Type": "application/json", }, body: JSON.stringify({ agent_id: 569, params: { granularity: "1d", wallet: "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd", start_time: "2026-02-10", end_time: "2026-02-28", }, pagination: { limit: 10, offset: 0 }, formatter_config: { format_type: "raw" }, }), } ); const data = await response.json(); components: schemas: PolymarketProfitAndLossRequest: type: object required: - params properties: agent_id: type: integer enum: - 569 default: 569 x-default: 569 description: Profit & Loss agent ID. params: $ref: '#/components/schemas/PolymarketProfitAndLossParams' pagination: $ref: '#/components/schemas/PolymarketProfitAndLossPagination' formatter_config: $ref: '#/components/schemas/PolymarketProfitAndLossFormatterConfig' PolymarketProfitAndLossResponse: type: object readOnly: true properties: timestamp: type: string readOnly: true params: $ref: '#/components/schemas/PolymarketProfitAndLossResponseParams' pagination: type: object readOnly: true properties: limit: type: integer readOnly: true offset: type: integer readOnly: true has_more: type: boolean readOnly: true data: type: object readOnly: true properties: results: type: array readOnly: true items: type: object readOnly: true additionalProperties: true request_id: type: string readOnly: true PolymarketProfitAndLossParams: type: object description: Filter parameters. All values must be strings. additionalProperties: false required: - granularity - wallet - start_time - end_time properties: granularity: type: string enum: - 1d - 3d - 1w - 1m - all default: 1d description: Aggregation interval (for example, "1d"). wallet: type: string default: '0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd' description: Wallet address to retrieve PnL for. start_time: type: string default: '2026-02-10' description: Start of the time range (for example, "2026-02-10"). end_time: type: string default: '2026-02-28' description: End of the time range (for example, "2026-02-28"). PolymarketProfitAndLossPagination: type: object properties: limit: type: integer minimum: 1 maximum: 200 default: 10 description: Maximum number of records returned per request. offset: type: integer minimum: 0 default: 0 description: Number of records to skip before returning results. PolymarketProfitAndLossFormatterConfig: type: object properties: format_type: type: string enum: - raw default: raw description: Output format. Use "raw" for structured JSON. PolymarketProfitAndLossResponseParams: type: object readOnly: true properties: granularity: type: string readOnly: true wallet: type: string readOnly: true start_time: type: string readOnly: true end_time: type: string readOnly: true condition_id: type: string readOnly: true securitySchemes: bearerAuth: type: http scheme: bearer description: Your Falcon API key from the dashboard ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.