List fills

View Markdown Ask in ChatGPT Ask in Claude

Fills for the authenticated account, most recent first. One order can produce many fills, each with its own price, fee and liquidity side.

GET

/api/v1/fills

Try it

Jurisdiction (demo)Base URL

Key ID stx_access_keyPrivate key (PEM or base64 seed) stx_private_key

Request

Every endpoint, in one place: the full Try it.

Signing happens in your browser with WebCrypto. Your private key is never sent anywhere; Send request sends your key ID and the signature to the demo host above. Only demo hosts are offered. The key ID and private key are saved in this browser's local storage, per jurisdiction, until you click Clear saved key. Use a demo key here, never a production one.

Parameters

Name	In	Type	Required	Description
`market_ids`	`query`	string	no	Comma-separated market UUIDs.
`order_ids`	`query`	string	no	Comma-separated order UUIDs. Returns only the fills those orders produced. Combines with `market_ids` and `status` (all filters must match), and pages with `cursor` like any other filter. An order id that is not yours matches nothing rather than erroring.
`status`	`query`	`created` \| `open` \| `settled` \| `cancelled`	no	A single fill status. This filter takes one value, not a comma-separated list.
`limit`	`query`	integer	no	Rows per page. Defaults to 100 and is silently clamped to 200; a larger value is not an error.
`cursor`	`query`	string	no	Cursor from the previous response. Omit for the first page.

Responses

Status	Description	Schema
`200`	Success	object
`400`	A parameter was missing or invalid.	Error
`401`	Missing, malformed or unrecognized signature, or a timestamp outside the 30-second window. Body: {“error”:“Missing or invalid API key credentials”}	Error
`403`	The account behind this key is not active, for example it is pending approval or suspended. Body: {“error”:“Your account is suspended. Contact support.”}, the message naming the account’s status.	Error

Example

Request:

curl --request GET \
  --url 'https://demo.stxapp.io/api/v1/fills' \
  --header 'X-STX-ACCESS-KEY: <key-id>' \
  --header 'X-STX-ACCESS-TIMESTAMP: <unix-ms>' \
  --header 'X-STX-ACCESS-SIGNATURE: <base64-ed25519>'

Response 200:

{
  "cursor": null,
  "fills": [
    {
      "account_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "action": "buy",
      "admin_log": null,
      "amended": null,
      "client_order_id": null,
      "closed_contracts": "2.00",
      "closed_fee": "0.6700",
      "closed_net_pnl": "0.6700",
      "closed_pnl": "0.6700",
      "closing": "2.00",
      "device_id": null,
      "expired_contracts": "2.00",
      "expired_fee": "0.6700",
      "expired_net_pnl": "0.6700",
      "expired_pnl": "0.6700",
      "expires_at": null,
      "filled": "2.00",
      "gross_pnl": "0.6700",
      "inserted_at": 0,
      "ip_address": null,
      "last_modified_at": null,
      "last_modified_by_admin_id": null,
      "liquidity_action": null,
      "market_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "opened_at": null,
      "order_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "original_filled": "2.00",
      "original_premium": "0.6700",
      "original_price": "0.6700",
      "original_risk": "0.6700",
      "original_to_win": "0.6700",
      "pc_premium": "0.6700",
      "pc_risk": "0.6700",
      "pc_to_win": "0.6700",
      "placed_pre_start": null,
      "points": null,
      "pre_start": null,
      "price": "0.6700",
      "remaining": "2.00",
      "remaining_potential_fee": "0.6700",
      "remaining_premium": "0.6700",
      "remaining_risk": "0.6700",
      "remaining_to_win": "0.6700",
      "settled_at": null,
      "settled_contracts": "2.00",
      "settlements_count": null,
      "status": "created",
      "time": "2026-08-25T04:42:46.242093Z",
      "total_fee": "0.6700",
      "trade_fee": "0.6700",
      "trade_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "traded_contracts": "2.00",
      "unrounded_trade_fee": "0.012345678",
      "updated_at": null,
      "virtual_remaining": "2.00"
    }
  ]
}

Response fields

