List open positions

View Markdown Ask in ChatGPT Ask in Claude

Your open positions as a point-in-time snapshot, largest position first. The body is identical to the all_positions frame the positions:{user_id} WebSocket channel sends on join, so a REST read can seed state that channel updated_positions deltas then keep current. This is a snapshot, not a feed: subscribe to the channel to hear about changes. Not paginated: the list is bounded by the markets you hold a live position in, and there is no cursor. A market you traded and closed out can appear with position "0.00" until it settles. Positions are not marked to market.

GET

/api/v1/positions

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. Returns only positions in these markets; an id you hold no position in matches nothing. Omit for every open position.

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/positions' \
  --header 'X-STX-ACCESS-KEY: <key-id>' \
  --header 'X-STX-ACCESS-TIMESTAMP: <unix-ms>' \
  --header 'X-STX-ACCESS-SIGNATURE: <base64-ed25519>'

Response 200:

{
  "positions": [
    {
      "account_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "average_open_premium": "0.6700",
      "buy_order_liability": "0.6700",
      "contracts_settled": "2.00",
      "event_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "gross_pnl": "0.6700",
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "market_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "max_potential_fee": "0.6700",
      "max_potential_profit": "0.6700",
      "max_risk": "0.6700",
      "open_potential_fee": "0.6700",
      "open_potential_profit": "0.6700",
      "open_risk": "0.6700",
      "position": "2.00",
      "position_premium_liability": "0.6700",
      "premium": "0.6700",
      "sell_order_liability": "0.6700",
      "total_fee": "0.6700",
      "total_settlement_pnl": "0.6700"
    }
  ]
}

Response fields

Field	Type	Description
`account_id`	uuid	The account the position belongs to.
`average_open_premium`	decimal	Average premium per contract for the open portion. In dollars.
`buy_order_liability`	decimal	Liability from your open buy orders on this market. In dollars.
`contracts_settled`	decimal	Contracts settled in the position so far.
`event_id`	uuid	The event the market belongs to.
`gross_pnl`	decimal	`total_settlement_pnl` plus any pending-close profit or loss that has not settled yet. In dollars.
`id`	uuid	The unique id of the position record.
`market_id`	uuid	The market the position is on.
`max_potential_fee`	decimal	Total potential fee across the position’s settlements. In dollars.
`max_potential_profit`	decimal	Total possible profit for the position if everything settles favorably. In dollars.
`max_risk`	decimal	Account-level risk on the position, netting in already settled profit and loss. In dollars.
`open_potential_fee`	decimal	Potential fee on the open contracts when they settle. In dollars.
`open_potential_profit`	decimal	Possible profit on the position’s open contracts. In dollars.
`open_risk`	decimal	Risk on the position’s open (unsettled) contracts. In dollars.
`position`	decimal	Net position in the market: positive if long (bought), negative if short (sold). Can be `"0.00"` for a market you have traded and closed out that has not settled yet. In contracts.
`position_premium_liability`	decimal	Liability from the position’s premium that counts against available balance. Routinely negative. In dollars.
`premium`	decimal	Total premium paid or received for the open portion of the position. In dollars.
`sell_order_liability`	decimal	Liability from your open sell orders on this market. In dollars.
`total_fee`	decimal	Total fees paid across the position’s settlements. In dollars.
`total_settlement_pnl`	decimal	Profit or loss realized from settlements so far. In dollars.

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