Migrating from WebSockets to Yellowstone gRPC Without Losing Updates
Map every WebSocket subscription to a Yellowstone filter, run both transports side by side, reconcile them by signature, and cut over with a fallback. Tested TypeScript included.
On this page +
Moving a Solana pipeline from WebSocket subscriptions to Yellowstone gRPC is mostly a translation job. The risk is in the switch itself: a few minutes of missed or double-counted transactions can corrupt a ledger, a backtest or a trading position. This guide moves a working WebSocket consumer to Yellowstone gRPC in five steps, running both side by side until the numbers agree, with TypeScript you can run today.
If you are still deciding whether to move, start with Yellowstone gRPC vs WebSockets, which compares the two transports. This post assumes you have decided, and covers how.
01The migration in five steps#
A safe WebSocket to Yellowstone gRPC migration follows the same order every time:
- Inventory every WebSocket subscription your system opens, and why.
- Map each subscription to a Yellowstone filter.
- Normalize both transports into one internal event type.
- Shadow-run both streams and reconcile them by transaction signature.
- Cut over behind a switch, keeping WebSockets as a fallback until gRPC has a clean record.
02Step 1: Inventory your subscriptions#
Grep your codebase for every subscribe call and write down four things for each: the method, its parameters, the commitment level, and what the consumer does with a notification. Teams often find subscriptions nobody remembers opening, and leftover signatureSubscribe calls that were never cleaned up.
Then check your connection budget, because the two transports count differently. WebSocket plans limit concurrent connections. Yellowstone plans limit concurrent streams, and one stream carries many named filters. On NoLimitNodes, Pro allows 5 WebSocket connections and 2 gRPC streams; Ultra allows 20 and 10. Free includes neither. Most WebSocket setups collapse into one or two gRPC streams, so plan the grouping now.
03Step 2: Map each subscription to a Yellowstone filter#
Every standard Solana WebSocket subscription has a Yellowstone equivalent. Table 1 is the translation sheet.
A filtered programSubscribe is the one people get wrong most often, because the field names and value types differ slightly. Offsets and sizes are strings in the TypeScript client:
04Step 3: Normalize both transports into one event#
The single most useful thing you can do is make your business logic stop caring which transport delivered a transaction. Define one internal event type, write one adapter per transport, and route both into the same handler. That is what makes the shadow run and the cutover a configuration change, not a rewrite.
The WebSocket adapter uses the ws package, because NoLimitNodes expects the API key in an x-api-key header on the upgrade request and the browser-style WebSocket constructor cannot set headers.
The gRPC adapter does the conversions that trip up most migrations: signatures arrive as bytes and need bs58, slots arrive as strings, and a failed transaction is marked by a present meta.err rather than a non-null one.
05Step 4: Shadow-run and reconcile by signature#
Run both adapters against the same program and compare what each one saw. A transaction signature is globally unique, so it is the natural join key. Wait about a minute before judging a slot, so a late arrival on either side is not counted as missing.
Each report line tells you three things: how many transactions both streams agreed on, how many only one side saw, and how much earlier gRPC delivered the shared ones. Let it run through busy and quiet periods before you trust it.
Align the filters before you compare
A mismatch is usually a filter difference, not a lost message. The most common one: logsSubscribe includes failed transactions, while most Yellowstone examples set failed: false. When we ran the WebSocket adapter above for 45 seconds against the Raydium CPMM program on 20 November 2026, 96 of 192 notifications (50%) were failed transactions. Compare that against a gRPC filter that drops failures and the WebSocket side appears to see twice as much. That is why the gRPC adapter above leaves failed unset.
- Same commitment on both sides. Comparing processed against confirmed guarantees mismatches.
- Same failed and vote settings. Decide whether failures matter to you, then filter both the same way.
- Look up every one-sided signature. Fetch it with
getTransactionand check how the program address appears in it. A difference that repeats is a filter rule to understand before cutover, not noise.
06Step 5: Cut over, keep a fallback, and close gaps#
Put the transport choice behind a setting such as SOURCE=ws|grpc|both. In both mode, send every event through the Dedupe class from step 3, so a transaction that arrives on both transports is handled once. Run both in production first, then switch to grpc, and keep the WebSocket path deployable for a few weeks.
Whatever transport you end on, connections drop. The safe pattern is the same for both: remember the last signature you handled, reconnect with exponential backoff, then ask plain RPC for everything you missed.
We tested this against mainnet by pausing for 20 seconds on the Raydium CPMM program. Backfill returned the 92 signatures that landed in the gap, oldest first, and a second run returned only the handful that had arrived since. Fetch each one with getTransaction before handling it. On very busy programs the gap can be thousands of signatures, so budget RPC calls for it. The Yellowstone protocol also has a fromSlot replay option; read the keepalive and replay docs before relying on it instead of a backfill.
07Pre-cutover checklist#
08Frequently asked questions#
How long should I run WebSockets and Yellowstone gRPC side by side?
Long enough to cover your busiest and quietest periods, usually several days. Switch only when one-sided signatures are rare and each one is explained, for example by a filter difference you understand and have accepted.
Does Yellowstone gRPC include failed transactions?
Only if you ask for them. Leave failed unset to receive successful and failed transactions, or set it to false to drop failures. WebSocket logsSubscribe includes failed transactions, so align this setting before comparing the two streams.
Can one Yellowstone stream replace several WebSocket connections?
Usually, yes. One stream carries many named filters across accounts, transactions and slots, and each update reports which filters matched it. Group your WebSocket subscriptions into a few streams that fit your plan's stream limit.
What happens to my data when a gRPC stream disconnects?
Updates sent while you were disconnected are not redelivered by a plain subscription. Reconnect with backoff, then backfill from the last signature you handled with getSignaturesForAddress, and deduplicate by signature so nothing is processed twice.
Do I still need RPC after moving to Yellowstone gRPC?
Yes. Streams tell you what changed, but you still need RPC to load starting state, backfill gaps, fetch blockhashes and send transactions.
A WebSocket to Yellowstone gRPC migration is safe when it is boring: map every subscription, normalize to one event type, compare the two streams by signature until they agree, then switch with a way back. New to the gRPC client? Build your first Yellowstone gRPC client in the Academy first. Plans and stream limits are on our Yellowstone gRPC page, and the Solana WebSocket nodes stay available for the shadow run.
Related reading: Solana gRPC API guide · Backfill history and switch to live gRPC · How to evaluate a Solana data stream provider
Per-program, per-instruction topics delivered in their source shape.
Standard Solana subscriptions for account, program, slot, and transaction updates.
Filtered Geyser streams for indexers, bots, and production data pipelines.
Every benchmark in this blog runs against our public endpoints.
Spin up an RPC, WebSocket, or gRPC endpoint in under a minute. Flat monthly pricing. Reproduce the numbers for your own workload.