Private WebSocket

The Private WebSocket endpoint provides real-time updates for user-specific data including orders, positions, and account balances.

Authentication RequiredThis WebSocket endpoint requires API key authentication in the connection handshake. See the Authentication guide for details.

Endpoint

wss://api.polymarket.us/v1/ws/private

Subscription Types

Value	Description
`SUBSCRIPTION_TYPE_ORDER`	Order updates (new, filled, canceled)
`SUBSCRIPTION_TYPE_ORDER_SNAPSHOT`	Initial snapshot of open orders
`SUBSCRIPTION_TYPE_POSITION`	Position changes
`SUBSCRIPTION_TYPE_ACCOUNT_BALANCE`	Account balance changes

Order Subscriptions

{
  "subscribe": {
    "requestId": "order-sub-1",
    "subscriptionType": "SUBSCRIPTION_TYPE_ORDER",
    "marketSlugs": ["market-slug-1"]
  }
}

Leave marketSlugs empty to subscribe to all markets.

Order Snapshot Response

Initial snapshot of open orders:

{
  "requestId": "order-sub-1",
  "subscriptionType": "SUBSCRIPTION_TYPE_ORDER",
  "orderSubscriptionSnapshot": {
    "orders": [
      {
        "id": "order-123",
        "marketSlug": "market-slug-1",
        "side": "ORDER_SIDE_BUY",
        "type": "ORDER_TYPE_LIMIT",
        "price": {"value": "0.555", "currency": "USD"},
        "quantity": 0.5,
        "leavesQuantity": 0.5,
        "state": "ORDER_STATE_PENDING_NEW",
        "intent": "ORDER_INTENT_BUY_LONG",
        "tif": "TIME_IN_FORCE_GOOD_TILL_CANCEL"
      }
    ],
    "eof": true
  }
}

Order Update Response

Real-time order execution updates:

{
  "requestId": "order-sub-1",
  "subscriptionType": "SUBSCRIPTION_TYPE_ORDER",
  "orderSubscriptionUpdate": {
    "execution": {
      "id": "exec-456",
      "order": {...},
      "lastShares": "0.25",
      "lastPx": {"value": "0.555", "currency": "USD"},
      "type": "EXECUTION_TYPE_PARTIAL_FILL",
      "tradeId": "trade-789"
    }
  }
}

Order quantities can contain decimals for partial-contract markets. lastShares is a string and may also contain a decimal quantity.

Position Subscriptions

{
  "subscribe": {
    "requestId": "pos-sub-1",
    "subscriptionType": "SUBSCRIPTION_TYPE_POSITION",
    "marketSlugs": ["market-slug-1"]
  }
}

Position Update Response

{
  "requestId": "pos-sub-1",
  "subscriptionType": "SUBSCRIPTION_TYPE_POSITION",
  "positionSubscription": {
    "beforePosition": {
      "netPosition": "1",
      "netPositionDecimal": "1.0000",
      "cost": {"value": "55.00", "currency": "USD"}
    },
    "afterPosition": {
      "netPosition": "2",
      "netPositionDecimal": "1.5000",
      "cost": {"value": "82.50", "currency": "USD"}
    },
    "updateTime": "2024-01-15T10:30:00Z",
    "entryType": "LEDGER_ENTRY_TYPE_ORDER_EXECUTION",
    "tradeId": "trade-789"
  }
}

Position messages can include netPositionDecimal, qtyBoughtDecimal, qtySoldDecimal, bodPositionDecimal, and qtyAvailableDecimal, matching GET /v1/portfolio/positions. Use those fields when present; the older integer fields are rounded and remain for backward compatibility.

Account Balance Subscriptions

{
  "subscribe": {
    "requestId": "balance-sub-1",
    "subscriptionType": "SUBSCRIPTION_TYPE_ACCOUNT_BALANCE"
  }
}

Balance Snapshot Response

