> ## Documentation Index > Fetch the complete documentation index at: https://docs.raze.bot/llms.txt > Use this file to discover all available pages before exploring further. # Perpetuals > Subscribe to perp events (`perp_fill`, `perp_liquidation`, `perp_position_update`, `perp_order`) for one or more `venue:symbol` markets — e.g. `jup:SOL-PERP`. Inverse-indexed alongside mint and signer subscriptions, so a single client can mix all three on the same socket. ## AsyncAPI ````yaml asyncapi-spec/websockets.yaml markets id: markets title: Perpetuals description: | Subscribe to perp events (`perp_fill`, `perp_liquidation`, `perp_position_update`, `perp_order`) for one or more `venue:symbol` markets — e.g. `jup:SOL-PERP`. Inverse-indexed alongside mint and signer subscriptions, so a single client can mix all three on the same socket. servers: - id: production protocol: wss host: ws.raze.bot bindings: [] variables: [] address: /ws/sol parameters: [] bindings: - protocol: ws version: 0.1.0 value: query: type: object properties: apiKey: type: string description: API key for authentication (format sk_xxx) required: - apiKey schemaProperties: - name: query type: object required: false properties: - name: apiKey type: string description: API key for authentication (format sk_xxx) required: true operations: - &ref_1 id: subscribeMarkets title: Subscribe to perpetuals description: Subscribe to perp events for one or more `venue:symbol` markets. type: receive messages: - &ref_8 id: subscribeMessage payload: - name: Subscribe to Perpetuals description: Subscribe to perp events for `venue:symbol` markets type: object properties: - name: action type: string enumValues: - subscribe required: true - name: markets type: array required: true properties: - name: item type: string required: false headers: [] jsonPayloadSchema: type: object description: Subscribe to perp events for one or more `venue:symbol` markets. properties: action: type: string enum: - subscribe x-parser-schema-id: markets: type: array items: type: string x-parser-schema-id: example: - jup:SOL-PERP - jup:BTC-PERP x-parser-schema-id: required: - action - markets x-parser-schema-id: MarketSubscribeMessage title: Subscribe to Perpetuals description: Subscribe to perp events for `venue:symbol` markets example: |- { "action": "", "markets": { "item": "" } } bindings: [] extensions: - id: x-parser-unique-object-id value: subscribeMessage bindings: [] extensions: &ref_0 - id: x-parser-unique-object-id value: markets - &ref_2 id: unsubscribeMarkets title: Unsubscribe from perpetuals description: Unsubscribe from perpetuals type: receive messages: - &ref_9 id: unsubscribeMessage payload: - name: Unsubscribe from Perpetuals description: Unsubscribe from perpetuals type: object properties: - name: action type: string enumValues: - unsubscribe required: true - name: markets type: array required: true properties: - name: item type: string required: false headers: [] jsonPayloadSchema: type: object properties: action: type: string enum: - unsubscribe x-parser-schema-id: markets: type: array items: type: string x-parser-schema-id: x-parser-schema-id: required: - action - markets x-parser-schema-id: MarketUnsubscribeMessage title: Unsubscribe from Perpetuals description: Unsubscribe from perpetuals example: |- { "action": "", "markets": { "item": "" } } bindings: [] extensions: - id: x-parser-unique-object-id value: unsubscribeMessage bindings: [] extensions: *ref_0 - &ref_3 id: receivePerpFills title: Receive perp fill events description: >- Real-time perp fills. Broadcast on `markets` (by `market_id`) and `signers` (by `signer`) subscriptions. type: send messages: - &ref_10 id: perpFillMessage payload: - name: Perp Fill description: Perp open / increase / decrease fill event type: object properties: - name: type type: string enumValues: - perp_fill required: false - name: venue type: string enumValues: - jup required: false - name: market_id type: string required: false - name: data type: object description: > Inner `data` payload — serialized from the shared `PerpEvent::Fill` struct with the discriminator `kind: "fill"`. required: false properties: - name: kind type: string enumValues: - fill required: false - name: market_id type: string required: false - name: venue type: string enumValues: - jup required: false - name: signer type: string required: false - name: side type: string enumValues: - long - short required: false - name: size type: integer description: Base-asset size, raw venue units. required: false - name: price type: integer description: Price normalized to USDC e6 (1e6 = $1). required: false - name: fee type: integer required: false - name: position_pubkey type: string required: false - name: slot type: integer required: false - name: block_time type: integer required: false - name: signature type: string required: false - name: ix_index type: integer required: false - name: parser_version type: integer required: false - name: program_data_hash type: string description: >- First 16 hex chars of sha256(program_event_data) — fingerprint for parser-drift detection. required: false - name: timestamp type: integer description: Server-assigned broadcast time (Unix ms). required: false - name: signature type: string required: false - name: priceInfo type: object description: Optional spot-price context attached to the fill. required: false headers: [] jsonPayloadSchema: type: object description: > Perp fill — emitted on every Increase / Decrease / Liquidate-Fill ix. Broadcast on `markets` (by `market_id`) and `signers` (by `signer`) subscriptions. properties: type: type: string enum: - perp_fill x-parser-schema-id: venue: type: string enum: - jup x-parser-schema-id: market_id: type: string example: jup:SOL-PERP x-parser-schema-id: data: type: object description: > Inner `data` payload — serialized from the shared `PerpEvent::Fill` struct with the discriminator `kind: "fill"`. properties: kind: type: string enum: - fill x-parser-schema-id: market_id: type: string x-parser-schema-id: venue: type: string enum: - jup x-parser-schema-id: signer: type: string x-parser-schema-id: side: type: string enum: - long - short x-parser-schema-id: size: type: integer format: int64 description: Base-asset size, raw venue units. x-parser-schema-id: price: type: integer format: int64 description: Price normalized to USDC e6 (1e6 = $1). x-parser-schema-id: fee: type: integer format: int64 x-parser-schema-id: position_pubkey: type: string x-parser-schema-id: slot: type: integer format: int64 x-parser-schema-id: block_time: type: integer format: int64 x-parser-schema-id: signature: type: string x-parser-schema-id: ix_index: type: integer x-parser-schema-id: parser_version: type: integer x-parser-schema-id: program_data_hash: type: string description: >- First 16 hex chars of sha256(program_event_data) — fingerprint for parser-drift detection. x-parser-schema-id: x-parser-schema-id: PerpFillData timestamp: type: integer format: int64 description: Server-assigned broadcast time (Unix ms). x-parser-schema-id: signature: type: string x-parser-schema-id: priceInfo: type: object description: Optional spot-price context attached to the fill. x-parser-schema-id: x-parser-schema-id: PerpFillMessage title: Perp Fill description: Perp open / increase / decrease fill event example: No examples found bindings: [] extensions: - id: x-parser-unique-object-id value: perpFillMessage bindings: [] extensions: *ref_0 - &ref_4 id: receivePerpLiquidations title: Receive perp liquidation events description: Real-time perp liquidations. type: send messages: - &ref_11 id: perpLiquidationMessage payload: - name: Perp Liquidation description: Perp liquidation event type: object properties: - name: type type: string enumValues: - perp_liquidation required: false - name: venue type: string enumValues: - jup required: false - name: market_id type: string required: false - name: data type: object required: false properties: - name: kind type: string enumValues: - liquidation required: false - name: market_id type: string required: false - name: venue type: string enumValues: - jup required: false - name: signer type: string required: false - name: position_pubkey type: string required: false - name: side type: string description: >- Side of the position being liquidated. Defaults to `long` for legacy events that lack the field — UI should treat as best-effort when absent. enumValues: - long - short required: false - name: size_closed type: integer required: false - name: oracle_price type: integer description: Oracle mark at liquidation, USDC e6. required: false - name: fee type: integer required: false - name: slot type: integer required: false - name: block_time type: integer required: false - name: signature type: string required: false - name: parser_version type: integer required: false - name: program_data_hash type: string required: false - name: timestamp type: integer required: false - name: signature type: string required: false - name: priceInfo type: object required: false headers: [] jsonPayloadSchema: type: object properties: type: type: string enum: - perp_liquidation x-parser-schema-id: venue: type: string enum: - jup x-parser-schema-id: market_id: type: string x-parser-schema-id: data: type: object properties: kind: type: string enum: - liquidation x-parser-schema-id: market_id: type: string x-parser-schema-id: venue: type: string enum: - jup x-parser-schema-id: signer: type: string x-parser-schema-id: position_pubkey: type: string x-parser-schema-id: side: type: string enum: - long - short description: >- Side of the position being liquidated. Defaults to `long` for legacy events that lack the field — UI should treat as best-effort when absent. x-parser-schema-id: size_closed: type: integer format: int64 x-parser-schema-id: oracle_price: type: integer format: int64 description: Oracle mark at liquidation, USDC e6. x-parser-schema-id: fee: type: integer format: int64 x-parser-schema-id: slot: type: integer format: int64 x-parser-schema-id: block_time: type: integer format: int64 x-parser-schema-id: signature: type: string x-parser-schema-id: parser_version: type: integer x-parser-schema-id: program_data_hash: type: string x-parser-schema-id: x-parser-schema-id: PerpLiquidationData timestamp: type: integer format: int64 x-parser-schema-id: signature: type: string x-parser-schema-id: priceInfo: type: object x-parser-schema-id: x-parser-schema-id: PerpLiquidationMessage title: Perp Liquidation description: Perp liquidation event example: No examples found bindings: [] extensions: - id: x-parser-unique-object-id value: perpLiquidationMessage bindings: [] extensions: *ref_0 - &ref_5 id: receivePerpPositionUpdates title: Receive perp position updates description: >- Position size / collateral / unrealized-PnL updates per Increase/Decrease/Liquidate event. type: send messages: - &ref_12 id: perpPositionUpdateMessage payload: - name: Perp Position Update description: Position size / collateral / unrealized-PnL update type: object properties: - name: type type: string enumValues: - perp_position_update required: false - name: venue type: string enumValues: - jup required: false - name: market_id type: string required: false - name: data type: object description: >- Emitted once per Increase / Decrease / Liquidate event. A `size` of 0 means the position is now closed. required: false properties: - name: kind type: string enumValues: - position_update required: false - name: market_id type: string required: false - name: venue type: string enumValues: - jup required: false - name: signer type: string required: false - name: position_pubkey type: string required: false - name: side type: string enumValues: - long - short required: false - name: size type: integer required: false - name: entry_price type: integer required: false - name: collateral type: integer required: false - name: unrealized_pnl type: integer required: false - name: slot type: integer required: false - name: block_time type: integer required: false - name: parser_version type: integer required: false - name: timestamp type: integer required: false - name: signature type: string required: false - name: priceInfo type: object required: false headers: [] jsonPayloadSchema: type: object properties: type: type: string enum: - perp_position_update x-parser-schema-id: venue: type: string enum: - jup x-parser-schema-id: market_id: type: string x-parser-schema-id: data: type: object description: >- Emitted once per Increase / Decrease / Liquidate event. A `size` of 0 means the position is now closed. properties: kind: type: string enum: - position_update x-parser-schema-id: market_id: type: string x-parser-schema-id: venue: type: string enum: - jup x-parser-schema-id: signer: type: string x-parser-schema-id: position_pubkey: type: string x-parser-schema-id: side: type: string enum: - long - short x-parser-schema-id: size: type: integer format: int64 x-parser-schema-id: entry_price: type: integer format: int64 x-parser-schema-id: collateral: type: integer format: int64 x-parser-schema-id: unrealized_pnl: type: integer format: int64 x-parser-schema-id: slot: type: integer format: int64 x-parser-schema-id: block_time: type: integer format: int64 x-parser-schema-id: parser_version: type: integer x-parser-schema-id: x-parser-schema-id: PerpPositionUpdateData timestamp: type: integer format: int64 x-parser-schema-id: signature: type: string x-parser-schema-id: priceInfo: type: object x-parser-schema-id: x-parser-schema-id: PerpPositionUpdateMessage title: Perp Position Update description: Position size / collateral / unrealized-PnL update example: No examples found bindings: [] extensions: - id: x-parser-unique-object-id value: perpPositionUpdateMessage bindings: [] extensions: *ref_0 - &ref_6 id: receivePerpOrders title: Receive perp order events description: >- Pending-order lifecycle (Open / Updated / Filled / Cancelled) for Jupiter Perps trigger orders. type: send messages: - &ref_13 id: perpOrderMessage payload: - name: Perp Order Event description: Pending-order state transition (Open/Updated/Filled/Cancelled) type: object properties: - name: type type: string enumValues: - perp_order required: false - name: venue type: string enumValues: - jup required: false - name: market_id type: string required: false - name: data type: object description: > One record per state transition on a Jupiter Perps `position_request` PDA. The orderbook view is materialized by aggregating rows by `order_id` and picking the latest `state`. **Note on field name:** the discriminator key on `kind` (`order`) is the outer `PerpEvent` enum tag. The order's user-facing kind (limit/TP/SL) is reported as `order_kind` to avoid serde shadowing. required: false properties: - name: kind type: string enumValues: - order required: false - name: market_id type: string required: false - name: venue type: string enumValues: - jup required: false - name: owner type: string required: false - name: order_id type: string description: >- `position_request` PDA — stable across the order's lifecycle. required: false - name: position_pubkey type: string required: false - name: order_kind type: string enumValues: - limit - take_profit - stop_loss required: false - name: side type: string enumValues: - long - short required: false - name: state type: string enumValues: - open - updated - filled - cancelled required: false - name: size_usd type: integer description: USD notional in e6. `0` for `entire_position=true` orders. required: false - name: collateral type: integer required: false - name: trigger_price type: integer description: USDC e6 — same scale as `entry_price` / `oracle_price`. required: false - name: trigger_above type: boolean description: >- True when trigger fires when oracle ≥ trigger; false for ≤. required: false - name: entire_position type: boolean required: false - name: slot type: integer required: false - name: block_time type: integer required: false - name: signature type: string required: false - name: ix_index type: integer required: false - name: parser_version type: integer required: false - name: program_data_hash type: string required: false - name: timestamp type: integer required: false - name: signature type: string required: false - name: priceInfo type: object required: false headers: [] jsonPayloadSchema: type: object description: >- Pending-order state transition (Open / Updated / Filled / Cancelled). properties: type: type: string enum: - perp_order x-parser-schema-id: venue: type: string enum: - jup x-parser-schema-id: market_id: type: string x-parser-schema-id: data: type: object description: > One record per state transition on a Jupiter Perps `position_request` PDA. The orderbook view is materialized by aggregating rows by `order_id` and picking the latest `state`. **Note on field name:** the discriminator key on `kind` (`order`) is the outer `PerpEvent` enum tag. The order's user-facing kind (limit/TP/SL) is reported as `order_kind` to avoid serde shadowing. properties: kind: type: string enum: - order x-parser-schema-id: market_id: type: string x-parser-schema-id: venue: type: string enum: - jup x-parser-schema-id: owner: type: string x-parser-schema-id: order_id: type: string description: >- `position_request` PDA — stable across the order's lifecycle. x-parser-schema-id: position_pubkey: type: string x-parser-schema-id: order_kind: type: string enum: - limit - take_profit - stop_loss x-parser-schema-id: side: type: string enum: - long - short x-parser-schema-id: state: type: string enum: - open - updated - filled - cancelled x-parser-schema-id: size_usd: type: integer format: int64 description: USD notional in e6. `0` for `entire_position=true` orders. x-parser-schema-id: collateral: type: integer format: int64 x-parser-schema-id: trigger_price: type: integer format: int64 description: USDC e6 — same scale as `entry_price` / `oracle_price`. x-parser-schema-id: trigger_above: type: boolean description: True when trigger fires when oracle ≥ trigger; false for ≤. x-parser-schema-id: entire_position: type: boolean x-parser-schema-id: slot: type: integer format: int64 x-parser-schema-id: block_time: type: integer format: int64 x-parser-schema-id: signature: type: string x-parser-schema-id: ix_index: type: integer x-parser-schema-id: parser_version: type: integer x-parser-schema-id: program_data_hash: type: string x-parser-schema-id: x-parser-schema-id: PerpOrderData timestamp: type: integer format: int64 x-parser-schema-id: signature: type: string x-parser-schema-id: priceInfo: type: object x-parser-schema-id: x-parser-schema-id: PerpOrderMessage title: Perp Order Event description: Pending-order state transition (Open/Updated/Filled/Cancelled) example: No examples found bindings: [] extensions: - id: x-parser-unique-object-id value: perpOrderMessage bindings: [] extensions: *ref_0 - &ref_7 id: receiveMarketSubscriptionConfirmed title: Market subscription confirmation description: Server acknowledges a `markets` subscribe with a typed confirmation frame. type: send messages: - &ref_14 id: marketSubscriptionConfirmedMessage payload: - name: Market Subscription Confirmed type: object properties: - name: type type: string enumValues: - market_subscription_confirmed required: false - name: markets type: array required: false properties: - name: item type: string required: false - name: total_market_subscriptions type: integer required: false - name: timestamp type: string required: false headers: [] jsonPayloadSchema: type: object properties: type: type: string enum: - market_subscription_confirmed x-parser-schema-id: markets: type: array items: type: string x-parser-schema-id: x-parser-schema-id: total_market_subscriptions: type: integer x-parser-schema-id: timestamp: type: string format: date-time x-parser-schema-id: x-parser-schema-id: MarketSubscriptionConfirmedMessage title: Market Subscription Confirmed example: |- { "type": "", "markets": { "item": "" }, "total_market_subscriptions": 123, "timestamp": "" } bindings: [] extensions: - id: x-parser-unique-object-id value: marketSubscriptionConfirmedMessage bindings: [] extensions: *ref_0 sendOperations: - *ref_1 - *ref_2 receiveOperations: - *ref_3 - *ref_4 - *ref_5 - *ref_6 - *ref_7 sendMessages: - *ref_8 - *ref_9 receiveMessages: - *ref_10 - *ref_11 - *ref_12 - *ref_13 - *ref_14 extensions: - id: x-parser-unique-object-id value: markets securitySchemes: - id: ApiKeyAuth name: apiKey type: httpApiKey description: API key passed as query parameter (format sk_xxx) in: query extensions: [] ````