Streaming Guide
Nodius supports two streaming protocols: WebSocket (standard Solana subscriptions) and Yellowstone gRPC (high-performance streaming). This guide covers connection requirements, billing, and operational details.
WebSocket
Connection Requirements
- Endpoint: wss://rpc.nodius.xyz/ws
- Authentication: Session token (Bearer) or API key via Authorization header or Sec-WebSocket-Protocol: auth.
- Minimum credits: 100 to connect
- Auto-disconnect: below 10 credits (close code 4002)
Connection Caps
| Limit | Value |
|---|---|
| Max concurrent subscriptions | 50 |
There is no hard limit on the number of WebSocket connections per account, but each connection shares the subscription limit.
Billing Intervals
| Event | Cost | When |
|---|---|---|
| Subscribe | 5 credits | Immediately on subscription creation |
| Notification | 1 credit | Each notification delivered to client |
| Unsubscribe | Free | No charge |
| Connect/Disconnect | Free | No charge |
Credits are deducted in real-time. The server checks credit balance periodically and disconnects clients that drop below the 10-credit minimum.
High-Frequency Subscription Costs
| Subscription | Approx Rate | Credits/Hour |
|---|---|---|
| slotSubscribe | ~2.5/sec | ~9,000 |
| accountSubscribe (active DEX pool) | ~10/sec | ~36,000 |
| logsSubscribe("all") | ~100+/sec | ~360,000 |
| programSubscribe (Token Program) | ~500+/sec | ~1,800,000 |
Be cautious with logsSubscribe("all") and programSubscribe on popular programs. These can drain credits extremely rapidly.
Disconnect Reasons
| Close Code | Reason | Description | Action |
|---|---|---|---|
| 1000 | normal | Clean close by client | No action |
| 1008 | policy_violation | Invalid or expired token | Re-authenticate |
| 4001 | auth_failed | Authentication failed | Check credentials |
| 4002 | insufficient_credits | Balance below 10 credits | Deposit more USDC |
| 4003 | rate_limited | Too many messages/sec | Reduce message rate |
| 1006 | abnormal | Network interruption | Reconnect with backoff |
Reconnect Behavior
Recommended reconnection strategy: 1. Detect disconnect via close event 2. Wait: min(2^attempt * 100ms, 30s) with jitter 3. Re-authenticate (refresh session token if expired) 4. Reconnect and re-subscribe to all previous subscriptions 5. Reset attempt counter on successful connection
The SDK (@nodius/sdk) handles reconnection and subscription restoration automatically.
Yellowstone gRPC
Connection Model
- Endpoint: grpc://rpc.nodius.xyz:10001
- Authentication: API key or session token in the
x-tokengRPC metadata field - Billing: 60 credits per minute while connected (flat rate)
- No per-notification charge
When to Use Yellowstone vs WebSocket
| Use Case | Recommended | Why |
|---|---|---|
| 1-5 account watches | WebSocket | Lower base cost |
| High-frequency streaming | Yellowstone | Flat rate, no per-notification charge |
| Block-level data | Yellowstone | Better throughput |
| Transaction filtering | Yellowstone | Server-side filtering |
| Simple slot/root updates | WebSocket | Lower overhead |
Yellowstone Subscription Types
- Account subscriptions (by pubkey or program owner)
- Transaction subscriptions (by account mention or program)
- Slot subscriptions
- Block subscriptions
- Entry subscriptions
Yellowstone Billing Details
- Billing starts when the gRPC SubscribeRequest is acknowledged
- Charged every 60 seconds
- If credits run out mid-connection, the stream is terminated
- Reconnecting starts a new billing cycle immediately
- No pro-rating: partial minutes are billed as full minutes
Cost Comparison Example
Monitoring 100 active accounts: - WebSocket: 100 subscriptions x 5 = 500 credits setup + ~100 notifications/sec x 1 = 360,000 credits/hour - Yellowstone: 60 credits/min x 60 = 3,600 credits/hour (unlimited notifications)
For high-throughput use cases, Yellowstone is significantly more cost-effective.