> ## 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. # Polymarket Trades > Returns historical trade data from Polymarket with different filters such as trader's address and market slug. **Platform:** Polymarket\ **Endpoint:** `POST /v2/semantic/retrieve/parameterized`\ **Authentication:** Bearer token ## Query parameters All requests use `agent_id` `556` (Polymarket Trades). Set filters inside `params` in the playground — all values must be strings. | Parameter | Type | Description | | - | - | - | | `proxy_wallet` | String | Filter by wallet address. Use `"ALL"` for every wallet. | | `condition_id` | String | Market condition ID. Use `"ALL"` for every market. | | `market_slug` | String | Filter by market slug (for example, `"bitcoin-up-or-down-january-9-10am-et"`). | | `start_time` | String | Earliest trade time: Unix timestamp in seconds. | | `end_time` | String | Latest trade time: Unix timestamp in seconds. | ## 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": 556, "params": { "proxy_wallet": "ALL", "condition_id": "ALL", "market_slug": "bitcoin-up-or-down-january-9-10am-et", "start_time": "1767973812", "end_time": "1767973860" }, "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": 556, "params": { "proxy_wallet": "ALL", "condition_id": "ALL", "market_slug": "bitcoin-up-or-down-january-9-10am-et", "start_time": "1767973812", "end_time": "1767973860" }, "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": 556, "params": { "proxy_wallet": "ALL", "condition_id": "ALL", "market_slug": "bitcoin-up-or-down-january-9-10am-et", "start_time": "1767973812", "end_time": "1767973860" }, "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": "1767973860", "market_slug": "bitcoin-up-or-down-january-9-10am-et", "proxy_wallet": "ALL", "start_time": "1767973812", "wallet_proxy": "ALL" }, "pagination": { "limit": 10, "offset": 0, "has_more": true }, "data": { "results": [ { "condition_id": "0x584654c869a3f1868f3ad1248e11ea988f3c4e332002839c6cac0e6db94485ee", "id": "0x19320a9cfc47d70e2ac56c25b3555a34f402484a236267a8c220fa060eba74c7_0x1e30835026c910cd5f676a504ce8c39666917f402dfe93bb46c19adf6b152c13", "outcome": "Down", "price": 0.001, "proxy_wallet": "0x11514fb5ef1e3fe110691243714fcf2182db1fed", "side": "BUY", "size": 225.23, "slug": "bitcoin-up-or-down-january-9-10am-et", "timestamp": "2026-01-09T15:51:00Z", "transaction_hash": "0x19320a9cfc47d70e2ac56c25b3555a34f402484a236267a8c220fa060eba74c7" }, { "condition_id": "0x584654c869a3f1868f3ad1248e11ea988f3c4e332002839c6cac0e6db94485ee", "id": "0x19320a9cfc47d70e2ac56c25b3555a34f402484a236267a8c220fa060eba74c7_0xb07225fa95a2b5dd0f15b3f41f07657d9eb9e928268d4e5ae9fdf7e178049ac7", "outcome": "Down", "price": 0.001, "proxy_wallet": "0x11514fb5ef1e3fe110691243714fcf2182db1fed", "side": "BUY", "size": 14.99, "slug": "bitcoin-up-or-down-january-9-10am-et", "timestamp": "2026-01-09T15:51:00Z", "transaction_hash": "0x19320a9cfc47d70e2ac56c25b3555a34f402484a236267a8c220fa060eba74c7" } ] } } ``` ## Response Fields | Field | Type | Description | | - | - | - | | `id` | String | Unique trade identifier | | `condition_id` | String | Ethereum condition ID for the market | | `price` | Float | Price per share (0–1 range) | | `side` | String | Trade direction: `"BUY"` or `"SELL"` | | `size` | Float | Number of shares traded | | `timestamp` | String (ISO 8601) | Timestamp of trade execution | | `transaction_hash` | String | Ethereum transaction hash | | `slug` | String | Market identifier | | `outcome` | String | Trade outcome (for example, `"Yes"`, `"No"`) | | `proxy_wallet` | String | Trader's wallet address | ## Notes > [!TIP] > > Use Unix timestamps as strings for `start_time` and `end_time`. Combine them with `market_slug` for focused, time-bounded queries. > [!TIP] > > Use pagination for large datasets to avoid timeouts. The `transaction_hash` field can be used to verify any trade directly on-chain. > [!TIP] > > Combine multiple filters for sophisticated queries ## OpenAPI ````yaml /api-reference/polymarket-trades.openapi.json POST /api/v2/semantic/retrieve/parameterized openapi: 3.1.0 info: title: Falcon API — Polymarket Trades 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: Polymarket Trades description: >- Returns historical trade data from Polymarket with filters such as trader wallet, market slug, and time range. operationId: polymarketTrades requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PolymarketTradesRequest' examples: default: summary: Trades for a market and time range value: agent_id: 556 params: proxy_wallet: ALL condition_id: ALL market_slug: bitcoin-up-or-down-january-9-10am-et start_time: '1767973812' end_time: '1767973860' pagination: limit: 10 offset: 0 formatter_config: format_type: raw responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/PolymarketTradesResponse' '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": 556, "params": { "proxy_wallet": "ALL", "condition_id": "ALL", "market_slug": "bitcoin-up-or-down-january-9-10am-et", "start_time": "1767973812", "end_time": "1767973860" }, "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": 556, "params": { "proxy_wallet": "ALL", "condition_id": "ALL", "market_slug": "bitcoin-up-or-down-january-9-10am-et", "start_time": "1767973812", "end_time": "1767973860" }, "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": 556, "params": { "proxy_wallet": "ALL", "condition_id": "ALL", "market_slug": "bitcoin-up-or-down-january-9-10am-et", "start_time": "1767973812", "end_time": "1767973860" }, "pagination": { "limit": 10, "offset": 0 }, "formatter_config": { "format_type": "raw" } }) }); const data = await response.json(); components: schemas: PolymarketTradesRequest: type: object required: - params properties: agent_id: type: integer enum: - 556 default: 556 x-default: 556 description: Polymarket Trades agent ID. params: type: object description: Query filter parameters. All values must be strings. additionalProperties: false properties: proxy_wallet: type: string default: ALL description: >- Filter by wallet address. Use "ALL" to include trades from every wallet. condition_id: type: string default: ALL description: >- Ethereum condition ID for the market. Use "ALL" to include trades from every market. market_slug: type: string default: bitcoin-up-or-down-january-9-10am-et description: >- Filter trades by a specific market (for example, "bitcoin-up-or-down-january-9-10am-et"). start_time: type: string default: '1767973812' description: >- Trades at or after this Unix timestamp in seconds, inclusive, as a string (for example, "1767973812"). end_time: type: string default: '1767973860' description: >- Trades at or before this Unix timestamp in seconds, inclusive, as a string (for example, "1767973860"). pagination: $ref: '#/components/schemas/PolymarketTradesPagination' formatter_config: $ref: '#/components/schemas/PolymarketTradesFormatterConfig' PolymarketTradesResponse: type: object readOnly: true properties: timestamp: type: string readOnly: true params: $ref: '#/components/schemas/PolymarketTradesResponseParams' 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 PolymarketTradesPagination: 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. PolymarketTradesFormatterConfig: type: object properties: format_type: type: string enum: - raw default: raw description: Output format. Use "raw" for structured JSON. PolymarketTradesResponseParams: type: object description: Echo of request filter parameters returned in the response. readOnly: true properties: proxy_wallet: type: string readOnly: true condition_id: type: string readOnly: true market_slug: type: string readOnly: true start_time: type: string readOnly: true end_time: 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.