Jetstream Protocol Reference

Available Endpoints

Jetstream is available in all OrbitFlare regions. Connect to the region closest to your infrastructure for the lowest latency.

US
Europe
Asia Pacific

City	Region Slug	Endpoint
New York	`ny`	`http://ny.jetstream.orbitflare.com`
Salt Lake City	`slc`	`http://slc.jetstream.orbitflare.com`

City	Region Slug	Endpoint
Frankfurt	`fra`	`http://fra.jetstream.orbitflare.com`
Amsterdam	`ams`	`http://ams.jetstream.orbitflare.com`
London	`lon`	`http://lon.jetstream.orbitflare.com`
Dublin	`dub`	`http://dub.jetstream.orbitflare.com`
Siauliai, Lithuania	`siau`	`http://siau.jetstream.orbitflare.com`

City	Region Slug	Endpoint
Tokyo	`jp`	`http://jp.jetstream.orbitflare.com`
Singapore	`sgp`	`http://sgp.jetstream.orbitflare.com`

Jetstream uses plain http:// (not https://) for gRPC connections. gRPC uses its own transport security negotiation over HTTP/2. Use https:// only if your dedicated node explicitly requires it.

Protocol Buffer Specification

This document outlines the Protocol Buffer (protobuf) specification used by OrbitFlare Jetstream. The complete specification can be found in our GitHub repository.

Service Definition

syntax = "proto3";

import "google/protobuf/timestamp.proto";
package jetstream;

// ============= Service Definition =============
service Jetstream {
  // Subscribe to data streams with filtering support
  rpc Subscribe(stream SubscribeRequest) returns (stream SubscribeUpdate) {}
  // Subscribe to data streams with filtering support and parsed instructions
  rpc SubscribeParsed(stream SubscribeParsedRequest) returns (stream SubscribeUpdateParsedTransaction) {}
  // Basic ping/pong for connection testing
  rpc Ping(PingRequest) returns (PongResponse) {}
  // Get information about current state
  rpc GetVersion(GetVersionRequest) returns (GetVersionResponse) {}
}

Request Messages

SubscribeRequest

The main request message for subscribing to data updates:

message SubscribeRequest {
  map<string, SubscribeRequestFilterTransactions> transactions = 1;
  map<string, SubscribeRequestFilterAccounts> accounts = 2;
  optional SubscribeRequestPing ping = 4;
}

Transaction Filtering

message SubscribeRequestFilterTransactions {
  repeated string account_include = 1;
  repeated string account_exclude = 2;
  repeated string account_required = 3;
}

Account Filtering

message SubscribeRequestFilterAccounts {
  repeated string account = 1;
  repeated string owner = 2;
  repeated SubscribeRequestFilterAccountsFilter filters = 3;
}

message SubscribeRequestFilterAccountsFilter {
  oneof filter {
    SubscribeRequestFilterAccountsFilterMemcmp memcmp = 1;
    uint64 datasize = 2;
    SubscribeRequestFilterAccountsFilterLamports lamports = 3;
  }
}

message SubscribeRequestFilterAccountsFilterMemcmp {
  uint64 offset = 1;
  oneof data {
    bytes bytes = 2;
    string base58 = 3;
    string base64 = 4;
  }
}

message SubscribeRequestFilterAccountsFilterLamports {
  oneof cmp {
    uint64 eq = 1;
    uint64 ne = 2;
    uint64 lt = 3;
    uint64 gt = 4;
  }
}

Ping Request

message SubscribeRequestPing {
  int32 id = 1;
}

Response Messages

SubscribeUpdate

The main response message containing updates:

message SubscribeUpdate {
  repeated string filters = 1;
  google.protobuf.Timestamp created_at = 2;
  oneof update_oneof {
    SubscribeUpdateTransaction transaction = 3;
    SubscribeUpdateAccount account = 4;
    SubscribeUpdatePing ping = 5;
    SubscribeUpdatePong pong = 6;
  }
}

Transaction Update

message SubscribeUpdateTransaction {
  SubscribeUpdateTransactionInfo transaction = 1;
  uint64 slot = 2;
}

message SubscribeUpdateTransactionInfo {
  bytes signature = 1;
  uint64 slot = 2;
  uint32 num_required_signatures = 3;
  uint32 num_readonly_signed_accounts = 4;
  uint32 num_readonly_unsigned_accounts = 5;
  bytes recent_blockhash = 6;
  repeated bytes signatures = 7;
  repeated bytes account_keys = 8;
  repeated CompiledInstruction instructions = 9;
  repeated MessageAddressTableLookup address_table_lookups = 10;
}

Account Update

message SubscribeUpdateAccount {
  SubscribeUpdateAccountInfo account = 1;
  uint64 slot = 2;
  bool is_startup = 3;
}

message SubscribeUpdateAccountInfo {
  bytes pubkey = 1;
  uint64 lamports = 2;
  bytes owner = 3;
  bool executable = 4;
  uint64 rent_epoch = 5;
  bytes data = 6;
  uint64 write_version = 7;
  optional bytes txn_signature = 8;
}

Ping/Pong Updates