{
  "requestId": "balance-sub-1",
  "subscriptionType": "SUBSCRIPTION_TYPE_ACCOUNT_BALANCE",
  "accountBalancesSnapshot": {
    "balances": [
      {
        "currentBalance": 1000.00,
        "currency": "USD",
        "buyingPower": 850.00
      }
    ]
  }
}

Balance Update Response

{
  "requestId": "balance-sub-1",
  "subscriptionType": "SUBSCRIPTION_TYPE_ACCOUNT_BALANCE",
  "accountBalancesUpdate": {
    "balanceChange": {
      "beforeBalance": {...},
      "afterBalance": {...},
      "description": "Order execution",
      "updateTime": "2024-01-15T10:30:00Z",
      "entryType": "LEDGER_ENTRY_TYPE_ORDER_EXECUTION"
    }
  }
}

Execution Types

Value	Description
`EXECUTION_TYPE_PARTIAL_FILL`	Order partially filled
`EXECUTION_TYPE_FILL`	Order fully filled
`EXECUTION_TYPE_CANCELED`	Order canceled
`EXECUTION_TYPE_REPLACE`	Order replaced/modified
`EXECUTION_TYPE_REJECTED`	Order rejected
`EXECUTION_TYPE_EXPIRED`	Order expired
`EXECUTION_TYPE_DONE_FOR_DAY`	Order done for the trading day

Ledger Entry Types

Value	Description
`LEDGER_ENTRY_TYPE_ORDER_EXECUTION`	Trade execution
`LEDGER_ENTRY_TYPE_DEPOSIT`	Account deposit
`LEDGER_ENTRY_TYPE_WITHDRAWAL`	Account withdrawal
`LEDGER_ENTRY_TYPE_RESOLUTION`	Market resolution
`LEDGER_ENTRY_TYPE_COMMISSION`	Commission charge
`LEDGER_ENTRY_TYPE_CORRECTION`	Balance correction
`LEDGER_ENTRY_TYPE_NETTING`	Netting adjustment
`LEDGER_ENTRY_TYPE_MANUAL_ADJUSTMENT`	Manual balance adjustment
`LEDGER_ENTRY_TYPE_CONTRACT_EXPIRATION`	Contract expiration

Order States

Value	Description
`ORDER_STATE_PENDING_NEW`	Order received, not yet processed
`ORDER_STATE_PENDING_REPLACE`	Modify request received, not yet processed
`ORDER_STATE_PENDING_CANCEL`	Cancel request received, not yet processed
`ORDER_STATE_PENDING_RISK`	Order pending risk approval
`ORDER_STATE_PARTIALLY_FILLED`	Order partially executed
`ORDER_STATE_FILLED`	Order fully executed
`ORDER_STATE_CANCELED`	Order canceled
`ORDER_STATE_REPLACED`	Order replaced
`ORDER_STATE_REJECTED`	Order rejected
`ORDER_STATE_EXPIRED`	Order expired

Order Intent

Value	Description
`ORDER_INTENT_BUY_LONG`	Buy YES contracts
`ORDER_INTENT_SELL_LONG`	Sell YES contracts
`ORDER_INTENT_BUY_SHORT`	Buy NO contracts
`ORDER_INTENT_SELL_SHORT`	Sell NO contracts

Subscription LimitsYou can subscribe to a maximum of 100 markets per subscription. Use multiple subscriptions if you need more.

​Private WebSocket

​Endpoint

​Subscription Types

​Order Subscriptions

​Subscribe to Orders

​Order Snapshot Response

​Order Update Response

​Position Subscriptions

​Subscribe to Positions

​Position Update Response

​Account Balance Subscriptions

​Subscribe to Balances

​Balance Snapshot Response

​Balance Update Response

​Execution Types

​Ledger Entry Types

​Order States

​Order Intent

Private WebSocket

Endpoint

Subscription Types

Order Subscriptions

Subscribe to Orders

Order Snapshot Response

Order Update Response

Position Subscriptions

Subscribe to Positions

Position Update Response

Account Balance Subscriptions

Subscribe to Balances

Balance Snapshot Response

Balance Update Response

Execution Types

Ledger Entry Types

Order States

Order Intent