position Channel

Subscribe to real-time position updates for a smart account. The service polls positions every second and delivers enriched position data including mark prices and Greeks.

Parameter	Required	Description
`account`	Yes	Smart account address (42 characters with `0x` prefix)
`market`	No	Base token filter: `"BTC"`, `"ETH"`, or `"ARB"`. If omitted, returns positions for all markets.

All positions:

{
  "channel": "position",
  "query": {
    "account": "0x1234567890abcdef1234567890abcdef12345678"
  }
}

ETH market only:

{
  "channel": "position",
  "query": {
    "account": "0x1234567890abcdef1234567890abcdef12345678",
    "market": "ETH"
  }
}

Event: position

{
  "kind": "event",
  "type": "position",
  "timestamp_ms": 1677721600000,
  "data": {
    "margin_account": "550e8400-e29b-41d4-a716-446655440000",
    "market": "ETH",
    "positions": [
      {
        "id": "pos-001",
        "margin_account_id": "550e8400-e29b-41d4-a716-446655440000",
        "instrument_name": "ETH_USDC-PERPETUAL",
        "size": 10.5,
        "average_price": 2450.00,
        "entry_fee": 2.50,
        "instrument_type": "perp",
        "mark_price": 2475.00,
        "current_funding_rate": 0.0001,
        "position_greeks": {
          "delta": 10.5
        }
      },
      {
        "id": "pos-002",
        "margin_account_id": "550e8400-e29b-41d4-a716-446655440000",
        "instrument_name": "ETH_USDC-31OCT25-3000-C",
        "size": 5.0,
        "average_price": 125.50,
        "entry_fee": 1.25,
        "instrument_type": "option",
        "mark_price": 130.00,
        "mark_iv": 0.65,
        "mark_interest": 0.05,
        "position_greeks": {
          "delta": 2.75,
          "gamma": 0.015,
          "theta": -12.5,
          "vega": 45.0,
          "rho": 8.5
        }
      }
    ]
  },
  "subscription": {
    "channel": "position",
    "query": {
      "account": "0x1234567890abcdef1234567890abcdef12345678",
      "market": "ETH"
    }
  }
}

Common Fields

Field	Type	Description
`margin_account`	string	Margin account UUID
`market`	string	Base token (`"BTC"`, `"ETH"`, or `"ARB"`)
`positions`	array	Array of position objects

Position Fields (Perpetual)

Field	Type	Description
`id`	string	Position UUID
`margin_account_id`	string	Parent margin account UUID
`instrument_name`	string	e.g., `"ETH_USDC-PERPETUAL"`
`size`	number	Position size (positive = long, negative = short)
`average_price`	number	Average entry price
`entry_fee`	number	Total fees paid on entry
`instrument_type`	string	`"perp"`
`mark_price`	number	Current mark price
`current_funding_rate`	number	Current hourly funding rate
`position_greeks.delta`	number	Position delta (equals size for perpetuals)

Position Fields (Option)

Field	Type	Description
`id`	string	Position UUID
`margin_account_id`	string	Parent margin account UUID
`instrument_name`	string	e.g., `"ETH_USDC-31OCT25-3000-C"`
`size`	number	Number of contracts (positive = long, negative = short)
`average_price`	number	Average entry price per contract
`entry_fee`	number	Total fees paid on entry
`instrument_type`	string	`"option"`
`mark_price`	number	Current mark price per contract
`mark_iv`	number	Mark implied volatility
`mark_interest`	number	Interest rate used in pricing
`position_greeks`	object	Full Greeks: delta, gamma, theta, vega, rho

Position events are delivered every second for subscribed accounts. An empty positions array indicates no open positions for that market.

Related channels

Channel	Why
Account State	Aggregated view — portfolio-level margin, equity, and Greeks. Position is the per-instrument breakdown that feeds into account state.
Trade	Fills create or modify positions. Trade events arrive before the next position update, giving you execution details (fees, index price) ahead of the position snapshot.
Index Price	Drives `mark_price` for perps positions. Index price changes flow into PnL.
IV (SVI)	Drives `mark_iv` and `mark_price` for options positions. Vol surface shifts reprice the entire options book.
Interest Rate	Drives `mark_interest` for options. Rate changes affect forward pricing and rho exposure.
Funding	`current_funding_rate` on perps positions. Funding accrues continuously — affects carry cost.