Account Subscriptions - Drift Protocol v2

Drift SDK supports three subscription mechanisms for receiving account updates: Polling, WebSocket, and gRPC. Each has different trade-offs for latency, reliability, and resource usage.

Subscription Types Overview

Polling

Best for: Most applications

Batched account fetches
Predictable RPC usage
Good performance

WebSocket

Best for: Real-time updates

Lower latency
Event-driven
Higher RPC load

gRPC

Best for: High frequency

Lowest latency
Highest throughput
Requires infrastructure

Polling Subscription

Polling is the recommended approach for most applications. It uses BulkAccountLoader to batch account fetches efficiently.

Setup

import {
  DriftClient,
  BulkAccountLoader,
  User,
} from '@drift-labs/sdk';
import { Connection } from '@solana/web3.js';

const connection = new Connection(process.env.RPC_URL!);

// Create bulk account loader
const bulkAccountLoader = new BulkAccountLoader(
  connection,
  'confirmed', // commitment
  1000 // polling frequency in milliseconds
);

// Initialize DriftClient with polling
const driftClient = new DriftClient({
  connection,
  wallet,
  programID,
  accountSubscription: {
    type: 'polling',
    accountLoader: bulkAccountLoader,
  },
});

await driftClient.subscribe();

// Create User with same account loader
const user = new User({
  driftClient,
  userAccountPublicKey: await driftClient.getUserAccountPublicKey(),
  accountSubscription: {
    type: 'polling',
    accountLoader: bulkAccountLoader,
  },
});

await user.subscribe();

Configuration

accountLoader

BulkAccountLoader

required

Shared BulkAccountLoader instance for batching

pollingFrequency

number

Milliseconds between polls (default: 1000)

Advantages

Efficient: Batches multiple account fetches into single RPC calls
Predictable: Constant RPC load
Reliable: No WebSocket connection issues
Shared: One loader can serve multiple accounts

Example: Multiple Users

// Share one BulkAccountLoader across multiple users
const bulkAccountLoader = new BulkAccountLoader(connection, 'confirmed', 1000);

const users: User[] = [];
for (let subAccountId = 0; subAccountId < 3; subAccountId++) {
  const user = new User({
    driftClient,
    userAccountPublicKey: await driftClient.getUserAccountPublicKey(subAccountId),
    accountSubscription: {
      type: 'polling',
      accountLoader: bulkAccountLoader,
    },
  });
  
  await user.subscribe();
  users.push(user);
}

// All users share the same polling mechanism

WebSocket Subscription

WebSocket provides real-time updates via Solana’s account change notifications.

Setup

import { DriftClient, User } from '@drift-labs/sdk';

// Initialize DriftClient with WebSocket
const driftClient = new DriftClient({
  connection,
  wallet,
  programID,
  accountSubscription: {
    type: 'websocket',
    resubscriptionOptions: {
      resubscribe: true,
      resubTimeoutMs: 30000,
      logResubscriptionErrors: true,
    },
  },
});

await driftClient.subscribe();

// Create User with WebSocket
const user = new User({
  driftClient,
  userAccountPublicKey: await driftClient.getUserAccountPublicKey(),
  accountSubscription: {
    type: 'websocket',
    resubscriptionOptions: {
      resubscribe: true,
      resubTimeoutMs: 30000,
    },
  },
});

await user.subscribe();

Resubscription Options

resubscribe

boolean

Automatically reconnect on disconnect (recommended: true)

resubTimeoutMs

number

Timeout before resubscription attempt (default: 30000)

logResubscriptionErrors

boolean

Log errors during resubscription attempts

Handling Events

// Listen for updates
user.eventEmitter.on('userAccountUpdate', (userAccount) => {
  console.log('User account updated');
  console.log('Positions:', userAccount.perpPositions.length);
  console.log('Orders:', userAccount.orders.length);
});

// Listen for errors
user.eventEmitter.on('error', (error) => {
  console.error('WebSocket error:', error);
  // Implement error handling/fallback
});

