> ## Documentation Index > Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt > Use this file to discover all available pages before exploring further. # 获取公开成交记录 > Get fill history for a registered account address. Rows include order IDs, exchange and builder fees, and position accounting. Builder identity and rate are omitted on this public surface. The default window starts 30 days before request time. When instrument_id is provided, returns only fills for that instrument and reads at most 250,000 physical rows; reads exceeding this cap return HTTP 413. Filtered reads cap the end time at the current time and, when the start is omitted, start 30 days before that effective end time. If no end time is provided, the current time will be used. Maximum of 100 entries returned per request. Results are ordered by time; use `sort` to choose newest-first (`desc`, default) or oldest-first (`asc`). To page through more than 100 fills, pass the `cursor` returned by the previous page (keep `sort` consistent across pages). Passing the trade ID of the last fill from the previous page is also accepted for unfiltered requests. When instrument_id is set, legacy numeric cursors are rejected with HTTP 400; use the returned keyset cursor. ## OpenAPI ````yaml api-spec/perps-openapi.json GET /v1/info/fills openapi: 3.0.3 info: title: Polymarket Perps HTTP API version: 1.0.0 description: HTTP API for Polymarket perpetual trading system. license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://api.perpetuals.polymarket.com description: Production Perps HTTP API security: [] paths: /v1/info/fills: get: summary: Get Public Fills description: > Get fill history for a registered account address. Rows include order IDs, exchange and builder fees, and position accounting. Builder identity and rate are omitted on this public surface. The default window starts 30 days before request time. When instrument_id is provided, returns only fills for that instrument and reads at most 250,000 physical rows; reads exceeding this cap return HTTP 413. Filtered reads cap the end time at the current time and, when the start is omitted, start 30 days before that effective end time. If no end time is provided, the current time will be used. Maximum of 100 entries returned per request. Results are ordered by time; use `sort` to choose newest-first (`desc`, default) or oldest-first (`asc`). To page through more than 100 fills, pass the `cursor` returned by the previous page (keep `sort` consistent across pages). Passing the trade ID of the last fill from the previous page is also accepted for unfiltered requests. When instrument_id is set, legacy numeric cursors are rejected with HTTP 400; use the returned keyset cursor. operationId: getPublicFills parameters: - name: address in: query required: true schema: $ref: '#/components/schemas/address' - name: start_timestamp in: query required: false schema: $ref: '#/components/schemas/start_timestamp' - name: instrument_id in: query schema: type: integer format: int64 minimum: 0 maximum: 4294967295 x-js-safe-integer: true - name: end_timestamp in: query required: false schema: $ref: '#/components/schemas/end_timestamp' - name: cursor in: query required: false schema: $ref: '#/components/schemas/cursor' - name: sort in: query required: false schema: $ref: '#/components/schemas/sort' responses: '200': description: Public fills response. content: application/json: schema: $ref: '#/components/schemas/AccountTrades' examples: liquidatedPosition: summary: >- Position opened in two fills, then closed by one liquidation fill value: data: - trade_id: 6790736448213776 order_id: 2237918023271485 instrument_id: 7 side: short price: '2507' quantity: '0.5649' taker: true fee: '7.36426236' builder_fee: '0' total_fee: '7.36426236' fee_asset: pUSD previous_size: '0.5649' previous_entry_price: '2567.1' pnl: '-33.95049' liquidation: true adl: false settlement: false timestamp: 1791466955844 hash: 0x - trade_id: 7117662635645083 order_id: 8048326000529043 instrument_id: 7 side: long price: '2567.1' quantity: '0.3115' taker: true fee: '0.1599303300000000000000000000' builder_fee: '0' total_fee: '0.1599303300000000000000000000' fee_asset: pUSD previous_size: '0' previous_entry_price: '0' pnl: '0' liquidation: false adl: false settlement: false timestamp: 1791377749140 hash: 0x - trade_id: 7117662635645082 order_id: 8048326000529043 instrument_id: 7 side: long price: '2567.1' quantity: '0.2534' taker: true fee: '0.1301006280000000000000000000' builder_fee: '0' total_fee: '0.1301006280000000000000000000' fee_asset: pUSD previous_size: '0' previous_entry_price: '0' pnl: '0' liquidation: false adl: false settlement: false timestamp: 1791377749140 hash: 0x more: false '400': $ref: '#/components/responses/Error400Response' '408': $ref: '#/components/responses/Error408Response' '413': description: >- Account history read exceeds the 250,000-row cap; narrow the time window. content: application/json: schema: $ref: '#/components/schemas/Error413' '429': $ref: '#/components/responses/Error429Response' '500': $ref: '#/components/responses/Error500Response' '503': $ref: '#/components/responses/Error503Response' security: [] components: schemas: address: type: string description: Address example: '0x1234567890abcdef1234567890abcdef12345678' start_timestamp: type: integer description: Start timestamp in milliseconds example: 1767225600000 end_timestamp: type: integer description: End timestamp in milliseconds example: 1767229200000 cursor: type: string description: >- Pagination cursor. Pass the opaque `cursor` returned by the previous page to fetch the next page. Paging follows the `sort` direction (strictly older fills when `sort=desc`, strictly newer when `sort=asc`). The trade ID of the last fill from the previous page is also accepted for backwards compatibility, except on instrument-filtered `/v1/info/fills`, which requires the returned keyset cursor. example: eyJ0cyI6MTc2NzIyNTYwMDAwMDAwMDAwMCwiaWQiOjF9 sort: type: string description: >- Time sort direction. `desc` (default) returns newest fills first; `asc` returns oldest first. default: desc enum: - desc - asc AccountTrades: type: object required: - data - more properties: data: type: array items: $ref: '#/components/schemas/AccountTradeData' description: Account's trade history more: $ref: '#/components/schemas/more' cursor: $ref: '#/components/schemas/fills_cursor' Error413: title: Error413 type: object required: - status - error properties: status: type: string enum: - err error: $ref: '#/components/schemas/error' AccountTradeData: type: object required: - trade_id - order_id - instrument_id - side - price - quantity - taker - fee - builder_fee - total_fee - fee_asset - previous_size - previous_entry_price - pnl - timestamp - liquidation - adl - hash - settlement properties: trade_id: $ref: '#/components/schemas/tid' order_id: $ref: '#/components/schemas/oid' instrument_id: $ref: '#/components/schemas/iid' side: $ref: '#/components/schemas/side' price: $ref: '#/components/schemas/p' quantity: $ref: '#/components/schemas/qty' taker: $ref: '#/components/schemas/taker' fee: $ref: '#/components/schemas/fee' fee_asset: $ref: '#/components/schemas/fea' previous_size: $ref: '#/components/schemas/psz' previous_entry_price: $ref: '#/components/schemas/pep' pnl: $ref: '#/components/schemas/pnl' description: >- Realized trading PnL before exchange and builder fees. Subtract total_fee once to calculate this fill's net trading result. liquidation: $ref: '#/components/schemas/liq' adl: $ref: '#/components/schemas/adl' timestamp: $ref: '#/components/schemas/ts' hash: $ref: '#/components/schemas/hash' builder_fee: $ref: '#/components/schemas/builder_fee' total_fee: $ref: '#/components/schemas/total_fee' builder: $ref: '#/components/schemas/Builder' description: >- Saved terms, only on authenticated account fill surfaces. Public account history omits identity and rate, even when builder_fee is nonzero. settlement: $ref: '#/components/schemas/settlement_fill' liquidation_details: $ref: '#/components/schemas/LiquidationDetails' more: type: boolean description: More data available fills_cursor: type: string description: >- Opaque keyset pagination cursor for the next page of fills. Present while `more` is true; pass it as `cursor` on the next request, keeping the other parameters the same across pages. example: eyJ0cyI6MTc2NzIyNTYwMDAwMDAwMDAwMCwiaWQiOjF9 Error400: title: Error400 type: object required: - status - error properties: status: type: string enum: - err error: $ref: '#/components/schemas/error' Error408: title: Error408 type: object required: - status - error properties: status: type: string enum: - err error: $ref: '#/components/schemas/error' error: type: string description: >- Error identifier. For domain rejections and transport errors (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case identifier that is part of the API contract and safe to branch on, e.g. `insufficient_margin`, `insufficient_balance`, `order_not_found`, `reduce_only_invalid`, `price_outside_bounds`, `position_not_found`, `position_exists`, `open_orders_exist`, `invalid_margin_mode`, `invalid_margin_amount`, `margin_below_required_initial`, `account_liquidating`, `instrument_close_only`, `instrument_settled`, `settlement_price_unavailable`, `settlement_insurance_insufficient`, `settlement_invalid_state`, `unauthorized`, `not_found`. `instrument_close_only` means user orders must reduce an existing position; `instrument_settled` is permanent. Settlement readiness errors leave the instrument and accounts unchanged. For `400` it is a human-readable validation detail whose wording may change. See the Error handling guide for the domain identifiers. (Post-only / Fill-or-Kill outcomes are order statuses such as `post_only_rejected`, not rejections.) example: insufficient_margin Error429: title: Error429 type: object required: - status - error properties: status: type: string enum: - err error: $ref: '#/components/schemas/error' Error500: title: Error500 type: object required: - status - error properties: status: type: string enum: - err error: $ref: '#/components/schemas/error' Error503: title: Error503 type: object required: - status - error properties: status: type: string enum: - err error: $ref: '#/components/schemas/error' tid: type: integer description: Trade ID example: 1 oid: type: integer description: Order ID example: 1234567890 iid: type: integer description: Instrument ID example: 1 side: type: string description: Side enum: - long - short p: type: string description: Price example: '100.00' qty: type: string description: Quantity in no. of contracts example: '10.00' taker: type: boolean description: Whether this side was the taker fee: type: string description: >- Signed exchange fee for this trade side, excluding builder_fee. Negative values are rebates example: '1.25' fea: type: string description: Fee asset name example: USDC psz: type: string description: Position size before the fill example: '26.86' pep: type: string description: Position entry price before the fill example: '100.00' pnl: type: string description: PnL in USD example: '100.00' liq: type: boolean description: >- Whether this fill was part of a liquidation of the account's position — true on forced closes and on any fill executed while the account was under liquidation on the instrument, maker or taker. False on the counterparty leg of an auto-deleveraging or backstop match — its fill is part of someone else's liquidation, flagged by `adl` where applicable adl: type: boolean description: Whether the fill came from auto-deleveraging ts: type: integer description: >- Request timestamp. Unix milliseconds for most operations; Unix seconds for withdrawals (must match the on-chain EIP-712 struct verified against block.timestamp). example: 1767225600000 hash: type: string description: On-chain transaction hash, "0x" if not yet mined default: 0x example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' builder_fee: type: string description: >- Actual additional builder fee in the same asset as fee, floored independently for each execution to that asset's token decimals (six for pUSD), with discarded dust and no carry. The fee is non-negative and is zero for older or untagged fills and excluded forced liquidation legs. example: '20.00' total_fee: type: string description: >- Exact signed sum of exchange fee and builder_fee in the same asset. May be negative when exchange rebates exceed the builder charge. example: '24.00' Builder: type: object description: >- Saved builder terms. Address is the registered Perps account, and fee_rate is an additional fraction of executed notional. Terms survive approval revocation for existing orders. required: - address - fee_rate properties: address: $ref: '#/components/schemas/address' fee_rate: $ref: '#/components/schemas/builder_fee_rate' settlement_fill: type: boolean description: >- Whether this fill closes a position during permanent instrument settlement. Settlement fills use the final settlement price and have no fees or liquidation penalties; they are not normal market trades or ADL. LiquidationDetails: type: object required: - mark - method properties: liquidated_user: type: string description: >- Checksummed address of the liquidated account. Present on authenticated fill surfaces and, on public account-scoped routes, only on the liquidated account's own rows; absent on fund-side public rows and the anonymous trade tape. mark: type: string description: >- Mark price captured when the liquidation command was issued. The fill price itself stays the accounting price. method: type: string enum: - market - backstop description: >- How the position was liquidated. Only backstop is emitted today; market is reserved for order-book liquidations, which currently carry no liquidation_details. builder_fee_rate: type: string description: >- Additional builder fee as a decimal fraction of executed notional, from 0 through 0.001 (10 basis points). Zero approval revokes future admission. Never a percentage string. example: '0.001' responses: Error400Response: description: | Bad request — the request was malformed or failed validation (bad query parameters, unparseable body, invalid signature, or a domain pre-check). The `error` field is a human-readable validation detail. content: application/json: schema: $ref: '#/components/schemas/Error400' Error408Response: description: | Request Timeout — the request body was not delivered within the gateway's read deadline. Protects against slow uploads holding connections open; send the complete body promptly and retry. `error` is `request_body_timeout`. content: application/json: schema: $ref: '#/components/schemas/Error408' Error429Response: description: > Too Many Requests. `error` distinguishes the limit that was hit: `ip_rate_limited` (per-IP token bucket), `action_rate_limited` (per-account action rate), or `open_orders_limit` (resting open-order cap). headers: Retry-After: description: > Whole seconds to wait before retrying. Present only on token-bucket rate-limit rejections (`ip_rate_limited` and `action_rate_limited`); a conservative estimate of when enough capacity will have refilled to admit the request. Absent on `open_orders_limit`, which is a capacity limit, not a rate limit — waiting does not free order slots; cancel resting orders or wait for fills instead. schema: type: integer example: 2 content: application/json: schema: $ref: '#/components/schemas/Error429' Error500Response: description: | Internal server error. `error` is `internal_error`. content: application/json: schema: $ref: '#/components/schemas/Error500' Error503Response: description: | Service unavailable — safe to retry with backoff, honoring `Retry-After` when present. `error` is `service_unavailable`. Most causes are a request deliberately shed before it reached the engine, so the request definitely did not execute: the replica's pod-level in-flight cap (shed before dispatch, with `Retry-After`), a database read shed as backpressure under overload (by the local read gate or by the database server's concurrency cap — the query never executed), a required internal cache that is stale or not yet primed and would return wrong data, or a full bounded deferred-write queue. On a subset of order/state-mutating routes, this status is also returned when the engine round-trip itself times out with zero responses observed. That is retryable engine backpressure, but — unlike the sheds above — it does not prove non-execution: the command may already have been admitted, with its response simply not reaching the gateway before the deadline. This status is only used for that case on routes that are safe to retry regardless (idempotent state-setting, or an engine-side replay guard); routes where a bare retry cannot safely resolve the ambiguity keep the outcome a non-retryable 500 instead. headers: Retry-After: description: | Whole seconds to wait before retrying. Present on pre-dispatch in-flight-cap sheds — a transient overload signal, so the hint is short and constant. schema: type: integer example: 1 content: application/json: schema: $ref: '#/components/schemas/Error503' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.