Fills

A fill is one trade print at the venue. Fills are the ledger every other number is derived from: a position's entry prices, a closed trade's realized PnL, and the fees you paid.

Endpoint	Returns
`GET /fills`	Fills across the trade account, paginated.
`GET /fills/{positionId}`	Every fill of one position, unpaginated.
`GET /fills/provisionals-lite`	Provisional fills, trimmed to the fields a syncer needs.

Read the fills of a position

curl "https://pro-gateway.pearprotocol.io/fills/$POSITION_ID" \
  -H "x-api-key: $PEAR_API_KEY" \
  -H "x-trade-account-id: $TRADE_ACCOUNT_ID"

{
  "fills": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "tradeAccountId": "5e7a1b20-8c34-4d19-b6f0-a1c2d3e4f567",
      "positionId": "9c1b2d3e-4f56-4789-a0b1-c2d3e4f56789",
      "connector": "hyperliquid",
      "symbol": "0",
      "side": "BUY",
      "status": "CONFIRMED",
      "quantity": "0.0052",
      "price": "96150.5",
      "usd": "500.00",
      "tradeFee": "0.22",
      "pearFee": "0.05",
      "reduceOnly": false,
      "isExternal": false,
      "synthetic": false,
      "cloid": "0x9f2c4a7e10b3486d",
      "exchangeFillId": "42917338",
      "timestamp": "2026-01-01T00:00:01.240Z"
    }
  ]
}

This endpoint takes no query parameters and returns no limit or nextCursor. It returns the position's entire fill ledger in one response, oldest first. It is scoped by trade account only, not by venue.

symbol is the instrument ID, not the ticker. See Instrument ID.

Fields

Field	Meaning
`quantity`, `price`	What filled, and at what price.
`usd`	The notional of the fill.
`tradeFee`	The exchange's fee. Optional, and usually absent on a `PROVISIONAL` fill.
`pearFee`	Pear's fee. Optional, and usually absent on a `PROVISIONAL` fill. See Trading Fees.
`reduceOnly`	Whether the order that produced it was reduce-only.
`tradeAccountId`	The trade account the fill belongs to.
`cloid`	The client order id Pear sent to the venue. Use it to match a fill to your own request. Optional.
`exchangeFillId`	The venue's own id for the print. Optional.
`isExternal`	`true` when the fill came from outside Pear, such as a trade placed on the exchange directly.
`synthetic`	`true` for a bridge fill Pear reconstructed to close a gap in the ledger, rather than a print the venue reported. On an unpriceable gone-close synthetic, `price` and `usd` are the literal string `"0"`. `"0"` is otherwise a real price, so check `synthetic` before trusting a zero.
`original`	Present only when one venue print spanned several positions. Pear splits that print into one fill per position and gives each a synthetic `exchangeFillId`; `original` carries the root print's `{ exchangeFillId, quantity }`. Use it to fold the parts back together.

Fill status

`status`	Meaning
`PROVISIONAL`	Recorded from the order result, before the venue's own record arrived. Fees may still change.
`CONFIRMED`	Settled with the venue's own record.
`RECONCILED`	Superseded. Never returned by either endpoint.

Neither fills endpoint ever returns a RECONCILED fill. When the venue's record supersedes a provisional fill, Pear marks the provisional RECONCILED and it disappears from these endpoints, replaced by a new CONFIRMED fill. So a fill can vanish and a different id take its place. Match on exchangeFillId where one is present, rather than on the fill's id. The transitions are driven by Pear's fill sync, exposed as the POST /sync/fills/* endpoints.

Treat PROVISIONAL fees as an estimate. If you compute PnL yourself, wait for CONFIRMED or read the composed numbers from Closed Position instead.

Listing across the account

curl "https://pro-gateway.pearprotocol.io/fills?limit=100&orderBy=-timestamp" \
  -H "x-api-key: $PEAR_API_KEY" \
  -H "x-trade-account-id: $TRADE_ACCOUNT_ID"

Parameter	Values
`orderBy`	`-timestamp` (newest first, the default) or `timestamp` (oldest first). Nothing else.
`limit`	Default `20`, maximum `2000`.
`cursor`	The `nextCursor` of the previous page.
`connector`	Accepted and ignored. The venue comes from the trade account.

GET /fills/provisionals-lite returns only id, positionId, symbol, cloid, and status. It exists so a syncer can find what still needs settling without pulling whole fill objects. Like the per-position read, it takes no query parameters and does not page.

Live updates

Fills stream over the WebSocket as part of the execution and position events. The action a fill belongs to is at Execution.

Read the fills of a position

Fields

Fill status

Listing across the account

Live updates

On this page