// DriftClient events
driftClient.eventEmitter.on('perpMarketAccountUpdate', (market) => {
  console.log(`Market ${market.marketIndex} updated`);
});

driftClient.eventEmitter.on('oraclePriceUpdate', (pubkey, source, data) => {
  console.log('Oracle price:', data.price.toString());
});

Advantages

Low latency: Immediate updates on account changes
Event-driven: React to changes as they happen
Real-time: Best for market making and high-frequency strategies

Considerations

WebSocket connections can disconnect. Always implement resubscription logic and error handling.

gRPC Subscription

gRPC provides the lowest latency and highest throughput using Yellowstone or Laser gRPC infrastructure.

Prerequisites

Access to a Yellowstone or Laser gRPC endpoint
Authentication token

Setup with Yellowstone

import { DriftClient, GrpcConfigs } from '@drift-labs/sdk';

const grpcConfig: GrpcConfigs = {
  endpoint: 'https://your-grpc-endpoint.com',
  token: process.env.GRPC_TOKEN!,
  channelOptions: {
    'grpc.max_receive_message_length': 1024 * 1024 * 100,
  },
};

const driftClient = new DriftClient({
  connection,
  wallet,
  programID,
  accountSubscription: {
    type: 'grpc',
    grpcConfig,
  },
});

await driftClient.subscribe();

Setup with Laser (Helius)

import { LaserstreamConfig } from '@drift-labs/sdk';

const laserConfig: LaserstreamConfig = {
  apiKey: process.env.HELIUS_API_KEY!,
};

const driftClient = new DriftClient({
  connection,
  wallet,
  programID,
  accountSubscription: {
    type: 'grpc',
    grpcConfig: laserConfig,
  },
});

await driftClient.subscribe();

Configuration

endpoint

string

required

gRPC server endpoint URL

token

string

Authentication token

channelOptions

object

gRPC channel configuration options

Advantages

Lowest latency: Sub-millisecond updates
High throughput: Handle many accounts efficiently
Reliable: Dedicated infrastructure
Professional: Used by market makers

Considerations

gRPC requires additional infrastructure and typically costs more than standard RPC. Best for professional trading operations.

Listening to Updates

All subscription types emit events that you can listen to:

User Account Updates

import { positionIsAvailable, OrderStatus } from '@drift-labs/sdk';

user.eventEmitter.on('userAccountUpdate', (userAccount) => {
  // User account changed
  console.log('Authority:', userAccount.authority.toBase58());
  console.log('Settled PnL:', userAccount.settledPerpPnl.toString());
  
  // Check positions
  for (const position of userAccount.perpPositions) {
    if (!positionIsAvailable(position)) {
      console.log(
        `Position ${position.marketIndex}:`,
        position.baseAssetAmount.toString()
      );
    }
  }
  
  // Check orders
  for (const order of userAccount.orders) {
    if (order.status === OrderStatus.OPEN) {
      console.log(
        `Order ${order.orderId}:`,
        order.baseAssetAmount.toString()
      );
    }
  }
});

Market Updates

driftClient.eventEmitter.on('perpMarketAccountUpdate', (market) => {
  console.log(`Market ${market.marketIndex} updated`);
  console.log('AMM base reserve:', market.amm.baseAssetReserve.toString());
  console.log('AMM quote reserve:', market.amm.quoteAssetReserve.toString());
});

driftClient.eventEmitter.on('spotMarketAccountUpdate', (market) => {
  console.log(`Spot market ${market.marketIndex} updated`);
  console.log('Deposit balance:', market.depositBalance.toString());
  console.log('Borrow balance:', market.borrowBalance.toString());
});

Oracle Price Updates

driftClient.eventEmitter.on('oraclePriceUpdate', (pubkey, source, data) => {
  console.log('Oracle updated:', pubkey.toBase58());
  console.log('Price:', convertToNumber(data.price, PRICE_PRECISION));
  console.log('Confidence:', data.confidence.toString());
  console.log('Slot:', data.slot);
});

