ORDER_PRIORITY

Overview

The ORDER_PRIORITY stream provides normalized priority-fee order events from Hyperliquid transaction data. It emits one JSON event per priority order action, derived from both mempool transactions and confirmed block data.

Stream Type: ORDER_PRIORITY
API Availability: gRPC Streaming API only
Volume: Variable - Depends on priority-fee order activity

When to Use ORDER_PRIORITY

Use ORDER_PRIORITY when you want to observe priority-fee order flow without parsing raw MEMPOOL_TXS or full BLOCKS/replica_cmds payloads yourself. This stream is an order-flow stream, not an order book stream.

This stream is valuable for:

Priority-Fee Monitoring - Track orders with priority fees in real-time
Fee Analysis - Analyze priority fee patterns across different markets
Order Flow Intelligence - Understand priority order submission patterns
Pre-Confirmation Visibility - See priority orders from mempool before block inclusion
Confirmation Tracking - Monitor execution outcomes for priority orders

Data Sources

The ORDER_PRIORITY stream derives events from two sources:

Source	Description	Additional Fields
mempool_txs	Pre-consensus priority activity from the mempool. Events are not finalized and may be rejected, reordered, or absent from the finalized chain.	first_seen_time, tx_hash, nonce, cloid
replica_cmds	Confirmed block data representing finalized transaction processing.	block_number, block_time, bundle_index, outcome

Priority Detection

Priority orders are detected when an order action contains the grouping field with a priority fee value:

"grouping": { "p": 10000 }

Priority Fee Values

The p value represents the priority fee in basis points (bps):

p Value	Basis Points	Notes
10000	1 bp	Base unit (p = 10000 means 1 bp)
80000	8 bps	Minimum for testnet IOC priority fees
1000000	100 bps	Maximum for testnet IOC priority fees

Testnet Protocol Behavior

On testnet:

IOC priority fees support the 8-100 bps range
ALO orders support priority fees
Within the 8-100 bps IOC range, priority fees are used as a sorting mechanism for orders received at a similar time and have the same mempool prioritization effect

ALO priority affects queue position after L1 execution and does not provide the same mempool-prioritization behavior as IOC priority.

Mainnet and testnet both support the gRPC stream types. Actual events depend on priority activity occurring on the selected network.

Event Structure

Mempool Event

{
  "type": "order",
  "source": "mempool_txs",
  "first_seen_time": "2026-06-02T13:48:49.578877529",
  "tx_hash": "0x...",
  "signed_action_index": 0,
  "order_index": 0,
  "asset_id": 0,
  "market_type": "perp",
  "coin": "BTC",
  "cloid": "0x...",
  "p": 10000,
  "side": "buy",
  "px": "100000",
  "sz": "0.001",
  "tif": "Ioc",
  "reduce_only": false,
  "nonce": 1780408128806
}

Confirmed Event (replica_cmds source)

{
  "type": "order",
  "source": "replica_cmds",
  "block_number": 581285917,
  "block_time": "2026-06-02T13:48:49.626754186",
  "bundle_index": 0,
  "asset_id": 0,
  "market_type": "perp",
  "coin": "BTC",
  "p": 10000,
  "side": "buy",
  "px": "100000",
  "sz": "0.001",
  "tif": "Ioc",
  "reduce_only": false,
  "outcome": "filled"
}

Response Fields