message SubscribeUpdatePing {}

message SubscribeUpdatePong {
  int32 id = 1;
}

Shared Types

message MessageAddressTableLookup {
  bytes account_key = 1;
  bytes writable_indexes = 2;
  bytes readonly_indexes = 3;
}

message CompiledInstruction {
  uint32 program_id_index = 1;
  bytes accounts = 2;
  bytes data = 3;
}

Parsed Instruction Support

Parsed Request

message SubscribeParsedRequest {
  optional SubscribeRequestPing ping = 1;
}

Parsed Transaction Update

message SubscribeUpdateParsedTransaction {
  bytes signature = 1;
  uint64 slot = 2;
  SubscribeUpdateAccount account = 3;
  bytes recent_blockhash = 4;
  repeated bytes signatures = 5;
  repeated Instruction instructions = 6;
}

Instruction Types

message Instruction {
  oneof instruction_oneof {
    Initialize initialize = 1;
    SetParams set_params = 2;
    Create create = 3;
    Buy buy = 4;
    Sell sell = 5;
    Withdraw withdraw = 6;
  }
}

message Initialize {}

message SetParams {
  bytes fee_recipient = 1;
  uint64 initial_virtual_token_reserves = 2;
  uint64 initial_virtual_sol_reserves = 3;
  uint64 initial_real_token_reserves = 4;
  uint64 token_total_supply = 5;
  uint64 fee_basis_points = 6;
}

message Create {
  string name = 1;
  string symbol = 2;
  string uri = 3;
}

message Buy {
  uint64 amount = 1;
  uint64 max_sol_cost = 2;
}

message Sell {
  uint64 amount = 1;
  uint64 min_sol_output = 2;
}

message Withdraw {}

Non-streaming Methods

message PingRequest {
  int32 count = 1;
}

message PongResponse {
  int32 count = 1;
}

message GetVersionRequest {}

message GetVersionResponse {
  string version = 1;
}

message GetSlotResponse {
  uint64 slot = 1;
}

Using the Protocol

When implementing a client for Jetstream, you’ll need to:

Generate client code from the protobuf definition
Implement the Subscribe RPC method for data streaming
Use SubscribeParsed for parsed instruction support
Use Ping/Pong for connection health checks
Use GetVersion to check server compatibility
Handle different types of updates (transactions, accounts, pongs)

Code Generation

For TypeScript/JavaScript:

protoc --plugin=protoc-gen-ts_proto=./node_modules/.bin/protoc-gen-ts_proto \
  --ts_proto_out=. \
  --ts_proto_opt=esModuleInterop=true \
  jetstream.proto

For Rust:

protoc --rust_out=. jetstream.proto

Best Practices

Version Compatibility
- Use GetVersion to check for protocol compatibility
- Monitor for breaking changes in beta releases
- Test thoroughly when upgrading
Error Handling
- Implement proper error handling for all message types
- Handle connection failures gracefully
- Validate message fields before processing
Connection Management
- Use Ping/Pong for connection health checks
- Implement automatic reconnection logic
- Set appropriate timeouts
Performance
- Use appropriate filters to minimize unnecessary data
- Consider using account filtering for large datasets
- Monitor resource usage, especially with account subscriptions
- Use SubscribeParsed for parsed instruction support when needed

Jetstream Overview

Getting started guide, examples, and filtering documentation.

Changelog

Version history and protocol updates.

Support

For technical questions about the protocol specification or implementation details, please visit our GitHub repository or join our Discord community.

Get Started

Agents

Products

Solutions

Fetching Data

RPC

Data Streaming

Trading APIs

Jetstream Protocol Reference

Available Endpoints

Protocol Buffer Specification

Service Definition

Request Messages

SubscribeRequest

Transaction Filtering

Account Filtering

Ping Request

Response Messages

SubscribeUpdate

Transaction Update

Account Update

Ping/Pong Updates

Shared Types

Parsed Instruction Support

Parsed Request

Parsed Transaction Update

Instruction Types

Non-streaming Methods

Using the Protocol

Code Generation

Best Practices

See Also

Jetstream Overview

Changelog

Support

​Available Endpoints

​Protocol Buffer Specification

​Service Definition

​Request Messages

​SubscribeRequest

​Transaction Filtering

​Account Filtering

​Ping Request

​Response Messages

​SubscribeUpdate

​Transaction Update

​Account Update

​Ping/Pong Updates

​Shared Types

​Parsed Instruction Support

​Parsed Request

​Parsed Transaction Update

​Instruction Types

​Non-streaming Methods

​Using the Protocol

​Code Generation

​Best Practices

​See Also

Jetstream Overview

Changelog

​Support

Available Endpoints

Protocol Buffer Specification

Service Definition

Request Messages

SubscribeRequest

Transaction Filtering

Account Filtering

Ping Request

Response Messages

SubscribeUpdate

Transaction Update

Account Update

Ping/Pong Updates

Shared Types

Parsed Instruction Support

Parsed Request

Parsed Transaction Update

Instruction Types

Non-streaming Methods

Using the Protocol

Code Generation

Best Practices

See Also

Support