Subscription Lifecycle

Subscribing

// Subscribe to start receiving updates
await driftClient.subscribe();
await user.subscribe();

console.log('Subscribed to account updates');

Unsubscribing

// Always unsubscribe when done to prevent memory leaks
await user.unsubscribe();
await driftClient.unsubscribe();

console.log('Unsubscribed from account updates');

Fetching Latest Data

// Force fetch latest data (useful for polling)
await user.fetchAccounts();
await driftClient.fetchAccounts();

const userAccount = user.getUserAccount();
console.log('Latest user account data fetched');

Best Practices

Choose the right subscription type

Polling: Default choice for most applications
WebSocket: When you need real-time updates and can handle reconnections
gRPC: For professional market making and HFT

Share BulkAccountLoader instances

// Good: Share one loader
const loader = new BulkAccountLoader(connection, 'confirmed', 1000);
const client = new DriftClient({ accountSubscription: { type: 'polling', accountLoader: loader } });
const user = new User({ accountSubscription: { type: 'polling', accountLoader: loader } });

// Bad: Create multiple loaders
const loader1 = new BulkAccountLoader(...);
const loader2 = new BulkAccountLoader(...); // Wasteful!

Handle errors gracefully

user.eventEmitter.on('error', async (error) => {
  console.error('Subscription error:', error);
  
  // Attempt to resubscribe
  try {
    await user.unsubscribe();
    await user.subscribe();
    console.log('Resubscribed successfully');
  } catch (resubError) {
    console.error('Failed to resubscribe:', resubError);
    // Implement fallback logic
  }
});

Monitor subscription health

// Check if still subscribed
if (!user.isSubscribed) {
  console.warn('User subscription lost');
  await user.subscribe();
}

// Periodic health check
setInterval(async () => {
  if (!user.isSubscribed) {
    console.warn('Resubscribing user...');
    await user.subscribe();
  }
}, 30000); // Check every 30s

Performance Comparison

Feature	Polling	WebSocket	gRPC
Latency	~1s	~100-500ms	~10-50ms
RPC Load	Low	High	N/A
Reliability	High	Medium	High
Setup Complexity	Low	Low	High
Cost	Standard RPC	Standard RPC	Premium

Next Steps

Account Subscribers API

Detailed API documentation

Oracle Integration

Work with oracle price feeds

WebSocket API

WebSocket subscriber reference

gRPC API

gRPC subscriber reference

Getting Started

Core Concepts

SDK Guides

Math & Calculations

​Subscription Types Overview

Polling

WebSocket

gRPC

​Polling Subscription

​Setup

​Configuration

​Advantages

​Example: Multiple Users

​WebSocket Subscription

​Setup

​Resubscription Options

​Handling Events

​Advantages

​Considerations

​gRPC Subscription

​Prerequisites

​Setup with Yellowstone

​Setup with Laser (Helius)

​Configuration

​Advantages

​Considerations

​Listening to Updates

​User Account Updates

​Market Updates

​Oracle Price Updates

​Subscription Lifecycle

​Subscribing

​Unsubscribing

​Fetching Latest Data

​Best Practices

​Performance Comparison

​Next Steps

Account Subscribers API

Oracle Integration

WebSocket API

gRPC API

Build docs developers (and LLMs) love

Subscription Types Overview

Polling Subscription

Setup

Configuration

Advantages

Example: Multiple Users

WebSocket Subscription

Setup

Resubscription Options

Handling Events

Advantages

Considerations

gRPC Subscription

Prerequisites

Setup with Yellowstone

Setup with Laser (Helius)

Configuration

Advantages

Considerations

Listening to Updates

User Account Updates

Market Updates

Oracle Price Updates

Subscription Lifecycle

Subscribing

Unsubscribing

Fetching Latest Data

Best Practices

Performance Comparison

Next Steps