Field	Type	Description
type	string	Event type: "order"
source	string	Data source: "mempool_txs" (pre-consensus) or "replica_cmds" (confirmed)
first_seen_time	string	(mempool_txs only) ISO 8601 timestamp when first seen in mempool
tx_hash	string	(mempool_txs only) Transaction hash (0x-prefixed)
signed_action_index	number	(mempool_txs only) Index of the signed action within the transaction
order_index	number	(mempool_txs only) Index of the order within the action
block_number	number	(replica_cmds only) Block number where the order was confirmed
block_time	string	(replica_cmds only) ISO 8601 timestamp of the block
bundle_index	number	(replica_cmds only) Index of the bundle within the block
asset_id	number	Numerical asset/coin ID
market_type	string	Market type (e.g., "perp")
coin	string	Trading pair symbol (e.g., "BTC", "ETH")
cloid	string	(optional) Client order ID
p	number	Priority fee value (10000 = 1 bp)
side	string	Order side: "buy" or "sell"
px	string	Order price
sz	string	Order size
tif	string	Time in force: "Ioc" (Immediate or Cancel) or "Alo" (Add Liquidity Only)
reduce_only	boolean	Whether the order can only reduce an existing position
nonce	number	(mempool_txs only) Transaction nonce
user	string	(optional) User address
broadcaster	string	(optional) Broadcaster address
outcome	string	(replica_cmds only) Execution outcome (e.g., "filled")

ALO Priority Orders

Add Liquidity Only (ALO) priority orders have tif set to "Alo":

{
  "tif": "Alo"
}

Filtering

The ORDER_PRIORITY stream supports standard gRPC field filtering. Useful fields:

Field	Example Values	Description
source	mempool_txs, replica_cmds	Filter by data source
type	order	Filter by event type
coin	BTC, ETH, SOL	Filter by trading pair
market_type	perp	Filter by market type
asset_id	0, 1, 2	Filter by asset ID
p	10000, 80000, 1000000	Filter by priority fee value
side	buy, sell	Filter by order side
tif	Ioc, Alo	Filter by time in force
outcome	filled	Filter by execution outcome (replica_cmds only)
user	0x...	Filter by user address
broadcaster	0x...	Filter by broadcaster address
tx_hash	0x...	Filter by transaction hash
block_number	581285917	Filter by block number

Filter Examples

// Get BTC priority orders only
filters: {
  "coin": FilterValues { values: ["BTC"] }
}

// Get IOC priority orders from mempool
filters: {
  "source": FilterValues { values: ["mempool_txs"] },
  "tif": FilterValues { values: ["Ioc"] }
}

// Get filled priority orders from confirmed blocks
filters: {
  "source": FilterValues { values: ["replica_cmds"] },
  "outcome": FilterValues { values: ["filled"] }
}

// Get high-value priority fees (8+ bps)
filters: {
  "p": FilterValues { values: ["80000", "100000", "500000", "1000000"] }
}

For complete filtering documentation, see Stream Filtering Guide.

Recommended Usage

For low-latency order-flow monitoring:

ORDER_PRIORITY + source=mempool_txs

For confirmation and reconciliation:

ORDER_PRIORITY + source=replica_cmds

Customers should persist events if they need historical search. StreamData is a live stream and does not provide historical replay by itself.

gRPC Streaming

Python Example

import grpc
import json
from pb import streaming_pb2, streaming_pb2_grpc

GRPC_ENDPOINT = 'your-endpoint.hype-mainnet.quiknode.pro:10000'
AUTH_TOKEN = 'your-auth-token'

def stream_order_priority():
    credentials = grpc.ssl_channel_credentials()
    channel = grpc.secure_channel(
        GRPC_ENDPOINT,
        credentials,
        options=[
            ('grpc.max_receive_message_length', 100 * 1024 * 1024),
        ]
    )

    stub = streaming_pb2_grpc.StreamingStub(channel)
    metadata = [('x-token', AUTH_TOKEN)]

    def request_generator():
        # Subscribe to ORDER_PRIORITY with filters
        subscribe_request = streaming_pb2.SubscribeRequest()
        subscribe_request.subscribe.stream_type = streaming_pb2.StreamType.ORDER_PRIORITY
        subscribe_request.subscribe.filters["coin"].values.extend(["BTC", "ETH"])
        subscribe_request.subscribe.filters["tif"].values.append("Ioc")
        yield subscribe_request

        # Keep connection alive with periodic pings
        while True:
            time.sleep(30)
            ping_request = streaming_pb2.SubscribeRequest()
            ping_request.ping.timestamp = int(time.time() * 1000)
            yield ping_request

    stream = stub.StreamData(request_generator(), metadata=metadata)

    for response in stream:
        if response.HasField('data'):
            data = json.loads(response.data.data)

            print(f"Priority Order Event")
            print(f"Source: {data.get('source')}")
            print(f"Coin: {data.get('coin')}")
            print(f"Priority Fee (p): {data.get('p')} ({data.get('p', 0) / 10000} bps)")
            print(f"Side: {data.get('side')}")
            print(f"Price: {data.get('px')}")
            print(f"Size: {data.get('sz')}")
            print(f"TIF: {data.get('tif')}")

            if data.get('source') == 'replica_cmds':
                print(f"Outcome: {data.get('outcome')}")
                print(f"Block: {data.get('block_number')}")

            print("---")