Field	Type	Description
`cursor`	string	Opaque cursor for the next page. Pass the value from the previous response; omit for the first page. `null` once there are no more pages.
`account_id`	uuid	The account the record belongs to.
`action`	string	The action of the trade relative to the user.
`admin_log`	object	Internal. Operator audit trail, not part of the supported contract; do not depend on it.
`amended`	boolean	True if STX has amended this trade. When true, compare `original_price` and `original_filled` against the current values.
`client_order_id`	string	The client order id of the order that produced this trade, when one was supplied.
`closed_contracts`	decimal	The number of contracts closed on this trade.
`closed_fee`	decimal	The fee the user paid when closing the trade. In dollars.
`closed_net_pnl`	decimal	Realized profit or loss on the closed portion. Negative for a loss. In dollars.
`closed_pnl`	decimal	The profit or loss the user made by closing the trade. In dollars.
`closing`	decimal	The amount of contracts (in position) that the trade is closing.
`device_id`	string	The device associated with this trade.
`expired_contracts`	decimal	Number of contracts settled when market expired.
`expired_fee`	decimal	The fee paid by the user when the market expired. In dollars.
`expired_net_pnl`	decimal	Realized profit or loss on the expired portion. In dollars.
`expired_pnl`	decimal	The profit or loss on the trade when the market expired. In dollars.
`expires_at`	int64	When the trade expires if the market has not settled, as UNIX microseconds.
`filled`	decimal	The number of contracts that were traded.
`gross_pnl`	decimal	The gross PNL as a result of the trade. In dollars.
`inserted_at`	int64	Creation time, as UNIX microseconds.
`ip_address`	string	The IP address associated with this trade
`last_modified_at`	int64	When STX last amended this trade, as UNIX microseconds. Null unless `amended` is true.
`last_modified_by_admin_id`	uuid	Internal. Operator audit field, not part of the supported contract; do not depend on it.
`liquidity_action`	string	Whether the associated order was the `provider` or the `taker` of the liquidity.
`market_id`	uuid	The market this record relates to.
`opened_at`	int64	When the position opened, as UNIX microseconds.
`order_id`	uuid	The ID of the order that caused the trade.
`original_filled`	decimal	Contracts filled at execution, before any amendment.
`original_premium`	decimal	The amount of premium received for the original trade. In dollars.
`original_price`	decimal	Fill price at execution. Unchanged by later amendments. In dollars.
`original_risk`	decimal	The original risk introduced for the original trade excluding `closed`. In dollars.
`original_to_win`	decimal	The original gain if the position wins, for the trade excluding `closed`. In dollars.
`pc_premium`	decimal	The amount of premium per contract. In dollars.
`pc_risk`	decimal	The amount of risk per contract. In dollars.
`pc_to_win`	decimal	What each contract gains if the position wins: `max_price - price` on a buy, `price` on a sell. In dollars.
`placed_pre_start`	boolean	True if the order was placed before the event started.
`points`	number	The total number of loyalty points awarded as a result of making the trade.
`pre_start`	boolean	Whether the trade was based on pre-start activity.
`price`	decimal	The price that the trade was executed at. In dollars.
`remaining`	decimal	The number of unsettled contracts in the trade.
`remaining_potential_fee`	decimal	The potential fee from unsettled contracts. In dollars.
`remaining_premium`	decimal	Premium as yet unsettled. In dollars.
`remaining_risk`	decimal	The total current risk for the trade. In dollars.
`remaining_to_win`	decimal	What the unsettled contracts gain if the position wins. In dollars.
`settled_at`	date-time	The timestamp when this trade’s status was set to `settled`
`settled_contracts`	decimal	Contracts already settled. Below `traded_contracts` on a partial settlement.
`settlements_count`	integer	The number of settlements where this trade is the opening trade.
`status`	string	Fill state. `created` once the matching engine has written the fill, `open` while the position is live, `settled` once it no longer contributes to a position, and `cancelled` if STX reversed it.
`time`	date-time	The ISO-8601 Date time the trade was created.
`total_fee`	decimal	Sum of on-trade fee plus fees paid from settlements linked with the trade. In dollars.
`trade_fee`	decimal	Per-trade fee (on-trade fee schedule). Included in total_fee. In dollars.
`trade_id`	uuid	Unique identifier for the trade.
`traded_contracts`	decimal	Number of contracts in this trade.
`unrounded_trade_fee`	decimal	Fee before rounding. Use the rounded fee for reconciliation. In dollars. Carries up to 9 decimal places; parse money with a variable-scale decimal type, not a fixed-width one.
`updated_at`	int64	Time of the last change, as UNIX microseconds.
`virtual_remaining`	decimal	Remaining contracts including unsettled exposure.

v1.5.9Changelog llms.txt llms-full.txt