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, and its range depends on the network and order type.

Testnet IOC values are expressed 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

Mainnet values look very different from the testnet IOC range. Note the units when comparing: p is a raw integer interpreted as the fraction p / 100,000,000, so 1 bp equals a raw p of 10000, and the 8-100 bps testnet IOC range corresponds to raw p values of 80000 to 1000000. Priority activity on mainnet is predominantly ALO orders carrying far smaller raw p values, typically between 1 and roughly 400 (about 0.04 bp at the upper end), often in per-user ladders as orders compete for queue position. A much smaller share of mainnet priority orders are IOC, and those can carry larger p values (raw values above 10000 observed), though still well below the testnet 8-100 bps band in observed traffic.

Per the official Hyperliquid priority fee documentation, ALO orders placed at the same price level within a T = 400 ms window are sorted in decreasing order of priority rate, and ALO priority fees are deducted at order placement from the undelegated staking balance, converted to HYPE using the spot mark price.

Network-Specific 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, and the observed p ranges, depend on the 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	Raw priority fee value, interpreted as the fraction p / 100,000,000 (10000 = 1 bp). Testnet IOC orders use 80000-1000000 (8-100 bps); mainnet ALO orders carry far smaller values, typically 1 to ~400 (up to ~0.04 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)
Network-Specific Ranges - The 8-100 bps IOC range applies to testnet and corresponds to raw p values of 80000-1000000 (10000 = 1 bp); on mainnet, priority activity is primarily ALO orders with far smaller raw p values, typically between 1 and ~400 (up to ~0.04 bp)
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​