if __name__ == "__main__":
    stream_order_priority()

JavaScript/Node.js Example

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const GRPC_ENDPOINT = 'your-endpoint.hype-mainnet.quiknode.pro:10000';
const AUTH_TOKEN = 'your-auth-token';

// Load proto file
const packageDefinition = protoLoader.loadSync('streaming.proto');
const proto = grpc.loadPackageDefinition(packageDefinition).hyperliquid;

// Create channel with credentials
const credentials = grpc.credentials.createSsl();
const client = new proto.Streaming(GRPC_ENDPOINT, credentials);

const metadata = new grpc.Metadata();
metadata.add('x-token', AUTH_TOKEN);

// Subscribe to ORDER_PRIORITY
const call = client.StreamData(metadata);

call.on('data', (response) => {
  if (response.data) {
    const data = JSON.parse(response.data.data);

    console.log(`Priority Order Event`);
    console.log(`Source: ${data.source}`);
    console.log(`Coin: ${data.coin}`);
    console.log(`Priority Fee (p): ${data.p} (${data.p / 10000} bps)`);
    console.log(`Side: ${data.side}`);
    console.log(`Price: ${data.px}`);
    console.log(`Size: ${data.sz}`);
    console.log(`TIF: ${data.tif}`);

    if (data.source === 'replica_cmds') {
      console.log(`Outcome: ${data.outcome}`);
      console.log(`Block: ${data.block_number}`);
    }

    console.log('---');
  }
});

call.on('error', (error) => {
  console.error('Stream error:', error);
});

// Send subscription with filters
call.write({
  subscribe: {
    stream_type: 9,  // ORDER_PRIORITY
    filters: {
      coin: { values: ['BTC', 'ETH'] },
      tif: { values: ['Ioc'] }
    }
  }
});

// Send periodic pings
setInterval(() => {
  call.write({
    ping: { timestamp: Date.now() }
  });
}, 30000);

Important Notes

Derived Stream - ORDER_PRIORITY is a derived stream that normalizes data from MEMPOOL_TXS and BLOCKS, saving you from parsing raw payloads
Not an Order Book - This stream provides priority order metadata, not order book state
Dual Sources - Events come from both mempool (pre-consensus) and confirmed blocks (post-consensus)
Testnet Features - Priority fee ranges (8-100 bps for IOC, ALO support) are currently testnet features
Compression - Consider enabling zstd compression on your gRPC channel for bandwidth efficiency

GOSSIP_PRIORITY - Gossip/read-priority bid events
MEMPOOL_TXS - Raw mempool transactions (source data for pre-consensus priority events)
BLOCKS - Raw blockchain data (source data for confirmed priority events)
ORDERS - Order lifecycle events
TRADES - Executed trades

For more information about gRPC streaming setup, see gRPC API Documentation.

Overview​

Data Sources​

Priority Detection​

Priority Fee Values​

Event Structure​

Mempool Event​

Confirmed Event (replica_cmds source)​

Response Fields​

ALO Priority Orders​

Filtering​

Filter Examples​

Recommended Usage​

gRPC Streaming​

Important Notes​

Related Streams​