> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thornode.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Yellowstone gRPC

> Stream filtered Solana updates through Yellowstone Dragon's Mouth.

ThorNode provides location-specific Yellowstone Dragon's Mouth endpoints compatible with `geyser.Geyser/Subscribe`. The dashboard labels this product **Yellowstone DM**.

Copy the target and token from the same location. Send the token as `x-token` request metadata when you open a subscription.

## Filtered Geyser streams

Yellowstone delivers long-lived, server-filtered Solana updates over gRPC.

Use [ThorEdge RPC](/products/thoredge-rpc) for request-response calls and WebSocket subscriptions. Use [Pulse Decoded Shreds](/products/pulse) for a sig-first or full-transaction feed over QUIC.

## Quick reference

| Item             | Value                                                                                                  |
| ---------------- | ------------------------------------------------------------------------------------------------------ |
| Dashboard path   | **Endpoints** sidebar → **Endpoints** tab → **Token & Endpoints** → **Streaming** → **Yellowstone DM** |
| Interface        | `geyser.Geyser/Subscribe`                                                                              |
| Client and proto | [`rpcpool/yellowstone-grpc`](https://github.com/rpcpool/yellowstone-grpc)                              |
| Transport        | Plaintext gRPC over HTTP/2 (`h2c`)                                                                     |
| Target           | Bare `host:port` copied from the dashboard                                                             |
| Authentication   | Location token sent as `x-token` request metadata                                                      |
| Live limits      | **Limits → gRPC Yellowstone → Concurrent streams** and **Accounts across filters**                     |

## Open a subscription

<Steps>
  <Step title="Choose a location">
    Open **Endpoints**, keep the **Endpoints** tab selected, choose the access,
    network, and location. Copy the token from the location token row and the
    target from **Yellowstone DM** in the **Streaming** section of **Token &
    Endpoints**.
  </Step>

  <Step title="Configure the client">
    Use a Yellowstone client built from the `geyser.proto` in the upstream
    repository.
  </Step>

  <Step title="Open the gRPC channel">
    Configure the copied target as a plaintext gRPC (`h2c`) channel.
  </Step>

  <Step title="Attach the token">
    Add the location token to the gRPC request metadata with the exact key
    `x-token`.
  </Step>

  <Step title="Subscribe">
    Start with a slot filter, or an account or transaction filter containing an
    explicit public key. Add more keys only after the first stream returns
    updates.
  </Step>
</Steps>

<Warning>
  The current Yellowstone target uses plaintext gRPC, so `x-token` metadata is
  not encrypted in transit. Connect through a trusted private network, VPN, or
  encrypted tunnel. Keep the token out of the target, query string, source code,
  and logs.
</Warning>

The subscription is running when it returns `SubscribeUpdate` messages whose `filters` field contains your filter name.

## Test a slot subscription

Follow the [Yellowstone quickstart](/products/yellowstone-grpc/quickstart) to stream slots with `grpcurl`, then narrow to a transaction filter. The [Subscribe reference](/api-reference/yellowstone/subscribe) lists every request field and what it returns on ThorNode.

## Run in production

* Keep receive-path work small and move expensive processing to bounded worker queues.
* Monitor stream count, filter usage, queue depth, and consumer lag.
* Reconnect with bounded exponential backoff and jitter.
* Recreate subscriptions after reconnecting.
* Detect gaps and reconcile through RPC when application correctness requires it.
* Close unused streams instead of leaving idle subscriptions open.

## Troubleshooting

| Problem               | Fix                                                                                                                                   |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `Unauthenticated`     | Recopy the token and Yellowstone target for the same location and send the token as `x-token` metadata.                               |
| Cannot connect        | Use the copied `host:port` with plaintext HTTP/2: `-plaintext` in `grpcurl` or an `http://` URI in clients that require a scheme.     |
| Subscription rejected | Reduce the request to one supported named filter, then check **Concurrent streams** and **Accounts across filters** under **Limits**. |
| Repeated disconnects  | Drain updates promptly, bound downstream queues, and reconnect with exponential backoff and jitter.                                   |

## Next steps

* [Run the quickstart](/products/yellowstone-grpc/quickstart)
* [Read the Subscribe reference](/api-reference/yellowstone/subscribe)
* [Protect streaming credentials](/reference/security)
* [Read current stream limits](/reference/plans-and-limits)
* [Use ThorEdge RPC for reconciliation](/products/thoredge-rpc)