> This is part 1 of 3 of the full documentation (pages 1–100 of 268).
> The content is paginated: fetch every part to see all of it.
> Next part: https://docs.triton.one/llms-full.txt/1
> Page index: https://docs.triton.one/llms.txt

# Welcome to Triton One

Premium bare-metal infrastructure for production workloads on Solana, Sui, and Monad.

Official documentation for Triton One's RPC infrastructure on Solana, Sui, and Monad: the nodes, streaming services, and data services your application uses to read from and write to the chain.

## Why teams choose us

Production teams have built on Triton since 2021:

* **Hardware per workload:** read clusters, streaming nodes, historical indexers, and transaction-routing nodes each run on machines configured for their role.
* **8 cities on 3 continents:** one Anycast address reaches the nearest region, with health checks, load balancing, and automatic failover.
* **Engineering support:** 1-1 support from senior engineers, through the chat in your customer dashboard.
* **Open markets:** Triton does not frontrun, backrun, sell, or extract value from your order flow. For what we log and how long we keep it, see [Privacy and data protection](https://docs.triton.one/security/privacy-and-security).
* **Solana clusters:** shared Solana mainnet runs on multi-node clusters in the US, Europe, and Asia-Pacific.

## Networks we support

{% tabs %}
{% tab title="Solana" %}

<table data-search="false"><thead><tr><th>Service</th><th align="center">Mainnet</th><th align="center">Devnet</th></tr></thead><tbody><tr><td><strong>Reading account state</strong></td><td align="center"></td><td align="center"></td></tr><tr><td>Standard RPC (JSON-RPC)</td><td align="center">✓</td><td align="center">✓</td></tr><tr><td>Account Sync</td><td align="center">✓</td><td align="center">✗</td></tr><tr><td>Cloudbreak accounts</td><td align="center">✓</td><td align="center">Partial‡</td></tr><tr><td>Metaplex DAS API</td><td align="center">✓</td><td align="center">✓</td></tr><tr><td><strong>Real-time streaming</strong></td><td align="center"></td><td align="center"></td></tr><tr><td>WebSocket</td><td align="center">✓</td><td align="center">✓</td></tr><tr><td>Yellowstone gRPC (Dragon's Mouth)</td><td align="center">✓</td><td align="center">✓</td></tr><tr><td>Fumarole persistent gRPC</td><td align="center">✓</td><td align="center">✗</td></tr><tr><td>Riptide</td><td align="center">✓</td><td align="center">✗</td></tr><tr><td>Shred Streaming</td><td align="center">✓</td><td align="center">✗</td></tr><tr><td>Preconfirmations gRPC</td><td align="center">✓</td><td align="center">✗</td></tr><tr><td><strong>Historical data</strong></td><td align="center"></td><td align="center"></td></tr><tr><td>Superbank archive</td><td align="center">✓</td><td align="center">✗*</td></tr><tr><td><strong>Sending transactions</strong></td><td align="center"></td><td align="center"></td></tr><tr><td>Transaction sending (Jet)</td><td align="center">✓</td><td align="center">✓†</td></tr><tr><td>Titan Swap API</td><td align="center">✓</td><td align="center">✗</td></tr></tbody></table>

\*On devnet, historical methods are served by standard Solana RPC nodes, not Superbank.\
†On devnet, only shared endpoints send through Jet. Devnet sends are not staked, so they don't get stake-weighted quality of service.\
‡On devnet, Cloudbreak serves only `getProgramAccounts`. Other account methods are served by standard Solana RPC nodes.

Go to the [Solana docs](https://docs.triton.one/solana/)
{% endtab %}

{% tab title="Sui" %}

| Service       | Mainnet | Testnet |
| ------------- | :-----: | :-----: |
| gRPC          |    ✓    |    ✓    |
| GraphQL       |    ✓    |    ✗    |
| Archival gRPC |    ✓    |    ✗    |
| Walrus        |    ✓    |    ✓    |
| Seal          |    ✓    |    ✓    |

Go to the [Sui docs](https://docs.triton.one/sui/)
{% endtab %}

{% tab title="Monad" %}

| Service   | Mainnet | Testnet |
| --------- | :-----: | :-----: |
| JSON-RPC  |    ✓    |    ✓    |
| WebSocket |    ✓    |    ✓    |

Go to the [Monad docs](https://docs.triton.one/monad/)
{% endtab %}
{% endtabs %}

**Need another chain?** [Contact sales](https://triton.one/contact).

## Find your way around

Five sections, switchable from the top of any page:

* **Triton** (this section): account, plans and billing, endpoints and regions, limits, authentication, and privacy. Applies to every chain.
* [**Solana**](https://docs.triton.one/solana/): reading account state, real-time streaming, historical data, and sending transactions, with quickstarts, use-case guides, and the RPC method reference.
* [**Sui**](https://docs.triton.one/sui/): gRPC, GraphQL, the archival service, Walrus, Seal, and dedicated nodes.
* [**Monad**](https://docs.triton.one/monad/): Ethereum-compatible JSON-RPC, WebSocket subscriptions, debug and tracing, and Monad extensions.
* [**Validators**](https://docs.triton.one/validators/): white-label Solana validators, and SOL staking with weekly USDC pay-outs.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-play">:play:</i> <strong>Quickstart</strong></td><td>Create an account, copy your endpoint, and send your first request.</td><td><a href="https://docs.triton.one/quickstart">Quickstart</a></td></tr><tr><td><i class="fa-credit-card">:credit-card:</i> <strong>Plans and billing</strong></td><td>Payment options, shared vs dedicated, and how usage is billed.</td><td><a href="https://docs.triton.one/account-and-billing/plans-and-billing">Plans and billing</a></td></tr></tbody></table>

## For AI agents

* **Page index:** `https://docs.triton.one/llms.txt`, every page with a one-line summary.
* **Full text:** `https://docs.triton.one/llms-full.txt`, every page in one file.
* **Any page as Markdown:** add `.md` to the page URL.
* **MCP server:** `https://docs.triton.one/~gitbook/mcp`, for AI agents to search the docs and fetch only the pages they need.

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Quickstart

Create your Triton account, copy your endpoint and token, and send your first request on Solana, Sui, or Monad.

{% stepper %}
{% step %}

#### Create your account

Sign up at [customers.triton.one](https://customers.triton.one/onboarding):

1. **Sign-in credentials:** choose **Individual** or **Business**. Enter your email, username, and password, then the code from the confirmation email.
2. **Personal details:** your real name, date of birth, address, and what you're building.
3. **Terms & conditions:** accept the terms.

Your details are checked against sanctions and politically exposed person (PEP) lists before you can pay. If your signup needs a manual review, Triton contacts you.

Business accounts also enter company details and name their administrators, beneficial owners, and authorized signatories. Only an authorized signatory can accept the terms.
{% endstep %}

{% step %}

#### Fund your balance

Set your deposit and pay in the Coinflow checkout.

* Minimum deposit: see the [pricing page](https://triton.one/pricing). Paid in USDC.
* Usable on Solana, Sui, and Monad. Usage is deducted as you go.
* Valid for 12 months. Non-refundable.
* Top up any time with **Buy Credits**, under your organization in the dashboard menu.

Can't pay in crypto, or need invoicing or a dedicated node? See [Plans and billing](https://docs.triton.one/account-and-billing/plans-and-billing).
{% endstep %}

{% step %}

#### Choose your chains

On **Create your first endpoint**:

* **Project name:** any name.
* **Select your chains:** Solana, Sui, Monad. Each chain gets a mainnet and a test-network subscription (Solana devnet and testnet, Sui testnet, Monad testnet). Each subscription has its own endpoint and token.
* **Enter your domain to activate RPC endpoints** (optional): your app's domain without `https://`, for example `app.example.com`. If you leave it blank, the endpoints start inactive. Turn each one on with its switch under **Endpoints** in the subscription.

To add a chain later, contact support.
{% endstep %}

{% step %}

#### Copy your endpoint and token

In the [customer dashboard](https://customers.triton.one), under **Subscriptions**, click the subscription whose **Type** is the chain and network you want, for example **Solana Mainnet**.

<div data-with-frame="true"><figure><img src="https://1114586215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoQO86QYVpwvJExgmA0oK%2Fuploads%2FBtVJsWRGUW9rQuNxipTq%2F02-home-subscriptions.png?alt=media&amp;token=2c564ddc-6c15-45fb-9836-07898e01ab3c" alt="Customer dashboard Home page, Subscriptions table. Callout 1 marks the subscription name. Callout 2 marks the Type column, for example Solana Mainnet." width="563"><figcaption><p>1: click the subscription name. 2: check its <strong>Type</strong>.</p></figcaption></figure></div>

Copy:

* **Endpoint name:** the first part of the hostname under **Endpoints** → **Hostname(s)**. For `abc123.mainnet.rpcpool.com`, it's `abc123`. Use it as `<your-endpoint>` in the next step.
* **Secret token:** under **RPC / gRPC Tokens**, click the token and copy **Secret token**. Or click **Copy** under **Connection String for Endpoint** for the full URL with the token.

{% hint style="info" %}
Never put the token in frontend code. Browser apps use the endpoint URL alone, authorized by allowed origins. See [Auth and security](https://docs.triton.one/security/authentication).
{% endhint %}
{% endstep %}

{% step %}

#### Send your first request

Replace `<your-endpoint>` and `<your-token>`, then run. TypeScript examples use top-level `await`: set `"type": "module"` in `package.json`.

**Solana**

Get the current slot:

{% tabs %}
{% tab title="curl" %}
{% code overflow="wrap" %}

```bash
curl "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSlot"}'
```

{% endcode %}
{% endtab %}

{% tab title="TypeScript" %}

```bash
npm install @solana/kit
```

{% code overflow="wrap" %}

```typescript
import { createSolanaRpc } from "@solana/kit";

const rpc = createSolanaRpc("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>");
const slot = await rpc.getSlot().send();
console.log(slot);
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}

```bash
pip install requests
```

{% code overflow="wrap" %}

```python
import requests

r = requests.post(
    'https://<your-endpoint>.mainnet.rpcpool.com/<your-token>',
    json={'jsonrpc': '2.0', 'id': 1, 'method': 'getSlot'},
)
print(r.json()['result'])
```

{% endcode %}
{% endtab %}

{% tab title="Rust" %}

```bash
cargo add solana-client
```

{% code overflow="wrap" %}

```rust
use solana_client::rpc_client::RpcClient;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = RpcClient::new(
        "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>".to_string(),
    );
    println!("{}", client.get_slot()?);
    Ok(())
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

Expected response (curl):

```json
{ "jsonrpc": "2.0", "result": 458705877, "id": 1 }
```

**Sui**

Get the current reference gas price on Sui mainnet (GraphQL):

{% hint style="info" %}
GraphQL is on mainnet only. On testnet, use gRPC.
{% endhint %}

{% tabs %}
{% tab title="curl" %}
{% code overflow="wrap" %}

```bash
curl "https://<your-endpoint>.mainnet.sui.rpcpool.com/graphql" \
  -H "X-Token: <your-token>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "{ epoch { referenceGasPrice } }" }'
```

{% endcode %}
{% endtab %}

{% tab title="TypeScript" %}
No install needed (built-in `fetch`, Node.js 18+).

{% code overflow="wrap" %}

```typescript
const res = await fetch("https://<your-endpoint>.mainnet.sui.rpcpool.com/graphql", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-Token": "<your-token>" },
  body: JSON.stringify({ query: "{ epoch { referenceGasPrice } }" }),
});
const { data } = (await res.json()) as { data: { epoch: { referenceGasPrice: string } } };
console.log(data.epoch.referenceGasPrice);
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}

```bash
pip install requests
```

```python
import requests

r = requests.post(
    'https://<your-endpoint>.mainnet.sui.rpcpool.com/graphql',
    headers={'X-Token': '<your-token>'},
    json={'query': '{ epoch { referenceGasPrice } }'},
)
print(r.json()['data']['epoch']['referenceGasPrice'])
```

{% endtab %}

{% tab title="Rust" %}

```bash
cargo add reqwest --features blocking,json
cargo add serde_json
```

```rust
use serde_json::{json, Value};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let body: Value = reqwest::blocking::Client::new()
        .post("https://<your-endpoint>.mainnet.sui.rpcpool.com/graphql")
        .header("X-Token", "<your-token>")
        .json(&json!({ "query": "{ epoch { referenceGasPrice } }" }))
        .send()?
        .json()?;
    println!("{}", body["data"]["epoch"]["referenceGasPrice"]);
    Ok(())
}
```

{% endtab %}
{% endtabs %}

Expected response (curl):

```json
{ "data": { "epoch": { "referenceGasPrice": "100" } } }
```

**Monad**

Get the latest block number:

{% tabs %}
{% tab title="curl" %}
{% code overflow="wrap" %}

```bash
curl "https://<your-endpoint>.mainnet.monad.rpcpool.com/<your-token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

{% endcode %}
{% endtab %}

{% tab title="TypeScript" %}

```bash
npm install viem
```

{% code overflow="wrap" %}

```typescript
import { createPublicClient, http } from "viem";

const client = createPublicClient({
  transport: http("https://<your-endpoint>.mainnet.monad.rpcpool.com/<your-token>"),
});
console.log(await client.getBlockNumber());
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}

```bash
pip install web3
```

{% code overflow="wrap" %}

```python
from web3 import Web3

w3 = Web3(Web3.HTTPProvider('https://<your-endpoint>.mainnet.monad.rpcpool.com/<your-token>'))
print(w3.eth.block_number)
```

{% endcode %}
{% endtab %}

{% tab title="Rust" %}

```bash
cargo add reqwest --features blocking,json
cargo add serde_json
```

{% code overflow="wrap" %}

```rust
use serde_json::{json, Value};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let body: Value = reqwest::blocking::Client::new()
        .post("https://<your-endpoint>.mainnet.monad.rpcpool.com/<your-token>")
        .json(&json!({ "jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": [] }))
        .send()?
        .json()?;
    println!("{}", body["result"]);
    Ok(())
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

Expected response (curl):

```json
{ "jsonrpc": "2.0", "result": "0x6d5a263", "id": 1 }
```

{% endstep %}
{% endstepper %}

## Start building

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-solana">:solana:</i> <strong>Solana</strong></td><td>RPC, streaming, historical data, transaction sending, and trading APIs for Solana mainnet and devnet.</td><td><a href="https://docs.triton.one/solana/">Solana</a></td></tr><tr><td><i class="fa-droplet">:droplet:</i> <strong>Sui</strong></td><td>gRPC, Seal and Walrus for Sui mainnet and testnet. GraphQL and archival for mainnet.</td><td><a href="https://docs.triton.one/sui/">SUI</a></td></tr><tr><td><i class="fa-cube">:cube:</i> <strong>Monad</strong></td><td>Ethereum-compatible JSON-RPC and WebSocket endpoints for Monad mainnet and testnet.</td><td><a href="https://docs.triton.one/monad/">Monad</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Plans and billing

Shared or dedicated infrastructure, pay-as-you-go or invoiced billing, and how requests and bandwidth are measured.

Current rates are on the [pricing page](https://triton.one/pricing). This page explains how billing works.

## Shared or dedicated

<table data-search="false"><thead><tr><th></th><th>Shared infrastructure</th><th>Dedicated node</th></tr></thead><tbody><tr><td><strong>Locations</strong></td><td>8 cities on 3 continents, routed to the nearest</td><td>One location of your choice</td></tr><tr><td><strong>Services</strong></td><td>Every service on every network</td><td>One network per node. Solana: the monthly price of a standard node includes Dragon's Mouth gRPC streaming. JSON-RPC and WebSocket run on shared infrastructure and are billed as shared usage. Fumarole is billed separately, per usage. Sui: see the Sui dedicated nodes page. Monad: dedicated nodes are not offered. Custom setups on request</td></tr><tr><td><strong>Latency</strong></td><td>Low: routed to the nearest region</td><td>Low: in the data centre you choose</td></tr><tr><td><strong>Capacity</strong></td><td>Shared with other customers</td><td>Fixed gRPC streaming capacity for your traffic only. WebSocket runs on shared servers by default. If your node goes down, traffic fails over to shared backup nodes by default</td></tr><tr><td><strong>Rate limits</strong></td><td>Flexible, adjustable on request. Rate limits do not affect pricing</td><td>Can be customized for your workload. Contact support to review them</td></tr><tr><td><strong>Billing</strong></td><td>Per request and per GB, pay-as-you-go or invoiced</td><td>Fixed monthly price per node, invoiced. On Solana it covers Dragon's Mouth gRPC streaming. On Sui it covers gRPC streaming, and unary gRPC, archival gRPC, Walrus and Seal are billed per usage. On Solana, WebSocket, Fumarole and JSON-RPC are billed separately, per usage</td></tr><tr><td><strong>Sign up</strong></td><td><a href="https://customers.triton.one/onboarding">Self-serve</a></td><td><a href="https://triton.one/contact">Contact sales</a></td></tr></tbody></table>

* Shared fits most workloads, including trading bots and market makers.
* [Riptide](https://docs.triton.one/solana/real-time-streaming/riptide) gRPC on shared infrastructure performs comparably to a dedicated node.
* Choose dedicated for high-volume gRPC streaming, when metered streaming would cost more than a node's fixed monthly price on the [pricing page](https://triton.one/pricing).
* Choose dedicated for a workload that needs isolated gRPC streaming capacity.

## Pay-as-you-go or invoiced

<table data-search="false"><thead><tr><th></th><th>Pay-as-you-go</th><th>Invoiced</th></tr></thead><tbody><tr><td><strong>Payment</strong></td><td>USDC, through <strong>Buy credits</strong> in the customer dashboard</td><td>Card, ACH, USDC, or wire</td></tr><tr><td><strong>How you're charged</strong></td><td>Usage is deducted from your prepaid balance</td><td>Invoiced on the 1st of each month for the coming month</td></tr><tr><td><strong>Minimum</strong></td><td>A minimum prepaid deposit, valid for 12 months</td><td>A minimum monthly invoice</td></tr><tr><td><strong>Going over</strong></td><td>Not possible. Service stops when your balance reaches zero. The last debit can be larger than what was left; your balance stops at zero and the difference isn't taken from your next deposit</td><td>Billed at the same rates on the next invoice, without interruption</td></tr><tr><td><strong>Coverage</strong></td><td>Every service and network</td><td>Every service and network</td></tr><tr><td><strong>Cancellation</strong></td><td>Set by the pay-as-you-go terms you accept at signup. Unused balance is not refunded</td><td>One calendar month's notice</td></tr><tr><td><strong>Sign up</strong></td><td><a href="https://customers.triton.one/onboarding">Self-serve</a></td><td><a href="https://triton.one/contact">Contact sales</a></td></tr></tbody></table>

* The minimum deposit is on the [pricing page](https://triton.one/pricing).
* Sales sets your minimum monthly invoice when you switch to invoicing.
* Deposits are non-refundable, under the terms you accept at signup.
* Devnet and testnet are free on every subscription and don't use your balance.

Teams with steady production traffic usually switch to invoicing:

* **Overages at the same rates.** Usage above your estimate is added to your next monthly invoice, with no service interruption.
* **Predictable bills.** The same line items each month, sized on the previous month's usage.

To switch, open the chat in your [customer dashboard](https://customers.triton.one) or [contact sales](https://triton.one/contact).

## Top-ups, alerts, and usage

* **Top up:** customer dashboard → **Billing** → **Buy credits**.
* **Low-balance alert:** in **Billing**, turn on **Low balance notifications**, set a threshold in USD, and click **Save**. Every user on the account gets the email.
* **Zero balance:** service stops and you get a balance-depleted email. Topping up reactivates it.
* **Usage:** **Billing** shows your requests and GB, with a breakdown by service.

## How usage is billed

Two meters:

* **Requests:** each call, billed per million.
* **Bandwidth:** data sent to you, billed per GB (1 GB = 1,024³ bytes). Data you send isn't counted.

{% tabs %}
{% tab title="Solana" %}

| Service                                                                           | Billed on                                                                                 |
| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Standard RPC, unary gRPC calls, Cloudbreak accounts, Superbank historical queries | Requests + bandwidth                                                                      |
| Metaplex DAS API                                                                  | Requests + bandwidth                                                                      |
| Streams: Yellowstone gRPC, Deshred, Fumarole, Riptide and WebSocket               | Bandwidth                                                                                 |
| Titan Swap API                                                                    | Bandwidth                                                                                 |
| Shred Streaming                                                                   | Per IP and data centre: by the minute at the 15-minute rate, or monthly on invoiced plans |
| Preconfirmations (Jito BAM, Harmonic)                                             | Per covered slot or per message, whichever is greater                                     |
| {% endtab %}                                                                      |                                                                                           |

{% tab title="Sui" %}

| Service                                          | Billed on            |
| ------------------------------------------------ | -------------------- |
| GraphQL, unary gRPC, archival gRPC, Seal, Walrus | Requests + bandwidth |
| gRPC streaming                                   | Bandwidth            |
| {% endtab %}                                     |                      |

{% tab title="Monad" %}

| Service       | Billed on            |
| ------------- | -------------------- |
| JSON-RPC      | Requests + bandwidth |
| WebSocket     | Bandwidth            |
| {% endtab %}  |                      |
| {% endtabs %} |                      |

Streams are recorded when they close. A long-lived stream appears in your usage all at once, and a stream still open at the end of a month is billed in the next month.

## How bandwidth is measured

| Traffic                                                                 | What's counted                        | Does compression lower the bill?                        |
| ----------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------- |
| gRPC streams, such as Yellowstone gRPC and Riptide                      | Compressed bytes sent                 | Yes. zstd or gzip lowers it, at a CPU and latency cost  |
| JSON-RPC and other HTTP calls, including Superbank, Cloudbreak, and DAS | Uncompressed response size            | No. gzip speeds up transfer but doesn't change the bill |
| WebSocket (listed as Whirligig on usage pages and invoices)             | Bytes sent (frames aren't compressed) | No                                                      |

* Filtering what you request or subscribe to is the most effective way to cut bandwidth.
* On Solana, `base64+zstd` account encoding and `dataSlice` shrink the response itself, so they do lower the bill.
* If your bandwidth is higher than you expect, contact support and we'll go through it with you.

## Errors and disconnects

| What happened                                                                                                                               | Billing                                                             |
| ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Requests rejected with HTTP 403, 429, 500, or 503                                                                                           | **Not billed**                                                      |
| A JSON-RPC or other HTTP response that Triton's load balancer cuts off before it completes. It ends with HTTP 500.                          | **Not billed**                                                      |
| Other error responses, such as 400, 404, 502, and 504                                                                                       | **Counted as requests**                                             |
| A request your client cancels or times out before the response completes                                                                    | **Counted as requests**                                             |
| A gRPC or WebSocket stream that Triton's load balancer closes after sending data, for example when a server goes down or traffic fails over | **Billed** for the data already delivered, if it's over 1,000 bytes |

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-gauge">:gauge:</i> <strong>Rate and connection limits</strong></td><td>Per-IP rate and connection limits, and 429 handling.</td><td><a href="https://docs.triton.one/using-your-endpoint/rate-and-connection-limits">Rate and connection limits</a></td></tr><tr><td><i class="fa-laptop">:laptop:</i> <strong>Customer dashboard tour</strong></td><td>Find your endpoint and token, check usage, and top up your balance.</td><td><a href="https://docs.triton.one/account-and-billing/platform-overview">Customer dashboard tour</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Customer dashboard tour

Find your endpoints and tokens, check usage and costs, top up, and manage your team.

Sign in at [customers.triton.one](https://customers.triton.one) with your username or email. To reset your password, click **Forgot your password?** on the sign-in page.

## Where things are

| In the sidebar                          | What's there                                                                                         |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Home**                                | **Quick start guide**, your **Subscriptions** and **Organizations**, and your profile (**User**)     |
| Your organization                       | Tabs: **Organization** (subscriptions and users), **Metrics**, **Billing**                           |
| A subscription, under your organization | **RPC / gRPC Tokens** and **Endpoints**, plus **Metrics** and **Billing** for that subscription only |
| **Buy Credits** (pay-as-you-go)         | Top up your balance                                                                                  |
| **Triton Docs**, **Chat with support**  | These docs, and the support chat                                                                     |

<div data-with-frame="true"><figure><img src="https://1114586215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoQO86QYVpwvJExgmA0oK%2Fuploads%2FOpOPSQ2rceF0MbDonYXM%2F01-home-sidebar.png?alt=media&amp;token=fa177562-c284-4141-9ad5-5de589c5cffc" alt="" width="563"><figcaption></figcaption></figure></div>

Access is grouped into subscriptions. The **Type** column under **Home** → **Subscriptions** shows each one's chain and network, for example **Solana Mainnet**.

<div data-with-frame="true"><figure><img src="https://1114586215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoQO86QYVpwvJExgmA0oK%2Fuploads%2FBtVJsWRGUW9rQuNxipTq%2F02-home-subscriptions.png?alt=media&amp;token=2c564ddc-6c15-45fb-9836-07898e01ab3c" alt="" width="563"><figcaption></figcaption></figure></div>

## Endpoints and tokens

Open a subscription:

* **Endpoint:** under **Endpoints** → **Hostname(s)**. Click the endpoint to rename it or edit its **Allowed origins**.
* **Token:** under **RPC / gRPC Tokens**, click the token and copy **Secret token**. Or click **Copy** under **Connection String for Endpoint** for the full URL with the token.
* **Test a request (shared Solana subscriptions):** **Home** → **Quick start guide** → **Endpoints and tokens**. Pick a subscription, endpoint, and method, then click **Send Request**.
* **No Endpoints card?** The subscription has no endpoints yet. Contact support to add one.
* **Disabled tokens and endpoints:** hidden while **Hide disabled** is ticked.

To turn an endpoint on or off, use its switch under **Endpoints** (pay-as-you-go accounts). Turning on an endpoint with no allowed origins adds `__blocked.rpcpool.com`, which keeps browsers out, so only requests with a token work. Don't remove it.

With the default standard role, contact support to create or delete tokens, add endpoints or chains, or change rate limits. Users with the operator role can create and delete tokens.

### Allowed origins

To let a website call your endpoint without a token, add its domain.

{% stepper %}
{% step %}

#### Open the endpoint

Click the endpoint, then **Add origin** under **Allowed origins**.
{% endstep %}

{% step %}

#### Enter the hostname

Enter it without `https://`, for example `app.example.com`.
{% endstep %}

{% step %}

#### Save

Click **Save**.
{% endstep %}
{% endstepper %}

* To stop allowing a site, switch the toggle next to its origin off and click **Save**.
* Saved origins can't be deleted.
* By default an endpoint can have up to 5 active origins. Contact support for more.

## Usage and costs

|                    | **Metrics**                                                              | **Billing**                               |
| ------------------ | ------------------------------------------------------------------------ | ----------------------------------------- |
| **Shows**          | Requests, failed requests, response times, bandwidth, gRPC subscriptions | Daily usage and cost                      |
| **Broken down by** | Endpoint, token, method, status code, origin                             | Product and subscription                  |
| **Time range**     | Last hour to last 7 days, with auto refresh                              | One month at a time                       |
| **Updates**        | Live                                                                     | About every 4 hours                       |
| **Export**         | None                                                                     | **Export CSV**, **Export per-method CSV** |

* To investigate errors, use **Metrics** → **Number of Failed Requests by Status Code/Method**.
* In **Billing** → **Usage charts**, **Product Breakdown** lists requests, bandwidth, and cost per product.

## Balance and payments

{% tabs %}
{% tab title="Pay-as-you-go" %}

* **Balance:** shown in the organization header and on **Billing**.
* **Top up:** **Buy Credits** under **Current Balance** or in the sidebar, or **Billing** → **Buy credits**. Pay in USDC through Coinflow, on the chain you pick at checkout. The processing fee is shown before you pay.
* **Low-balance alert:** **Billing** → turn on **Low balance notifications** → set a threshold in USD → **Save**. Every user in the organization gets one email when the balance drops to the threshold.
* **History:** **Billing** → **Transactions** → **Daily usage summary**, with credits and debits per day.
* **At zero:** the organization is deactivated and every user gets the email "Organization Deactivated: Your Triton RPC balance has been depleted". Topping up with **Buy Credits** reactivates it.
  {% endtab %}

{% tab title="Invoiced" %}

* **Invoices:** **Billing** → **Invoices** → **View** or **Download**.
* **Pay an invoice:** at [customers.triton.one/pay-invoice](https://customers.triton.one/pay-invoice), enter the invoice number, amount, and receipt email, then pay by card, ACH, or USDC.
  {% endtab %}
  {% endtabs %}

<div data-with-frame="true"><figure><img src="https://1114586215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoQO86QYVpwvJExgmA0oK%2Fuploads%2F0Wi26uu9bPeykYINxsQP%2F04-billing.png?alt=media&amp;token=1ed4991a-0b46-488c-b3c2-625b7f1ac9bc" alt="" width="563"><figcaption></figcaption></figure></div>

## Your team

* **Invite:** your organization → **Organization** tab → **Users** → **Invite user** → **Email address** → **Send Invitation**. They get an email to create their login.
* **Remove:** click the trash icon next to the user, then **Remove**. You can't remove yourself.

<div data-with-frame="true"><figure><img src="https://1114586215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoQO86QYVpwvJExgmA0oK%2Fuploads%2F449ApWPCaVycGTVRecsT%2F03-organization.png?alt=media&amp;token=02ae6470-7c89-46b1-a7e2-f9ad46f21512" alt="" width="563"><figcaption></figcaption></figure></div>

## Profile

* **Profile and password:** **Home** → **User** → **Profile** or **Password**. Or click your username at the bottom of the sidebar → **Edit Profile**.
* **Theme:** your username → **Theme: Auto** (the label shows the current mode). Each click switches between Auto, Light, and Dark.
* **Sign out:** your username → **Sign Out**. Inactive sessions sign out after 7 days.

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-credit-card">:credit-card:</i> <strong>Plans and billing</strong></td><td>Payment options, shared vs dedicated, and how usage is billed.</td><td><a href="https://docs.triton.one/account-and-billing/plans-and-billing">Plans and billing</a></td></tr><tr><td><i class="fa-shield">:shield:</i> <strong>Auth and security</strong></td><td>Tokens, allowed origins, and how to keep your endpoint safe.</td><td><a href="https://docs.triton.one/security/authentication">Auth and security</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Account management API

Manage your Triton subscriptions, endpoints, and tokens programmatically through a REST API.

{% hint style="warning" %}
Customers can't use the account management API. Only Triton administrators can create API tokens, and tokens are read-only.
{% endhint %}

Use the [customer dashboard](https://customers.triton.one) to manage your subscriptions, endpoints, secret tokens, and allowed origins. See [Customer dashboard tour](https://docs.triton.one/account-and-billing/platform-overview).

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Auth & headers

Authenticate account management API requests by passing your token in the Authorization header.

## **Auth**

Pass your token in through the Authorization header to make scoped, authenticated requests against the account management API. You can use the `GET /api/v1/accounts` endpoint to test your token. If you get a 200 status code response, your token is being passed correctly. This token is only used for the account management API (`customers.triton.one/api`). You'll create separate tokens for consuming the RPC API.

Account management API tokens start with `trt_`. Send the token on its own or as `Bearer <token>`. A missing or invalid token returns `401`. Tokens are read-only: any request other than `GET` or `HEAD` returns `403`. Only Triton administrators can create tokens.

Examples in this account management API guide are demonstrated using curl, but you should use an HTTP library of your choice.

```
$ curl -H "Authorization: secret" -H "Content-Type: application/json" -H "Accept:application/json" https://customers.triton.one/api/v1/accounts         
```

## **Headers**

All endpoints accept and return JSON, and you should pass both an Accept and Content-Type header of `application/json`

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Accounts

List, retrieve, create, and update accounts, the billing entities your subscriptions belong to.

## **Overview**

Accounts are only used for billing. You cannot create new accounts yourself. Instead, you'll need to ask an administrator to do this for you, if you'd like to have separate billing for your subscriptions.

## List accounts

<mark style="color:blue;">`GET /api/v1/accounts`</mark>

Returns all accounts that the current authentication token has access to.

**Parameters**

All parameters are optional.

<table><thead><tr><th width="220">Name</th><th width="216.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>name</td><td><code>string</code></td><td>Will filter the results by account name, there is nothing by default</td></tr><tr><td>per</td><td><code>integer</code></td><td>Will limit the results to NN entries per page, defaults to 500 (also the maximum)</td></tr><tr><td>page</td><td><code>integer</code></td><td>Will return the results from passed page, defaults to 1</td></tr></tbody></table>

**Request**

Example requests with page filtering, number of accounts per page and filtering by name.

```url
curl 'https://customers.triton.one/api/v1/accounts' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json"
```

```url
curl 'https://customers.triton.one/api/v1/accounts?name=Account-123' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json" 
```

```
curl 'https://customers.triton.one/api/v1/accounts?per=10&page=2' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json" 
```

### Response

Returns a hash with the `accounts` key containing an array of account summaries (`uuid`, `name`, `is_active`, `created_at`, `updated_at`, `users_count`, `subscriptions_count`, `billing_country_code`, `payment_method` and `metered_billing_balance`) and the `meta` containing pagination data. Use [Get account](#get-account) for the full account object.

```json
{
   "accounts": [
      { account_object_1 },
      { account_object_2 },
      { account_object_3 },
      ...
   ],
   "meta": {
      "current_page": 1,
      "next_page": null,
      "per_page": 500,
      "prev_page": null,
      "total_pages": 1,
      "total_count": 3
   }
}
```

## Get account

<mark style="color:blue;">`GET /api/v1/accounts/:account-uuid`</mark>

Get Account that the current authentication token has access to.

**Parameters**

`account-uuid` is the only parameter that needs to be provided.

**Request**

Example request containing `account-uuid`

```url
curl 'https://customers.triton.one/api/v1/accounts/c92a9cea-47cc-494b-b1b0-4230a2316ee5' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json" 
```

### Response

Returns a hash with the `account` key containing the full account object, with its subscriptions. Below is the sample response.

```json
{
   "account": {
      "uuid": "c92a9cea-47cc-494b-b1b0-4230a2316ee5",
      "name": "John Doe",
      "billing_address1": "1645 S Telegraph Rd",
      "billing_address2": null,
      "billing_address3": null,
      "billing_city": "Bloomfield Hills",
      "billing_state_or_province": "Michigan",
      "billing_postal_code": "48302",
      "billing_country_code": "US",
      "telephone_country_code": "US",
      "telephone": "(248) 858-2300",
      "last_time_activated": "2023-06-28T11:26:52Z",
      "is_active": true,
      "created_at": "2023-06-22T09:11:11Z",
      "updated_at": "2023-06-28T11:26:52Z",
      "users_count": 1,
      "tokens_count": 6,
      "endpoints_count": 4,
      "payment_method": "manual",
      "maximum_tokens": -1,
      "address_watch_lists": false,
      "allow_ip_ranges": false,
      "shred_stream_ips_enabled": false,
      "shred_stream_ips_limit": 0,
      "num_permitted_allowed_origins_per_endpoint": null,
      "company_number": null,
      "vat_number": null,
      "user_emails": ["john.doe@example.com"],
      "has_metered_billing_transactions": false,
      "subscriptions": [
         { subscription_object_1 },
         ...
      ]
   }
}
```

## **Create account**

<mark style="color:red;">This API is available only to Triton administrators.</mark>

## **Update account**

<mark style="color:red;">API tokens are read-only, so this request returns 403 Forbidden.</mark>

<mark style="color:blue;">`PUT /api/v1/accounts/:account-uuid`</mark>

Update account that the current authentication token has access to.

**Parameters**

All parameters are optional unless marked as required.

<table><thead><tr><th width="311">Name</th><th width="155.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>name</td><td><code>string</code></td><td>A human-readable display name to describe the account. Only Triton administrators can change it.</td></tr><tr><td>billing_address1</td><td><code>string</code></td><td></td></tr><tr><td>billing_address2</td><td><code>string</code></td><td></td></tr><tr><td>billing_address3</td><td><code>string</code></td><td></td></tr><tr><td>billing_city</td><td><code>string</code></td><td></td></tr><tr><td>billing_state_or_province</td><td><code>string</code></td><td></td></tr><tr><td>billing_postal_code</td><td><code>string</code></td><td></td></tr><tr><td>billing_country_code</td><td><code>string</code></td><td></td></tr><tr><td>telephone_country_code</td><td><code>string</code></td><td></td></tr><tr><td>telephone</td><td><code>string</code></td><td></td></tr></tbody></table>

**Request**

Request JSON (`-d` command line parameter) must contain `account` key for account object. All parameters should be placed inside.

```url
curl -X PUT 'https://customers.triton.one/api/v1/accounts/c6b8c375-27ab-4531-94f4-d8d08250fcfa' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json" -d '
{
    "account": {
        "name": "John Doe",
        "billing_address1": "1645 S Telegraph Rd",
        "billing_address2": "line 2",
        "billing_address3": "line 3",
        "billing_city": "Bloomfield Hills",
        "billing_state_or_province": "Michigan",
        "billing_postal_code": "48302",
        "billing_country_code": "US",
        "telephone_country_code": "US",
        "telephone": "(248) 858-2300"
    }
}'
```

**Response**

Returns a hash with the `account` key containing an account object. The response data for account object is the same as for <mark style="color:blue;">`GET /api/v1/accounts/:account-uuid`</mark> and <mark style="color:blue;">`GET /api/v1/accounts`</mark>

```json
{
   "account": {
      "uuid": "c92a9cea-47cc-494b-b1b0-4230a2316ee5",
      "name": "John Doe",
      "billing_address1": "1645 S Telegraph Rd",
      "billing_address2": null,
      "billing_address3": null,
      "billing_city": "Bloomfield Hills",
      "billing_state_or_province": "Michigan",
      "billing_postal_code": "48302",
      "billing_country_code": "US",
      "telephone_country_code": "US",
      "telephone": "(248) 858-2300",
      ...
      "subscriptions": [
         { subscription_object_1 },
         { subscription_object_2 },
         { subscription_object_3 },
         ...
      ],
      "deactivation_reasons": [
         { deactivation_reason_object_1 },
         { deactivation_reason_object_2 },
         { deactivation_reason_object_3 },
         ...
      ]
   }
}
```

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Address watch lists

Add, list, and delete address watch lists on a subscription (operator and reseller tokens only).

{% hint style="info" %}
API tokens are read-only: you can list watch lists, but adding or deleting one returns `403`.
{% endhint %}

## Add watch list

<mark style="color:blue;">`POST /api/v1/subscriptions/:subscription-uuid/address_watch_lists`</mark>

**Parameters**

<table><thead><tr><th width="263.3333333333333">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>variant</code> <mark style="color:red;">*required</mark></td><td><code>string</code></td><td>Must be either <code>collection</code> or <code>tree</code></td></tr><tr><td><code>encoded_value</code> <mark style="color:red;">*required</mark></td><td><code>string</code></td><td></td></tr></tbody></table>

## List watch lists

<mark style="color:blue;">`GET /api/v1/address_watch_lists`</mark>

**Query parameters**

| Name                | Type     | Description |
| ------------------- | -------- | ----------- |
| `variant`           | `string` |             |
| `subscription_uuid` | `string` |             |
| `subscription_type` | `string` |             |

## Delete watch list

<mark style="color:blue;">`DELETE /api/v1/address_watch_lists/:uuid`</mark>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Subscriptions

List, create, update, activate, and deactivate subscriptions.

## **Overview**

A Subscription is the primary resource, and it encapsulates all things related to the endpoints and tokens you define. This also includes a name, a start and end timestamp, and other metadata. This is one of the first resources that you should create to get started using Triton and making RPC requests. You'll need to have an account and obtain an `account_uuid` to create a subscription.

## **List subscriptions**

<mark style="color:blue;">`GET /api/v1/subscriptions`</mark>

Returns subscriptions that the current authentication token has access to.

**Parameters**

All parameters are optional.

| Name               | Type      | Description                                                                                            |
| ------------------ | --------- | ------------------------------------------------------------------------------------------------------ |
| subscription\_type | `string`  | Will filter the results by subscription\_type.                                                         |
| account\_uuid      | `string`  | Will filter the results by account\_uuid.                                                              |
| user\_uuid         | `string`  | Will filter the results by user\_uuid.                                                                 |
| per                | `integer` | Will limit the results to NN entries per page, defaults to 500 (also the maximum)                      |
| page               | `integer` | Will return the results from passed page, defaults to 1                                                |
| include            | `string`  | Pass any value (for example `endpoints,tokens`) to get full subscription objects instead of summaries. |

**Request**

Example requests with page filtering, number of subscriptions per page and filtering by subscription type, account uuid or user uuid.

```url
curl 'https://customers.triton.one/api/v1/subscriptions' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json"
```

```url
curl 'https://customers.triton.one/api/v1/subscriptions?subscription_type=mainnet-shared' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json" 
```

```
curl 'https://customers.triton.one/api/v1/subscriptions?account_uuid=c92a9cea-47cc-494b-b1b0-4230a2316ee5' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json" 
```

```
curl 'https://customers.triton.one/api/v1/subscriptions?per=10&page=2' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json" 
```

### Response

Returns a hash with the `subscriptions` key containing an array of subscriptions, newest first, and the `meta` containing pagination data. Without `include`, each entry is a summary: `uuid`, `name`, `is_active`, `bam_preconfs_enabled`, `harmonic_preconfs_enabled`, `created_at`, `updated_at`, `current_billing_plan_code`, and short `account` and `subscription_type` objects.

<pre class="language-json"><code class="lang-json">{
   "subscriptions": [
      { subscription_object_1 },
      { subscription_object_2 },
      { subscription_object_3 },
      ...
   ],
<strong>   "meta": {
</strong>      "current_page": 1,
      "next_page": null,
      "per_page": 500,
      "prev_page": null,
      "total_pages": 1,
      "total_count": 3
   }
}
</code></pre>

## Get subscription

<mark style="color:blue;">`GET /api/v1/subscriptions/:subscription-uuid`</mark>

Get Subscription that the current authentication token has access to.

**Parameters**

`subscription-uuid` is the only parameter that needs to be provided.

**Request**

Example request containing `subscription-uuid`

```
curl 'https://customers.triton.one/api/v1/subscriptions/c92a9cea-47cc-494b-b1b0-4230a2316ee5' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json" 
```

**Response**

Returns a hash with the `subscription` key containing the full subscription object. Below is the sample response.

| Name                   | Type                                       | Description                                                                     |
| ---------------------- | ------------------------------------------ | ------------------------------------------------------------------------------- |
| uuid                   | `string`                                   | The generated primary key to reference this subscription.                       |
| endpoints              | `array[{endpoint_object}, ...]`            | An array of Endpoint objects, documented in the Endpoints section.              |
| tokens                 | `array[{token_object}, ...]`               | An array of Token objects, documented in the Tokens section.                    |
| supported\_rate\_tiers | `array[{supported_rate_tier_object}, ...]` | An array of Supported Rate Tiers objects, documented in the Rate Tiers section. |
| deactivation\_reasons  | `array[{deactivation_reason_object}, ...]` | An array of Deactivation Reasons objects.                                       |

```json
{
   "subscription": {
      "uuid": "5d8d4591-12cc-424a-8f39-32de0ba6acc3",
      "name": "Example App",
      "account_uuid": "4ad26b8a-a9a1-4f9b-b0fa-c13a682d64b1",
      "subscription_type": {
         "uuid": "8ddbdbc8-b513-4ba5-a833-2ce8402a9c50",
         "name": "mainnet-shared",
         "pool_name": "pool name",
         ...
      },
      "starts_at": null,
      "ends_at": null,
      "is_active": false,
      "account": { // An account that is assigned to a given subscription
         "uuid": "4ad26b8a-a9a1-4f9b-b0fa-c13a682d64b1",
         "name": "Example Org",
         "billing_address1": "420 Effertz Estates",
         "billing_address2": null,
         "billing_address3": null,
         "billing_city": "Padbergville",
         "billing_state_or_province": "Alabama",
         "billing_postal_code": "78007",
         "billing_country_code": "US",
         "telephone_country_code": "+61-8",
         "telephone": "870-800-5877",
         "last_time_activated": "2023-05-02T16:32:46Z",
         "is_active": true,
         "created_at": "2023-05-02T16:32:46Z",
         "updated_at": "2023-05-02T16:32:46Z",
         "payment_method": "manual",
         "maximum_tokens": -1,
         "address_watch_lists": false,
         "allow_ip_ranges": false
      },
      "supported_rate_tiers": [ // A roll-up of related supported rate tiers
         {
            "uuid": "ca141949-a46f-446a-abee-a031e501fea0",
            "name": "developer",
            "is_restricted": false
         }
      ],
      "endpoints": [ // A roll-up of related endpoints
         {
            "uuid": "23ab660b-cb09-4ca5-b49a-518b422a8d81",
            "name": "Jacobson LLC cbp4i3u71m",
            "slug": "academy-strict-fnalfmab4l",
            "rate_tier": "developer",
            "is_active": true,
            "value_override": null,
            "values": [
               "academy-strict-fnalfmab4l.TEST 1",
               "academy-strict-fnalfmab4l.TWST 2"
            ],
            "default_values": [
               "academy-strict-fnalfmab4l.TEST 1",
               "academy-strict-fnalfmab4l.TWST 2"
            ],
            "allowed_origins": [
               {
                  "uuid": "b4d5ec62-410d-45f8-8b45-44fe6641cf1f",
                  "value": "vonrueden-haag.co",
                  "is_active": true
               }
            ]
         }
      ],
      "tokens": [ // A roll-up of tokens for related Subscription, Account, & Users
         {
            "uuid": "fa2fec9c-c3e6-4625-b11f-7906dff5f37c",
            "name": "Token name",
            "value": "8d43f8dc-8aa3-4fa2-b09e-361f6af8d972",
            "rate_tier": "tier1",
            "auth_username": "tylerqt-tylerwi-db8c",
            "is_active": false
         }
      ],
      "deactivation_reasons": [
         {
            "description": "Deactivation reason description",
            "created_at": "2023-07-03T12:00:22Z"
         }
      ]
   }
}
```

## **Create subscription**

<mark style="color:red;">API tokens are read-only, so this request returns 403 Forbidden.</mark>

<mark style="color:blue;">`POST /api/v1/subscriptions`</mark>

**Parameters**

| Name                                                          | Type       | Description                                                                                                                                              |
| ------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_uuid <mark style="color:red;">\*required</mark>      | `string`   | Primary key of the account that the subscription should belong to.                                                                                       |
| subscription\_type <mark style="color:red;">\*required</mark> | `string`   | Name of the subscription type. Obtained from [Subscription types](https://docs.triton.one/account-and-billing/account-management-api/subscription-types) |
| name <mark style="color:red;">\*required</mark>               | `string`   | A human readable display name to describe the subscription.                                                                                              |
| starts\_at                                                    | `datetime` | The scheduled timestamp for the subscription to become active. Defaults to null, which means the subscription is immediately active.                     |
| ends\_at                                                      | `datetime` | The timestamp for which the subscription becomes inactive. Defaults to null, which means the subscription never becomes inactive.                        |

**Request**

Request JSON (`-d` command line parameter) must contain `subscription` key for a subscription object. All parameters should be placed inside.

```url
curl -X POST 'https://customers.triton.one/api/v1/subscriptions' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept: application/json" -d '
{
    "subscription": {
        "account_uuid": "c92a9cea-47cc-494b-b1b0-4230a2316ee5", // obtain from UI
        "subscription_type": "mainnet-shared",
        "name": "Example App",
        "starts_at": "2023-07-10T10:25:30Z",
        "ends_at": "2023-07-30T05:00:00Z"
    }
}'
```

**Response**

Returns a hash with the `subscription` key containing a subscription object. Note that `endpoints`, `tokens` and `deactivation_reasons` arrays are empty because this is newly created subscription. Below is the sample response.

```json
 {
   "subscription": {
      "uuid": "5d8d4591-12cc-424a-8f39-32de0ba6acc3",
      "name":"Example App",
      "account_uuid": "4ad26b8a-a9a1-4f9b-b0fa-c13a682d64b1",
      "subscription_type": {
         "uuid": "8ddbdbc8-b513-4ba5-a833-2ce8402a9c50",
         "name": "mainnet-shared",
         "pool_name": "pool name",
         ...
      },
      "starts_at": null,
      "ends_at": null,
      "is_active": false,
      "account": {
         "uuid": "4ad26b8a-a9a1-4f9b-b0fa-c13a682d64b1",
         "name": "Example Org",
         "billing_address1": "420 Effertz Estates",
         "billing_address2": null,
         "billing_address3": null,
         "billing_city": "Padbergville",
         "billing_state_or_province": "Alabama",
         "billing_postal_code": "78007",
         "billing_country_code": "US",
         "telephone_country_code": "+61-8",
         "telephone": "870-800-5877",
         "last_time_activated": "2023-05-02T16:32:46Z",
         "is_active": true,
         "created_at": "2023-05-02T16:32:46Z",
         "updated_at": "2023-05-02T16:32:46Z",
         "payment_method": "manual",
         "maximum_tokens": -1,
         "address_watch_lists": false,
         "allow_ip_ranges": false
      },
      "supported_rate_tiers": [
         {
            "uuid": "ca141949-a46f-446a-abee-a031e501fea0",
            "name": "developer",
            "is_restricted": false
         }
      ],
      "endpoints": [],
      "tokens": [],
      "deactivation_reasons": []
   }
}
 
```

## **Update subscription**

<mark style="color:red;">API tokens are read-only, so this request returns 403 Forbidden.</mark>

<mark style="color:blue;">`PUT /api/v1/subscriptions/:subscription_uuid`</mark>

Update attributes like `name` on an existing Subscription that the current authentication token has access to. Any other updatable attributes for a Subscription like Endpoints and Tokens should be updated via their distinct account management APIs.

**Parameters**

| Name | Type     | Description                                                 |
| ---- | -------- | ----------------------------------------------------------- |
| name | `string` | A human readable display name to describe the subscription. |

**Request**

Request JSON (`-d` command line parameter) must contain `subscription` key for a subscription object. All parameters should be placed inside.

```url
curl -X PUT 'https://customers.triton.one/api/v1/subscriptions/c92a9cea-47cc-494b-b1b0-4230a2316ee5' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept: application/json" -d '
{
    "subscription": {
        "name": "Example App"
    }
}'
```

**Response**

Returns a hash with the `subscription` key containing a subscription object. The response data for subscription object is the same as for <mark style="color:blue;">`GET /api/v1/subscriptions/:subscription-uuid`</mark> and <mark style="color:blue;">`GET /api/v1/subscriptions`</mark>

```json
{
   "subscription": {
      "name": "Example App" // subscription attributes are the same as for GET and POST 
      ...
      "supported_rate_tiers": [ // A roll-up of related supported rate tiers
         { supported_rate_tier_object_1 },
         { supported_rate_tier_object_2 },
         { supported_rate_tier_object_3 },
         ...
      ],
      "endpoints": [ // A roll-up of related endpoints
         { endpoint_object_1 },
         { endpoint_object_2 },
         { endpoint_object_3 },
         ...
      ],
      "tokens": [ // A roll-up of tokens for related Subscription, Account, & Users
         { token_object_1 },
         { token_object_2 },
         { token_object_3 },
         ...
      ],
      "deactivation_reasons": [
         { deactivation_reason_object_1 },
         { deactivation_reason_object_2 },
         { deactivation_reason_object_3 },
         ...
      ]
   }
}
```

## **Activate subscription**

<mark style="color:red;">API tokens are read-only, so this request returns 403 Forbidden.</mark>

<mark style="color:blue;">`PUT /api/v1/subscriptions/:subscription_uuid/activate`</mark>

Activate a subscription so that it can be used.

**Parameters**

<mark style="color:blue;">`subscription_uuid`</mark> is the only parameter that needs to be provided.

**Request**

```url
curl -X PUT 'https://customers.triton.one/api/v1/subscriptions/74ea9d9a-4b2a-4f01-af47-1c175f8a2af6/activate' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json"
```

**Response**

```json
204 No Content
```

## **Deactivate subscription**

<mark style="color:red;">API tokens are read-only, so this request returns 403 Forbidden.</mark>

<mark style="color:blue;">`PUT /api/v1/subscriptions/:subscription_uuid/deactivate`</mark>

Deactivate a subscription so that it cannot be used.

**Parameters**

All parameters are optional.

| Name                 | Type     | Description                                                       |
| -------------------- | -------- | ----------------------------------------------------------------- |
| deactivation\_reason | `string` | A human readable description to describe the deactivation reason. |

**Request**

Example request with `deactivation_reason`.

```url
curl -X PUT 'https://customers.triton.one/api/v1/subscriptions/74ea9d9a-4b2a-4f01-af47-1c175f8a2af6/deactivate' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json" -d '
{
    "deactivation_reason": "Deactivation reason description"
}' 
```

**Response**

Returns the deactivation reason that was recorded.

```json
{
   "deactivation_reason": {
      "description": "Deactivation reason description",
      "created_at": "2023-06-26T20:16:05Z"
   }
}
```

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Subscription types

List, create, and update subscription types.

## **Overview**

A Subscription Type defines what kind of pool a subscription is for. This is how endpoints are distinguished between a dedicated pool and a shared pool. It also can determine which Solana RPC environment the subscription and endpoints target.

The developer subscription is used to encapsulate the devnet and testnet Solana environments. Any endpoints or tokens created under a developer Subscription will automatically be usable for both Solana environments, typically at no cost.

## **List subscription types**

<mark style="color:blue;">`GET /api/v1/subscription_types`</mark>

Returns all subscription types that the current authentication token has access to.

**Parameters**

Archived subscription types are left out by default. Pass `include_archived=true` to include them.

**Request**

<pre><code><strong>curl 'https://customers.triton.one/api/v1/subscription_types' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json" 
</strong></code></pre>

**Response**

Returns all subscription types that a Subscription can get created with.

```json
{
   "subscription_types": [
      {
         "uuid": "413defdd-b011-4dda-8145-fa782524284c",
         "name": "developer",
         "pool_name": "test pool name",
         "subscriptions_count": 10,
         "endpoint_default_suffixes": [
            "TEST 1",
            "TWST 2"
         ]
      },
      {
         "uuid": "8ddbdbc8-b513-4ba5-a833-2ce8402a9c50",
         "name": "mainnet-shared",
         "pool_name": "pool name",
         "subscriptions_count": 10,
         "endpoint_default_suffixes": [
            "endpoint suffix"
         ]
      },
      {
         "uuid": "b97a3264-2c0a-4af5-85ff-14dce864afc9",
         "name": "mainnet-dedicated",
         "pool_name": "pool name",
         "subscriptions_count": 5,
         "endpoint_default_suffixes": [
            "endpoint suffix"
         ]
      }
   ]
}
```

## **Create subscription type / update subscription type**

<mark style="color:red;">This API is available only to Triton administrators.</mark>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Endpoints

List, create, update, activate, and deactivate endpoints URLs.

## **Overview**

An Endpoint is what clients will call to consume the RPC. Endpoints belong to a Subscription, which holds its metadata. An endpoint's hostname prefix (`slug`) is randomly generated when it's created.

## List endpoints

<mark style="color:blue;">`GET /api/v1/endpoints`</mark>

Returns all endpoints to which the current authentication token has access.

**Parameters**

<table><thead><tr><th width="220">Name</th><th width="216.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>account_uuid <mark style="color:red;">*</mark></td><td><code>string</code></td><td>Will filter the results by account_uuid.</td></tr><tr><td>subscription_uuid <mark style="color:red;">*</mark></td><td><code>string</code></td><td>Will limit the results by subscription_uuid.</td></tr><tr><td>rate_tier_uuid <mark style="color:red;">*</mark></td><td><code>string</code></td><td>Will limit the results by rate_tier_uuid.</td></tr><tr><td>name</td><td><code>string</code></td><td>Will filter the results to endpoints whose name starts with this value.</td></tr><tr><td>per</td><td><code>integer</code></td><td>Will limit the results to NN entries per page, defaults to 500 (also the maximum)</td></tr><tr><td>page</td><td><code>integer</code></td><td>Will return the results from passed page, defaults to 1</td></tr></tbody></table>

<mark style="color:red;">\* One of</mark> <mark style="color:red;">`account_uuid`</mark><mark style="color:red;">,</mark> <mark style="color:red;">`subscription_uuid`</mark> <mark style="color:red;">or</mark> <mark style="color:red;">`rate_tier_uuid`</mark> <mark style="color:red;">is required</mark>

**Request**

Example requests with account\_uuid and subscription\_uuid filtering.

```url
curl 'https://customers.triton.one/api/v1/endpoints?account_uuid=c92a9cea-47cc-494b-b1b0-4230a2316ee5' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json" 
```

```
curl 'https://customers.triton.one/api/v1/endpoints?subscription_uuid=74ea9d9a-4b2a-4f01-af47-1c175f8a2af6' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json" 
```

### Response

Returns a hash with the `endpoints` key containing an array of endpoints objects and the `meta` containing pagination data.

```json
{
   "endpoints": [
      {
         "uuid": "23ab660b-cb09-4ca5-b49a-518b422a8d81",
         "name": "Jacobson LLC cbp4i3u71m",
         "slug": "academy-strict-fnalfmab4l",
         "rate_tier": "developer",
         "is_active": true,
         "value_override": null,
         "values": [
            "academy-strict-fnalfmab4l.TEST 1",
            "academy-strict-fnalfmab4l.TWST 2",
            "academy-strict-fnalfmab4l.value-3"
         ],
         "default_values": [
            "academy-strict-fnalfmab4l.TEST 1",
            "academy-strict-fnalfmab4l.TWST 2",
            "academy-strict-fnalfmab4l.value-3"
         ],
         "allowed_origins": [
            {
               "uuid": "b4d5ec62-410d-45f8-8b45-44fe6641cf1f",
               "value": "vonrueden-haag.co",
               "is_active": true
            }
         ],
         "deactivation_reasons": [
            {
               "description": "Deactivation reason description",
               "created_at": "2023-06-26T20:16:05Z"
            }
         ]
      },
      { endpoint_object_2 },
      { endpoint_object_3 },
      ...
   ]
}
```

## **Get endpoint**

<mark style="color:red;">This API is not available.</mark>

## **Create endpoint**

<mark style="color:red;">API tokens are read-only, so this request returns 403 Forbidden.</mark>

<mark style="color:blue;">`POST /api/v1/subscriptions/:subscription_uuid/endpoints`</mark>

**Parameters**

| Name                                                  | Type                                                | Description                                                                                                                                                |
| ----------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name <mark style="color:red;">\*required</mark>       | `string`                                            | A human-readable name to describe the endpoint.                                                                                                            |
| rate\_tier <mark style="color:red;">\*required</mark> | `string`                                            | The name of the Rate Tier for this endpoint, which defines rate limits on the Endpoint. Rate tiers don't affect pricing.                                   |
| allowed\_origins                                      | `array[{ value: dns_cname }, { value: dns_cname }]` | An array of DNS CNAME records that define origins that can access the endpoint. This is commonly used by frontends that can't obscure an API access token. |

**Request**

Example requests with account\_uuid and subscription\_uuid filtering. All new allowed origins are automatically enabled.

```url
curl -X POST 'https://customers.triton.one/api/v1/subscriptions/74ea9d9a-4b2a-4f01-af47-1c175f8a2af6/endpoints' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json" -d '
{
    "endpoint": {
        "name": "Endpoint 123",
        "rate_tier": "developer",
        "allowed_origins":  [{ value: "example.com" }, { value: "frontend.website.com" }]
    }
}' 
```

**Response**

All submitted keys, plus the following are returned:

| Name   | Type                             | Description                                                              |
| ------ | -------------------------------- | ------------------------------------------------------------------------ |
| uuid   | `string`                         | The generated primary key to reference this endpoint.                    |
| values | `array[string (DNS CNAME), ...]` | The endpoint values that should be called by clients to consume the RPC. |

```json
{
   "endpoint": {
      "uuid": "a5131884-1ce4-4415-98f8-d040901ecbd0",
      "name": "Endpoint 123",
      "slug": "tylerqt-example-3c6e",
      "rate_tier": "developer",
      "is_active": false,
      "value_override": null,
      "values": [
         "tylerqt-example-3c6e.TEST 1",
         "tylerqt-example-3c6e.TWST 2",
         "tylerqt-example-3c6e.value-3"
      ],
      "default_values": [
         "tylerqt-example-3c6e.TEST 1",
         "tylerqt-example-3c6e.TWST 2",
         "tylerqt-example-3c6e.value-3"
      ],
      "allowed_origins": [
         {
            "uuid": "4d63807d-84f2-491c-898e-9190fa334592",
            "value": "example.com",
            "is_active": true
         },
         {
            "uuid": "a21d362b-f488-4778-8e5c-d3c917efd764",
            "value": "frontend.website.com",
            "is_active": true
         }
      ],
      "deactivation_reasons": []
   }
}    
```

## **Update endpoint**

<mark style="color:red;">API tokens are read-only, so this request returns 403 Forbidden.</mark>

<mark style="color:blue;">`PUT /api/v1/endpoints/:endpoint_uuid`</mark>

Update an endpoint's name and allowed\_origins. Accepts updates as full-updates, where the passed in list overwrites any existing allowed\_origins.

**Parameters**

| Name                                                                                                                            | Type                                                                                        | Description                                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                                                                                                                            | `string`                                                                                    | A human-readable name to describe the endpoint.                                                                                                                           |
| rate\_tier <mark style="color:red;">\*resellers and Triton administrators only; restricted tiers are administrator-only.</mark> | `string`                                                                                    | A Rate Tier name. It's assigned to an Endpoint to set its rate limits.                                                                                                    |
| allowed\_origins <mark style="color:red;">\*up to 5 active origins per endpoint by default.</mark>                              | `array[{ value: dns_cname, is_active: boolean }, { value: dns_cname, is_active: boolean }]` | An array of DNS CNAME and is\_active records that define origins that can access the endpoint. This is commonly used by frontends that can't obscure an API access token. |

**Request**

Example requests with account\_uuid and subscription\_uuid filtering.

```url
curl -X PUT 'https://customers.triton.one/api/v1/endpoints/74ea9d9a-4b2a-4f01-af47-1c175f8a2af6' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json" -d '
{
    "endpoint": {
        "name": "Endpoint 123",
        "rate_tier": "developer",
        "allowed_origins": [{ value: "example.com", is_active: true }, { value: "frontend.website.com", is_active: true }]
    }
}' 
```

**Response**

All submitted keys, plus the following are returned:

| Name   | Type                             | Description                                                              |
| ------ | -------------------------------- | ------------------------------------------------------------------------ |
| uuid   | `string`                         | The generated primary key to reference this endpoint.                    |
| values | `array[string (DNS CNAME), ...]` | The endpoint values that should be called by clients to consume the RPC. |

```json
{
   "endpoint": {
      "uuid": "6ec86e74-783b-4779-b626-937a5c1e2a89",
      "name": "New Endpoint Name",
      "slug": "tylerqt-example-f988",
      "rate_tier": "developer",
      "is_active": false,
      "value_override": null,
      "values": [
         "tylerqt-example-f988.TEST 1",
         "tylerqt-example-f988.TWST 2",
         "tylerqt-example-f988.value-3"
      ],
      "default_values": [
         "tylerqt-example-f988.TEST 1",
         "tylerqt-example-f988.TWST 2",
         "tylerqt-example-f988.value-3"
      ],
      "allowed_origins": [
         {
            "uuid": "32d511f0-3fb0-4570-8922-f8bc988b41a1",
            "value": "example.com",
            "is_active": true
         }
      ],
      "deactivation_reasons": [
          {
            "description": "Deactivation reason description",
            "created_at": "2023-07-03T12:00:22Z"
         }
      ]
   }
}
```

## **Activate endpoint**

<mark style="color:red;">API tokens are read-only, so this request returns 403 Forbidden.</mark>

<mark style="color:blue;">`PUT /api/v1/endpoints/:endpoint_uuid/activate`</mark>

Activate an endpoint so that it can be used.

**Parameters**

<mark style="color:blue;">`endpoint_uuid`</mark> is the only parameter that needs to be provided.

**Request**

```url
curl -X PUT 'https://customers.triton.one/api/v1/endpoints/74ea9d9a-4b2a-4f01-af47-1c175f8a2af6/activate' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json"
```

**Response**

Returns a hash with the `endpoint` key containing the activated endpoint object.

## **Deactivate endpoint**

<mark style="color:red;">API tokens are read-only, so this request returns 403 Forbidden.</mark>

<mark style="color:blue;">`PUT /api/v1/endpoints/:endpoint_uuid/deactivate`</mark>

Deactivate an endpoint so that it cannot be used.

**Parameters**

All parameters are optional.

| Name                 | Type     | Description                                                       |
| -------------------- | -------- | ----------------------------------------------------------------- |
| deactivation\_reason | `string` | A human readable description to describe the deactivation reason. |

**Request**

Example request with optional `deactivation_reason`.

```url
curl -X PUT 'https://customers.triton.one/api/v1/endpoints/74ea9d9a-4b2a-4f01-af47-1c175f8a2af6/deactivate' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json" -d '
{
    "deactivation_reason": "Deactivation reason description"
}' 
```

**Response**

Returns the deactivation reason that was recorded.

```json
{
   "deactivation_reason": {
      "description": "Deactivation reason description",
      "created_at": "2023-06-26T20:16:05Z"
   }
}
```

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Tokens

List, create, activate, and deactivate the secret tokens.

## **Overview**

Create private access tokens to allow your backend services to make authenticated RPC requests to an Endpoint. This allows you to make requests from any backend origin.

<mark style="color:red;">This token is private information and should never be exposed on a front-end.</mark>

Send the token in the URL path or in an `x-token` header; see [Auth and security](https://docs.triton.one/security/authentication).

## List tokens

<mark style="color:blue;">`GET /api/v1/tokens`</mark>

Returns all tokens that the current authentication token has access to.

**Parameters**

<table><thead><tr><th width="220">Name</th><th width="216.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>account_uuid <mark style="color:red;">*</mark></td><td><code>string</code></td><td>Will filter the results by account_uuid.</td></tr><tr><td>subscription_uuid <mark style="color:red;">*</mark></td><td><code>string</code></td><td>Will limit the results by subscription_uuid.</td></tr><tr><td>rate_tier_uuid <mark style="color:red;">*</mark></td><td><code>string</code></td><td>Will limit the results by rate_tier_uuid.</td></tr><tr><td>name</td><td><code>string</code></td><td>Will filter the results to tokens whose name contains this value.</td></tr><tr><td>per</td><td><code>integer</code></td><td>Will limit the results to NN entries per page, defaults to 500 (also the maximum)</td></tr><tr><td>page</td><td><code>integer</code></td><td>Will return the results from passed page, defaults to 1</td></tr></tbody></table>

<mark style="color:red;">\* One of</mark> <mark style="color:red;">`account_uuid`</mark><mark style="color:red;">,</mark> <mark style="color:red;">`subscription_uuid`</mark> <mark style="color:red;">or</mark> <mark style="color:red;">`rate_tier_uuid`</mark> <mark style="color:red;">is required</mark>

**Request**

Example requests with page filtering, number of tokens per page and filtering by account uuid and subscription uuid.

```url
curl 'https://customers.triton.one/api/v1/tokens?account_uuid=c92a9cea-47cc-494b-b1b0-4230a2316ee5' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json" 
```

<pre><code><strong>curl 'https://customers.triton.one/api/v1/tokens?subscription_uuid=74ea9d9a-4b2a-4f01-af47-1c175f8a2af6' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json" 
</strong></code></pre>

```
curl 'https://customers.triton.one/api/v1/tokens?per=10&page=2&subscription_uuid=74ea9d9a-4b2a-4f01-af47-1c175f8a2af6' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json" 
```

### Response

Returns a hash with the `tokens` key containing an array of tokens objects and the `meta` containing pagination data.

```json
{
   "tokens": [
      {
         "uuid": "fa2fec9c-c3e6-4625-b11f-7906dff5f37c",
         "name": "token-name",
         "value": "8d43f8dc-8aa3-4fa2-b09e-361f6af8d972",
         "rate_tier": "tier1",
         "auth_username": "example-backend-db8c",
         "is_active": false,
         "created_at": "2023-06-22T09:11:11Z",
         "updated_at": "2023-06-28T11:26:52Z",
         "subscription_uuid": "74ea9d9a-4b2a-4f01-af47-1c175f8a2af6",
         "subscription_name": "Mainnet Shared Subscription",
         "subscription_is_active": true,
         "account_uuid": "c92a9cea-47cc-494b-b1b0-4230a2316ee5",
         "account_is_active": true
      },
      { token_object_2 },
      { token_object_3 },
      ...
   ],
   "meta": {
      "current_page": 1,
      "next_page": null,
      "per_page": 10,
      "prev_page": null,
      "total_pages": 1,
      "total_count": 1
   }
}
```

## **Get token**

<mark style="color:red;">This API is not available.</mark>

## **Create token**

<mark style="color:red;">API tokens are read-only, so this request returns 403 Forbidden.</mark>

<mark style="color:blue;">`POST /api/v1/subscriptions/:subscription_uuid/tokens`</mark>

Add a new token that can be used to access the Subscription's Endpoints

**Parameters**

| Name                                                  | Type     | Description                                                                                                                                                                                    |
| ----------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name <mark style="color:red;">\*required</mark>       | `string` | A human readable name to describe the token.                                                                                                                                                   |
| rate\_tier <mark style="color:red;">\*required</mark> | `string` | The name of the [rate tier](https://docs.triton.one/account-and-billing/account-management-api/rate-limits) for this token, which defines rate limits for it. Rate tiers don't affect pricing. |

**Request**

Example requests with account\_uuid and subscription\_uuid filtering.

```url
curl -X POST 'https://customers.triton.one/api/v1/subscriptions/74ea9d9a-4b2a-4f01-af47-1c175f8a2af6/tokens' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json" -d '
{
    "token": {
        "name": "Token 123",
        "rate_tier": "developer" 
    }
}' 
```

**Response**

All submitted keys, plus the following are returned:

| Name           | Type     | Description                                                                     |
| -------------- | -------- | ------------------------------------------------------------------------------- |
| uuid           | `string` | The generated primary key to reference this token.                              |
| auth\_username | `string` | A randomly generated value that can be used for basic authentication if needed. |
| value          | `string` | The value used for authentication.                                              |

```json
{
   "token":  {
      "uuid": "b51e9812-ece9-4cb0-81f1-0c4bbdc8a3b7",
      "name": "Token 123",
      "value": "b4274ebd-e2f5-46fd-8e99-8aff8f9f4a85",
      "rate_tier": "developer",
      "auth_username": "tylerqt-example-73d1",
      "is_active": true
   }
}
```

## **Activate token**

<mark style="color:red;">API tokens are read-only, so this request returns 403 Forbidden.</mark>

<mark style="color:blue;">`PUT /api/v1/tokens/:token_uuid/activate`</mark>

Activate a token so that it can be used.

**Parameters**

<mark style="color:blue;">`token_uuid`</mark> is the only parameter that needs to be provided.

**Request**

```url
curl -X PUT 'https://customers.triton.one/api/v1/tokens/74ea9d9a-4b2a-4f01-af47-1c175f8a2af6/activate' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json"
```

**Response**

```json
204 No Content
```

## **Deactivate token**

<mark style="color:red;">API tokens are read-only, so this request returns 403 Forbidden.</mark>

<mark style="color:blue;">`PUT /api/v1/tokens/:token_uuid/deactivate`</mark>

Deactivate a token so that it cannot be used.

**Parameters**

All parameters are optional.

| Name                 | Type     | Description                                                       |
| -------------------- | -------- | ----------------------------------------------------------------- |
| deactivation\_reason | `string` | A human readable description to describe the deactivation reason. |

**Request**

Example request with `deactivation_reason`.

```url
curl -X PUT 'https://customers.triton.one/api/v1/tokens/74ea9d9a-4b2a-4f01-af47-1c175f8a2af6/deactivate' -H "Authorization: secret-api-token" -H "Content-Type: application/json" -H "Accept:application/json" -d '
{
    "deactivation_reason": "Deactivation reason description"
}' 
```

**Response**

Returns the deactivation reason that was recorded.

```json
{
   "deactivation_reason": {
      "description": "Deactivation reason description",
      "created_at": "2023-06-26T20:16:05Z"
   }
}
```

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Rate limits

Check the per-second, per-IP request limits applied to your endpoints.

## **Overview**

A rate limit caps how many requests an IP can send in a rolling 10-second window. Triton's load balancers enforce it per client IP to keep endpoints stable and protect against abusive traffic. See [Rate and connection limits](https://docs.triton.one/using-your-endpoint/rate-and-connection-limits).

Our goal is to allow legitimate application traffic to flow smoothly while mitigating the impact of aggressive bots.

Tokens and endpoints each have their own rate tier. Requests with a token use the token's tier, and requests from allowed origins use the endpoint's tier. New subscriptions get the same tier for both.

Rate limits do not affect pricing. Our products are billed by usage (per million requests plus per GB of bandwidth).

## **Get rate limits**

<mark style="color:blue;">`GET /api/v1/rate_tiers`</mark>

Returns all Rate Tier types that an Endpoint and Token can get created with. Each rate tier has a `uuid`, a `name` and an `is_restricted` flag; only Triton administrators can assign a restricted tier.

```json
{
  "rate_tiers": [
    { "uuid": "ca141949-a46f-446a-abee-a031e501fea0", "name": "developer", "is_restricted": false },
    ...
  ]
}
```

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Endpoints, regions, and routing

Points of presence, endpoint hostnames, protocols, and region pinning.

Standard endpoints use BGP Anycast, so one hostname serves all of Triton's regions. Your requests reach the closest point of presence in network terms, with health checks and failover built in. You don’t need routing logic of your own to reach the nearest region.

* Your endpoint connects to a pool of redundant load balancers.
* The load balancers spread your requests across healthy nodes.
* If a node or data centre goes down, new requests and connections go to healthy capacity automatically.
* Open gRPC and WebSocket streams on that node are closed, so reconnect automatically.
* A load balancer restart or a network path change can also close a long-lived gRPC or WebSocket connection.

Solana devnet and testnet endpoints don't use Anycast. DNS sends them to the closest healthy devnet or testnet node. City hostnames, `<your-endpoint>.shared.rpcpool.com` hostnames and some dedicated endpoints also use DNS instead of Anycast.

## Regions and points of presence

Triton's shared infrastructure has points of presence in 8 cities on 3 continents:

| Region       | Cities (city code)                                           |
| ------------ | ------------------------------------------------------------ |
| US           | Salt Lake City (`slc`), New York (`nyc`), Pittsburgh (`pit`) |
| Europe       | Amsterdam (`ams`), Frankfurt (`fra`), London (`lon`)         |
| Asia Pacific | Singapore (`sgp`), Tokyo (`tyo`)                             |

Sui and Monad nodes run in fewer cities than these points of presence.

## Endpoint hostnames

Copy your endpoint and secret token from the [customer dashboard](https://customers.triton.one). Each chain has its own hostname format:

| Chain  | Hostname                                      | Networks                 |
| ------ | --------------------------------------------- | ------------------------ |
| Solana | `<your-endpoint>.<network>.rpcpool.com`       | mainnet, devnet, testnet |
| Sui    | `<your-endpoint>.<network>.sui.rpcpool.com`   | mainnet, testnet         |
| Monad  | `<your-endpoint>.<network>.monad.rpcpool.com` | mainnet, testnet         |

Some endpoints use `<your-endpoint>.rpcpool.com`, and Sui dedicated nodes use `<your-endpoint>.sui.rpcpool.com`. Always use the exact hostname shown in the dashboard.

## Protocols and authentication

The same hostname serves these protocols:

| Protocol                             | Chains           | Send your token                                                                                                                             |
| ------------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **JSON-RPC** over HTTPS              | Solana and Monad | In the URL path or the `x-token` header, or use an allowed origin                                                                           |
| **WebSocket** over `wss://`          | Solana and Monad | In the URL path or the `x-token` header, or use an allowed origin                                                                           |
| **gRPC** over HTTPS                  | Solana and Sui   | In the `x-token` header. A token in the URL path doesn’t work, because gRPC clients build the request path from the service and method name |
| **GraphQL** over HTTPS at `/graphql` | Sui mainnet      | In the `x-token` header or in the URL path                                                                                                  |

Sui archival gRPC uses `archive.mainnet.sui.rpcpool.com`. Preconfirmations gRPC uses `preconfs.rpcpool.com`. Riptide uses `riptide.rpcpool.com`. Fumarole uses the `ams` and `nyc` city hostnames; see below.

## Pin a region

Anycast to the closest city (the default) is right for most workloads. To send transactions from several regions at once, or to benchmark one data centre, replace your endpoint's full hostname with a city hostname and keep your token:

```url
https://<city-code>.rpcpool.com/<your-token>
```

City codes are in the table above.

* City hostnames serve shared Solana mainnet.
* They accept your token only. Allowed origins don't work on them.

A city hostname sends your traffic only to that city's load balancers. If one fails, the others in that city take over, but you lose failover between cities. Support can add a hostname for your endpoint that points at one city if you must keep traffic out of other regions. That hostname loses failover between cities the same way.

**Not reaching the region you expect?** Anycast sends your traffic to the point of presence closest in network terms to where it enters the internet, which is usually the nearest one geographically. A VPN or proxy moves that entry point, so test without it, or use a city hostname. If your traffic still reaches the wrong region, contact support.

**Fumarole** is addressed by region: connect to `ams.rpcpool.com` (Europe) or `nyc.rpcpool.com` (US). Each region keeps its own consumer groups and their committed offsets. A consumer group created in one region doesn’t exist in the other.

**Dedicated nodes** run in the Triton data centre you choose. For the lowest latency, choose a city with a point of presence near your backend.

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-lock">:lock:</i> <strong>Auth and security</strong></td><td>Authenticate requests and lock your endpoint to trusted origins.</td><td><a href="https://docs.triton.one/security/authentication">Auth and security</a></td></tr><tr><td><i class="fa-gauge">:gauge:</i> <strong>Rate and connection limits</strong></td><td>Per-method rate limits and streaming connection limits.</td><td><a href="https://docs.triton.one/using-your-endpoint/rate-and-connection-limits">Rate and connection limits</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Rate and connection limits

Per-IP request and connection limits, how to check yours, and what to do after a 429.

Triton applies limits per IP:

* **Rate limits** cap how many requests an IP can send in a rolling 10-second window. JSON-RPC, gRPC and REST requests all count.
* **Connection limits** cap an IP's connection rate and how many WebSocket connections it can hold open at once.

Behind a proxy, all your users share one IP's limits. See [Proxying](https://docs.triton.one/using-your-endpoint/proxying).

Your rate tier sets the values. New subscriptions start on a default tier for their network. On Solana, some RPC methods also have their own caps.

If you need higher limits, contact support. Your rate tier doesn't change your price.

## Rate limits

These budgets apply at the same time, counted over a rolling 10-second window:

* **Total requests.** A budget for your IP across all methods, endpoints and tokens.
* **Per-method limits.** A cap for each method from your IP. Some methods, mostly heavy ones, have their own cap. Every other method uses your tier's default per-method cap.
* **Endpoint requests.** On some tiers, a budget for each token. Requests without a token share one budget per endpoint hostname.

Requests with your token use your token's rate tier. Requests without a token, such as browser calls from an allowed origin, use your endpoint's rate tier. New subscriptions get the same tier for both.

Triton splits some JSON-RPC batches, for example any batch that contains `getProgramAccounts`, `getTransaction` or `sendTransaction`. Each call in a split batch counts as a request, so batching doesn't always save budget.

{% hint style="warning" %}
If any check fails, you get `HTTP 429 Too Many Requests` with `Retry-After: 10`. Pause all requests from that IP for 10 seconds before retrying. Requests you send during the pause still count, so retrying sooner keeps you over the limit.
{% endhint %}

For each 429 message and a backoff example, see [Handle 429 rate-limit errors](https://docs.triton.one/solana/faq/error-handling/handle-429-rate-limit-errors).

### Solana per-method limits

Which methods have their own cap, and the values, depend on your rate tier. Where your endpoint returns them, the `X-Ratelimit-Method-Limit` and `X-Ratelimit-Method-Remaining` headers show the cap that applied to each request. For a batch, they show the strictest cap among its methods. Contact support for your tier's full list.

New Solana mainnet shared subscriptions start with these limits per IP:

| Limit                     | Requests per 10 seconds   |
| ------------------------- | ------------------------- |
| Total, across all methods | 2,000                     |
| Default per-method cap    | 2,000                     |
| `sendTransaction`         | 2,000                     |
| `/sendtx`                 | 2,000, on its own counter |

Some heavy methods have lower caps. To see your current total budget, [check your limits](#check-your-limits).

Solana mainnet doesn't serve `getLargestAccounts` or `requestAirdrop`. They return HTTP `410`, or HTTP `429` if your rate tier caps the method at zero. See [Triton RPC error codes](https://docs.triton.one/solana/faq/error-handling/triton-rpc-error-codes).

On devnet, `requestAirdrop` also has an hourly cap, counted per /24 block of IP addresses. Going over returns `429` with `Retry-After: 86400`.

## Connection limits

Shared endpoints limit:

| Limit                     | What it caps                                              | Going over                                                                                    |
| ------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **Connection rate**       | Counted over the same 10-second window                    | Returns `429` with `Retry-After: 10`                                                          |
| **WebSocket connections** | How many WebSocket connections your IP holds open at once | Returns `429` with no `Retry-After` header. A slot frees when one of your connections closes. |

To stay under the WebSocket limit:

* Close unused connections before you open new ones.
* Put many subscriptions on one connection instead of opening one connection per subscription.
* If you need more, contact support or consider a dedicated node.

Dedicated subscriptions have their own rate tier. Contact support to review it.

## Check your limits

Add `/ratelimits` to your endpoint URL to see your current limits. For example, on Solana mainnet:

```bash
curl "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>/ratelimits"
```

The response is JSON with your request (`rps`), connection (`connections`) and connection-rate (`connrate`) limits, each with how many you have left.

| Field         | What it is                                                                                   |
| ------------- | -------------------------------------------------------------------------------------------- |
| `rps`         | Request limit. Counts requests from your IP in the current 10-second window, not per second. |
| `connections` | Connection limit. For reference only. Going over it doesn't return a `429`.                  |
| `connrate`    | Connection-rate limit                                                                        |
| `airdrop`     | On devnet, the response also includes your `requestAirdrop` limit.                           |

* Values are strings. A limit of `-1` means unlimited.
* `remaining` is the limit minus your current usage.
* With a `-1` limit, `remaining` is always negative. It doesn’t mean you’re over.
* With any other limit, `remaining` below zero means you’re over that limit.
* Per-method caps, the endpoint budget and the WebSocket connection limit aren't included. Where your endpoint returns them, use the `X-Ratelimit-Method-*`, `x-ratelimit-endpoint-*` and `X-Ratelimit-Pubsub-*` headers for those.

Responses can also carry `X-Ratelimit-*` headers. Not every endpoint returns them, and responses served from Triton's cache never do. Where they appear, watch them in your client to slow down **before** you hit a 429:

| Header                                                                                                                 | What it tells you                                                                                                                                |
| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `X-Ratelimit-Tier`                                                                                                     | The rate tier applied to your requests                                                                                                           |
| `x-ratelimit-rps-limit` / `x-ratelimit-rps-remaining`, `x-ratelimit-endpoint-limit` / `x-ratelimit-endpoint-remaining` | Request budget for the current 10-second window, per IP (`rps`) and per token or tokenless hostname (`endpoint`), and how many requests are left |
| `X-Ratelimit-Conn-*`, `X-Ratelimit-ConnRate-Limit`, `X-Ratelimit-Pubsub-*`                                             | Concurrent connections (for reference only), connection rate, and WebSocket (pubsub) connections                                                 |
| `X-Ratelimit-Method-Limit`                                                                                             | Per-method cap for this RPC                                                                                                                      |
| `X-Ratelimit-Method-Remaining`                                                                                         | How many of this method you have left                                                                                                            |

## Client-side browser limits

If you connect through a browser, it caps how many requests run in parallel to one host, so a busy frontend can throttle itself before Triton's limits ever apply. To avoid it:

* Reuse one connection per page instead of opening one per call.
* Batch reads with `getMultipleAccounts` instead of many parallel `getAccountInfo` calls.
* Move heavy reads (program scans, signature crawls) to your backend and cache the results. Per-method caps still apply to your backend's IP.

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-laptop">:laptop:</i> <strong>Customer dashboard tour</strong></td><td>Find your endpoint and token, check usage, and top up your balance.</td><td><a href="https://docs.triton.one/account-and-billing/platform-overview">Customer dashboard tour</a></td></tr><tr><td><i class="fa-earth-americas">:earth-americas:</i> <strong>Endpoints, regions, and routing</strong></td><td>Points of presence, endpoint hostnames, protocols, and region pinning.</td><td><a href="https://docs.triton.one/using-your-endpoint/endpoints-regions-routing">Endpoints, regions, and routing</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Proxying

What a proxy in front of a Triton endpoint changes, and what it must do to work.

{% hint style="warning" %}
Triton doesn't recommend putting a proxy in front of an endpoint. Contact support before you set one up.
{% endhint %}

## What a proxy changes

* **Anycast hostnames.** Triton routes by where your connection enters its network.
* **DNS-routed hostnames** (Solana devnet and testnet). Sui and Monad customer endpoints use Anycast. Triton routes by where the DNS lookup comes from.
* **Behind a proxy,** both mean the proxy's location, not your user's. See [Endpoints, regions, and routing](https://docs.triton.one/using-your-endpoint/endpoints-regions-routing).
* **DNS caching delays failover.** On DNS-routed hostnames, Triton removes an unhealthy node or load balancer from DNS answers. A proxy that caches or pins the answer keeps sending traffic to it.
* **All users share one IP.** Triton applies [rate and connection limits](https://docs.triton.one/using-your-endpoint/rate-and-connection-limits) and blocks per source IP. Every user behind your proxy shares one IP's limits.
* **Repeated 403 blocks cut off the IP.** When one IP triggers `403` blocks at a high rate, Triton rejects its new connections and drops its requests without a response. `429` responses don't count. Behind a proxy, that cuts off every user. See [Earlier connection drops for repeat offenders](https://docs.triton.one/security/privacy-and-security#earlier-connection-drops-for-repeat-offenders).

| Requests without a token                                   | What happens                                                                                                                                                                         |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| From data-centre IP ranges (cloud, hosting and Cloudflare) | Can get `HTTP 403` with `Your IP or provider is blocked from this endpoint`. See [Triton RPC error codes](https://docs.triton.one/solana/faq/error-handling/triton-rpc-error-codes). |
| From some server HTTP clients                              | Get the same `403` from any IP                                                                                                                                                       |
| Plain `http://`                                            | Get the same `403`                                                                                                                                                                   |
| From Cloudflare Workers, with a `CF-Worker` header         | Get the same `403`                                                                                                                                                                   |

{% hint style="warning" %}
**A TLS-terminating proxy reads your traffic.** That includes your token.
{% endhint %}

## Instead of a proxy

* **Keep a token out of browser code.** Use allowed origins with no token. See [Auth and security](https://docs.triton.one/security/authentication#allowed-origins-frontend).
* **Control the region.** Use a city hostname with your token (shared Solana mainnet only), or ask support for a hostname that points at one city. Allowed origins don't work on city hostnames. See [Pin a region](https://docs.triton.one/using-your-endpoint/endpoints-regions-routing#pin-a-region).
* **Other goals.** Tell support what the proxy is for.

## If you still need a proxy

* **Token.** Send your token on every request, in the URL path or the `x-token` header.
* **Token in logs.** Keep your token out of proxy logs and error responses.
* **Host.** Send your endpoint's exact hostname from the customer dashboard as `Host`.
* **Host lookup.** Triton uses `Host` to find your network, then looks up your token there.
* **Unknown Host.** If Triton doesn't know the `Host`, it doesn't recognise your token. Your own domain isn't known by default.
* **Origin.** Only for requests without a token: pass `Origin` unchanged. Triton checks it against your allowed origins.
* **HTTPS.** Connect to Triton over HTTPS and validate its certificate. Triton's certificates are issued for `rpcpool.com` hostnames.

| Protocol      | What to do                                                                                                         | Otherwise                                |
| ------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------- |
| **JSON-RPC**  | Pass `POST` and the `Content-Type` header unchanged. Triton accepts `application/json` and `application/json-rpc`. | Other content types return `415`         |
| **WebSocket** | Pass `Upgrade: websocket`, `Connection: upgrade` and `Sec-WebSocket-Version: 13`                                   | Without version 13, Triton returns `426` |
| **gRPC**      | Use HTTP/2 to Triton and pass `Content-Type: application/grpc` unchanged. Send the token in the `x-token` header.  |                                          |

* **Client IP.** Triton doesn't take the client IP from request headers such as `X-Forwarded-For` or `X-Real-IP`.
* **Client IP header.** To rate-limit by your users' IPs, ask support whether a client-IP header is available for your setup. Blocks still count against your proxy's IP.
* **Rate tier.** Ask support to review your rate tier.
* **DNS.** Resolve Triton's hostname again at each TTL. Don't pin the IP.

{% hint style="danger" %}
If a proxy sends abusive traffic, Triton can block the proxy's IP addresses for your endpoint. That blocks every user behind them.
{% endhint %}

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-earth-americas">:earth-americas:</i> <strong>Endpoints, regions, and routing</strong></td><td>Points of presence, endpoint hostnames, protocols, and region pinning.</td><td><a href="https://docs.triton.one/using-your-endpoint/endpoints-regions-routing">Endpoints, regions, and routing</a></td></tr><tr><td><i class="fa-gauge">:gauge:</i> <strong>Rate and connection limits</strong></td><td>Per-IP rate and connection limits, and 429 handling.</td><td><a href="https://docs.triton.one/using-your-endpoint/rate-and-connection-limits">Rate and connection limits</a></td></tr><tr><td><i class="fa-lock">:lock:</i> <strong>Auth and security</strong></td><td>Tokens, allowed origins, and what to do if a token leaks.</td><td><a href="https://docs.triton.one/security/authentication">Auth and security</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Auth and security

Send requests with a secret token or from an allowed origin, and respond if a token leaks.

|                                                                                         | Secret token                         | Allowed origin                          |
| --------------------------------------------------------------------------------------- | ------------------------------------ | --------------------------------------- |
| **Use from**                                                                            | Servers, scripts, bots, gRPC clients | Browser apps                            |
| **Sent as**                                                                             | URL path or `x-token` header         | Nothing. The browser sends its `Origin` |
| [**Rate tier**](https://docs.triton.one/using-your-endpoint/rate-and-connection-limits) | Your token's tier                    | Your endpoint's tier                    |

## Secret tokens (backend)

{% hint style="danger" %}
Never put a token in frontend code. Anyone who can read it can use it from any origin, and the requests count against your account.
{% endhint %}

{% tabs %}
{% tab title="URL path" %}
JSON-RPC and WebSocket:

```url
https://<your-endpoint>.mainnet.rpcpool.com/<your-token>
wss://<your-endpoint>.mainnet.rpcpool.com/<your-token>
```

For gRPC, use the `x-token` header.
{% endtab %}

{% tab title="x-token header" %}
JSON-RPC, WebSocket and gRPC:

```bash
curl "https://<your-endpoint>.mainnet.rpcpool.com" \
  -H "X-Token: <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSlot"}'
```

On WebSocket and gRPC, send the same `x-token` header (gRPC metadata).
{% endtab %}
{% endtabs %}

`<your-endpoint>` is your endpoint name, the first part of your hostname. For other chains and networks, see [Endpoint hostnames](https://docs.triton.one/using-your-endpoint/endpoints-regions-routing#endpoint-hostnames).

* A token works only on the network of its subscription.
* A token can't be limited to one origin, endpoint or method.

## Allowed origins (frontend)

Browser apps call the endpoint URL with no token, over `https://` or `wss://`:

```url
https://<your-endpoint>.mainnet.rpcpool.com
```

* If an endpoint has active allowed origins, Triton accepts a tokenless browser request only from those origins.
* If an endpoint has active allowed origins, a tokenless JSON-RPC request with no `Origin` header gets `403`.
* A listed hostname also allows its subdomains.
* An origin with a port, such as `https://app.example.com:3000`, doesn't match a hostname entry.
* Allowed origins apply only to the hostnames under **Hostname(s)** in the dashboard. City hostnames need a token.
* Tokenless requests that look like backend traffic can get `403`. See [Stricter filters on tokenless backend traffic](https://docs.triton.one/security/privacy-and-security#stricter-filters-on-tokenless-backend-traffic).
* Tokenless `http://` requests get `403`. Use `https://` or `wss://`.
* Changes can take a few minutes to apply.

{% hint style="warning" %}
An allowed origin isn't a secret. A non-browser client can send any `Origin` header. Use a token for servers.
{% endhint %}

### Add an allowed origin

{% stepper %}
{% step %}
Open the [customer dashboard](https://customers.triton.one) and click the subscription.
{% endstep %}

{% step %}
Under **Endpoints**, click the hostname under **Hostname(s)**.
{% endstep %}

{% step %}
Under **Allowed origins**, click **Add origin**, then enter the hostname, for example `app.example.com`.
{% endstep %}

{% step %}
Click **Save**.
{% endstep %}
{% endstepper %}

| Entry                                  | Rule                                                                                             |
| -------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `app.example.com`                      | Enter a bare hostname, without `https://` or a path.                                             |
| `chrome-extension://<extension-id>`    | For a Chrome extension, enter its full origin.                                                   |
| `moz-extension://`                     | A Firefox extension’s ID differs in each browser install, so one entry matches only one install. |
| `localhost`, `127.0.0.1`, `vercel.app` | Rejected. For Vercel, enter your full subdomain, such as `my-app.vercel.app`.                    |
| `*.example.com`                        | A wildcard entry never matches.                                                                  |

* An endpoint accepts up to 5 active origins by default. Contact support for more.
* To stop allowing a site, switch the toggle next to its origin off and click **Save**. Saved origins can't be deleted.

### `__blocked.rpcpool.com`

* Triton adds it when you turn on an endpoint that has no allowed origins.
* It allows no browser origin, so only requests with a token work.
* It counts toward the 5 active origins while it's active.
* An active endpoint needs at least one active origin. The dashboard won't save it with none.

## Endpoint hygiene

* **Use HTTPS.** Send every request to `https://` or `wss://`. A token sent over `http://` or `ws://` can be read on the network.
* **Turn off unused endpoints.** Use the endpoint's switch under **Endpoints** (pay-as-you-go accounts), or contact support.
* **Set low balance notifications.** Pay-as-you-go accounts: under **Billing**, turn on **Low balance notifications**, set a threshold and click **Save**. At zero balance, the organization is deactivated.
* **Check Metrics.** Look for unfamiliar methods, traffic at unusual hours and sudden bandwidth jumps.
* **Keep tokens out of logs.** Treat a token like a database password.
* **Use one token per environment.** Create separate production, staging and test tokens under **RPC / gRPC Tokens** (operator role).
* **Keep `dev` out of token names.** **Metrics** doesn’t list a token whose name contains `dev`.

## If a token leaks

{% stepper %}
{% step %}

### Replace the token

Creating, deactivating and deleting tokens needs the operator role. Otherwise, contact support from the dashboard chat.

In the [customer dashboard](https://customers.triton.one), open the subscription. Under **Create new token**, enter a **Display Name**, choose a **Rate limit** and click **Add Token**. Update your services to use the new token.

* If the dashboard says `Please disable an existing token to create a new one`, your organization has a token limit. Deactivate a token you don't need, or contact support.
  {% endstep %}

{% step %}

### Check usage

Open **Metrics** and choose the leaked token in the resource dropdown. Look for traffic spikes or unfamiliar methods since the suspected leak.

* Check usage before you delete the token. Metrics doesn’t show a deleted token or its past traffic.
* A deactivated token can’t be chosen in the resource dropdown.
  {% endstep %}

{% step %}

### Delete the leaked token

Click the trash icon on the leaked token, then confirm **Delete**.

* Delete can't be undone. To keep the token, switch its toggle off and confirm instead. The reason is optional.
* A deleted or deactivated token can take a few minutes to stop working.
  {% endstep %}

{% step %}

### Search for the token

Search all repositories, config files, CI/CD pipelines and environment files for the token string. Triton tokens are UUIDs with no prefix, so don't rely on GitHub secret scanning to find them.
{% endstep %}

{% step %}

### Review allowed origins

Deactivate origins you don't recognise or that are broader than you need. A hostname also allows its subdomains.
{% endstep %}

{% step %}

### Rotate related credentials

Replace any token reused across environments, and any secret stored alongside the leaked token.
{% endstep %}
{% endstepper %}

## Proxying

Contact support before you put a proxy in front of an endpoint. See [Proxying](https://docs.triton.one/using-your-endpoint/proxying).

## Report a security issue

<security@triton.one>

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-laptop">:laptop:</i> <strong>Customer dashboard tour</strong></td><td>Find your endpoint and token, check usage, and top up your balance.</td><td><a href="https://docs.triton.one/account-and-billing/platform-overview">Customer dashboard tour</a></td></tr><tr><td><i class="fa-gauge">:gauge:</i> <strong>Rate and connection limits</strong></td><td>Per-IP rate and connection limits, and 429 handling.</td><td><a href="https://docs.triton.one/using-your-endpoint/rate-and-connection-limits">Rate and connection limits</a></td></tr><tr><td><i class="fa-shield-halved">:shield-halved:</i> <strong>Privacy and data protection</strong></td><td>Triton's defence-in-depth security model and how your data is protected.</td><td><a href="https://docs.triton.one/security/privacy-and-security">Privacy and data protection</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Privacy and data protection

Our defence-in-depth security model, designed to protect your data, services, and endpoints.

{% hint style="info" %}
Securing your own endpoint with tokens and allowed origins: [Auth and security](https://docs.triton.one/security/authentication).
{% endhint %}

## Endpoint defences

* **Allowed origins and tokens.** Browser apps use allowed origins. Backend services use a secret token.
* **Rate limiting.** Based on IP address and other factors. See [Rate and connection limits](https://docs.triton.one/using-your-endpoint/rate-and-connection-limits).
* **Traffic filtering.** Malformed requests are rejected before they reach the node software:
  * Unsupported method or path: `405`
  * Wrong content type: `415`
  * WebSocket version other than 13: `426`
  * Request body too large: `413`
  * JSON that doesn't parse: `-32700`
* **Client filtering.** Requests without a token from known non-browser clients are rejected. Requests with a token skip this check.

## DDoS protection

You don't need Cloudflare or another commercial provider in front of your endpoint. See [Proxying](https://docs.triton.one/using-your-endpoint/proxying).

## Internal security posture

### Access

* **Permissions.** Centralised identity and access management, with least-privilege access.
* **MFA.** Required wherever a service supports it.
* **Hardware keys.** Required for privileged staff accounts.
* **SSO.** Staff sign in through company SSO wherever a service supports it.
* **SSH.** Access to servers is restricted to authenticated staff.

### Network

* **Internal traffic.** Runs over a private encrypted network by default.
* **Host firewalls.** Follow a minimal-exposure policy.
* **Encryption in transit.** HTTPS connections are encrypted.

### Systems

* **Work devices.** Required to use full disk encryption and antivirus software, and a VPN on untrusted networks.
* **Security patching.** Servers install security updates automatically every day.
* **Vulnerability monitoring.** Server packages are monitored for known vulnerabilities (CVEs).

### Personnel

* **Onboarding.** Formal onboarding with gradual access provisioning.
* **Offboarding.** A documented offboarding procedure revokes access.
* **Training.** Regular security awareness training.

### Audit and incident response

* **Audits.** Daily automated security audits on all hosts.
* **Alerting.** Critical alerts page the on-call team 24/7.
* **Security reports.** Emails to <security@triton.one> page the on-call engineer.
* **Incident response.** Documented security incident response and disaster recovery plans.

## Data privacy

Triton handles customer data in compliance with GDPR and equivalent regulations.

### Customer data we process

* Validator node identity keys for customers running validators on our infrastructure
* RPC service logs generated by user interaction with endpoints
* Account and billing information required for invoicing and account management

### How we protect it

* **Validator keys.** Never stored or transmitted unencrypted. Decrypted only in process memory while actively in use.
* **Billing details.** Card numbers and similar sensitive payment info are never stored on Triton systems. Billing is handled entirely by separate, dedicated, compliant third-party processors.

### RPC log retention and privacy levels

**Shared services.** Logs collected solely for abuse prevention and operational stability. Triton does not identify or de-anonymise individual end users. Retention: 4 weeks.

**Dedicated services.** Customers choose the policy that fits their legal or privacy requirements:

| Policy                         | What is logged                                                                                           | Notes                                                                                                           |
| ------------------------------ | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Max privacy**                | No request parameters or payloads logged.                                                                | Highest privacy, but limits some abuse-detection capability. Required for any shared infrastructure components. |
| **Enhanced privacy (default)** | Method parameters may be logged, but the signer of a transaction cannot be linked to the originating IP. | Balance of operational insight and user privacy.                                                                |
| **GDPR privacy**               | All parameters may be logged for technical support, legal, or compliance reasons.                        | Fully GDPR-compliant handling.                                                                                  |

## Abuse-mitigation measures

### Earlier connection drops for repeat offenders

* **What counts.** Repeated `403` responses from one source IP.
* **Over the limit.** Triton rejects new connections from that IP and drops its requests without a response.
* **In your logs.** First `403` errors, then network-level failures ("network connection failed" or similar) instead of an HTTP error.
* **Fix.** Check that your token is correct and enabled, that your allowed origins include the requesting origin, and that your organization is active in the [customer dashboard](https://customers.triton.one).
* **After the fix.** Back off for at least one minute.

### Stricter filters on tokenless backend traffic

* **Tokenless backend requests.** Requests without a token that appear to come from a backend environment can get `403`.
* **Backend services.** Send a token on every request.
* **Allowed origins.** For browser apps only. A backend service that relies on allowed origins instead of a token is likely to be blocked.
* **Disabled tokens.** A disabled token, or a token of an inactive organization, counts as no token.

## Contact

* General security or privacy questions: contact support by clicking the chat icon in the bottom right of your [customer dashboard](https://customers.triton.one)
* Urgent security reports: <security@triton.one>

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-gauge">:gauge:</i> <strong>Rate and connection limits</strong></td><td>Per-IP rate and connection limits, and 429 handling.</td><td><a href="https://docs.triton.one/using-your-endpoint/rate-and-connection-limits">Rate and connection limits</a></td></tr><tr><td><i class="fa-laptop">:laptop:</i> <strong>Customer dashboard tour</strong></td><td>Find your endpoint and token, check usage, and top up your balance.</td><td><a href="https://docs.triton.one/account-and-billing/platform-overview">Customer dashboard tour</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Account and signup

Creating an account, inactive organizations and endpoints, sign-in and passwords, teammates and roles, and contacting support.

<details>

<summary>How do I create an account?</summary>

Sign up at [customers.triton.one](https://customers.triton.one/onboarding):

1. Choose **Individual** or **Business**. Enter your email, username and password, then the code from the confirmation email.
2. Enter your personal details.
3. Accept the terms.

* Triton checks your details against sanctions and politically exposed person (PEP) lists before you can pay.
* If your signup needs a manual review, Triton contacts you.
* Business accounts also enter company details and name their administrators, beneficial owners and authorized signatories. Only an authorized signatory can accept the terms.

See [Quickstart](https://docs.triton.one/quickstart).

</details>

<details>

<summary>Why is my organization or endpoint inactive?</summary>

* **Zero balance (pay-as-you-go):** the organization is deactivated. Topping up with **Buy Credits** reactivates it.
* **Blank domain at signup:** endpoints start inactive. Turn each one on with its switch under **Endpoints** in the subscription.
* **Effect on requests:** a token of an inactive organization counts as no token, so backend requests can get `403`.
* **Warning before zero:** under **Billing**, turn on **Low balance notifications** and set a threshold to get an email.

See [Balance and payments](https://docs.triton.one/account-and-billing/platform-overview#balance-and-payments) and [Quickstart](https://docs.triton.one/quickstart).

</details>

<details>

<summary>How do I sign in or reset my password?</summary>

* **Sign in:** [customers.triton.one](https://customers.triton.one), with your username or email.
* **Forgot your password:** click **Forgot your password?** on the sign-in page.
* **Change it while signed in:** **Home** → **User** → **Password**.
* Inactive sessions sign out after 7 days.

See [Profile](https://docs.triton.one/account-and-billing/platform-overview#profile).

</details>

<details>

<summary>How do I add or remove a teammate?</summary>

* **Invite:** your organization → **Organization** tab → **Users** → **Invite user** → **Email address** → **Send Invitation**. They get an email to create their login.
* **Remove:** click the trash icon next to the user, then **Remove**. You can't remove yourself.
* **Roles:** with the default standard role, contact support to create or delete tokens, add endpoints or chains, or change rate limits. Users with the operator role can create and delete tokens.

See [Your team](https://docs.triton.one/account-and-billing/platform-overview#your-team).

</details>

<details>

<summary>How do I get the operator role?</summary>

* Operators can create, deactivate and delete tokens. The default standard role can't.
* **New teammate:** an operator invites them and picks **Operator** under **Role**. Standard users don't see the **Role** choice.
* **Existing user:** contact support. You can't change a user's role in the dashboard.

See [Your team](https://docs.triton.one/account-and-billing/platform-overview#your-team).

</details>

<details>

<summary>How do I contact support?</summary>

* **Support:** click the chat icon in your [customer dashboard](https://customers.triton.one), or **Chat with support** in the sidebar.
* **Sales:** [contact sales](https://triton.one/contact).

See [Where things are](https://docs.triton.one/account-and-billing/platform-overview#where-things-are).

</details>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Billing and payments

Top-ups, payment methods, shared or dedicated, invoices, what’s billed, compression, usage, refunds, free trials, and test networks.

## Top-ups and payments

<details>

<summary>How do I top up my balance?</summary>

* Click **Buy Credits** under **Current Balance** or in the dashboard sidebar, or **Billing** → **Buy credits**.
* Enter the deposit in USD.
* Pay in USDC through Coinflow, on the chain you pick at checkout.
* The processing fee is shown before you pay.
* The minimum deposit is on the [pricing page](https://triton.one/pricing).
* Deposits are valid for 12 months.

See [Balance and payments](https://docs.triton.one/account-and-billing/platform-overview#balance-and-payments).

</details>

<details>

<summary>Why hasn't my deposit shown up in my balance?</summary>

* **Check:** **Billing** → **Transactions** → **Daily usage summary**. Expand the day. A credited deposit is listed under **Credits** with type **Payment**.
* **Amount:** your balance gets the deposit amount. The processing fee is charged on top and isn't added.
* **Invoice payments:** paying an invoice at [customers.triton.one/pay-invoice](https://customers.triton.one/pay-invoice) never adds to your balance.
* **Still missing:** contact support from the dashboard chat.

See [Balance and payments](https://docs.triton.one/account-and-billing/platform-overview#balance-and-payments).

</details>

<details>

<summary>What payment methods does Triton accept?</summary>

* **Pay-as-you-go:** USDC, through **Buy credits**.
* **Invoiced:** card, ACH, USDC or wire.
* **Can't pay in crypto:** ask about invoiced billing in the dashboard chat or [contact sales](https://triton.one/contact).

See [Pay-as-you-go or invoiced](https://docs.triton.one/account-and-billing/plans-and-billing#pay-as-you-go-or-invoiced).

</details>

## Plans and infrastructure

<details>

<summary>Should I use shared or dedicated infrastructure?</summary>

* **Shared:** fits most workloads, including trading bots and market makers. Sign up at [customers.triton.one](https://customers.triton.one/onboarding).
* **Dedicated:** for high-volume gRPC streaming, when metered streaming would cost more than a node's fixed monthly price. Also for a workload that needs isolated gRPC streaming capacity. [Contact sales](https://triton.one/contact).
* A dedicated node covers gRPC streaming for one network at a fixed monthly price.
* JSON-RPC and WebSocket run on shared infrastructure at shared rates.
* Fumarole is billed separately, per usage.

See [Shared or dedicated](https://docs.triton.one/account-and-billing/plans-and-billing#shared-or-dedicated).

</details>

<details>

<summary>Can I run scripts or bots on shared infrastructure?</summary>

Yes.

* Shared fits most workloads, including trading bots and market makers.
* Authenticate scripts and bots with a secret token. Tokenless backend requests can get `403`.
* Your IP's rate and connection limits apply. Contact support for higher limits.

See [Shared or dedicated](https://docs.triton.one/account-and-billing/plans-and-billing#shared-or-dedicated) and [Secret tokens (backend)](https://docs.triton.one/security/authentication#secret-tokens-backend).

</details>

<details>

<summary>How do pay-as-you-go and invoiced billing differ?</summary>

* **Pay-as-you-go:** usage is deducted from a prepaid USDC balance. Service stops at zero.
* **Invoiced:** charged on the 1st of each month for the coming month. Usage above your estimate goes on the next invoice, with no interruption.

See [Pay-as-you-go or invoiced](https://docs.triton.one/account-and-billing/plans-and-billing#pay-as-you-go-or-invoiced).

</details>

<details>

<summary>How do I switch to invoiced billing?</summary>

Open the chat in your [customer dashboard](https://customers.triton.one) or [contact sales](https://triton.one/contact).

See [Pay-as-you-go or invoiced](https://docs.triton.one/account-and-billing/plans-and-billing#pay-as-you-go-or-invoiced).

</details>

## Invoices

<details>

<summary>Where do I find and pay my invoice?</summary>

* **Find it:** on invoiced accounts, go to **Billing** → **Invoices** and click **View** or **Download**.
* **Pay it:** open [customers.triton.one/pay-invoice](https://customers.triton.one/pay-invoice), enter the invoice number, amount and receipt email, and pay by card, ACH or USDC.

See [Balance and payments](https://docs.triton.one/account-and-billing/platform-overview#balance-and-payments).

</details>

<details>

<summary>How do I change who receives my invoices?</summary>

* Contact support from the dashboard chat with the email addresses that should receive invoices.
* You can't change invoice recipients in the dashboard.

See [Balance and payments](https://docs.triton.one/account-and-billing/platform-overview#balance-and-payments).

</details>

## Usage and what counts toward your bill

<details>

<summary>What counts toward my bill?</summary>

* **Requests:** billed per million.
* **Bandwidth:** billed per GB of data sent to you. Data you send isn't counted.
* **Streams:** billed on bandwidth only.
* **Not billed:** requests rejected with HTTP `403`, `429`, `500` or `503`.
* **Billed:** a gRPC or WebSocket stream that Triton's load balancer closes after sending data is billed for the data already delivered, if it's over 1,000 bytes.

Some products bill on other bases. Rates are on the [pricing page](https://triton.one/pricing).

See [How usage is billed](https://docs.triton.one/account-and-billing/plans-and-billing#how-usage-is-billed) for each chain's table and [Errors and disconnects](https://docs.triton.one/account-and-billing/plans-and-billing#errors-and-disconnects).

</details>

<details>

<summary>Is compressed or uncompressed bandwidth billed?</summary>

* **gRPC streams** (Yellowstone gRPC, Riptide): compressed bytes sent. zstd or gzip lowers the bill, at a CPU and latency cost.
* **JSON-RPC and other HTTP calls** (including Superbank, Cloudbreak and DAS): uncompressed response size. gzip doesn't change the bill.
* **WebSocket**: bytes sent. Frames aren't compressed.
* Filtering what you request or subscribe to is the most effective way to cut bandwidth.
* On Solana, `base64+zstd` account encoding and `dataSlice` shrink the response itself, so they lower the bill.

See [How bandwidth is measured](https://docs.triton.one/account-and-billing/plans-and-billing#how-bandwidth-is-measured).

</details>

<details>

<summary>How do I see which token or method uses my traffic?</summary>

* **Metrics:** requests, failed requests, response times, bandwidth and gRPC subscriptions, broken down by endpoint, token, method, status code and origin. It covers the last hour to 7 days.
* **Billing** → **Usage charts** → **Product Breakdown:** requests, bandwidth and cost per product.
* **Export:** **Billing** has **Export CSV** and **Export per-method CSV**.

See [Usage and costs](https://docs.triton.one/account-and-billing/platform-overview#usage-and-costs).

</details>

<details>

<summary>Can I see my usage per IP address?</summary>

No.

* **Metrics** breaks usage down by endpoint, token, method, status code and origin, not by IP.
* To track clients separately, give each its own token and select it in **Metrics**.
* Rate and connection limits apply per IP.

See [Usage and costs](https://docs.triton.one/account-and-billing/platform-overview#usage-and-costs) and [Rate and connection limits](https://docs.triton.one/using-your-endpoint/rate-and-connection-limits).

</details>

<details>

<summary>Why doesn't my usage or bill match what I expected?</summary>

* **Billing** updates about every 4 hours.
* Streams are recorded when they close, so a long-lived stream appears all at once.
* A stream still open at the end of a month is billed in the next month.
* If your bandwidth is higher than you expect, contact support from the dashboard chat.

See [Usage and costs](https://docs.triton.one/account-and-billing/platform-overview#usage-and-costs) and [How usage is billed](https://docs.triton.one/account-and-billing/plans-and-billing#how-usage-is-billed).

</details>

## Refunds, cancelling, free trials and test networks

<details>

<summary>Can I get a refund, cancel my plan or close my account?</summary>

* **Pay-as-you-go:** deposits are non-refundable under the terms you accept at signup, including any unused balance.
* **Invoiced:** cancel with one calendar month's notice.
* **Close your account:** contact support from the dashboard chat. There's no close option in the dashboard.

See [Pay-as-you-go or invoiced](https://docs.triton.one/account-and-billing/plans-and-billing#pay-as-you-go-or-invoiced).

</details>

<details>

<summary>Is there a free trial?</summary>

No.

* Devnet and testnet are free on every subscription.
* The minimum deposit on the [pricing page](https://triton.one/pricing) goes entirely to usage and is valid for 12 months.

See [Pay-as-you-go or invoiced](https://docs.triton.one/account-and-billing/plans-and-billing#pay-as-you-go-or-invoiced).

</details>

<details>

<summary>Is devnet or testnet free?</summary>

Yes.

* Devnet and testnet are free on every subscription and don't use your balance.
* Each chain you choose at signup gets a mainnet subscription and a test-network subscription, each with its own endpoint and token.

See [Quickstart](https://docs.triton.one/quickstart) and [Plans and billing](https://docs.triton.one/account-and-billing/plans-and-billing).

</details>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Endpoints and tokens

Finding your endpoint URL and token, regions, rotating and sending tokens, and connecting over WebSocket.

<details>

<summary>Where do I find my endpoint URL and token?</summary>

In the [customer dashboard](https://customers.triton.one), click the subscription whose **Type** is your chain and network, for example **Solana Mainnet**.

* **Hostname:** **Endpoints** → **Hostname(s)**.
* **Token:** **RPC / gRPC Tokens** → **Secret token**.
* **Full URL with the token:** **Copy** under **Connection String for Endpoint**.
* **No Endpoints card:** the subscription has no endpoints yet. Contact support to add one.

See [Endpoints and tokens](https://docs.triton.one/account-and-billing/platform-overview#endpoints-and-tokens) and [Endpoint hostnames](https://docs.triton.one/using-your-endpoint/endpoints-regions-routing#endpoint-hostnames).

</details>

<details>

<summary>Which region do my requests reach?</summary>

* Standard endpoints use BGP Anycast, so requests reach the closest of Triton's 8 cities automatically.
* **Pin a city on shared Solana mainnet:** use `https://<city-code>.rpcpool.com/<your-token>` with `slc`, `nyc`, `pit`, `ams`, `fra`, `lon`, `sgp` or `tyo`. You lose failover between cities.
* Support can also add a hostname for your endpoint that points at one city.

See [Pin a region](https://docs.triton.one/using-your-endpoint/endpoints-regions-routing#pin-a-region).

</details>

<details>

<summary>How do I rotate or replace a token?</summary>

These steps also apply if a token leaks.

1. Create a new token and update your services to use it.
2. Before you delete the old token, check its usage in **Metrics**, which doesn't show deleted tokens.
3. Delete the old token, or deactivate it with its toggle. It can take a few minutes to stop working. Delete can't be undone.

* Creating, deactivating and deleting tokens needs the operator role. Otherwise, contact support from the dashboard chat.
* If the dashboard says `Please disable an existing token to create a new one`, your organization has a token limit. Deactivate a token you don't need, or contact support.

See [If a token leaks](https://docs.triton.one/security/authentication#if-a-token-leaks).

</details>

<details>

<summary>How do I send my token with a request?</summary>

* **URL path (JSON-RPC and WebSocket):** `https://<your-endpoint>.mainnet.rpcpool.com/<your-token>` or `wss://<your-endpoint>.mainnet.rpcpool.com/<your-token>`.
* **`x-token` header (JSON-RPC, WebSocket and gRPC):** send `X-Token: <your-token>`. On gRPC it is metadata.
* **gRPC:** use the header only. A token in the URL path doesn't work.
* **Browsers:** never put a token in frontend code. Use an allowed origin.

See [Secret tokens (backend)](https://docs.triton.one/security/authentication#secret-tokens-backend).

</details>

<details>

<summary>How do I connect over WebSocket?</summary>

* **Connect:** `wss://<your-endpoint>.mainnet.rpcpool.com/<your-token>`, or send the token in the `x-token` header. Browser apps use an allowed origin and no token.
* **Version:** use WebSocket version 13. Other versions get `426`.
* **Reconnect:** a node failure, a load balancer restart or a network path change can close a connection, so reconnect automatically.
* **Limit:** your IP can hold a limited number of open connections. Over it you get `429`. Put many subscriptions on one connection.

See [Protocols and authentication](https://docs.triton.one/using-your-endpoint/endpoints-regions-routing#protocols-and-authentication) and [Connection limits](https://docs.triton.one/using-your-endpoint/rate-and-connection-limits#connection-limits).

</details>

<details>

<summary>Why are my requests not reaching the region I expect?</summary>

* Anycast sends traffic to the point of presence closest in network terms to where it enters the internet. That is usually the nearest one geographically.
* A VPN or proxy moves that entry point. Test without it.
* Or use a city hostname on shared Solana mainnet. It accepts your token only, and you lose failover between cities.
* If your traffic still reaches the wrong region, contact support.

See [Pin a region](https://docs.triton.one/using-your-endpoint/endpoints-regions-routing#pin-a-region).

</details>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Limits and errors

HTTP 403 and 429 errors, dropped connections, per-method limits, and raising your limits.

<details>

<summary>Why do I get HTTP 403 "Your IP or provider is blocked from this endpoint"?</summary>

A request without a token can get this `403` when it looks like backend traffic.

**Fix:** send your token on every request from a backend. Allowed origins are for browser apps only. A disabled token, or a token of an inactive organization, counts as no token.

See [Stricter filters on tokenless backend traffic](https://docs.triton.one/security/privacy-and-security#stricter-filters-on-tokenless-backend-traffic) and [Allowed origins](https://docs.triton.one/security/authentication#allowed-origins-frontend).

</details>

<details>

<summary>Why do my requests fail with network errors after several 403 errors?</summary>

* When one IP triggers `403` errors at a high rate, Triton rejects its new connections and drops its requests without a response.
* Check that your token is correct and enabled, that your allowed origins include the requesting origin, and that your organization is active.
* Then back off for at least one minute.

See [Earlier connection drops for repeat offenders](https://docs.triton.one/security/privacy-and-security#earlier-connection-drops-for-repeat-offenders).

</details>

<details>

<summary>Why do I get HTTP 429?</summary>

`429` means your IP went over a limit.

* **Rate limit:** requests in a rolling 10-second window. The `429` carries `Retry-After: 10`. Pause all requests from that IP for 10 seconds, because requests you send during the pause still count.
* **Connection rate:** counted over the same 10-second window. The `429` carries `Retry-After: 10`.
* **WebSocket connections:** connections your IP holds open at once. The `429` has no `Retry-After`. Close unused connections before you open new ones.

See [Rate limits](https://docs.triton.one/using-your-endpoint/rate-and-connection-limits#rate-limits) and [Connection limits](https://docs.triton.one/using-your-endpoint/rate-and-connection-limits#connection-limits).

</details>

<details>

<summary>Do some methods have their own rate limit?</summary>

* On Solana, some RPC methods have their own cap, on top of your total request budget. Which methods and what values depend on your rate tier.
* On new Solana mainnet shared subscriptions, the default per-method cap is 2,000 requests per 10 seconds per IP, the same as the total budget. `sendTransaction` is also capped at 2,000. Some heavy methods have lower caps.
* Where your endpoint returns them, `X-Ratelimit-Method-Limit` and `X-Ratelimit-Method-Remaining` show the cap that applied. For a batch, they show the strictest cap.
* Contact support for your tier's full list.

See [Solana per-method limits](https://docs.triton.one/using-your-endpoint/rate-and-connection-limits#solana-per-method-limits).

</details>

<details>

<summary>How do I raise my limits?</summary>

* Contact support. Your rate tier sets the values and doesn't change your price.
* To see your current limits, add `/ratelimits` at the end of your endpoint URL, after the token.

See [Check your limits](https://docs.triton.one/using-your-endpoint/rate-and-connection-limits#check-your-limits).

</details>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Security and privacy

Calling your endpoint from a website, proxies and Cloudflare, logging, the \_\_blocked.rpcpool.com origin, and security contacts.

<details>

<summary>How do I call my endpoint from my website without exposing my token?</summary>

Never put a token in frontend code. Add your site as an allowed origin and call the endpoint URL with no token:

1. Under the endpoint's **Allowed origins**, click **Add origin**.
2. Enter the hostname without `https://`, for example `app.example.com`.
3. Click **Save**.

* An endpoint accepts up to 5 active origins by default.
* An allowed origin isn't a secret, so use a token for servers.

See [Allowed origins](https://docs.triton.one/security/authentication#allowed-origins-frontend).

</details>

<details>

<summary>Can I put a proxy or Cloudflare in front of my endpoint?</summary>

* Triton doesn't recommend a proxy. You don't need Cloudflare or another provider for DDoS protection.
* If you still need one, contact support first.
* Every user behind a proxy shares one IP's rate limits and blocks.
* Tokenless requests from data-centre IPs can get `403`.

See [Proxying](https://docs.triton.one/using-your-endpoint/proxying).

</details>

<details>

<summary>What does Triton log, and for how long?</summary>

* **Shared services:** RPC logs are collected only for abuse prevention and operational stability, and kept for 4 weeks. Triton doesn't identify or de-anonymise individual end users.
* **Dedicated services:** you choose max privacy, enhanced privacy (the default) or GDPR privacy.

See [RPC log retention and privacy levels](https://docs.triton.one/security/privacy-and-security#rpc-log-retention-and-privacy-levels).

</details>

<details>

<summary>What is `__blocked.rpcpool.com` in my allowed origins?</summary>

* Triton adds it when you turn on an endpoint that has no allowed origins.
* It allows no browser origin, so only requests with a token work.
* Don't remove it. An active endpoint needs at least one active origin.
* It counts toward the 5 active origins while it's active.

See [Allowed origins](https://docs.triton.one/security/authentication#allowed-origins-frontend).

</details>

<details>

<summary>Who do I contact about privacy or security?</summary>

* **General security or privacy questions:** click the chat icon in the bottom right of your [customer dashboard](https://customers.triton.one).
* **Urgent security reports:** <security@triton.one>.

See [Contact](https://docs.triton.one/security/privacy-and-security#contact).

</details>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Solana overview

Triton's Solana products by workload: account reads, real-time streaming, historical data, transaction sending, trading APIs and dedicated nodes.

Triton is one of Solana's original validators, running since the testnet, and has provided Solana RPC since 2021.

## Start here

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-signs-post">:signs-post:</i> <strong>Choose a Solana product</strong></td><td>Match your task to the Triton product and page that handles it.</td><td><a href="https://docs.triton.one/solana/decision-tree">Choose a Solana product</a></td></tr><tr><td><i class="fa-chart-line">:chart-line:</i> <strong>Trading and market making</strong></td><td>Real-time DEX data, a pre-execution signal from Deshred, priority fees and transaction landing.</td><td><a href="https://docs.triton.one/solana/quickstart/use-cases/trading-and-market-making">Trading and market making</a></td></tr><tr><td><i class="fa-wallet">:wallet:</i> <strong>Building a wallet</strong></td><td>Balances, account-change streaming, history, and sending SOL and SPL tokens.</td><td><a href="https://docs.triton.one/solana/quickstart/use-cases/building-a-wallet">Building a wallet</a></td></tr></tbody></table>

## Every subscription

* **Shred Streaming and Preconfirmations gRPC:** billed separately and enabled on request. See [Plans and billing](https://docs.triton.one/account-and-billing/plans-and-billing).
* **Devnet and testnet:** free on every subscription.
* **Network support:** not every product runs on devnet or testnet. See [Networks we support](https://docs.triton.one/#networks-we-support).
* **Limits:** set by your rate tier and raised at no extra cost. See [Rate and connection limits](https://docs.triton.one/using-your-endpoint/rate-and-connection-limits).

## Reading account state

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-server">:server:</i> <strong>Standard RPC</strong></td><td>Solana JSON-RPC methods for reading accounts and tokens, on bare-metal nodes.</td><td><a href="https://docs.triton.one/solana/rpc-methods/readme">Account methods</a></td></tr><tr><td><i class="fa-database">:database:</i> <strong>Cloudbreak</strong></td><td>getProgramAccounts and SPL token account queries served from indexes. The getProgramAccounts indexes are built automatically from real query traffic. You call them like any other Solana RPC method; there is nothing to enable or route on your side.</td><td><a href="https://docs.triton.one/solana/reading-account-state/cloudbreak-indexed-accounts">Cloudbreak Accounts</a></td></tr><tr><td><i class="fa-image">:image:</i> <strong>Metaplex DAS API</strong></td><td>One API for NFTs, compressed NFTs and fungible tokens, including Token-2022.</td><td><a href="https://docs.triton.one/solana/reading-account-state/metaplex-das-api">Metaplex DAS API</a></td></tr><tr><td><i class="fa-arrows-rotate">:arrows-rotate:</i> <strong>Account Sync</strong></td><td>Triton SDKs that serve reads of tracked accounts from memory, kept current by a stream.</td><td><a href="https://docs.triton.one/solana/reading-account-state/account-sync">Account Sync</a></td></tr></tbody></table>

## Real-time streaming

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-radio">:radio:</i> <strong>Dragon's Mouth gRPC</strong></td><td>Yellowstone gRPC stream of account, transaction, slot, block and entry updates, with intra-slot account and transaction updates at processed commitment.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc">Dragon's Mouth gRPC</a></td></tr><tr><td><i class="fa-water">:water:</i> <strong>Riptide</strong></td><td>Dragon's Mouth over a faster network path: same protocol, filters and client code. On a shared mainnet subscription, only the endpoint URL changes.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/riptide">Riptide</a></td></tr><tr><td><i class="fa-satellite-dish">:satellite-dish:</i> <strong>Shred Streaming</strong></td><td>Raw shreds sent to the IP and port you register, before blocks are assembled. Enabled on request.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/shred-streaming">Shred Streaming</a></td></tr><tr><td><i class="fa-fire">:fire:</i> <strong>Deshred Transactions gRPC</strong></td><td>Transactions rebuilt from shreds and streamed before the node executes them, with the Dragon's Mouth subscription pattern.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/deshred-transactions">Deshred Transactions gRPC</a></td></tr><tr><td><i class="fa-stopwatch">:stopwatch:</i> <strong>Preconfirmations gRPC</strong></td><td>Preconfirmed transactions from Harmonic and Jito BAM, streamed before any shred exists. Enabled on request.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc">Preconfirmations gRPC</a></td></tr><tr><td><i class="fa-rotate-right">:rotate-right:</i> <strong>WebSocket</strong></td><td>Triton's Solana WebSocket API for browsers and frontends, served from Dragon's Mouth gRPC, with <code>transactionSubscribe</code>.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/whirligig-websockets">WebSocket</a></td></tr><tr><td><i class="fa-layer-group">:layer-group:</i> <strong>Fumarole</strong></td><td>Persistent gRPC streams that resume where you left off after a disconnect, from about 4 days of retained data.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/fumarole-persistent-streams">Fumarole Persistent gRPC</a></td></tr></tbody></table>

## Historical data

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-clock-rotate-left">:clock-rotate-left:</i> <strong>Superbank</strong></td><td>Solana ledger history back to the genesis block, served through Solana-compatible JSON-RPC.</td><td><a href="https://docs.triton.one/solana/historical-data">Historical data</a></td></tr></tbody></table>

## Sending transactions

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-paper-plane">:paper-plane:</i> <strong>Jet</strong></td><td>sendTransaction on mainnet and on shared devnet and testnet endpoints goes through Jet, which sends to upcoming leaders over QUIC. Mainnet sends get SWQoS.</td><td><a href="https://docs.triton.one/solana/sending-transactions">Sending transactions</a></td></tr><tr><td><i class="fa-bolt">:bolt:</i> <strong>sendTx</strong></td><td>Send a signed transaction over plain HTTP, without the JSON-RPC envelope.</td><td><a href="https://docs.triton.one/solana/rpc-methods/sending-transactions/sendtx">sendTx</a></td></tr><tr><td><i class="fa-arrow-trend-up">:arrow-trend-up:</i> <strong>Priority fees API</strong></td><td>Adds a percentile parameter to getRecentPrioritizationFees for fee estimates.</td><td><a href="https://docs.triton.one/solana/sending-transactions/priority-fees-api">Priority fees API</a></td></tr><tr><td><i class="fa-shield">:shield:</i> <strong>Shield</strong></td><td>An on-chain policy that limits which validators can process your transactions.</td><td><a href="https://docs.triton.one/solana/sending-transactions/shield-mev-protection">Shield Protection</a></td></tr><tr><td><i class="fa-route">:route:</i> <strong>Titan Swap API</strong></td><td>Meta-aggregated Solana swap quotes streamed over WebSocket, with the route re-optimized at execution.</td><td><a href="https://docs.triton.one/solana/sending-transactions/3rd-party-apis/titan-swap-api">Titan Swap API</a></td></tr><tr><td><i class="fa-box">:box:</i> <strong>Jito Bundle Simulation</strong></td><td>simulateBundle on Triton's Jito-enabled RPC, to test atomic bundles before they go to auction.</td><td><a href="https://docs.triton.one/solana/sending-transactions/3rd-party-apis/jito-bundles">Jito Bundle Simulation</a></td></tr><tr><td><i class="fa-rocket">:rocket:</i> <strong>Yellowstone Jet TPU client</strong></td><td>Open-source Rust client that sends from your own backend straight to validator TPUs over QUIC.</td><td><a href="https://docs.triton.one/solana/quickstart/sending-transactions/yellowstone-jet-tpu-client">Yellowstone Jet TPU client</a></td></tr></tbody></table>

## Dedicated nodes

* Runs gRPC streaming for one network, in a region you choose.
* Isolated gRPC streaming capacity with its own rate tier.
* JSON-RPC stays on shared infrastructure.
* WebSocket connections run on Triton's shared servers by default.
* Custom setups such as DAS, indexing or history clusters are on request: [contact sales](https://triton.one/contact).

See [Dedicated nodes](https://docs.triton.one/solana/dedicated-nodes).

## Open-source work

* **RPC 2.0:** a rebuild of Solana's read layer with the Solana Foundation, shipping in stages. Cloudbreak and Superbank are its live parts. See the [announcement](https://blog.triton.one/announcing-rpc-2-0-with-solana-foundation-rethinking-solanas-read-layer-from-the-ground-up/).
* **Yellowstone gRPC:** the open-source Geyser gRPC interface that Dragon's Mouth runs on. See [GitHub](https://github.com/rpcpool/yellowstone-grpc).
* **Old Faithful:** Solana's ledger history from genesis as CAR files anyone can download and verify. See [docs.old-faithful.net](https://docs.old-faithful.net).
* **Metaplex DAS API:** co-developed with Metaplex. Ingestion now runs on Yellowstone gRPC.
* **Shipstern:** open-source toolkit that parses Solana program data from a gRPC stream. See [How to use Shipstern + gRPC](https://docs.triton.one/solana/quickstart/streaming/how-to-use-shipstern-grpc).
* **Thorofare:** open-source tool that benchmarks gRPC endpoints against each other. See [Benchmark gRPC endpoints with Thorofare](https://docs.triton.one/solana/quickstart/streaming/benchmark-grpc-endpoints-with-thorofare).

## Need a chain we don't list?

We run validators and nodes on many networks and can set up dedicated infrastructure for others. [Contact sales](https://triton.one/contact).

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Choose a Solana product

Choose a Solana product by workload: sendTransaction (Jet), Dragon's Mouth gRPC, WebSocket, Fumarole, Cloudbreak, Superbank, Titan Swap API, and DAS.

## Transaction submission

| I need…                                                                                           | Use                                                                                             | Page                                                                                           |
| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| To send from any Solana SDK with the standard JSON-RPC method                                     | **`sendTransaction`** on your Triton endpoint, routed through the Jet sending engine on mainnet | [Sending transactions](https://docs.triton.one/solana/sending-transactions)                    |
| Lower send latency without an RPC client library, for example from a browser or an HFT backend    | **`/sendtx`**, a direct HTTP POST that skips the JSON-RPC envelope and always skips preflight   | [Sending transactions](https://docs.triton.one/solana/sending-transactions)                    |
| Full client-side control and lower latency, for bots or custom routers                            | The open-source **Jet TPU client**, a Rust crate you self-host                                  | [Sending transactions](https://docs.triton.one/solana/sending-transactions)                    |
| A priority fee based on the market rate instead of the minimum                                    | **`getRecentPrioritizationFees`** with Triton's `percentile` parameter                          | [Priority fees API](https://docs.triton.one/solana/sending-transactions/priority-fees-api)     |
| To keep your transactions away from validators you don't trust, such as those running harmful MEV | **Shield**: attach an on-chain allowlist or blocklist policy to your send                       | [Shield Protection](https://docs.triton.one/solana/sending-transactions/shield-mev-protection) |

## Streaming

| I need…                                                                                      | Use                                                                                                                                                  | Page                                                                                                       |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Live account, transaction, slot, and block updates in a backend, at `processed` commitment   | **Dragon's Mouth gRPC** (Yellowstone gRPC)                                                                                                           | [Dragon's Mouth gRPC](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc)              |
| A lower-latency path for Dragon's Mouth on shared mainnet subscriptions                      | **Riptide** at `riptide.rpcpool.com`: same streams, protocol, and SDK support                                                                        | [Riptide](https://docs.triton.one/solana/real-time-streaming/riptide)                                      |
| Transactions before the node executes them                                                   | **Deshred Transactions gRPC**. It carries no execution results or confirmation                                                                       | [Deshred Transactions gRPC](https://docs.triton.one/solana/real-time-streaming/deshred-transactions)       |
| Raw shreds before a block is assembled, decoded by your own software                         | **Shred Streaming**, available on request                                                                                                            | [Shred Streaming](https://docs.triton.one/solana/real-time-streaming/shred-streaming)                      |
| Transactions the moment the block producer executes or commits them, before any shred exists | **Preconfirmations gRPC**, from the Harmonic and BAM block production systems, for slots led by validators running those clients. Enabled on request | [Preconfirmations gRPC](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc)          |
| Live updates in a browser, or through a Solana WebSocket client                              | **WebSocket**, including `transactionSubscribe`                                                                                                      | [WebSocket](https://docs.triton.one/solana/real-time-streaming/whirligig-websockets)                       |
| A pipeline that resumes where it left off after a disconnect                                 | **Fumarole Persistent gRPC**, with 4 days of rolling retention                                                                                       | [Fumarole Persistent gRPC](https://docs.triton.one/solana/real-time-streaming/fumarole-persistent-streams) |

## Account state

| I need…                                                                                                        | Use                                                                                                                                                                      | Page                                                                                                    |
| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| To read accounts with standard Solana JSON-RPC                                                                 | **`getAccountInfo`**, **`getMultipleAccounts`**, and the other standard account methods (except `getLargestAccounts`, which isn't served on Triton's mainnet endpoints)  | [Reading account state](https://docs.triton.one/solana/reading-account-state)                           |
| Every account a program owns, or token accounts by owner or delegate                                           | **Cloudbreak**, which serves `getProgramAccounts`, `getTokenAccountsByOwner`, and `getTokenAccountsByDelegate` from indexes, with nothing to enable                      | [Cloudbreak Accounts](https://docs.triton.one/solana/reading-account-state/cloudbreak-indexed-accounts) |
| Faster repeated account reads, such as polling `getAccountInfo`, in `@solana/web3.js` or Rust `RpcClient` code | **Yellowstone Account Sync**, used through the Triton SDKs. It serves supported account reads from an in-memory copy of the accounts it tracks, updated by a live stream | [Yellowstone Account Sync](https://docs.triton.one/solana/reading-account-state/account-sync)           |
| A live stream of account changes instead of polling                                                            | **Dragon's Mouth gRPC**                                                                                                                                                  | [Dragon's Mouth gRPC](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc)           |

## Ledger and historical data

| I need…                                                                                                                                                                                            | Use                                                                                                                                                                         | Page                                                                                                                                  |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Blocks and transactions from anywhere in the ledger, back to genesis, with standard methods                                                                                                        | On mainnet endpoints, standard JSON-RPC methods such as `getBlock`, `getTransaction`, and `getSignaturesForAddress`, served automatically from Triton's historical backends | [Historical data](https://docs.triton.one/solana/historical-data)                                                                     |
| An address's transaction history (signatures or full transactions) in one query instead of `getSignaturesForAddress` plus one `getTransaction` per result, with server-side filters and pagination | **`getTransactionsForAddress`**, Triton's extension method                                                                                                                  | [Historical data](https://docs.triton.one/solana/historical-data#gettransactionsforaddress)                                           |
| To backfill months or years of history                                                                                                                                                             | **Jetstreamer** with the public Old Faithful archive. It reads Old Faithful, not a Triton endpoint                                                                          | [Historical data best practices](https://docs.triton.one/solana/historical-data/best-practices#backfill-large-history-with-streaming) |
| To run the historical backend yourself                                                                                                                                                             | **Superbank**, open source under AGPL                                                                                                                                       | [Historical data](https://docs.triton.one/solana/historical-data#self-hosting)                                                        |

## Trading

| I need…                                                                                           | Use                                                                                                                                                                                                                                   | Page                                                                                                      |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Live swap quotes with routes you can execute, as swap instructions or a ready-to-sign transaction | **Titan Swap API** on the `/titan` path of your endpoint, enabled by default on Triton's Solana mainnet endpoints                                                                                                                     | [Titan Swap API](https://docs.triton.one/solana/sending-transactions/3rd-party-apis/titan-swap-api)       |
| To simulate a Jito bundle before you submit it                                                    | **`simulateBundle`** on Triton's Jito-enabled RPC                                                                                                                                                                                     | [Jito Bundle Simulation](https://docs.triton.one/solana/sending-transactions/3rd-party-apis/jito-bundles) |
| To submit a Jito bundle for inclusion                                                             | **`sendBundle`**, sent directly to the Jito Block Engine. Triton simulates bundles but doesn't forward them                                                                                                                           | [Jito Bundle Simulation](https://docs.triton.one/solana/sending-transactions/3rd-party-apis/jito-bundles) |
| Early market data for trading and MEV                                                             | **Dragon's Mouth gRPC** for `processed` data and **Deshred** for pre-execution transactions. For slots led by Harmonic or BAM validators, **Preconfirmations gRPC** (enabled on request) reports transactions before any shred exists | [Real-time streaming](https://docs.triton.one/solana/real-time-streaming)                                 |

## Digital assets

| I need…                                                               | Use                                                                          | Page                                                                                      |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Metadata and ownership for NFTs, compressed NFTs, and fungible tokens | **Metaplex DAS API**: `getAsset`, or `getAssets` for several IDs             | [Metaplex DAS API](https://docs.triton.one/solana/reading-account-state/metaplex-das-api) |
| Assets owned by a wallet, or created or controlled by an address      | **`getAssetsByOwner`**, **`getAssetsByCreator`**, **`getAssetsByAuthority`** | [Metaplex DAS API](https://docs.triton.one/solana/reading-account-state/metaplex-das-api) |
| A Merkle proof for a compressed asset                                 | **`getAssetProof`**                                                          | [Metaplex DAS API](https://docs.triton.one/solana/reading-account-state/metaplex-das-api) |
| The transaction signatures for a compressed asset                     | **`getSignaturesForAsset`**                                                  | [Metaplex DAS API](https://docs.triton.one/solana/reading-account-state/metaplex-das-api) |
| Token accounts by owner or by mint                                    | **`getTokenAccounts`**                                                       | [Metaplex DAS API](https://docs.triton.one/solana/reading-account-state/metaplex-das-api) |

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Reading account state

Choose how to read Solana account state: standard JSON-RPC, Cloudbreak for getProgramAccounts and token queries, Account Sync, or the Metaplex DAS API.

Solana keeps all of its state in accounts: a wallet, each token balance, a DEX market, an open order, and the program code itself. The standard way to read this state is Solana JSON-RPC polling, supported by every Triton endpoint.

However, Agave nodes make some of these reads slow or expensive as you scale:

* **Set queries like `getProgramAccounts` (gPA).** Fetching every account a program owns scans the program's entire account set and applies filters only after each account is loaded, so an unindexed scan gets slow and can time out on large programs.
* **Polling for fresh state.** Re-fetching the same accounts on a loop leaves your data stale between calls and burns requests (and rate limits) against the same endpoint.
* **NFT and compressed NFT.** Assembling an asset's owner, metadata, and (for compressed NFTs) its Merkle proof from raw accounts takes custom indexing, decompression, and many calls.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-server">:server:</i> <strong>Standard RPC</strong></td><td>The standard Solana JSON-RPC account methods are supported. Program and token account queries route through Cloudbreak; most other account reads are served by Triton's standard RPC nodes.</td><td><a href="https://docs.triton.one/solana/rpc-methods/readme">Account methods</a></td></tr><tr><td><i class="fa-database">:database:</i> <strong>Cloudbreak</strong></td><td>getProgramAccounts and SPL token account queries served from Cloudbreak indexes. Your requests are routed through Cloudbreak automatically, with nothing for you to set up.</td><td><a href="https://docs.triton.one/solana/reading-account-state/cloudbreak-indexed-accounts">Cloudbreak Accounts</a></td></tr><tr><td><i class="fa-arrows-rotate">:arrows-rotate:</i> <strong>Account Sync</strong></td><td>Account reads served from a local cache kept fresh by a live gRPC or WS stream, with the method names you already call.</td><td><a href="https://docs.triton.one/solana/reading-account-state/account-sync">Account Sync</a></td></tr><tr><td><i class="fa-image">:image:</i> <strong>DAS API</strong></td><td>One API to fetch ownership, metadata, and balances for NFTs, cNFTs, and tokens, via the Metaplex Digital Asset Standard, an extension of JSON-RPC.</td><td><a href="https://docs.triton.one/solana/reading-account-state/metaplex-das-api">Metaplex DAS API</a></td></tr></tbody></table>

## Read path for each method

Every account-read method is served by one of these. Standard RPC covers the methods the node answers directly; the rest route through a specialized service.

| Service                                                                             | Account-read methods                                                                                                                                                                                                                                                                                           |
| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Standard RPC** (Triton's standard RPC nodes)\*                                    | `getAccountInfo`, `getMultipleAccounts`, `getBalance`, `getTokenAccountBalance`, `getTokenLargestAccounts`, `getTokenSupply`, `getSupply`, `getVoteAccounts`, `getStakeMinimumDelegation`, `getMinimumBalanceForRentExemption`                                                                                 |
| **Cloudbreak** (your requests route through it by default, no changes on your side) | `getProgramAccounts` (including Token and Token-2022 program queries with `memcmp` filters), `getTokenAccountsByOwner`, `getTokenAccountsByDelegate`                                                                                                                                                           |
| **Account Sync** (served from RAM via SDK)                                          | `getAccountInfo`, `getMultipleAccountsInfo`, `getParsedAccountInfo`, `getMultipleParsedAccounts` (and `*AndContext` variants)                                                                                                                                                                                  |
| **DAS API** (Metaplex JSON-RPC extension)                                           | `getAsset`, `getAssets` (also `getAssetBatch`), `getAssetProof`, `getAssetProofs` (also `getAssetProofBatch`), `getAssetsByOwner`, `getAssetsByAuthority`, `getAssetsByCreator`, `getAssetsByGroup`, `searchAssets`, `getTokenAccounts`, `getNftEditions`, `getSignaturesForAsset` (also `getAssetSignatures`) |

\*`getTokenLargestAccounts` is served by the DAS index on most endpoints and, on shared infrastructure, billed as a standard RPC call.

{% hint style="info" %}
The single and multiple account reads (`getAccountInfo`, `getMultipleAccounts`) are served by Triton's standard RPC nodes by default, but you can also use Account Sync (the `@triton-one/triton-sdk` SDK) to resolve them from your local cache instead of a network call.
{% endhint %}

Depending on your use case, your build might combine multiple read paths:

| Use case                                                                                    | Read path                                                                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Reading many program accounts at scale** (DEX, lending, indexers)                         | Cloudbreak serves indexed `getProgramAccounts` and token queries, so repeated filter shapes avoid a full account scan.                                                                                                                                    |
| **Tracking a set of accounts live** (any frontend or backend with a large polling codebase) | Account Sync keeps your existing code, stores the accounts locally in RAM, backed by a stream, and serves your reads from there without an RPC request for each read.                                                                                     |
| **Wallets and NFT apps**                                                                    | DAS API fetches assets and metadata you need in one call, while Cloudbreak or Account Sync handle user balance lookups.                                                                                                                                   |
| **Low-latency trading and market making**                                                   | We recommend streaming account updates with gRPC ([Dragon's Mouth](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc)). If you want account reads in a web3.js-shaped client, Account Sync reduces read latency compared to polling. |

## Limitations

* **`getLargestAccounts`.** It is disabled on Triton's mainnet endpoints and returns HTTP `410` with `The RPC call or parameters have been disabled`.
* **`requestAirdrop`.** It is disabled on Triton's mainnet endpoints and returns HTTP `410`. See [requestAirdrop](https://docs.triton.one/solana/rpc-methods/utility-methods/requestairdrop) for devnet airdrops and the faucet.
* **`getTokenAccountsByMint`.** It is not available on shared endpoints and returns JSON-RPC error `-32601 Method not found`.
* **`getTokenLargestAccounts`.** It is served from the DAS index on most endpoints and returns the top 20 accounts. If you pass it a config, set `commitment` to `confirmed` or `finalized`; `processed` and an empty `{}` return an error.
* **Light Protocol (ZK Compression).** Accounts owned by the Account Compression program `compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq` are excluded from Yellowstone streams by default. On shared endpoints, `getProgramAccounts` for them is served by standard RPC nodes, without Cloudbreak's index.
* **Token program filters on shared endpoints.** `getProgramAccounts` calls for SPL Token and Token-2022 need a `memcmp` with the full 32-byte owner pubkey at offset `32` or the full mint pubkey at offset `0`. Calls without one are rejected with HTTP `403`.
* **System Program filter on shared endpoints.** `getProgramAccounts` calls for the System Program need a `memcmp` filter. Calls without one are rejected with HTTP `403`.
* **Commitment.** Cloudbreak ingests from a gRPC stream at `confirmed` commitment, so `processed` requests on the methods routed through Cloudbreak are answered at `confirmed` instead.
* **Batches.** `getProgramAccounts`, `getTokenAccountsByOwner` and `getTokenAccountsByDelegate` are split out of JSON-RPC batches and processed individually, as is any batch that mixes methods served by different backends.
* **Result order.** Results can come back in a different order from your requests, so match each result to its request by `id`.

## Pricing

Account Sync usage is billed under your plan. See [triton.one/pricing](https://triton.one/pricing).

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-play">:play:</i> <strong>Quickstart</strong></td><td>Query account state via JSON-RPC and set up Account Sync.</td><td><a href="https://docs.triton.one/solana/reading-account-state/quickstart">Reading account state quickstart</a></td></tr><tr><td><i class="fa-list-check">:list-check:</i> <strong>Best practices</strong></td><td>Reduce latency and cost on your account state reads.</td><td><a href="https://docs.triton.one/solana/reading-account-state/best-practices">Reading account state best practices</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Reading account state quickstart

Read a Solana account with getAccountInfo in TypeScript, Rust or curl, then through Yellowstone Account Sync with @triton-one/triton-sdk.

In this quickstart we'll show you how to poll account state in two ways:

1. **Standard Agave polling.** You call an RPC node and it answers over the network, one request per read. Works with any standard Solana SDK, like web3.js or `@solana/kit`.
2. **Account Sync (`@triton-one/triton-sdk`)** is a drop-in for web3.js 1.x. It keeps a local copy of the accounts you track in RAM and resolves reads for those accounts against it, with no network round-trip. It auto-subscribes to each new account your code polls: RPC or the stream, whichever answers first, completes the first read, and while the account stays tracked, later reads come from memory at lower latency, and at lower cost if you read the account more often than it changes.

## 0. Prerequisites

* An active Triton subscription
* Your endpoint URL and secret token (for backends) from the [customer dashboard](https://customers.triton.one/)
* An environment in TypeScript, Rust, or curl (the Account Sync steps use TypeScript)

## 1. Install

{% tabs %}
{% tab title="Standard RPC" %}
{% tabs %}
{% tab title="TypeScript" %}

```bash
mkdir solana-reads && cd solana-reads
npm init --yes && npm pkg set type=module
npm install @solana/web3.js
npm install --save-dev typescript tsx @types/node
npx tsc --init
```

{% endtab %}

{% tab title="Rust" %}

```bash
cargo new solana-reads && cd solana-reads
```

{% code title="Cargo.toml (replace \[dependencies])" %}

```toml
[dependencies]
solana-client = "2"
solana-pubkey = "2"
anyhow = "1"
```

{% endcode %}
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="Account Sync" %}

```bash
mkdir account-sync && cd account-sync
npm init --yes && npm pkg set type=module
npm install @triton-one/triton-sdk
npm install --save-dev typescript tsx @types/node
npx tsc --init
```

{% endtab %}
{% endtabs %}

## 2. Connect and read

**What we're doing:** read a single account, the USDC mint. TypeScript and curl decode it with `jsonParsed`; Rust returns the raw account.

{% tabs %}
{% tab title="Standard RPC" %}
{% tabs %}
{% tab title="TypeScript" %}
{% code title="main.ts" %}

```typescript
import { Connection, PublicKey } from "@solana/web3.js";

const connection = new Connection(
  "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>"
);

const usdcMint = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
const account = await connection.getParsedAccountInfo(usdcMint);

console.log(account.value);
```

{% endcode %}
{% endtab %}

{% tab title="curl" %}

```bash
curl https://<your-endpoint>.mainnet.rpcpool.com/<your-token> -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getAccountInfo",
    "params": [
      "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      { "encoding": "jsonParsed" }
    ]
  }'
```

{% endtab %}

{% tab title="Rust" %}
{% code title="src/main.rs" %}

```rust
use {solana_client::rpc_client::RpcClient, solana_pubkey::Pubkey, std::str::FromStr};

fn main() -> anyhow::Result<()> {
    let client = RpcClient::new(
        "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>".to_string(),
    );
    let usdc = Pubkey::from_str("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v")?;
    let account = client.get_account(&usdc)?;
    println!("{:?}", account);
    Ok(())
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

For every read method and its parameters, see [Account methods](https://docs.triton.one/solana/rpc-methods/readme).
{% endtab %}

{% tab title="Account Sync" %}
Swap `@solana/web3.js` for `@triton-one/triton-sdk`. Your polling code stays the same: the same `getParsedAccountInfo` call is answered from a local buffer fed by the stream once the account is tracked.

{% code title="main.ts" %}

```typescript
import { AccountSyncTransports, Connection, PublicKey } from "@triton-one/triton-sdk";

const usdcMint = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";

const connection = new Connection(
  "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>",
  {
    accountSync: {
      transport: AccountSyncTransports.GRPC, // Node backend; use AccountSyncTransports.WS in the browser
      initialAccounts: [usdcMint], // seed the accounts to stream and track
    },
  }
);

const account = await connection.getParsedAccountInfo(new PublicKey(usdcMint));
console.log(account.value);

await connection.close();
```

{% endcode %}

In Node backends, use `transport: AccountSyncTransports.GRPC`. Browsers must use `transport: AccountSyncTransports.WS`. If you omit `subscriptionEndpoint`, gRPC uses your RPC endpoint as is and WebSocket derives its URL from it. Set `subscriptionEndpoint` when your stream endpoint differs from your RPC endpoint; the [Account Sync quick start](https://docs.triton.one/solana/reading-account-state/account-sync#quick-start) shows both URLs.
{% endtab %}
{% endtabs %}

## 3. Verify it works

Run your code:

{% tabs %}
{% tab title="TypeScript" %}

```bash
npx tsx main.ts
```

{% endtab %}

{% tab title="Rust" %}

```bash
cargo run
```

{% endtab %}

{% tab title="curl" %}
The response prints straight to your terminal.
{% endtab %}
{% endtabs %}

Then check:

1. **You got a `result`, not an `error`.** A JSON-RPC error has an `error` object with a `code`. The common ones are in [Common Solana errors](https://docs.triton.one/solana/faq/error-handling/common-solana-errors).
2. **The account exists.** `getAccountInfo` returns `null` when the address holds no account. The USDC mint above always returns data.
3. **Account Sync only: the stream.** If the stream can't connect, reads fall back to RPC and still return a result. See [Background errors](https://docs.triton.one/solana/reading-account-state/account-sync/typescript-sdk-reference#background-errors) for how to read stream errors.

### Expected response

In `result.value` you'll see the USDC mint object, decoded with `jsonParsed`. The block below is `result.value` from curl. In TypeScript, `owner` is a `PublicKey`. In the Standard RPC tab (`@solana/web3.js` 3.x), `lamports`, `space` and `rentEpoch` print as bigint, for example `82n`, and `console.log` shows nested objects such as `info` as `[Object]`. Rust prints the raw account instead: `lamports`, `data.len`, `owner`, `executable`, `rent_epoch`, and the first 64 bytes of `data` as hex. Live values like `supply` and `lamports` will differ when you run it.

```json
{
  "data": {
    "parsed": {
      "info": {
        "decimals": 6,
        "freezeAuthority": "7dGbd2QZcCKcTndnHcTL8q7SMVXAkp688NTQYwrRCrar",
        "isInitialized": true,
        "mintAuthority": "BJE5MMbqXjVwjAF7oxwPYXnTXDyspzZyt4vwenNw5ruG",
        "supply": "7957814436632629"
      },
      "type": "mint"
    },
    "program": "spl-token",
    "space": 82
  },
  "executable": false,
  "lamports": 511210011619,
  "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
  "rentEpoch": 18446744073709551615,
  "space": 82
}
```

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-arrows-rotate">:arrows-rotate:</i> <strong>Account Sync</strong></td><td>Streaming-backed local cache for faster and cheaper account reads, via the web3.js-compatible SDK.</td><td><a href="https://docs.triton.one/solana/reading-account-state/account-sync">Account Sync</a></td></tr><tr><td><i class="fa-database">:database:</i> <strong>Cloudbreak Accounts</strong></td><td>getProgramAccounts and SPL token account queries served from indexes built automatically from real query traffic.</td><td><a href="https://docs.triton.one/solana/reading-account-state/cloudbreak-indexed-accounts">Cloudbreak Accounts</a></td></tr><tr><td><i class="fa-image">:image:</i> <strong>Metaplex DAS API</strong></td><td>Query NFTs, tokens, and compressed assets via the Digital Asset Standard interface.</td><td><a href="https://docs.triton.one/solana/reading-account-state/metaplex-das-api">Metaplex DAS API</a></td></tr><tr><td><i class="fa-compass">:compass:</i> <strong>Streaming overview</strong></td><td>Compare every Triton streaming service and choose the right fit for your workload.</td><td><a href="https://docs.triton.one/solana/real-time-streaming">Real-time streaming</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Yellowstone Account Sync

Yellowstone Account Sync streams Solana account updates into your process, so reads of tracked accounts in the Triton SDKs resolve from memory, not RPC.

Yellowstone Account Sync (Account Sync for short) adds buffered account reads to the Triton SDKs, which keep the method names you already call:

* **TypeScript / JavaScript:** `@triton-one/triton-sdk`, a `@solana/web3.js` 1.x `Connection` with Account Sync-backed account reads.
* **Rust:** the `triton-sdk` crate, a wrapper around the asynchronous Solana `RpcClient` from `solana-client`.

## Read latency

| Method                | Median latency | p90 latency |
| --------------------- | :------------: | :---------: |
| `@solana/web3.js` RPC |    12.01 ms    |   14.94 ms  |
| Account Sync          |     1.65 ms    |   1.98 ms   |
| **Reduction**         |    **86.3%**   |  **86.8%**  |

Measured with Triton's [JavaScript `getMultipleAccountsInfo` benchmark](https://github.com/rpcpool/triton-js-sdk/blob/main/examples/account-sync/src/compare_get_multiple_accounts_info_latency.ts). It and the [Rust timing example](https://github.com/rpcpool/triton-rust-sdk/blob/main/triton-sdk/examples/compare_multiple_accounts_latency.rs) measure how long a read takes, not stream delivery latency, and a successful read alone doesn't prove the result came from the stream. Measure with your own accounts and network.

## When to use it

Account Sync trades continuous stream bandwidth for lower-latency repeated reads. It pays off when you read the same accounts more often than they change.

**A good fit** if your application:

* reads the same accounts repeatedly, for example by polling `getAccountInfo` or `getMultipleAccountsInfo`;
* needs the latest account state with low read latency; or
* makes enough account reads that request volume or RPC cost matters.

**Use something else** when:

* you read accounts only occasionally, or only after a user action: use standard JSON-RPC. The stream delivers every update to every tracked account whether or not you read it, so for occasional reads its cost can outweigh the savings;
* you need to react to every account change or need intermediate history: Account Sync keeps only the newest value per account. Use [Dragon's Mouth gRPC](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc), or [Fumarole](https://docs.triton.one/solana/real-time-streaming/fumarole-persistent-streams) if you can't miss updates;
* you need minimum latency per update, such as for liquidations or market making: stream directly with [Dragon's Mouth gRPC](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc). Account Sync adds a fan-out hop and a local buffer; or
* you need RPC methods other than account reads: every other method still goes to JSON-RPC.

## SDKs and transports

| SDK and environment                  | WebSocket     | gRPC |
| ------------------------------------ | ------------- | ---- |
| TypeScript / JavaScript in Node.js   | Yes (default) | Yes  |
| TypeScript / JavaScript in a browser | Yes           | No   |
| Rust with Tokio                      | No            | Yes  |

## How a read works

1. **The account is in the buffer.** The SDK returns the value from memory. No RPC request is made. The buffer holds the newest observed value for every tracked account.
2. **The account is not in the buffer.** The SDK sends a one-time RPC request for it and, by default, adds a temporary stream subscription so later reads hit the buffer. Whichever answers first, the stream or RPC, completes the read.
3. **RPC reports the account doesn't exist.** The read reports it as missing:
   * TypeScript returns `null`.
   * Rust `get_account_with_commitment` and `get_multiple_accounts*` return `None`.
   * Rust `get_account` and `get_account_data` return an `AccountNotFound` error.
   * A single-account context read carries the slot at which RPC observed the absence. A multiple-account context read carries the lowest slot among its results.
   * A timeout, a network failure or an RPC error is never returned as missing: it rejects or returns an error.
4. **Startup and set changes.** When accounts are tracked, the SDK loads their current values over RPC so it doesn't have to wait for the next change. Stream updates that arrive meanwhile are reconciled by slot and write order, and the newest value wins.
5. **The stream disconnects.** The SDK reconnects with exponential backoff and then reloads the tracked accounts. Meanwhile the TypeScript SDK polls every tracked account over RPC (once a second by default), so reads stay fresh. In 0.1.0 the Rust SDK doesn't poll: a value it fetches through RPC during the outage is served from the buffer, unrefreshed, until the stream is back (see the [Rust SDK reference](https://docs.triton.one/solana/reading-account-state/account-sync/rust-sdk-reference#stream-lifecycle)).

A buffered value's context slot is the slot of that account's last update, which can be well behind the cluster if the account hasn't changed. Don't use it as a measure of cluster progress.

Each commitment level (`processed`, `confirmed`, `finalized`) has its own stream and buffer.

## Quick start

Account Sync works with your existing Triton endpoint. Nothing new is needed: use the same endpoint URL, ending in `/<your-token>`, for both the JSON-RPC URL and the Account Sync stream URL. The Rust SDK requires the stream URL. The TypeScript SDK uses the RPC URL for the stream when you omit `subscriptionEndpoint`.

```bash
export RPC_URL='https://<your-endpoint>.mainnet.rpcpool.com/<your-token>'
export ACCOUNT_SYNC_URL='https://<your-endpoint>.mainnet.rpcpool.com/<your-token>'
```

{% hint style="warning" %}
Keep these URLs on your backend. They contain your token. Browser apps use the WebSocket transport; see the [TypeScript SDK reference](https://docs.triton.one/solana/reading-account-state/account-sync/typescript-sdk-reference#browser-apps).
{% endhint %}

{% tabs %}
{% tab title="TypeScript" %}
Install the SDK. It needs Node.js 18 or newer (for global `fetch`) and is an ES module. The example uses top-level `await`, so save it as `.mts` (or set `"type": "module"` in `package.json`) and run it with `tsx` or another ESM-aware runner.

```bash
npm install @triton-one/triton-sdk
# or: pnpm add @triton-one/triton-sdk
# or: yarn add @triton-one/triton-sdk
```

Save as `quickstart.mts` and run `npx tsx quickstart.mts`:

```ts
import {
  AccountSyncTransports,
  Connection,
  PublicKey,
} from "@triton-one/triton-sdk";

const endpoint = process.env.RPC_URL;
const subscriptionEndpoint = process.env.ACCOUNT_SYNC_URL;

if (!endpoint || !subscriptionEndpoint) {
  throw new Error("Set RPC_URL and ACCOUNT_SYNC_URL");
}

const address = new PublicKey("So11111111111111111111111111111111111111112");

const connection = new Connection(endpoint, {
  accountSync: {
    transport: AccountSyncTransports.GRPC,
    subscriptionEndpoint,
    commitment: "confirmed",
    initialAccounts: [address],
  },
});

try {
  const response = await connection.getAccountInfoAndContext(address);
  console.log("Observed at slot:", response.context.slot);
  console.log("Account:", response.value);
} finally {
  await connection.close();
}
```

Set `transport` with the `AccountSyncTransports` enum. The string literals `"grpc"` and `"ws"` don't type-check in TypeScript.
{% endtab %}

{% tab title="Rust" %}
Add the SDK and Tokio. The crate requires Rust 1.97.1 or newer, the minimum Rust version of its `solana-client` 4.3.0 dependency.

```bash
cargo add triton-sdk
cargo add tokio --features rt,macros
```

Save as `src/main.rs` and run `cargo run`:

```rust
use std::{env, error::Error};

use triton_sdk::{AccountSyncConfig, CommitmentConfig, Pubkey, RpcClient};

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), Box<dyn Error>> {
    let address: Pubkey = "So11111111111111111111111111111111111111112".parse()?;

    let client =
        RpcClient::new_with_commitment(env::var("RPC_URL")?, CommitmentConfig::confirmed())
            .with_account_sync(AccountSyncConfig {
                endpoint: env::var("ACCOUNT_SYNC_URL")?,
                pinned_accounts: [address].into(),
                ..Default::default()
            })?;

    let result = client
        .get_account_with_commitment(&address, client.commitment())
        .await;
    let closed = client.close().await;
    let response = result?;
    closed?;

    println!("Observed at slot: {}", response.context.slot);
    println!("Account: {:?}", response.value);
    Ok(())
}
```

`with_account_sync` turns a plain client into one with buffered reads. Account Sync starts on the first supported read, not at construction.
{% endtab %}
{% endtabs %}

Always close the connection or client when you're done. It owns streams, timers and retries.

Runnable examples: [TypeScript](https://github.com/rpcpool/triton-js-sdk/tree/main/examples/account-sync) and [Rust](https://github.com/rpcpool/triton-rust-sdk/tree/main/triton-sdk/examples).

## Pricing

Account Sync usage is billed under your plan. See [Plans and billing](https://docs.triton.one/account-and-billing/plans-and-billing) for how billing works and the [pricing page](https://triton.one/pricing) for current rates.

Your usage has two parts:

* **Stream traffic**, billed as bandwidth. Every update to every tracked account streams to your application, whether or not you read it. Its volume is roughly the size of each tracked account multiplied by how often it changes. Reads served from the buffer send no RPC request.
* **RPC requests the SDK makes for you:** loading initial values, cache misses, reloading tracked accounts after the tracked set changes or the stream reconnects, polling during stream outages (TypeScript), reads that need a newer slot than the buffer has, and mint lookups for parsed token accounts.

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-js">:js:</i> <strong>TypeScript SDK reference</strong></td><td>Configuration, read semantics, tracked accounts, errors, production guidance and the full API for <code>@triton-one/triton-sdk</code>.</td><td><a href="https://docs.triton.one/solana/reading-account-state/account-sync/typescript-sdk-reference">TypeScript SDK reference</a></td></tr><tr><td><i class="fa-rust">:rust:</i> <strong>Rust SDK reference</strong></td><td>Configuration, read semantics, pinned and temporary accounts, errors and the full API for the <code>triton-sdk</code> crate.</td><td><a href="https://docs.triton.one/solana/reading-account-state/account-sync/rust-sdk-reference">Rust SDK reference</a></td></tr><tr><td><i class="fa-tower-broadcast">:tower-broadcast:</i> <strong>Dragon's Mouth gRPC</strong></td><td>Sub-slot real-time updates for accounts, transactions, slots, and blocks via gRPC.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc">Dragon's Mouth gRPC</a></td></tr><tr><td><i class="fa-rotate-right">:rotate-right:</i> <strong>WebSocket</strong></td><td>Triton's Solana WebSocket API for browsers and frontends, served from Dragon's Mouth gRPC, with <code>transactionSubscribe</code>.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/whirligig-websockets">WebSocket</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Account Sync TypeScript SDK reference

Reference for Account Sync in @triton-one/triton-sdk: connection modes, configuration, read semantics, tracked accounts, errors and the full API.

`@triton-one/triton-sdk` adds [Yellowstone Account Sync](https://docs.triton.one/solana/reading-account-state/account-sync) to the `@solana/web3.js` `Connection`. Six account-read methods resolve from an in-memory buffer fed by a stream; every other method uses JSON-RPC as usual. For what Account Sync is and a first program, see the [overview](https://docs.triton.one/solana/reading-account-state/account-sync).

{% tabs %}
{% tab title="npm" %}

```bash
npm install @triton-one/triton-sdk
```

{% endtab %}

{% tab title="pnpm" %}

```bash
pnpm add @triton-one/triton-sdk
```

{% endtab %}

{% tab title="Yarn" %}

```bash
yarn add @triton-one/triton-sdk
```

{% endtab %}
{% endtabs %}

The package is an ES module. It needs a runtime with global `fetch` or a browser build tool. It is built on `@solana/web3.js` 1.x (`^1.98.4`, installed as its dependency) and re-exports all of it, so use its `PublicKey` and other web3.js classes rather than ones from a separately installed web3.js 3.x.

## Connection modes

`new Connection(endpoint, config)` returns one of two classes:

| Second argument                                                        | Returns                                     |
| ---------------------------------------------------------------------- | ------------------------------------------- |
| Nothing, a commitment string, or web3.js options without `accountSync` | A plain web3.js `Connection` with no buffer |
| An object with `accountSync: undefined`                                | A plain web3.js `Connection`                |
| An object whose `accountSync` is set, including `accountSync: {}`      | An `AccountSyncConnection`                  |

{% hint style="warning" %}
`new Connection(endpoint, "finalized")` does **not** enable Account Sync. To set a commitment and enable it, write `new Connection(endpoint, { commitment: "finalized", accountSync: {} })`.
{% endhint %}

`AccountSyncConnection` has `addAccounts`, `removeAccounts`, `setAccounts`, `close` and `getLastTransportError`; a plain `Connection` doesn't. The exported `Connection` **type** is the web3.js type, so annotate variables with `AccountSyncConnection`, or let TypeScript infer the type from the constructor:

```ts
import { AccountSyncConnection, Connection } from "@triton-one/triton-sdk";

const connection: AccountSyncConnection = new Connection(endpoint, {
  accountSync: {},
});
```

In plain mode, web3.js options such as `fetch`, `fetchMiddleware`, `httpHeaders` and `wsEndpoint` go straight to web3.js. In Account Sync mode, inherited web3.js methods still use them, but the SDK's own RPC requests don't.

## Endpoints and tokens

* `endpoint` (the first constructor argument) is your Solana JSON-RPC URL. Inherited web3.js methods use it, and so does the SDK for initial values, cache misses and outage polling. The SDK's own requests send no custom headers, so put your token in the URL path: `https://<your-endpoint>.mainnet.rpcpool.com/<your-token>`.
* `endpoint` must start with `http:` or `https:`, or the constructor throws.
* `accountSync.subscriptionEndpoint` is the Account Sync stream URL. When you omit it, gRPC uses `endpoint` as is, and WebSocket uses `endpoint` with `http` changed to `ws` and `https` to `wss`.
* **gRPC:** the stream URL path must be empty or exactly `/<token>`. The SDK strips the token from the URL and sends it as `x-token` metadata.
* **gRPC:** a longer path in the stream URL, or a scheme other than `http`/`https` in `subscriptionEndpoint`, makes the stream fail to connect. The constructor doesn't throw: the error appears in `getLastTransportError()` while reads fall back to RPC.
* **WebSocket:** the SDK rewrites the path to `/<token>/YellowstoneAccountSyncService/ws`, taking the token from the last path segment.
* **WebSocket:** `subscriptionEndpoint` can start with `ws:` or `wss:`.

Both URLs must point at the same cluster. If RPC and the stream use different hosts, set `subscriptionEndpoint`:

```ts
import { AccountSyncTransports, Connection } from "@triton-one/triton-sdk";

const connection = new Connection("https://rpc.example.com/<RPC_TOKEN>", {
  accountSync: {
    transport: AccountSyncTransports.GRPC,
    subscriptionEndpoint: "https://stream.example.com/<STREAM_TOKEN>",
  },
});
```

## Configuration

All Account Sync options go under `accountSync`:

| Option                     | Type                                                       | Default                             | Meaning                                                                              |
| -------------------------- | ---------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------ |
| `transport`                | `AccountSyncTransports.WS` or `AccountSyncTransports.GRPC` | `WS`                                | Stream transport. Browsers use `WS`; `GRPC` isn't available.                         |
| `subscriptionEndpoint`     | `string`                                                   | Derived from `endpoint`             | Stream URL. JSON-RPC always uses `endpoint`.                                         |
| `commitment`               | `"processed"`, `"confirmed"` or `"finalized"`              | See below                           | Default commitment for reads and account-set methods.                                |
| `initialAccounts`          | Array of `string` or `PublicKey`                           | `[]`                                | Accounts pinned from startup.                                                        |
| `autoSubscribeOnMiss`      | `boolean`                                                  | `true`                              | Temporarily subscribe to an untracked account when a default-commitment read misses. |
| `missTimeoutMs`            | positive safe integer                                      | `5000`                              | Deadline for a read that misses the buffer.                                          |
| `rpcPollIntervalMs`        | positive safe integer                                      | `1000`                              | Interval between RPC polls of tracked accounts while the stream is down.             |
| `reconnectInitialDelayMs`  | positive safe integer                                      | `100`                               | First reconnect delay. Doubles after each failed attempt.                            |
| `reconnectMaxDelayMs`      | positive safe integer                                      | `5000`                              | Largest reconnect delay. Must be at least `reconnectInitialDelayMs`.                 |
| `connectTimeoutMs`         | positive safe integer                                      | `10000`                             | Limit for one WebSocket connection attempt. Not used by gRPC.                        |
| `closeTimeoutMs`           | positive safe integer                                      | `5000`                              | Limit for `close()`.                                                                 |
| `dynamicSubscriptionTtlMs` | positive safe integer                                      | `60000`                             | Idle lifetime of a temporary subscription.                                           |
| `grpc`                     | object                                                     | See [gRPC settings](#grpc-settings) | gRPC transport tuning. Requires `AccountSyncTransports.GRPC`.                        |

Times are milliseconds. A safe integer is a whole number that JavaScript can represent exactly (up to `Number.MAX_SAFE_INTEGER`). Zero, negative, fractional, `NaN` and out-of-range values throw in the constructor, as do invalid `initialAccounts` addresses.

`transport` is a TypeScript string enum. Pass `AccountSyncTransports.GRPC` or `AccountSyncTransports.WS`: the literals `"grpc"` and `"ws"` fail to type-check.

**Default commitment.** The SDK uses `accountSync.commitment` if set. Otherwise it uses the top-level `commitment` if that is `processed`, `confirmed` or `finalized`, and otherwise `confirmed`. Any other top-level value (such as `"max"`) silently becomes `confirmed`, while the same value passed to a read throws.

### gRPC settings

Set these under `accountSync.grpc`, with `transport: AccountSyncTransports.GRPC`:

| Option                         | Default             | Meaning                                              |
| ------------------------------ | ------------------- | ---------------------------------------------------- |
| `flowControlWindowBytes`       | `16777216` (16 MiB) | Fixed HTTP/2 receive window used by `@grpc/grpc-js`. |
| `maxReceiveMessageLengthBytes` | `16777216` (16 MiB) | Largest gRPC message the client accepts.             |
| `keepAliveIntervalMs`          | `30000`             | Time between keepalive pings.                        |
| `keepAliveTimeoutMs`           | `10000`             | Time allowed for a keepalive response.               |
| `keepAlivePermitWithoutCalls`  | `true`              | Send keepalive pings while no call is active.        |

Numbers must be positive safe integers. The Node.js constructor throws if you pass `grpc` with the WebSocket transport. The JavaScript gRPC transport doesn't support Zstd stream compression.

## Reading accounts

These six methods keep their web3.js signatures and result shapes: `getAccountInfo`, `getAccountInfoAndContext`, `getMultipleAccountsInfo`, `getMultipleAccountsInfoAndContext`, `getParsedAccountInfo` and `getMultipleParsedAccounts`.

### How a read resolves

1. If the buffer holds a suitable value, the read returns it with no RPC request.
2. Otherwise the SDK sends one `getMultipleAccounts` request containing every unresolved account in the call and, by default, starts a temporary subscription. It also waits for the stream. The first source to answer wins, including an RPC error.
3. If neither answers within `missTimeoutMs`, context and multiple-account methods reject with `AccountSyncReadTimeoutError`.

`null` means RPC confirmed the account doesn't exist, at the slot in `context.slot`. It never means a timeout or a failure. A missing account doesn't block the read until it appears.

### Context slot

A value from RPC carries the RPC response's context slot. A value from the stream carries the slot of that account's last update, which can lag the cluster when the account hasn't changed. For multiple-account reads, `context.slot` is the lowest slot among all results, including missing accounts. It doesn't mean the accounts came from one bank snapshot.

### Several accounts

Results stay in input order. Duplicate addresses get duplicate positions, and a missing account is `null` in its position.

```ts
const response = await connection.getMultipleAccountsInfoAndContext([
  addressA,
  addressB,
  addressA,
]);

console.log("Lowest slot:", response.context.slot);
console.log("Accounts:", response.value);
```

{% hint style="warning" %}
**Known limitation (verified on 0.1.0, 0.1.1 and 0.1.2):** the SDK fetches all of a call's unbuffered accounts in a single RPC request, and RPC nodes accept at most 100 accounts per `getMultipleAccounts` request. A call that needs more than 100 accounts from RPC can be rejected. Keep each multiple-account read to 100 addresses or fewer.
{% endhint %}

### `dataSlice`

```ts
const account = await connection.getAccountInfo(address, {
  dataSlice: { offset: 8, length: 32 },
});
```

This returns at most 32 bytes starting at byte 8. Both numbers must be non-negative safe integers. A zero length or an offset past the end returns an empty `Buffer`. The slice is applied locally: the stream still delivers, and the buffer still holds, the full account. Parsed methods ignore `dataSlice`.

### `minContextSlot`

```ts
const recentSlot = await connection.getSlot("finalized");

const response = await connection.getAccountInfoAndContext(address, {
  minContextSlot: recentSlot,
});
```

`minContextSlot` must be a non-negative safe integer. A buffered value older than it doesn't count, so the read goes to RPC, which receives the same `minContextSlot`. A node that hasn't reached that slot typically returns error `-32016`, which rejects the read immediately. Because an unchanged account keeps its last update slot, reads with a recent `minContextSlot` often go to RPC.

### Parsed accounts

`getParsedAccountInfo` and `getMultipleParsedAccounts` return `AccountInfo<Buffer | ParsedAccountData>`: `ParsedAccountData` when the parser can parse the account, and from version 0.1.1 the raw `Buffer` when it can't, for example an unsupported owner program or a System-owned account that isn't a nonce account. Check for `parsed` before you use it:

```ts
const response = await connection.getParsedAccountInfo(address);

if (response.value && "parsed" in response.value.data) {
  console.log("Parsed:", response.value.data.parsed);
}
```

* Parsing happens locally, on the full buffered account.
* If the parser doesn't support the account's owner program, behavior depends on the version. In 0.1.0 the read **rejects** with `WasmParserError` (for `getMultipleParsedAccounts`, one failure rejects the whole call). From 0.1.1, `getParsedAccountInfo` and `getMultipleParsedAccounts` return the raw data as a `Buffer` instead. Missing accounts are `null` in every version.
* Parsing an SPL token account needs its mint. The connection loads the mint through its own `getAccountInfo`. It caches the mint of an SPL Token account (256 entries, 5 minutes). Concurrent parses of an SPL Token account that need the same uncached mint share one fetch. From version 0.1.1 it doesn't cache Token-2022 mints. From version 0.1.1, if the mint request fails, the read rejects with the error from that call: an `Error` whose message starts `failed to get info about account <mint>`.
* From version 0.1.1, parsing a Token-2022 account also loads the Clock sysvar (`SysvarC1ock11111111111111111111111111111111`) through the same `getAccountInfo` and passes its Unix timestamp to the parser as `unixTimestamp`. If the Clock account is missing, the read rejects with `InvalidAccountDataError`.

### The `space` field

From version 0.1.1, reads return `space`: the full size of the buffered account, even when you use `dataSlice`. In version 0.1.0, `space` is not returned; use `data.length`, which is the size of the data you received (smaller than the account when you use `dataSlice`).

## Tracked accounts

A tracked account is one the stream sends updates for. Each is either pinned or temporary.

**Pinned** accounts stay tracked until you remove them or close the connection. Set them with `initialAccounts` or `addAccounts`. Adding an account that has a temporary subscription makes it pinned.

**Temporary** subscriptions are created when a read misses the buffer at the default commitment and `autoSubscribeOnMiss` is `true`, and always for reads at another commitment. One expires `dynamicSubscriptionTtlMs` (60 s) after the last read of that account finishes. Each read renews it.

**With `autoSubscribeOnMiss: false`,** a default-commitment read of an untracked account makes a one-time RPC request and returns the real account (or `null` if it doesn't exist). Nothing is subscribed and the value isn't kept.

**`removeAccounts`** drops the pin or temporary subscription, deletes the buffered value immediately and clears any cached mint for that address. A read already in progress can still finish through RPC, and a later read can create a new temporary subscription. Removing an untracked address isn't an error.

**`setAccounts`** makes its list the complete pinned set, removes every temporary subscription and deletes the buffered values of accounts that leave the set.

All three methods take an optional commitment, defaulting to the connection's Account Sync commitment, and settle once the change is recorded:

```ts
await connection.addAccounts([addressC, addressD]);
await connection.removeAccounts([addressA]);
await connection.setAccounts([addressB, addressC], "finalized");
```

Addresses can be strings or `PublicKey` values. Duplicates are ignored, and an invalid address throws before anything changes. The SDK sets no limit on the number of tracked accounts.

## Commitment levels

The SDK supports `processed`, `confirmed` and `finalized`. Each has its own stream, buffer and tracked set. The default commitment's stream opens when you construct the connection. A read or `addAccounts` at another commitment opens that commitment's stream, which closes again once it has no pinned or temporary accounts and no reads in progress. Override the commitment for one read with a string, as in `getAccountInfo(address, "processed")`, or with `{ commitment }`. Any other commitment name throws.

## Stream outages

When the stream drops, the SDK records the error, polls every tracked account over RPC every `rpcPollIntervalMs`, and reconnects with backoff from `reconnectInitialDelayMs` up to `reconnectMaxDelayMs`. After reconnecting, it resends the full tracked set, reloads the accounts over RPC and then stops polling. Reads keep working throughout.

## Errors and recovery

| Outcome                                                            | Meaning                                                                                                                                                    |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `null` value                                                       | RPC confirmed the account doesn't exist.                                                                                                                   |
| `AccountSyncReadTimeoutError`                                      | Neither the buffer nor RPC answered within `missTimeoutMs`.                                                                                                |
| `SolanaJSONRPCError`                                               | The RPC node returned an error, such as `-32016` for an unreached `minContextSlot`.                                                                        |
| `Error` with an HTTP status                                        | The RPC request failed at the HTTP level.                                                                                                                  |
| `WasmParserError`                                                  | The parser failed. In 0.1.0 this includes an unsupported program.                                                                                          |
| `Error` with a message starting `failed to get info about account` | `getAccountInfo` wraps any failure in this message, including a timeout or an RPC error. From 0.1.1 it also covers a failed mint request in a parsed read. |
| `Error`                                                            | Invalid input (address, commitment, `dataSlice`, `minContextSlot`), or the connection is closed.                                                           |

### Read timeouts

```ts
import { AccountSyncReadTimeoutError } from "@triton-one/triton-sdk";

try {
  const response = await connection.getAccountInfoAndContext(address);
  console.log(response.value);
} catch (error) {
  if (error instanceof AccountSyncReadTimeoutError) {
    console.error(error.accountId, error.commitment, error.timeoutMs);
    console.error("Minimum slot:", error.minContextSlot ?? "not set");
  } else {
    throw error;
  }
}
```

### RPC errors

```ts
import { SolanaJSONRPCError } from "@triton-one/triton-sdk";

try {
  await connection.getAccountInfoAndContext(address, {
    minContextSlot: requiredSlot,
  });
} catch (error) {
  if (error instanceof SolanaJSONRPCError && error.code === -32016) {
    console.error("The RPC node hasn't reached the requested slot yet");
  } else {
    throw error;
  }
}
```

`getAccountInfo` follows web3.js and wraps every failure in a new `Error` whose message names the account, so `instanceof` checks don't match. Use the context or multiple-account methods when you need the typed error.

### Background errors

```ts
const error = connection.getLastTransportError();

if (error) {
  console.warn("Account Sync background error:", error.message);
}
```

This returns the latest error from stream, polling, initial-value or reconnect work. It's never cleared, so a non-null value doesn't mean the connection is broken now. Use it for logs, not as a health check.

### Connect and close timeouts

A WebSocket attempt longer than `connectTimeoutMs` fails with an error named `AccountSyncConnectTimeoutError`. If shutdown takes longer than `closeTimeoutMs`, `close()` rejects with an error named `AccountSyncCloseTimeoutError`, and the connection is closed anyway. After `close()`, reads and most account-set calls reject with `account-sync connection is closed`. Calling `close()` again returns the same result.

{% hint style="warning" %}
**Known limitation (verified on 0.1.0, 0.1.1 and 0.1.2, Node.js):** calling `close()` while a WebSocket stream is still connecting can crash the process with an unhandled `WebSocket was closed before the connection was established` error. In Node.js, use the gRPC transport.
{% endhint %}

## Browser apps

Browser build tools pick the package's browser entry automatically. It uses the WebSocket transport and doesn't load gRPC code. Passing `AccountSyncTransports.GRPC` or `grpc` options throws in the constructor.

{% hint style="danger" %}
Anything you ship to a browser is public. Don't put a secret token in browser code. See [Auth and security](https://docs.triton.one/security/authentication#allowed-origins-frontend) for browser access.
{% endhint %}

```ts
import {
  AccountSyncTransports,
  Connection,
  PublicKey,
} from "@triton-one/triton-sdk";

const address = new PublicKey("So11111111111111111111111111111111111111112");

const connection = new Connection("https://<your-browser-endpoint>", {
  accountSync: {
    transport: AccountSyncTransports.WS,
    initialAccounts: [address],
  },
});

async function showBalance(): Promise<void> {
  const response = await connection.getAccountInfoAndContext(address);
  const output = document.querySelector("#balance");
  if (output) {
    output.textContent = response.value
      ? `${response.value.lamports} lamports at slot ${response.context.slot}`
      : `Account missing at slot ${response.context.slot}`;
  }
}

void showBalance().catch(console.error);

window.addEventListener("pagehide", () => {
  void connection.close();
});
```

## Complete lifecycle example

`autoSubscribeOnMiss: false` keeps the tracked accounts to the explicit calls.

{% code title="lifecycle.mts" %}

```typescript
import {
  AccountSyncTransports,
  Connection,
  PublicKey,
} from "@triton-one/triton-sdk";

const endpoint = process.env.RPC_URL;
const subscriptionEndpoint = process.env.ACCOUNT_SYNC_URL;

if (!endpoint || !subscriptionEndpoint) {
  throw new Error("Set RPC_URL and ACCOUNT_SYNC_URL");
}

const address = new PublicKey("So11111111111111111111111111111111111111112");
const newAddress = new PublicKey("SysvarC1ock11111111111111111111111111111111");

const connection = new Connection(endpoint, {
  accountSync: {
    transport: AccountSyncTransports.GRPC,
    subscriptionEndpoint,
    commitment: "confirmed",
    autoSubscribeOnMiss: false,
  },
});

try {
  await connection.addAccounts([address]);

  const first = await connection.getAccountInfoAndContext(address);
  console.log("First read:", first);

  await connection.removeAccounts([address]);

  // Re-add it before the next read so it remains pinned.
  await connection.addAccounts([address]);

  const second = await connection.getAccountInfoAndContext(address);
  console.log("Read after re-add:", second);

  await connection.setAccounts([newAddress]);

  const third = await connection.getAccountInfoAndContext(newAddress);
  console.log("New account:", third);
} finally {
  await connection.close();
}
```

{% endcode %}

## Production guidance

* **Reuse one connection and close it on shutdown.** It owns streams, timers and retries, and an open connection keeps a Node.js process alive.
* **Size your RPC usage, not just the stream.** The SDK calls RPC for initial values, misses, reloads after set changes and reconnects, outage polling and mint lookups. These count against your [rate limits](https://docs.triton.one/using-your-endpoint/rate-and-connection-limits) and are billed under your [plan](https://docs.triton.one/account-and-billing/plans-and-billing).
* **Keep the tracked set stable.** Every change to a commitment's tracked set, including a temporary subscription starting or expiring, reloads all of that commitment's tracked accounts over RPC, in batches of 100. For large sets, pin the accounts you need and consider `autoSubscribeOnMiss: false`.
* **Watch memory and bandwidth.** The full data of every tracked account sits in process memory, and every update streams in full. Start with the default 16 MiB gRPC window, and test with realistic account sizes and update rates before you raise it or the message limit.
* **Keep up with the stream.** Triton closes a session whose server-side queue fills because the client can't consume updates fast enough. The SDK reconnects and polls in the meantime. Avoid short-lived function workers for a continuous stream.
* **Monitor read outcomes.** Track read errors, timeouts and latency. A successful read can come from RPC, so it doesn't prove the stream is healthy.

## Troubleshooting

### Why is my result `null`?

RPC confirmed the account didn't exist at the returned slot at that commitment. Check the address and commitment.

### Why did my read time out?

Neither the stream nor RPC answered within `missTimeoutMs`. Check both URLs, the token, RPC health and any `minContextSlot`. Raise the timeout if the read needs longer.

### Why was my minimum slot not reached?

The RPC node can return `-32016`, which rejects the read immediately. Use a slot the cluster has reached and a suitable commitment. A stream value carries the slot of the account's last update.

### Reads work, but is the stream connected?

Call `getLastTransportError()`. Reads can be served by RPC polling while the stream fails, for example because a gRPC URL has more than one path segment or the endpoint doesn't serve Account Sync.

### Why doesn't the WebSocket connect?

Check that:

* `endpoint` starts with `http:` or `https:`.
* The token is in the URL path when the endpoint needs one.
* Your endpoint serves the Account Sync WebSocket service.
* Any proxy in between allows WebSocket upgrades.
* In a browser, your page's origin is allowed for the endpoint.

Then call `getLastTransportError()` for the latest background error. The SDK can still be serving reads through RPC polling.

### Why does the browser say gRPC is unsupported?

Browsers can't use gRPC. Use `AccountSyncTransports.WS`. gRPC is available in Node.js.

### Why does `getLastTransportError()` return an error after recovery?

The SDK keeps the most recent background error and never clears it.

### Why won't my Node.js process exit?

Await `connection.close()`.

### Why didn't a removed account stay removed?

A later read created a new temporary subscription. Stop reading it on this connection, or set `autoSubscribeOnMiss: false`.

## Advanced account encoding

These helpers convert raw account values to Solana RPC encodings; most applications don't need them. They run in a WebAssembly module bundled with the package that loads on first use. Under Node.js it is read from disk; in a browser it is loaded as a static asset of the package. It makes no RPC calls.

| Encoding      | Output                                                                                                              |
| ------------- | ------------------------------------------------------------------------------------------------------------------- |
| `binary`      | A base58 string (legacy name).                                                                                      |
| `base58`      | A `[data, "base58"]` tuple.                                                                                         |
| `base64`      | A `[data, "base64"]` tuple.                                                                                         |
| `base64+zstd` | A `[data, "base64+zstd"]` tuple of zstd-compressed data.                                                            |
| `jsonParsed`  | Parsed data. When the account can't be parsed, 0.1.0 rejects and 0.1.1 and later return a `[data, "base64"]` tuple. |

```ts
import {
  accountInfoToEncodingInput,
  convertAccountData,
  encodeAccount,
} from "@triton-one/triton-sdk";

const base58Data = await convertAccountData("AQID", "base64", "base58");

const accountInfo = await connection.getAccountInfo(address);
if (accountInfo) {
  const encoded = await encodeAccount(
    accountInfoToEncodingInput(address, accountInfo),
    "base64",
  );
  console.log(base58Data, encoded.data, encoded.space);
}
```

### Functions

* `convertAccountData(input, from, to)` converts between raw encodings. It rejects `jsonParsed`.
* `encodeAccount(input, encoding, options?)` returns a `UiAccount` (`lamports`, `data`, `owner`, `executable`, `rentEpoch`, `space`). With `options.dataSlice`, `space` still reports the full size; slices don't apply to `jsonParsed`.
  * `options.unixTimestamp`: Unix time in seconds for `jsonParsed` parsers whose output depends on the time. Set it in `parseContext` or at the top level of `options`; the top-level value wins. It must be a safe integer.
* `parseJsonParsed(input, options?)` exists in version 0.1.0. It parses once with the context in `options.parseContext` (for example `splTokenMint: { pubkey, data }`) and never fetches data. Version 0.1.1 removed it: use `encodeAccount(input, "jsonParsed", { parseContext })`.
* `loadAccountEncodingWasm()` loads and initializes the bundled encoder. Repeated and concurrent calls share one initialization.
* `toWeb3JsParsedAccountInfo(account)` converts a `UiAccount` from `encodeAccount(input, "jsonParsed")` into a web3.js account with a `PublicKey` owner.
  * From 0.1.1 it returns `AccountInfo<Buffer | ParsedAccountData>`, and a `[data, "base64"]` tuple becomes a `Buffer`.
  * In 0.1.0 it returns `AccountInfo<ParsedAccountData>`.
  * It throws `UnsupportedEncodingError` when `data` is neither parsed data nor (from 0.1.1) a `[data, "base64"]` tuple.

### `AccountEncodingInput`

Use `accountInfoToEncodingInput` to build one from a web3.js account.

| Field        | Type                               | Notes                                               |
| ------------ | ---------------------------------- | --------------------------------------------------- |
| `pubkey`     | `string` or `PublicKey`            | Address of the account.                             |
| `owner`      | `string` or `PublicKey`            | Address of the program that owns the account.       |
| `lamports`   | `number`, `bigint` or `string`     | Unsigned 64-bit integer. A string must be decimal.  |
| `executable` | `boolean`                          | Whether the account contains an executable program. |
| `rentEpoch`  | `number`, `bigint` or `string`     | Unsigned 64-bit integer. A string must be decimal.  |
| `data`       | `Uint8Array`, `Buffer` or `string` | Raw account bytes, or a base64 string.              |

The SDK rejects numbers that aren't safe integers, negative values, values above the unsigned 64-bit maximum, invalid addresses and invalid base64.

### Errors

| Error                      | Meaning                                                                                                                                          |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `UnsupportedEncodingError` | Unsupported encoding or conversion.                                                                                                              |
| `InvalidAccountDataError`  | Invalid account field, encoded value or option.                                                                                                  |
| `MissingParseContextError` | Parsing needs data you didn't supply.                                                                                                            |
| `WasmParserError`          | The parser failed. In 0.1.0 this includes an unsupported program; from 0.1.1, an unsupported program returns a `[data, "base64"]` tuple instead. |

## web3.js compatibility

To migrate, change the import, add `accountSync` to the constructor config, and call `close()` when you're done:

```diff
- import { Connection, PublicKey } from "@solana/web3.js";
+ import { Connection, PublicKey } from "@triton-one/triton-sdk";
```

Behavior differs from web3.js in the ways on this page: buffered values, temporary subscriptions, per-commitment streams, outage polling, typed timeout errors, parsed reads that reject instead of returning raw data (in 0.1.0; from 0.1.1 they return a `Buffer`), and `space` missing in version 0.1.0.

## Public API

```
new Connection(endpoint, commitmentOrConfig?)

connection.getAccountInfo(publicKey, commitmentOrConfig?)
connection.getAccountInfoAndContext(publicKey, commitmentOrConfig?)
connection.getParsedAccountInfo(publicKey, commitmentOrConfig?)
connection.getMultipleAccountsInfo(publicKeys, commitmentOrConfig?)
connection.getMultipleAccountsInfoAndContext(publicKeys, commitmentOrConfig?)
connection.getMultipleParsedAccounts(publicKeys, config?)

connection.addAccounts(accountIds, commitment?)
connection.removeAccounts(accountIds, commitment?)
connection.setAccounts(accountIds, commitment?)
connection.getLastTransportError()
connection.close()
```

**Values and classes:** `Connection`, `AccountSyncConnection`, `AccountSyncTransports`, `AccountSyncReadTimeoutError`, `AccountParseContextCache`, `ContextFetchError`, `InvalidAccountDataError`, `MissingParseContextError`, `UnsupportedEncodingError`, `WasmParserError`, `accountInfoToEncodingInput`, `bufferedAccountToEncodingInput`, `convertAccountData`, `encodeAccount`, `isBase64ZstdEncodingSupported`, `loadAccountEncodingWasm`, `parseJsonParsed` (version 0.1.0; removed in 0.1.1), `toWeb3JsParsedAccountInfo`, and everything from `@solana/web3.js`.

**Types (both builds):** `AccountSyncCommitment`, `AccountSyncOptions<TTransport>`, `AccountSyncReadTimeoutErrorOptions`, `BufferedAccountState`, and the encoding types `AccountDataEncoding`, `AccountEncodingInput`, `AccountEncodingOptions`, `AccountParseContext`, `AccountParseContextAccount`, `AccountParseContextCacheOptions`, `AccountParseContextFetcher`, `AccountParseContextMint`, `ConvertAccountDataOptions`, `EncodedAccountData` and `UiAccount`.

**Node.js build:** `GrpcTransportOptions`, `NodeAccountSyncConnectionConfig`, `NodeSubscriptionTransport`. **Browser build:** `BrowserAccountSyncConnectionConfig`, `BrowserSubscriptionTransport`.

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Account Sync Rust SDK reference

Yellowstone Account Sync in the triton-sdk Rust crate: RpcClient modes, AccountSyncConfig defaults, get\_account reads, pinned accounts, errors and API.

The `triton-sdk` crate (version 0.1.0) adds [Yellowstone Account Sync](https://docs.triton.one/solana/reading-account-state/account-sync) to the asynchronous Solana `RpcClient`. Five raw account-read methods resolve from an in-memory buffer fed by a gRPC stream; every other method goes to JSON-RPC through the wrapped client. For what Account Sync is and a first program, start with the [overview](https://docs.triton.one/solana/reading-account-state/account-sync).

```bash
cargo add triton-sdk
cargo add tokio --features rt,macros
```

* Requires **Rust 1.97.1 or newer**. Version 0.1.0 pins `solana-client` 4.3.0, which sets that minimum.
* Account Sync runs on Tokio. Reads must happen inside a Tokio runtime.
* Import Solana types (`Pubkey`, `Account`, `CommitmentConfig`) from `triton_sdk` so they match its Solana versions.

## Client modes

`RpcClient` has two modes, tracked in its type:

* **`RpcClient<Plain>`** (the default type) comes from `RpcClient::new`, `new_with_commitment`, `new_with_timeout`, `new_with_timeout_and_commitment` or `from_inner`. It uses Solana RPC directly.
* **`RpcClient<Configured>`** comes from `with_account_sync(config)`. It adds buffered reads and account controls.

```rust
let client = RpcClient::new_with_commitment(rpc_url, CommitmentConfig::confirmed())
    .with_account_sync(AccountSyncConfig {
        endpoint: account_sync_url,
        ..Default::default()
    })?;
```

`with_account_sync` validates the configuration and returns `ConfigError` if it's invalid. It starts nothing: the first supported read at a commitment starts that commitment's stream.

* `RpcClient::from_inner(existing)` wraps a `solana_client::nonblocking::rpc_client::RpcClient` (version 4.3.0) and keeps its URL, timeout and commitment.
* `client.inner()` returns the wrapped Solana client. Its methods bypass the buffer.
* Every other Solana client method is available on `RpcClient` through `Deref` and goes to RPC.
* `triton_sdk::RpcClient` isn't Solana's `RpcClient` type.
* After `with_account_sync`, change explicit type annotations that used the plain `RpcClient` to `RpcClient<Configured>`.
* There is no blocking Account Sync client.
* Clones share the RPC client and Account Sync state. Closing one clone stops Account Sync for all of them.
* The default read commitment comes from the wrapped client: `RpcClient::new` uses `finalized`, so pass a commitment explicitly if you want `confirmed`.
* RPC request timeouts also belong to the wrapped client. Set them with `new_with_timeout_and_commitment` or `from_inner`.

## Endpoint and token

`AccountSyncConfig.endpoint` is the Account Sync gRPC URL. It is required and is never derived from the RPC URL; use the same URL for both if your endpoint serves both.

* The scheme must be `http` or `https`. Without a scheme, the SDK uses `https`, or `http` for `localhost`, `127.0.0.1`, `[::1]` and `0.0.0.0`.
* The path must be empty or exactly `/<token>`. The SDK sends the token as `x-token` metadata, not in the URL. Query strings and fragments are ignored.
* A `ws://` URL fails with `ConfigError::EndpointScheme`, and a longer path with `ConfigError::EndpointPath`.
* `https` uses TLS with the operating system's root certificates.

The RPC URL belongs to the wrapped Solana client, with your token in its path as usual.

## Configuration

Pass an `AccountSyncConfig` to `with_account_sync`. Durations are `std::time::Duration` values.

```rust
use std::time::Duration;

let config = AccountSyncConfig {
    endpoint: account_sync_url,
    pinned_accounts: [address].into(),
    cache_miss_wait: Duration::from_secs(5),
    dynamic_subscription_lifetime: Duration::from_secs(60),
    ..Default::default()
};
```

| Field                           | Type              | Default             | Meaning                                                                                       |
| ------------------------------- | ----------------- | ------------------- | --------------------------------------------------------------------------------------------- |
| `endpoint`                      | `String`          | Empty (must be set) | Account Sync gRPC URL.                                                                        |
| `pinned_accounts`               | `HashSet<Pubkey>` | Empty               | Accounts tracked at every commitment until removed.                                           |
| `automatic_subscriptions`       | `bool`            | `true`              | Track an unpinned account temporarily when it's read.                                         |
| `cache_miss_wait`               | `Duration`        | 5 s                 | How long a read waits for the buffer before relying only on RPC. Not a deadline for the read. |
| `subscription_refresh`          | `Duration`        | 1 s                 | Tick for expiring temporary subscriptions and retrying failed initial loads.                  |
| `reconnect_min_delay`           | `Duration`        | 100 ms              | First reconnect delay. Doubles after each failure.                                            |
| `reconnect_max_delay`           | `Duration`        | 5 s                 | Largest reconnect delay. Must be at least `reconnect_min_delay`.                              |
| `connect_timeout`               | `Duration`        | 10 s                | Limit for establishing the gRPC connection.                                                   |
| `close_timeout`                 | `Duration`        | 5 s                 | Limit for `close()` to wait for background tasks.                                             |
| `dynamic_subscription_lifetime` | `Duration`        | 60 s                | Lifetime of a temporary subscription after its most recent read.                              |
| `http2_window_size`             | `u32`             | 16 MiB              | Initial HTTP/2 connection and stream receive windows.                                         |
| `max_decoded_message_size`      | `usize`           | 16 MiB              | Largest decoded gRPC message accepted.                                                        |
| `keepalive_interval`            | `Duration`        | 30 s                | Interval between HTTP/2 keepalive pings.                                                      |
| `keepalive_timeout`             | `Duration`        | 10 s                | Time allowed for a keepalive response.                                                        |
| `keepalive_while_idle`          | `bool`            | `true`              | Send keepalive pings while no stream is active.                                               |

Every duration and both size limits must be nonzero. There's no commitment field, no transport selector and no WebSocket option. The client accepts gzip and Zstd stream compression.

`client.account_sync_config()` returns an owned snapshot of the configuration, including the current pinned set. Changing the snapshot doesn't affect the client.

## Reading accounts

These methods on `RpcClient<Configured>` use the buffer:

| Method                                                        | Success value                                                                                         |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `get_account(&pubkey)`                                        | `Account`. A missing account is a `ClientError` with the message `AccountNotFound: pubkey=<address>`. |
| `get_account_data(&pubkey)`                                   | `Vec<u8>`. A missing account is the same error as `get_account`.                                      |
| `get_account_with_commitment(&pubkey, commitment)`            | `Response<Option<Account>>`                                                                           |
| `get_multiple_accounts(&pubkeys)`                             | `Vec<Option<Account>>`                                                                                |
| `get_multiple_accounts_with_commitment(&pubkeys, commitment)` | `Response<Vec<Option<Account>>>`                                                                      |

All are `async` and return the Solana `ClientError` type on failure. `get_account`, `get_account_data` and `get_multiple_accounts` use the wrapped client's commitment.

### How a read resolves

1. If the buffer holds every requested account, the read returns from memory with no RPC request.
2. Otherwise the SDK makes the normal Solana RPC call and waits up to `cache_miss_wait` for the buffer at the same time. Whichever finishes first wins, including an RPC error. If the wait expires, the read waits for RPC under the wrapped client's timeout.
3. Successful RPC results are stored for accounts that are tracked.

`None`, or an error message starting with `AccountNotFound`, means RPC observed the account as missing. RPC failures stay errors.

Multiple-account reads use the buffer only for 1 to 100 addresses. An empty list or more than 100 addresses goes straight to the RPC method, which accepts at most 100 and applies its usual validation and errors. The SDK doesn't split a larger list into batches. Results keep input order and duplicates.

### Context slot

A value from RPC carries the RPC context slot. A value from the stream carries the slot of that account's last update, which can lag the cluster for an unchanged account. A buffered multiple-account response uses the lowest slot among its accounts.

### What isn't buffered

The buffered methods take no `dataSlice`, `min_context_slot` or encoding options, and return raw `Account` values (which have no `space` field; use `data.len()`). Methods such as `get_ui_account_with_config`, `get_multiple_ui_accounts_with_config` and parsed reads go to RPC.

## Pinned and temporary accounts

**Pinned** accounts stay tracked at every commitment until you remove them. Set them in `pinned_accounts` or change them at runtime:

```rust
client.add_accounts([address_c, address_d]).await?;
client.remove_accounts([address_a]).await?;
client.replace_accounts([address_b, address_c]).await?;
```

* The methods take any `IntoIterator<Item = Pubkey>` and return `Result<(), AccountSyncError>`.
* There is no commitment argument: changes apply to every running commitment and to commitments started later.
* Removing an address that isn't pinned succeeds. A change made before the first read only updates the configuration.

**Temporary** subscriptions are created when you read an unpinned account and `automatic_subscriptions` is `true`. One lasts `dynamic_subscription_lifetime` after the most recent read of that account and is removed on the next `subscription_refresh` tick. Temporary subscriptions belong to the commitment of the read.

`remove_accounts` and `replace_accounts` don't end a temporary subscription; it stays until it expires, and reads renew it. To make the pinned set the complete tracked set, set `automatic_subscriptions: false`. Unpinned reads then go to RPC and their results aren't kept.

The SDK sets no limit on the number of tracked accounts.

## Commitment levels

Each `CommitmentConfig` you read with gets its own stream and buffer, started by the first read at that commitment. All commitments share the pinned set. A commitment's stream with nothing to track waits idle, and its task runs until `close()`.

## Stream lifecycle

* When a stream session opens, the SDK loads every tracked account at that commitment over RPC, one `getAccountInfo` request per account. Stream updates that arrive first are kept when they're newer. Failed loads are retried on each `subscription_refresh` tick.
* Any change to a commitment's tracked set, including a temporary subscription starting or expiring, clears that commitment's buffer, reconnects its stream with the new set and reloads every tracked account.
* If the stream fails, the SDK clears that commitment's buffer and reconnects with backoff from `reconnect_min_delay` to `reconnect_max_delay`. It doesn't poll tracked accounts in the meantime.

{% hint style="warning" %}
**Known limitation (0.1.0):** while a stream is disconnected, an account value that a read fetched through RPC stays in the buffer, and later reads return it without refreshing until the stream reconnects. If the stream can never connect (wrong `endpoint`, token or access) and the tracked set stays the same, those values never refresh. Confirm the stream works before production, for example by checking that the context slot of a frequently changing account advances. For a read that must come from RPC, call `client.inner()`.
{% endhint %}

## Errors

| Operation                                                      | Error type         | Variants                                                                                                                              |
| -------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `with_account_sync`                                            | `ConfigError`      | `EndpointScheme`, `EndpointUrl`, `EndpointPath`, `EndpointToken`, `Endpoint`, `Zero(field)`, `ReconnectRange`                         |
| Buffered reads                                                 | `ClientError`      | Solana client errors. A missing account from `get_account` or `get_account_data` has the message `AccountNotFound: pubkey=<address>`. |
| `add_accounts`, `remove_accounts`, `replace_accounts`, `close` | `AccountSyncError` | `Closed` after `close()`; `CloseTimeout` or `TaskJoin` from `close()`; `ChannelClosed` if background work stopped unexpectedly        |

Stream failures trigger reconnection and are not returned to your code. There's no public accessor for the last stream error, and a successful read doesn't prove the stream is connected.

**Closing.** `close().await` cancels Account Sync work and waits up to `close_timeout` for it to stop, returning `AccountSyncError::CloseTimeout` if it doesn't. Later calls return `Ok(())`. After closing, account controls return `AccountSyncError::Closed`, and reads go straight to RPC. Dropping the last clone also cancels background work, without waiting.

## Complete lifecycle example

```rust
use std::{env, error::Error};

use triton_sdk::{AccountSyncConfig, CommitmentConfig, Pubkey, RpcClient};

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), Box<dyn Error>> {
    let address: Pubkey = "So11111111111111111111111111111111111111112".parse()?;
    let new_address: Pubkey = "SysvarC1ock11111111111111111111111111111111".parse()?;

    let client =
        RpcClient::new_with_commitment(env::var("RPC_URL")?, CommitmentConfig::confirmed())
            .with_account_sync(AccountSyncConfig {
                endpoint: env::var("ACCOUNT_SYNC_URL")?,
                automatic_subscriptions: false,
                ..Default::default()
            })?;

    let result = async {
        client.add_accounts([address]).await?;
        let first = client.get_account_with_commitment(&address, client.commitment()).await?;
        println!("First read: {first:?}");

        client.remove_accounts([address]).await?;
        client.add_accounts([address]).await?;
        let second = client.get_account_with_commitment(&address, client.commitment()).await?;
        println!("After re-adding: {second:?}");

        client.replace_accounts([new_address]).await?;
        let third = client
            .get_account_with_commitment(&new_address, client.commitment())
            .await?;
        println!("Replacement: {third:?}");
        println!("Pinned: {:?}", client.account_sync_config().pinned_accounts);
        Ok::<_, Box<dyn Error>>(())
    }
    .await;

    let closed = client.close().await;
    result?;
    closed?;
    Ok(())
}
```

The example saves the result, always awaits `close()`, then returns the first error.

## Production guidance

* **Share one client and close it on shutdown.** Clone it into tasks; clones share state.
* **Size your RPC usage, not just the stream.** The SDK calls RPC for cache misses and to load every tracked account whenever a session opens or the tracked set changes. These requests count against your [rate limits](https://docs.triton.one/using-your-endpoint/rate-and-connection-limits) and are billed under your [plan](https://docs.triton.one/account-and-billing/plans-and-billing).
* **Keep the tracked set stable.** Every set change reconnects the stream and reloads each tracked account with its own request. For large sets, pin the accounts you need and set `automatic_subscriptions: false`.
* **Watch memory and bandwidth.** The full data of every tracked account sits in process memory, and every update streams in full. Test with realistic account sizes and update rates before you raise `http2_window_size` or `max_decoded_message_size`.
* **Keep up with the stream.** Triton closes a session whose server-side queue fills because the client can't consume updates fast enough. The SDK reconnects. Avoid short-lived function workers for a continuous stream.
* **Monitor freshness.** Track read errors and latency, and alert if context slots of active accounts stop advancing. See the known limitation above.

## Troubleshooting

### I configured pinned accounts, but no stream started

Configuration and pin changes don't start anything. Make a buffered read inside a Tokio runtime.

### Reads work, but the values don't change

The stream is probably not connected, and reads are returning values fetched through RPC. Check that `endpoint` is the Account Sync gRPC URL for the same cluster as the RPC URL, with at most one path segment (your token).

### My read takes longer than `cache_miss_wait`

That setting limits the wait for the buffer, not the whole read. Set the RPC timeout on the wrapped client.

### Removing a pin didn't unsubscribe the account

A temporary subscription is still active, and reads renew it. Set `automatic_subscriptions: false` if the pinned set must be the whole tracked set.

### Reads still work after `close()`

That's expected: after closing, reads use RPC. Account controls return `AccountSyncError::Closed`.

### My read always uses RPC

Only the five methods above use the buffer, and multiple-account reads only for 1 to 100 addresses. Calls through `inner()` and `_with_config` methods always use RPC.

## Public API

```rust
RpcClient::new(url)
RpcClient::new_with_commitment(url, commitment)
RpcClient::new_with_timeout(url, timeout)
RpcClient::new_with_timeout_and_commitment(url, timeout, commitment)
RpcClient::from_inner(solana_client)
plain_client.with_account_sync(config)          -> Result<RpcClient<Configured>, ConfigError>
client.inner()                                  -> &solana_client::nonblocking::rpc_client::RpcClient

configured.get_account(&pubkey).await
configured.get_account_data(&pubkey).await
configured.get_account_with_commitment(&pubkey, commitment).await
configured.get_multiple_accounts(&pubkeys).await
configured.get_multiple_accounts_with_commitment(&pubkeys, commitment).await

configured.account_sync_config()                -> AccountSyncConfig
configured.add_accounts(keys).await             -> Result<(), AccountSyncError>
configured.remove_accounts(keys).await          -> Result<(), AccountSyncError>
configured.replace_accounts(keys).await         -> Result<(), AccountSyncError>
configured.close().await                        -> Result<(), AccountSyncError>
```

**Crate exports:** `RpcClient` (also at `triton_sdk::nonblocking::rpc_client`), `Plain`, `Configured`, `AccountSyncConfig`, `ConfigError`, `AccountSyncError`, `Account`, `Pubkey`, `CommitmentConfig`, `CommitmentLevel`, `ClientError` and the Solana `response` module.

Runnable examples are in the [triton-rust-sdk repository](https://github.com/rpcpool/triton-rust-sdk/tree/main/triton-sdk/examples). The [read timings example](https://github.com/rpcpool/triton-rust-sdk/blob/main/triton-sdk/examples/compare_multiple_accounts_latency.rs) reads 100 accounts and measures read duration, not stream delivery latency.

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Cloudbreak Accounts

Cloudbreak custom indexes serve getProgramAccounts, getTokenAccountsByOwner and getTokenAccountsByDelegate: parameters, commitment, limits and error codes.

On an endpoint where Cloudbreak is enabled, Cloudbreak answers the supported methods from its index automatically. There is nothing to enable or route on your side.

## Use cases

* **Reading many program accounts at scale** (AMMs, indexers): repeated `getProgramAccounts` queries with `memcmp` or `dataSize` filters are served from a matching index instead of a full scan.
* **SPL token queries** by owner or delegate.

**What not to use it for.** Cloudbreak answers point-in-time queries on current account state and does not serve transaction history. For a live stream of account changes, use [Dragon's Mouth](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc). `processed` requests on Cloudbreak-routed methods are answered at `confirmed` commitment.

## Features and benefits

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-magnifying-glass">:magnifying-glass:</i> <strong>Fast getProgramAccounts</strong></td><td>getProgramAccounts against a program with a large account set, especially with memcmp or dataSize filters you run repeatedly.</td><td></td></tr><tr><td><i class="fa-check-double">:check-double:</i> <strong>Standard Solana RPC format</strong></td><td>Requests and responses match standard Solana JSON-RPC for every supported method, so existing clients work without changes.</td><td></td></tr><tr><td><i class="fa-coins">:coins:</i> <strong>SPL token queries</strong></td><td>Token account queries by owner or delegate, plus Token and Token-2022 getProgramAccounts queries with memcmp filters.</td><td></td></tr><tr><td><i class="fa-bolt">:bolt:</i> <strong>Dynamic indexing on live traffic</strong></td><td>Indexes are built automatically from real query traffic: heavily requested filter shapes get their own index, with nothing to configure on your side.</td><td></td></tr></tbody></table>

## How it works

Cloudbreak builds its index from a validator snapshot for the starting state and a Yellowstone gRPC stream of account updates to stay current. It tracks both `confirmed` and `finalized` commitment as the chain advances, so a query reads the same state the chain has reached at the commitment you ask for.

```mermaid
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#F2EDF6','primaryBorderColor':'#7A4BA0','primaryTextColor':'#171717','lineColor':'#956FB3','secondaryColor':'#E4DBEC','tertiaryColor':'#D7C9E3','edgeLabelBackground':'#F2EDF6'},'flowchart':{'nodeSpacing':35,'rankSpacing':55,'curve':'linear'}}}%%
flowchart LR
    vsnap["Validator snapshot"] --> state["Account<br/>state"]
    live["Live gRPC updates"] --> state
    live --> idx["Cloudbreak indexes"]
    state --> q["JSON-RPC<br/>query layer"]
    idx --> q
    q --> you["Your app"]
    idx -.- tracker["Query tracker"]
    tracker -.- you
    style you fill:#D6EAF8,stroke:#259DD0
```

### How indexes get created

A `getProgramAccounts` query is fast when an index matches its filter shape. Cloudbreak creates these indexes from real traffic: it counts the query shapes it receives, and once a shape is requested often enough it builds the matching index automatically, backing off while the index catches up so index creation does not compete with ingestion. Token and Token-2022 program queries with `memcmp` filters use Cloudbreak's dedicated token indexes rather than this path.

A query with no matching index yet still returns correct results, it just runs slower until the index is built.

## Supported methods

| Method                       | Returns                                                                                                              |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `getProgramAccounts`         | All accounts owned by a program, with filters, including Token and Token-2022 program queries with `memcmp` filters. |
| `getTokenAccountsByOwner`    | SPL Token and Token-2022 token accounts owned by a wallet.                                                           |
| `getTokenAccountsByDelegate` | SPL Token and Token-2022 token accounts a delegate controls.                                                         |

Other account methods, such as `getAccountInfo`, `getMultipleAccounts`, `getBalance` and `getTokenAccountBalance`, are served by Triton's standard RPC nodes, not Cloudbreak. Other methods Cloudbreak does not cover (`getVoteAccounts`, transaction methods, block methods) are not accelerated, and your endpoint serves them as usual. `getTokenAccountsByMint` is not available on shared endpoints and returns JSON-RPC error `-32601 Method not found`.

### getProgramAccounts

Returns every account owned by a program, with optional filtering. This is the method Cloudbreak is built to accelerate. Compatible with the standard [Solana `getProgramAccounts` API](https://solana.com/docs/rpc/http/getprogramaccounts).

Position 0 is the program pubkey (base58 string), required. Position 1 is an optional config object:

| Field            | Required | Default     | Description                                                                                                                                                             |
| ---------------- | -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `encoding`       | optional | `binary`    | `base64`, `base58`, `base64+zstd`, or `jsonParsed`.                                                                                                                     |
| `filters`        | optional | none        | Array of `memcmp`, `dataSize`, and `tokenAccountState` filters. All filters must match. There's no limit on the number of filters. Results are always sorted by pubkey. |
| `dataSlice`      | optional | full data   | `{ "offset": <number>, "length": <number> }`. Returns only that byte range of account data.                                                                             |
| `commitment`     | optional | `finalized` | `confirmed` or `finalized`.                                                                                                                                             |
| `minContextSlot` | optional | none        | Fail with `-32016` if the index has not reached this slot yet.                                                                                                          |
| `withContext`    | optional | `false`     | When `true`, wrap the result in `{ "context": { "slot": N }, "value": [...] }`.                                                                                         |

A `memcmp` filter matches a base58-encoded byte sequence at a fixed offset: `{ "memcmp": { "offset": 32, "bytes": "<base58-bytes>" } }`. A `dataSize` filter matches accounts of an exact data length: `{ "dataSize": 165 }`.

On shared endpoints, SPL Token and Token-2022 queries need a `memcmp` filter with the full 32-byte owner pubkey at offset `32` or the full mint pubkey at offset `0`, and System Program queries need a `memcmp` filter. Calls without them are rejected with HTTP `403` before they reach Cloudbreak. A shorter `bytes` value at offset `0` or `32` returns `-32602`. Other programs need no filter.

{% tabs %}
{% tab title="Request" %}

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getProgramAccounts",
  "params": [
    "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8",
    {
      "encoding": "base64",
      "commitment": "confirmed",
      "withContext": true,
      "filters": [{ "dataSize": 752 }]
    }
  ]
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "context": { "slot": 250000042 },
    "value": [
      {
        "pubkey": "58oQChx4yWmvKdwLLZzBi4ChoCc2fqCUWBkwMihLYQo2",
        "account": {
          "lamports": 1234567,
          "owner": "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8",
          "executable": false,
          "rentEpoch": 18446744073709551615,
          "space": 752,
          "data": ["<base64-string>", "base64"]
        }
      }
    ]
  }
}
```

{% endtab %}
{% endtabs %}

Without `withContext`, `result` is the array directly rather than the `{ context, value }` envelope, matching standard Solana RPC behavior.

{% hint style="info" %}
`getProgramAccounts` responses are streamed back as a chunked HTTP body, so a client can begin parsing accounts before the query finishes and peak memory stays bounded on both ends. Standard HTTP and JSON-RPC clients consume the chunked body transparently. If a request fails before the first batch is sent, you get a normal JSON-RPC error. If it fails partway through streaming, the connection is aborted and your client reports a transport error. A response still streaming at the 90-second limit ends early, and your JSON parser reports an incomplete document. Treat a transport error or a JSON parse error on `getProgramAccounts` as a failed request, and retry.
{% endhint %}

### getTokenAccountsByOwner

Returns the SPL Token and Token-2022 token accounts owned by a wallet. Cloudbreak indexes the token owner and mint as dedicated columns, so this method stays fast even though the SPL Token program has a very large account set. Compatible with the standard [Solana `getTokenAccountsByOwner` API](https://solana.com/docs/rpc/http/gettokenaccountsbyowner).

{% hint style="info" %}
For SPL token data, use the token methods rather than a raw `getProgramAccounts` against the Token program. The token methods use Cloudbreak's dedicated token indexes; a `getProgramAccounts` over the Token program without an owner or mint `memcmp` filter is rejected on shared endpoints.
{% endhint %}

Position 0 is the owner pubkey (base58), required. Position 1 is a filter object, required, with exactly one of:

| Filter                               | Description                                                                                                                          |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `{ "mint": "<mint-pubkey>" }`        | Restrict to a single mint.                                                                                                           |
| `{ "programId": "<token-program>" }` | Restrict to SPL Token (`TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA`) or Token-2022 (`TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`). |

Position 2 is an optional config object accepting `encoding`, `dataSlice`, `commitment`, and `minContextSlot`, with the same meanings as in `getProgramAccounts`.

{% tabs %}
{% tab title="Request" %}

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getTokenAccountsByOwner",
  "params": [
    "<owner-wallet-pubkey>",
    { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" },
    { "encoding": "jsonParsed", "commitment": "confirmed" }
  ]
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "context": { "slot": 250000042 },
    "value": [
      {
        "pubkey": "<token-account-pubkey>",
        "account": {
          "lamports": 2039280,
          "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
          "executable": false,
          "rentEpoch": 18446744073709551615,
          "space": 165,
          "data": {
            "program": "spl-token",
            "parsed": {
              "type": "account",
              "info": {
                "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
                "owner": "<owner-wallet-pubkey>",
                "tokenAmount": {
                  "amount": "1000000",
                  "decimals": 6,
                  "uiAmount": 1.0,
                  "uiAmountString": "1"
                },
                "state": "initialized",
                "isNative": false
              }
            },
            "space": 165
          }
        }
      }
    ]
  }
}
```

{% endtab %}
{% endtabs %}

The token methods always wrap their result in the `{ context, value }` envelope, matching standard Solana RPC.

### getTokenAccountsByDelegate

Identical parameters and response shape to `getTokenAccountsByOwner`, but position 0 is the delegate pubkey and results are the SPL Token and Token-2022 token accounts that delegate has authority over. Compatible with the standard [Solana `getTokenAccountsByDelegate` API](https://solana.com/docs/rpc/http/gettokenaccountsbydelegate).

{% tabs %}
{% tab title="Request" %}

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getTokenAccountsByDelegate",
  "params": [
    "<delegate-pubkey>",
    { "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
    { "encoding": "jsonParsed" }
  ]
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "context": { "slot": 250000042 },
    "value": [
      {
        "pubkey": "<token-account-pubkey>",
        "account": {
          "lamports": 2039280,
          "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
          "executable": false,
          "rentEpoch": 18446744073709551615,
          "space": 165,
          "data": {
            "program": "spl-token",
            "parsed": {
              "type": "account",
              "info": {
                "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
                "owner": "<owner-wallet-pubkey>",
                "delegate": "<delegate-pubkey>",
                "delegatedAmount": {
                  "amount": "500000",
                  "decimals": 6,
                  "uiAmount": 0.5,
                  "uiAmountString": "0.5"
                },
                "state": "initialized",
                "isNative": false
              }
            },
            "space": 165
          }
        }
      }
    ]
  }
}
```

{% endtab %}
{% endtabs %}

## Making requests

The Cloudbreak-accelerated methods are standard Solana JSON-RPC, so you call them the same way you call any other method on your RPC endpoint. There is nothing Cloudbreak-specific to install or configure on the client side, and existing Solana clients (`@solana/web3.js`, `solana-py`, and others) work without changes.

Every call is an HTTP POST with `Content-Type: application/json`:

```shell
curl https://<your-rpc-endpoint> \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getTokenAccountsByOwner","params":["<owner-wallet-pubkey>",{"programId":"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"},{"encoding":"base64"}]}'
```

* **Coverage is automatic.** Every program's accounts are indexed except a few excluded programs (see the FAQ), and query shapes that receive enough traffic get their own index over time, so common queries are fast with no setup on your side. See [How indexes get created](#how-indexes-get-created).
* **Commitment levels** are `confirmed` and `finalized`. The default is `finalized`. `processed` requests are answered at `confirmed` commitment on Triton endpoints. See [Commitment and consistency](#commitment-and-consistency).
* **Encodings** are `base64`, `base58`, `base64+zstd`, and `jsonParsed`. If you do not set `encoding`, the response uses the legacy `binary` format, which is a single base58 string rather than a `[data, encoding]` array. Set `encoding` to `base64` for most uses.

{% hint style="warning" %}
The default `binary` encoding and `base58` only work for account data of 128 bytes or fewer, after any `dataSlice`. Larger accounts return `-32600` with a message telling you to switch to `base64`. Because the default is `binary`, set `encoding` to `base64` whenever an account can exceed 128 bytes.
{% endhint %}

## Batch requests

Send an array of request objects to run several in one round trip. The response is an array with one result per request. On Triton endpoints, a batch that contains `getProgramAccounts`, `getTokenAccountsByOwner`, or `getTokenAccountsByDelegate` is split, so every request in it runs individually, and each result is added to the one response array as it completes. Results can arrive in a different order from your requests, so match each result to its request by `id`. A `getProgramAccounts` result inside a batch is returned in full rather than streamed.

{% tabs %}
{% tab title="Request" %}

```json
[
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getTokenAccountsByOwner",
    "params": [
      "<owner-wallet-pubkey>",
      { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" },
      { "encoding": "base64" }
    ]
  },
  {
    "jsonrpc": "2.0",
    "id": 2,
    "method": "getTokenAccountsByDelegate",
    "params": [
      "<delegate-pubkey>",
      { "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
      { "encoding": "base64" }
    ]
  }
]
```

{% endtab %}

{% tab title="Response" %}

```json
[
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": { "context": { "slot": 250000042 }, "value": [] }
  },
  {
    "jsonrpc": "2.0",
    "id": 2,
    "result": { "context": { "slot": 250000042 }, "value": [] }
  }
]
```

{% endtab %}
{% endtabs %}

## Commitment and consistency

Cloudbreak tracks two commitment levels and serves point-in-time reads against them.

* **`confirmed`** reflects account state as soon as a block is confirmed. The indexer writes the slot's accounts first, then advances the confirmed marker, so a confirmed read never sees a half-written slot.
* **`finalized`** (the default) reflects account state at the latest finalized slot.

`processed` requests are answered at `confirmed` commitment on Triton endpoints.

Use `minContextSlot` to guarantee freshness. If you read a slot from one call and want a later query to be at least as fresh, pass that slot as `minContextSlot`. If the index has not reached it, the call fails with `-32016` rather than returning stale data. `getProgramAccounts` and the token methods check it on every call.

Use `withContext: true` on `getProgramAccounts` when you need to know which slot a result corresponds to. The token methods always include the context.

## Performance characteristics

* **`getProgramAccounts` and token queries** return in milliseconds once an index matches the query shape. A shape with no matching index still returns correct data, it just runs slower until the index exists. See [How indexes get created](#how-indexes-get-created).
* **Large repeated queries are cached.** Triton runs Cloudbreak with response caching on. For a large response (about 200 KB or more), the serialized result is kept per query shape (program, filters, encoding, data slice, and commitment), and the next time you run that query only the accounts that changed since the last response are read and re-encoded. Frequent polling of the same large query stays fast.
* **Large results stream back.** A response is sent as the index reads it, so a large `getProgramAccounts` result starts arriving right away. Queries have a 45-second limit (20 seconds for the token methods and Token or Token-2022 `getProgramAccounts` queries). A query that exceeds it before the first result is sent returns error `-32603`; a `getProgramAccounts` response that has already started streaming ends early. Responses have a 90-second limit; a response still streaming at the limit ends early, so your JSON parser reports an incomplete document. Treat that as a failed request and retry. Narrow large queries with filters or `dataSlice`.

## Benchmarks

Cloudbreak serves indexed `getProgramAccounts` reads faster than a full Agave scan, with latency that scales with the size of the result rather than the program. Measured end-to-end within a single datacenter for responses up to 10 MB (`getProgramAccounts`, base64):

| Response size | Agave avg | Cloudbreak avg | Agave p90 | Cloudbreak p90 |
| ------------- | --------- | -------------- | --------- | -------------- |
| 1-10 KB       | 1,725 ms  | 4 ms           | 2,478 ms  | 5 ms           |
| 10-100 KB     | 2,725 ms  | 7 ms           | 4,699 ms  | 11 ms          |
| 100 KB-1 MB   | 3,971 ms  | 8 ms           | 4,693 ms  | 13 ms          |
| 1-10 MB       | 3,693 ms  | 47 ms          | 4,708 ms  | 25 ms          |

Full benchmarks and methodology: [Inside Cloudbreak](https://blog.triton.one/inside-cloudbreak-indexing-architecture-for-performant-account-reads).

## Error reference

| Code     | Name                              | Meaning                                                                                                |
| -------- | --------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `-32601` | Method not found                  | The method is not implemented. See [Supported methods](#supported-methods).                            |
| `-32010` | Key excluded from secondary index | The program is excluded from Cloudbreak's index, so `getProgramAccounts` isn't served for it.          |
| `-32602` | Invalid params                    | Bad pubkey, malformed filter, or a Token program `memcmp` whose `bytes` isn't a full 32-byte pubkey.   |
| `-32600` | Invalid request                   | `binary` or `base58` requested for account data over 128 bytes. Use `base64`.                          |
| `-32016` | Minimum context slot not reached  | The index has not yet reached your `minContextSlot`. `data.contextSlot` holds the slot it has reached. |
| `-32005` | Node is unhealthy                 | Sent with HTTP `503` while a node catches up with the chain. Retry with backoff.                       |
| `-32603` | Internal error                    | A database error or a query that exceeded the server-side timeout.                                     |

## FAQ

<details>

<summary>Can I send the exact same requests I send to a normal Solana RPC node?</summary>

Yes, for the supported methods. The request and response formats are JSON-RPC 2.0 and match standard Solana RPC, so existing clients and tooling work without changes.

</details>

<details>

<summary>Why does my <code>getProgramAccounts</code> for a program return <code>-32010</code>?</summary>

The program is on Cloudbreak's exclusion list, so `getProgramAccounts` isn't served for it on shared endpoints. Every other program is indexed. The excluded keys are currently:

* Serum DEX v3 (`9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin`)
* Candy Machine v1 and v2 (`cndyAnrLdpjq1Ssp1z8xxDsB8dxe7u4HL5Nxi2K5WXZ`, `cndy3Z4yapfJBmL3ShUp5exZKqR3z33thTzeNMm2gRZ`)
* Legacy Metaplex auction programs (`auctxRXPeJoc4817jDhf4HbjnhEcr1cCXenosMhK5R8`, `p1exdMJcjVao65QdewkaZRUnU6VPSXhus9n2GzWfh98`)
* Kin token mint (`kinXdEcpDQeHPEuQnqmUgtYykqKGVFq6CeVX5iAHJq6`)

Light Protocol account compression (`compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq`) is served by standard RPC nodes on shared endpoints, without Cloudbreak's index. SPL Token and Token-2022 queries are served by Cloudbreak's token indexes instead. If you need data from an excluded program, contact support.

</details>

<details>

<summary>Why is one <code>getProgramAccounts</code> query fast and a similar one slow?</summary>

The fast one has a matching index and the slow one does not. A new query shape becomes fast once it is requested often enough for automatic index creation to pick it up. Both return correct data regardless.

</details>

<details>

<summary>My large <code>getProgramAccounts</code> response failed to parse. What happened?</summary>

A stream that errors partway through aborts the connection, so your client sees a transport error. A response still streaming at the 90-second limit ends early, so your JSON parser reports an incomplete document. Treat either as a failed request and retry; do not treat a partial body as a partial result.

</details>

<details>

<summary>How fresh is the data?</summary>

A `confirmed` read reflects state at the latest confirmed slot; a `finalized` read reflects the latest finalized slot. Use `withContext: true` to see the exact slot, and `minContextSlot` to require a minimum. If a node is behind the chain, it answers HTTP `503` (`-32005`) rather than serve stale data. Retry with backoff.

</details>

<details>

<summary>Can I get a live stream of changes instead of polling?</summary>

Use Dragon's Mouth. Cloudbreak answers point-in-time queries; Dragon's Mouth streams updates as they occur.

</details>

## Pricing

For rates, see [triton.one/pricing](https://triton.one/pricing). For how usage is billed, see [Plans and billing](https://docs.triton.one/account-and-billing/plans-and-billing).

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-play">:play:</i> <strong>Quickstart</strong></td><td>Query account state via JSON-RPC and set up Account Sync.</td><td><a href="https://docs.triton.one/solana/reading-account-state/quickstart">Reading account state quickstart</a></td></tr><tr><td><i class="fa-arrows-rotate">:arrows-rotate:</i> <strong>Account Sync</strong></td><td>Streams account updates into your process, so Triton SDK reads of tracked accounts resolve from memory instead of RPC.</td><td><a href="https://docs.triton.one/solana/reading-account-state/account-sync">Account Sync</a></td></tr><tr><td><i class="fa-list-check">:list-check:</i> <strong>Best practices</strong></td><td>How to keep account, program and token reads fast and fresh at scale.</td><td><a href="https://docs.triton.one/solana/reading-account-state/best-practices">Reading account state best practices</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Metaplex DAS API

Metaplex DAS API overview on Solana: NFTs, compressed NFTs, fungible and Token-2022 tokens, getAsset and searchAssets, pagination, and billing.

Decompression and data caching are done server-side. DAS is available on most Triton Solana endpoints, shared and dedicated, and is not offered on testnet. If your endpoint does not serve DAS, contact support.

Triton's open-source DAS work includes ingestion re-architected onto Yellowstone gRPC, new parsers for fungible tokens and Token-2022, and a query rework that brings `getAsset` to \~50 ms at P90.

## Features and benefits

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-clock-rotate-left">:clock-rotate-left:</i> <strong>Asset transaction history</strong></td><td>The transaction signatures for any compressed asset.</td><td></td></tr><tr><td><i class="fa-wallet">:wallet:</i> <strong>Easy token data</strong></td><td>Current holders and balances for any token.</td><td></td></tr><tr><td><i class="fa-filter">:filter:</i> <strong>Search and filter</strong></td><td>Find assets by owner, creator, authority, or collection.</td><td></td></tr><tr><td><i class="fa-shapes">:shapes:</i> <strong>Every asset type</strong></td><td>One interface across regular and programmable NFTs, compressed NFTs, MPL Core, fungible tokens, and Metaplex agent tokens.</td><td></td></tr><tr><td><i class="fa-box-open">:box-open:</i> <strong>Server-side decompression</strong></td><td>Merkle proofs and decompressed metadata for compressed assets, served by the API.</td><td></td></tr></tbody></table>

## Supported methods

The API follows JSON-RPC 2.0. Every method's parameters and example request and response are in the [DAS API reference](https://docs.triton.one/solana/rpc-methods/readme/das-api).

| Method                                                        | Returns                                                                                                                             |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `getAsset`                                                    | A single asset by ID: metadata, ownership, royalty, and collection                                                                  |
| `getAssets` (also `getAssetBatch`)                            | Up to 1000 assets by ID in one call                                                                                                 |
| `getAssetProof`, `getAssetProofs` (also `getAssetProofBatch`) | Merkle proofs for compressed assets. `getAssetProofs` takes up to 1000 IDs                                                          |
| `getAssetsByOwner`                                            | Assets owned by an address                                                                                                          |
| `getAssetsByAuthority`                                        | Assets controlled by an authority                                                                                                   |
| `getAssetsByCreator`                                          | Assets created by a creator address                                                                                                 |
| `getAssetsByGroup`                                            | Assets in a group, for example a collection                                                                                         |
| `searchAssets`                                                | Assets matching your search criteria                                                                                                |
| `getTokenAccounts`                                            | Token accounts by owner or mint. Needs `ownerAddress` or `mintAddress`. Hides zero-balance accounts unless `showZeroBalance` is set |
| `getTokenLargestAccounts`                                     | The 20 largest token accounts for a mint                                                                                            |
| `getNftEditions`                                              | Edition NFTs printed from a master edition                                                                                          |
| `getSignaturesForAsset` (also `getAssetSignatures`)           | Transaction signatures for a compressed asset. Pass `id`, or `tree` and `leafIndex`, not both                                       |

## Get started

DAS is enabled by default on most Triton endpoints. Point DAS calls at your endpoint:

* **Backend:** `https://<your-endpoint>.<network>.rpcpool.com/<your-token>`, or pass your token as an `x-token` header.
* **Frontend:** `https://<your-endpoint>.<network>.rpcpool.com/`, with your domain set as an allowed origin in your [customer dashboard](https://customers.triton.one).

Your [rate and connection limits](https://docs.triton.one/using-your-endpoint/rate-and-connection-limits) apply to DAS calls.

### Fetch an asset

`getAsset` returns one asset by ID. The example uses a Mad Lads NFT, so the response carries the asset's metadata, owner, royalty, and collection:

```bash
curl https://<your-endpoint>.mainnet.rpcpool.com/<your-token> \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getAsset",
    "params": { "id": "F9Lw3ki3hJ7PF9HQXsBzoY8GyE6sPoEZZdXJBsTTD2rk" }
  }'
```

Metaplex publishes a JavaScript DAS client with examples: [digital-asset-standard-api](https://github.com/metaplex-foundation/digital-asset-standard-api/tree/main/clients/js#examples). For the protocol and asset model, see the [Metaplex DAS API documentation](https://www.metaplex.com/docs/dev-tools/das-api).

## Pagination and sorting

Methods that return a list of assets page through results:

| Parameter         | Rule                                                                                                |
| ----------------- | --------------------------------------------------------------------------------------------------- |
| `limit`           | Default `1000`, maximum `1000`.                                                                     |
| `page`            | Starts at `1`. `page: 0` returns an error. Can't be combined with `before`, `after` or `cursor`.    |
| `before`, `after` | Asset IDs to page from. Can't be combined with `cursor`. Work only with `sortBy` `id`, the default. |
| `cursor`          | The cursor from the previous response. Works only with `sortBy` `id`, the default.                  |

`sortBy` is an object: `{ "sortBy": "<field>", "sortDirection": "asc" }`. The field is `id`, `created`, `updated`, `recent_action` or `none`. `sortDirection` is `asc` (default) or `desc`. Any `sortBy` other than `id` needs `page`; without it the call returns a pagination error.

`displayOptions` takes these flags, all `false` by default: `showUnverifiedCollections`, `showCollectionMetadata`, `showZeroBalance`, `showInscription` and `showFungible`.

DAS methods with named parameters reject unknown fields, so a misspelled or misplaced parameter returns an error.

## Fungible tokens and Token-2022

The DAS API indexes all mints and token accounts for the Solana Token Program and the Token Extensions (Token-2022) Program, so you can query token balances, metadata, and program details alongside NFTs.

Balances can be queried across:

* SPL tokens
* Token-2022 tokens
* NFTs, both regular and compressed

These methods cover fungible tokens:

* `getAsset` — details of a specific token mint.
* `getAssetsByOwner` — the tokens held by an account. It returns fungible tokens only when you set `"displayOptions": { "showFungible": true }`.
* `searchAssets` — search with filters, including `tokenType` (`fungible`, `nonFungible`, `regularNFT`, `compressedNFT` or `all`). `tokenType` needs `ownerAddress` and can't be combined with `ownerType` or `interface`.

### Query every token an address holds

```json
{
    "jsonrpc": "2.0",
    "id": "string",
    "method": "searchAssets",
    "params": {
        "ownerAddress": "5aZZ4duJUKiMsJN9vRsoAn4SDX7agvKu7Q3QdFWRfWze",
        "tokenType": "all"
    }
}
```

Each fungible token in the response carries a `token_info` object at the top level of the asset, outside `content`, with its supply, decimals, token program, mint and freeze authorities, balance, and associated token address:

```json
{
    "id": "TokenMintAddress",
    "token_info": {
        "supply": 500000000000,
        "decimals": 9,
        "token_program": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
        "mint_authority": "MintAuthorityPublicKey",
        "freeze_authority": "FreezeAuthorityPublicKey",
        "balance": 1000000000,
        "associated_token_address": "H7iLu4DPFpzEx1AGN8BCN7Qg966YFndt781p6ukhgki9"
    },
    "content": {
        "metadata": {
            "name": "Jito Staked SOL",
            "symbol": "JitoSOL",
            "token_standard": "Fungible"
        }
    }
}
```

### Token-2022 extensions

For Token-2022 mints, the response includes a `mint_extensions` field when applicable. For example, a mint with a transfer fee:

```json
{
    "mint_extensions": {
        "transfer_fee_config": {
            "withheld_amount": 0,
            "older_transfer_fee": {
                "epoch": 450,
                "maximum_fee": 1000000000,
                "transfer_fee_basis_points": 250
            },
            "newer_transfer_fee": {
                "epoch": 500,
                "maximum_fee": 1000000000,
                "transfer_fee_basis_points": 500
            },
            "withdraw_withheld_authority": "AuthorityPublicKey",
            "transfer_fee_config_authority": "AuthorityPublicKey"
        }
    }
}
```

## Pricing

* DAS is billed on requests and bandwidth. For rates, see [pricing](https://triton.one/pricing).
* On shared infrastructure, `getTokenLargestAccounts` is billed as a standard RPC call.
* Your usage per product is in the [customer dashboard](https://customers.triton.one) under **Billing** → **Usage charts**. For how each product is billed, see [How usage is billed](https://docs.triton.one/account-and-billing/plans-and-billing#how-usage-is-billed).

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>DAS API reference</strong></td><td>Parameters and example request and response for every DAS method.</td><td><a href="https://docs.triton.one/solana/rpc-methods/readme/das-api">Metaplex DAS API methods</a></td></tr><tr><td><i class="fa-list-check">:list-check:</i> <strong>Best practices</strong></td><td>Batch, trim, filter and stream account state reads, and handle 429s.</td><td><a href="https://docs.triton.one/solana/reading-account-state/best-practices">Reading account state best practices</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Reading account state best practices

How to read Solana account state: batch getMultipleAccounts, trim with dataSlice, filter getProgramAccounts, set minContextSlot, stream updates, handle 429s.

## Batch and trim your reads

* **Read many accounts in one `getMultipleAccounts` call** instead of many `getAccountInfo` calls. Results come back in input order, with `null` for any address not found.
* **Request only the bytes you need with `dataSlice`** (`{ offset, length }`) rather than the whole account.
* **Set `encoding` to `base64`.** The default `binary` and `base58` encodings only work when the returned data, after any `dataSlice`, is 128 bytes or fewer. Larger data returns `-32600` telling you to switch to `base64`.
* **Filter `getProgramAccounts` with `memcmp` and `dataSize`.** [Cloudbreak](https://docs.triton.one/solana/reading-account-state/cloudbreak-indexed-accounts) creates an index for frequently used filter shapes automatically, with nothing to route or configure. Once an index matches your filter, responses up to 10 MB return in milliseconds on average ([benchmarks](https://docs.triton.one/solana/reading-account-state/cloudbreak-indexed-accounts#benchmarks)); latency grows with the size of the result.

## Read token data the supported way

| Case                                                               | What to do                                                                                                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| To list a wallet's or delegate's token accounts                    | Use `getTokenAccountsByOwner` or `getTokenAccountsByDelegate`, not a raw `getProgramAccounts` over the Token program.                                                                                                                                                                                                                              |
| To list the token accounts of a mint                               | Use `getProgramAccounts` with a `memcmp` on the mint at offset `0`. `getTokenAccountsByMint` isn't available on shared endpoints and returns `-32601`.                                                                                                                                                                                             |
| If you must use `getProgramAccounts` on the original Token program | Include `dataSize: 165` to select only valid token accounts.                                                                                                                                                                                                                                                                                       |
| For Token-2022 (variable size)                                     | Omit `dataSize` and filter on the account-type byte instead: `memcmp` at offset `165` equal to `2` (base58 `3`). This matches only token accounts that have extensions; accounts without extensions are exactly 165 bytes. For request examples, see [Query token program](https://docs.triton.one/solana/quickstart/how-tos/query-token-program). |
| For higher-level filtering of tokens and compressed NFTs           | Use the [Metaplex DAS API](https://docs.triton.one/solana/reading-account-state/metaplex-das-api).                                                                                                                                                                                                                                                 |

{% hint style="warning" %}
On shared endpoints, Token and Token-2022 `getProgramAccounts` calls also need a `memcmp` with the full 32-byte owner pubkey at offset `32` or the full mint pubkey at offset `0`. Calls without one are rejected with HTTP `403`.

If `getProgramAccounts` on the Token or Token-2022 program returns `excluded from account secondary indexes; this RPC method unavailable for key`, check that your query includes the owner or mint `memcmp` filter and, for the original Token program, `dataSize: 165`. For Token-2022, include the account-type `memcmp` (offset `165` equal to `2`) instead. If errors continue, contact support.
{% endhint %}

## Get freshness right

* **Use `confirmed` or `finalized`; on Alpenglow they are the same state and both are final.** `processed` slots can be dropped during minority forks or congestion. Cloudbreak answers `processed` requests for `getProgramAccounts`, `getTokenAccountsByOwner` and `getTokenAccountsByDelegate` at `confirmed`.
* **Use `minContextSlot` to fail fast on stale data.** Pass a slot you have already seen. If the node hasn't reached it, the call fails with `-32016` rather than returning older state. It works on `getAccountInfo`, `getMultipleAccounts`, `getProgramAccounts`, `getTokenAccountsByOwner` and `getTokenAccountsByDelegate`. Not every method accepts it.
* **Use `withContext: true` on `getProgramAccounts`** when you need the slot a result corresponds to. The account, token, and balance methods already include it.

## Stream instead of polling for live data

| If you need                                                       | Use                                                                                                                                                                                                                                                                                                                                   |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Account or transaction changes as they happen                     | [Dragon's Mouth](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc) (Yellowstone gRPC), not polling. Point-in-time reads answer "now"; a stream pushes updates as they occur.                                                                                                                                    |
| Live updates in a browser                                         | [WebSocket](https://docs.triton.one/solana/real-time-streaming/whirligig-websockets). gRPC is server-to-server only and is not supported in web browsers.                                                                                                                                                                             |
| Live account state without rewriting your read code               | Account Sync. Swap in the Triton SDK's `Connection` and add an `accountSync` config, and it keeps account state live in a local buffer fed by a stream, so `getAccountInfo` stays current without polling and without changing your read code. See [Account Sync](https://docs.triton.one/solana/reading-account-state/account-sync). |
| A workload that can't miss data (indexers, analytics, accounting) | [Fumarole](https://docs.triton.one/solana/real-time-streaming/fumarole-persistent-streams). It persists your stream position with 4 days of retention and an at-least-once delivery guarantee, so you can disconnect, resume where you left off, and backfill anything you missed.                                                    |

## Manage client connections

* **Reuse persistent connections; don't open one per request.** Node's built-in `fetch` (undici) doesn't cap connections, so heavy concurrency opens one socket per in-flight request and can exhaust ephemeral ports, causing `fetch failed` / `ECONNRESET` / `Connect Timeout`.
* **Start with a 50-connection pool, then raise it only if all 50 are consistently in use.** For built-in `fetch`, set a global undici dispatcher with `new Agent({ connections: 50 })`. For axios, use an `https.Agent` with `keepAlive: true` and `maxSockets: 50`. Pooling also lowers load on the RPC servers. See [Web3JS socket/connection issues](https://docs.triton.one/solana/faq/error-handling/web3js-socket-connection-issues).

## Stay within rate limits

{% hint style="warning" %}
**On HTTP `429`, pause all requests from that IP for 10 seconds before retrying.** Requests you send during the pause still count. See [Handle 429 rate-limit errors](https://docs.triton.one/solana/faq/error-handling/handle-429-rate-limit-errors).
{% endhint %}

* **Your rate tier sets the request budget for your IP, counted over a rolling 10-second window.** See [Rate and connection limits](https://docs.triton.one/using-your-endpoint/rate-and-connection-limits).
* **Budget expensive methods separately.** Methods such as `getProgramAccounts` can have their own caps, depending on your rate tier. See [Solana per-method limits](https://docs.triton.one/using-your-endpoint/rate-and-connection-limits#solana-per-method-limits).
* **Watch the `X-Ratelimit-*` response headers where your endpoint returns them.**
* **Add `/ratelimits` to your endpoint URL to see your limits.** See [Check your limits](https://docs.triton.one/using-your-endpoint/rate-and-connection-limits#check-your-limits).

{% hint style="danger" %}
**Send backend requests with a token and browser requests from an allowed origin.** Never put a token in frontend code.
{% endhint %}

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Real-time streaming

Choose a Triton Solana stream: Dragon's Mouth gRPC, Riptide, Deshred, Shred Streaming, Preconfirmations, WebSocket, or Fumarole.

Solana produces a new block several times per second. If you poll RPC every 200 ms, your data can be up to 200 ms old when you see it, and you'll easily hit rate limits when hammering the same endpoint.

Streaming inverts the model: you open one connection, say what you need (specific accounts, programs, or transactions), and the node pushes you matching events as they happen.

{% columns %}
{% column %}

```mermaid
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#F2EDF6','primaryBorderColor':'#7A4BA0','primaryTextColor':'#171717','lineColor':'#956FB3','actorBkg':'#F2EDF6','actorBorder':'#7A4BA0','actorTextColor':'#171717','signalColor':'#956FB3','signalTextColor':'#171717','noteBkgColor':'#F2EDF6','noteBorderColor':'#7A4BA0','noteTextColor':'#171717','labelBoxBkgColor':'#E4DBEC','labelBoxBorderColor':'#7A4BA0'}}}%%
sequenceDiagram
    participant C as Your app
    participant S as RPC
    C->>S: getAccountInfo
    S-->>C: stale data
    C->>S: getAccountInfo
    S-->>C: stale data
    C->>S: getAccountInfo
    S-->>C: 429 Too Many Requests
```

{% endcolumn %}

{% column %}

```mermaid
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#F2EDF6','primaryBorderColor':'#7A4BA0','primaryTextColor':'#171717','lineColor':'#956FB3','actorBkg':'#F2EDF6','actorBorder':'#7A4BA0','actorTextColor':'#171717','signalColor':'#956FB3','signalTextColor':'#171717','noteBkgColor':'#F2EDF6','noteBorderColor':'#7A4BA0','noteTextColor':'#171717','labelBoxBkgColor':'#E4DBEC','labelBoxBorderColor':'#7A4BA0'}}}%%
sequenceDiagram
    participant C as Your app
    participant S as Node
    Note over C,S: one handshake
    C->>S: subscribe + filters
    S-->>C: event (intra-slot)
    S-->>C: event
    S-->>C: event
```

{% endcolumn %}
{% endcolumns %}

Dragon's Mouth, Riptide, and the WebSocket `accountSubscribe` and `programSubscribe` methods send intra-slot updates at `processed`, and the gRPC products return structured Protobuf payloads.

For teams with heavy polling codebases, [Account Sync](https://docs.triton.one/solana/reading-account-state/account-sync) in the Triton SDK serves account reads from memory: swap in the SDK's `Connection`, add an `accountSync` config, and call `close()` when done.

Streaming needs a high-bandwidth internet connection and a fast client environment. Frequent disconnections are a sign of a weak client setup. See streaming [best practices](https://docs.triton.one/solana/real-time-streaming/best-practices).

## Triton streaming stack

Triton built Yellowstone gRPC, the open-source Geyser plugin behind Dragon's Mouth, and also runs Deshred, Riptide, Shred Streaming, Preconfirmations, the Solana WebSocket API, and Fumarole. At production scale, running on Triton gives you:

* **Separate streaming clusters.** Streaming runs on its own host groups, apart from the shared RPC pool.
* **Several shred sources.** Deshred and Shred Streaming ingest shreds from Triton's validators, DoubleZero Edge, partner validators, and Turbine.
* **Anycast across 8 points of presence.** On standard mainnet endpoints, gRPC and WebSocket connections reach the closest of Triton's 8 cities in network terms (Salt Lake City, New York, Pittsburgh, Amsterdam, Frankfurt, London, Singapore, Tokyo), with health checks and failover for new connections. Fumarole connects to regional endpoints, and Shred Streaming runs in five regions; see each product page.
* **Separate services.** Dragon's Mouth, WebSocket, and Fumarole each run as their own service.

## Pick your stream

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-radio">:radio:</i> <strong>Dragon's Mouth gRPC</strong></td><td>Sub-slot account and transaction updates, plus slot and block updates, via gRPC.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc">Dragon's Mouth gRPC</a></td></tr><tr><td><i class="fa-water">:water:</i> <strong>Riptide</strong></td><td>Dragon's Mouth gRPC over a lower-latency path. Same streams, filters, and SDKs on shared subscriptions.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/riptide">Riptide</a></td></tr><tr><td><i class="fa-satellite-dish">:satellite-dish:</i> <strong>Shred Streaming</strong></td><td>Deduplicated raw shreds delivered to your servers in five regions before blocks are assembled. Available on request.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/shred-streaming">Shred Streaming</a></td></tr><tr><td><i class="fa-fire">:fire:</i> <strong>Deshred Transactions gRPC</strong></td><td>Transactions reconstructed from raw shreds before the node executes them, over gRPC.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/deshred-transactions">Deshred Transactions gRPC</a></td></tr><tr><td><i class="fa-stopwatch">:stopwatch:</i> <strong>Preconfirmations gRPC</strong></td><td>Preconfirmed transactions over gRPC from Harmonic and BAM, before any shred exists. Enabled on request.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc">Preconfirmations gRPC</a></td></tr><tr><td><i class="fa-rotate-right">:rotate-right:</i> <strong>WebSocket</strong></td><td>Triton's Solana WebSocket API for browsers and frontends, served from Dragon's Mouth gRPC, with <code>transactionSubscribe</code>.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/whirligig-websockets">WebSocket</a></td></tr><tr><td><i class="fa-layer-group">:layer-group:</i> <strong>Fumarole Persistent gRPC</strong></td><td>Redundant streaming layer with 4 days of stored data and built-in cursor resume.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/fumarole-persistent-streams">Fumarole Persistent gRPC</a></td></tr></tbody></table>

* **Dragon's Mouth** is the base gRPC stream for live data, with **Deshred**, a separate method on the same gRPC service, giving you pre-execution transactions.
* **Riptide** serves Dragon's Mouth over a lower-latency path on shared subscriptions.
* **Shred Streaming** delivers raw shreds to your own servers before blocks are assembled.
* **Preconfirmations gRPC** streams preconfirmed transactions from the Harmonic and BAM block production systems, before any shred exists.
* **WebSocket** serves Dragon's Mouth data as Solana WebSocket notifications. Use it in browsers, where gRPC is not supported.
* **Fumarole** consumes multiple Dragon's Mouth nodes, deduplicates, and stores your cursor on the server side so you can resume from where you left off after a disconnect.
  * Within a region, consumers see the same data for a given slot. Fumarole does not guarantee the same event order across connections or reconnects.
  * Use the Rust or TypeScript client instead of calling Fumarole's gRPC methods directly.

| Capability                             | Dragon's Mouth |    Riptide    |       Shred Streaming      | Deshred tx | Preconfirmations | WebSocket | Fumarole |
| -------------------------------------- | :------------: | :-----------: | :------------------------: | :--------: | :--------------: | :-------: | :------: |
| Real-time data                         |        ✓       |       ✓       |              ✓             |      ✓     |         ✓        |     ✓     |     ✓    |
| Data before the node replays the block |        ✗       |       ✗       |              ✓             |      ✓     |         ✓        |     ✗     |     ✗    |
| Historical replay                      |  \~1,000 slots | \~1,000 slots |              ✗             |      ✗     |         ✗        |     ✗     |  4 days  |
| Persistent cursor                      |        ✗       |       ✗       |              ✗             |      ✗     |         ✗        |     ✗     |     ✓    |
| Browser-compatible                     |        ✗       |       ✗       |              ✗             |      ✗     |         ✗        |     ✓     |     ✗    |
| Commitment                             |       all      |      all      |              ✗             |      ✗     |         ✗        |    all    |    all   |
| Protocol                               |      gRPC      |      gRPC     | Shreds to your IP and port |    gRPC    |       gRPC       | WebSocket |   gRPC   |

On Dragon's Mouth and Riptide, stream at `processed` and track `confirmed` and `finalized` yourself from slot updates, instead of asking the server to buffer by commitment. A slots subscription sends an update for each of the three statuses by default. Setting `filter_by_commitment` to `true` limits it to the request's commitment level. On Alpenglow clusters, a block's `confirmed` and `finalized` slot updates arrive back to back.

It's normal to combine more than one product in a pipeline. Open one connection per Dragon's Mouth, Riptide, or Deshred stream, for example Dragon's Mouth and Deshred on separate connections. Streams that share one TCP connection are all delayed when a packet is lost (head-of-line blocking). Some setups break behind Triton's load balancer. Common patterns:

| Pattern                               | Use                                                                                                                                                                                                                                          |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Trading and MEV**                   | Riptide or Dragon's Mouth gRPC for processed data, Deshred for pre-execution transactions, Shred Streaming or Preconfirmations gRPC for data before the block is complete                                                                    |
| **DEX or wallet frontend**            | WebSocket for frontend updates, Dragon's Mouth gRPC for backend setups                                                                                                                                                                       |
| **Indexer, analytics, or compliance** | Fumarole for reliable, persistent data with automatic backfill of 4 days of data, and Jetstreamer with the public Old Faithful archive for bulk historical backfills (see [Historical data](https://docs.triton.one/solana/historical-data)) |

## Limitations

Accounts owned by the Light Protocol program are excluded from all our streams, and `getProgramAccounts` is unavailable for it. At peak load, it accounted for over 50% of all Geyser traffic, making it impractical to include in standard streams.

| Program                         | Address                                       |
| ------------------------------- | --------------------------------------------- |
| Light Protocol / ZK Compression | `compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq` |

## Pricing

On shared infrastructure, Dragon's Mouth, Riptide, WebSocket, and Fumarole are billed on bandwidth, not per request. See [triton.one/pricing](https://triton.one/pricing) for rates by product, and streaming [best practices](https://docs.triton.one/solana/real-time-streaming/best-practices) for filtering, guides, and other ways to reduce bandwidth.

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-play">:play:</i> <strong>Streaming quickstart</strong></td><td>Connect, subscribe, and verify a live stream with Dragon's Mouth, WebSocket, Fumarole, or Deshred.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/quickstart">Real-time streaming quickstart</a></td></tr><tr><td><i class="fa-arrows-rotate">:arrows-rotate:</i> <strong>Account Sync</strong></td><td>Reads of tracked accounts in the TypeScript and Rust SDKs resolve from memory, kept current by a Triton stream.</td><td><a href="https://docs.triton.one/solana/reading-account-state/account-sync">Account Sync</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Real-time streaming quickstart

Install a client, subscribe, and verify a live Solana stream with Yellowstone gRPC (Dragon's Mouth), WebSocket, Fumarole, or Deshred Transactions.

| Service                                                                                                        | What it is                                                                                                                                                                                 |
| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [**Dragon's Mouth gRPC**](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc)              | Also called Yellowstone gRPC. Sub-slot real-time updates for accounts, transactions, slots, and blocks over gRPC. Use for backends. Browsers can't use gRPC.                               |
| [**WebSocket**](https://docs.triton.one/solana/real-time-streaming/whirligig-websockets)                       | Solana WebSocket API served from Dragon's Mouth gRPC. Use for browsers and frontends.                                                                                                      |
| [**Fumarole Persistent gRPC**](https://docs.triton.one/solana/real-time-streaming/fumarole-persistent-streams) | A redundant streaming layer with a server-side cursor, auto-backfill on reconnect (4 days of stored data), and at-least-once delivery, for indexers and pipelines that need complete data. |
| [**Deshred Transactions gRPC**](https://docs.triton.one/solana/real-time-streaming/deshred-transactions)       | Pre-execution transactions reconstructed from raw shreds before the node's replay stage.                                                                                                   |

## 0. Prerequisites

{% hint style="warning" %}
The samples below authenticate with a secret token. Never put the secret token in frontend code: browser apps use the endpoint URL alone, authorized by [allowed origins](https://docs.triton.one/security/authentication#allowed-origins-frontend).
{% endhint %}

* An active Triton subscription
* Your endpoint URL and secret token from the [customer dashboard](https://customers.triton.one/)
* An environment in TypeScript or Rust. For Go, Python, and other languages, see [yellowstone-grpc/examples](https://github.com/rpcpool/yellowstone-grpc/tree/master/examples).

## 1. Install

{% tabs %}
{% tab title="Dragon’s Mouth" %}
{% tabs %}
{% tab title="TypeScript" %}

```bash
mkdir solana-grpc-stream && cd solana-grpc-stream
npm init --yes && npm pkg set type=module
npm install @triton-one/yellowstone-grpc
npm install --save-dev typescript tsx @types/node
npx tsc --init --module esnext --moduleResolution bundler --types node
```

{% endtab %}

{% tab title="Rust" %}

```bash
cargo new solana-grpc-stream && cd solana-grpc-stream
```

{% code title="Cargo.toml" %}

```toml
[dependencies]
yellowstone-grpc-client = "17"
yellowstone-grpc-proto = "14"
tokio = { version = "1", features = ["full"] }
futures = "0.3"
tonic = { version = "0.14", features = ["tls-native-roots", "tls-ring"] }
anyhow = "1"
```

{% endcode %}
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="WebSocket" %}
{% tabs %}
{% tab title="TypeScript" %}

```bash
mkdir websocket-stream && cd websocket-stream
npm init --yes && npm pkg set type=module
npm install ws
npm install --save-dev typescript tsx @types/node @types/ws
npx tsc --init --module esnext --moduleResolution bundler --types node
```

{% endtab %}

{% tab title="Rust" %}
Uses Solana's `PubsubClient` from `solana-pubsub-client`. `solana-pubsub-client` 4.3 needs Rust 1.97.1 or later.

```bash
cargo new websocket-stream && cd websocket-stream
```

{% code title="Cargo.toml" %}

```toml
[dependencies]
solana-pubsub-client = "4"
solana-rpc-client-types = "4"
solana-account-decoder-client-types = "4"
solana-pubkey = "4"
solana-commitment-config = "3"
anyhow = "1"
tokio = { version = "1", features = ["full"] }
futures = "0.3"
rustls = { version = "0.23", default-features = false, features = ["ring"] } # TLS crypto provider for wss://
```

{% endcode %}
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="Fumarole" %}
{% tabs %}
{% tab title="TypeScript" %}
The Fumarole TypeScript client requires Node.js 22 or later.

```bash
mkdir fumarole-stream && cd fumarole-stream
npm init --yes && npm pkg set type=module
npm install @triton-one/yellowstone-fumarole-client
npm install --save-dev typescript tsx @types/node
npx tsc --init --module esnext --moduleResolution bundler --types node
```

{% endtab %}

{% tab title="Rust" %}

```bash
cargo new fumarole-stream && cd fumarole-stream
```

{% code title="Cargo.toml" %}

```toml
[dependencies]
yellowstone-fumarole-client = "0.9"
serde_yaml = "0.9"
anyhow = "1"
yellowstone-grpc-proto = "14"
tokio = { version = "1", features = ["full"] }
futures = "0.3"
```

{% endcode %}
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="Deshred" %}
{% tabs %}
{% tab title="TypeScript" %}

```bash
mkdir deshred-stream && cd deshred-stream
npm init --yes && npm pkg set type=module
npm install @triton-one/yellowstone-grpc
npm install --save-dev typescript tsx @types/node
npx tsc --init --module esnext --moduleResolution bundler --types node
```

{% endtab %}

{% tab title="Rust" %}

```bash
cargo new deshred-stream && cd deshred-stream
```

{% code title="Cargo.toml" %}

```toml
[dependencies]
yellowstone-grpc-client = "17"
yellowstone-grpc-proto = "14"
solana-signature = "3"
tokio = { version = "1", features = ["full"] }
futures = "0.3"
tonic = { version = "0.14", features = ["tls-native-roots", "tls-ring"] }
anyhow = "1"
```

{% endcode %}
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## 2. Connect and subscribe

{% tabs %}
{% tab title="Dragon’s Mouth" %}
**What we're doing:** connect to the endpoint, stream at the `processed` commitment level, subscribe to slot updates and to all writes on a specific account (the USDC mint), and log each Protobuf-decoded update.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import Client from "@triton-one/yellowstone-grpc";

const client = new Client(
  "https://<your-endpoint>.mainnet.rpcpool.com",
  "<your-token>",
  undefined
);

await client.connect();

const version = await client.getVersion();
console.log(version);
```

{% endtab %}

{% tab title="Rust" %}

```rust
use {
    futures::stream::StreamExt,
    std::collections::HashMap,
    tonic::transport::channel::ClientTlsConfig,
    yellowstone_grpc_client::GeyserGrpcClient,
    yellowstone_grpc_proto::prelude::{
        CommitmentLevel, SubscribeRequest, SubscribeRequestFilterAccounts,
        SubscribeRequestFilterSlots,
    },
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let endpoint = "https://<your-endpoint>.mainnet.rpcpool.com:443";
    let x_token = "<your-token>";

    let mut client = GeyserGrpcClient::build_from_shared(endpoint)?
        .x_token(Some(x_token))?
        .tls_config(ClientTlsConfig::new().with_native_roots())?
        .connect()
        .await?;

    let version = client.get_version().await?;
    println!("{:?}", version);
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import { CommitmentLevel, SubscribeRequest } from "@triton-one/yellowstone-grpc";

const stream = await client.subscribe();

stream.on("data", (data) => {
  console.log("data", data);
});

const request: SubscribeRequest = {
  slots: { slots: {} },
  accounts: {
    "usdc": {
      account: ["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"],
      owner: [],
      filters: [],
    },
  },
  transactions: {},
  transactionsStatus: {},
  entry: {},
  blocks: {},
  blocksMeta: {},
  blockFooter: {},
  accountsDataSlice: [],
  commitment: CommitmentLevel.PROCESSED,
  ping: undefined,
};

await new Promise<void>((resolve, reject) => {
  stream.write(request, (err) => {
    if (err === null || err === undefined) {
      resolve();
    } else {
      reject(err);
    }
  });
}).catch((reason) => {
  console.error(reason);
  throw reason;
});
```

{% endtab %}

{% tab title="Rust" %}

```rust
    let mut accounts = HashMap::new();
    accounts.insert(
        "usdc".to_string(),
        SubscribeRequestFilterAccounts {
            account: vec!["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v".to_string()],
            owner: vec![],
            filters: vec![],
            ..Default::default()
        },
    );

    let mut slots = HashMap::new();
    slots.insert("client".to_string(), SubscribeRequestFilterSlots::default());

    let request = SubscribeRequest {
        accounts,
        slots,
        commitment: Some(CommitmentLevel::Processed.into()),
        ..Default::default()
    };

    let (_sink, mut stream) = client.subscribe_with_request(Some(request)).await?;

    while let Some(message) = stream.next().await {
        println!("data: {:?}", message?);
    }

    Ok(())
}
```

{% endtab %}

{% tab title="grpcurl" %}

```shell
./grpcurl \
  -import-path . \
  -proto geyser.proto \
  -d '{"slots": { "slots": {} }, "accounts": { "usdc": { "account": ["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"] } }, "transactions": {}, "blocks": {}, "blocks_meta": {}}' \
  -H "x-token: <your-token>" \
  <your-endpoint>.mainnet.rpcpool.com:443 \
  geyser.Geyser/Subscribe
```

Download `geyser.proto` and `solana-storage.proto` from the [proto directory](https://github.com/rpcpool/yellowstone-grpc/tree/master/yellowstone-grpc-proto/proto) into the current folder.
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="WebSocket" %}
**What we're doing:** open a WebSocket connection to your endpoint and subscribe to changes on the system clock sysvar.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import WebSocket from "ws";

const ws = new WebSocket(
  "wss://<your-endpoint>.mainnet.rpcpool.com/<your-token>"
);

ws.on("open", () => {
  ws.send(
    JSON.stringify({
      jsonrpc: "2.0",
      id: 1,
      method: "accountSubscribe",
      params: [
        "SysvarC1ock11111111111111111111111111111111",
        { commitment: "processed", encoding: "base58" },
      ],
    })
  );
});

ws.on("message", (data) => {
  console.log("Update:", JSON.parse(data.toString()));
});
```

{% endtab %}

{% tab title="Rust" %}

```rust
use {
    futures::StreamExt,
    solana_account_decoder_client_types::UiAccountEncoding,
    solana_commitment_config::CommitmentConfig,
    solana_pubkey::Pubkey,
    solana_pubsub_client::nonblocking::pubsub_client::PubsubClient,
    solana_rpc_client_types::config::RpcAccountInfoConfig,
    std::str::FromStr,
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let endpoint =
        "wss://<your-endpoint>.mainnet.rpcpool.com/<your-token>";

    let client = PubsubClient::new(endpoint).await?;

    let pubkey = Pubkey::from_str("SysvarC1ock11111111111111111111111111111111")?;
    let config = RpcAccountInfoConfig {
        encoding: Some(UiAccountEncoding::Base58),
        commitment: Some(CommitmentConfig::processed()),
        ..Default::default()
    };

    let (mut stream, _unsubscribe) =
        client.account_subscribe(&pubkey, Some(config)).await?;

    while let Some(account) = stream.next().await {
        println!("Update: {:?}", account);
    }

    Ok(())
}
```

{% endtab %}
{% endtabs %}

The WebSocket endpoint follows the [standard Solana WebSocket API](https://solana.com/docs/rpc/websocket) and adds `transactionSubscribe`, a Triton extension. Full method reference: [WebSocket](https://docs.triton.one/solana/real-time-streaming/whirligig-websockets).
{% endtab %}

{% tab title="Fumarole" %}
**What we're doing:** connect to a regional Fumarole endpoint (`ams.rpcpool.com` for Europe, `nyc.rpcpool.com` for the US), use a persistent subscriber, and stream account writes and transactions for the SPL Token program (the TypeScript sample creates the subscriber; the Rust sample streams account writes only and expects the subscriber to exist).

* Don't call Fumarole's gRPC methods directly. Connect with the Rust or TypeScript client.
* Reconnecting with the same subscriber name resumes from where the cursor left off.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import {
  FumaroleClient,
  CommitmentLevel,
  SubscribeRequest,
} from "@triton-one/yellowstone-fumarole-client";

const TOKEN_ADDRESS = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
const subscriberName = "helloworld";

const client = await FumaroleClient.connect({
  endpoint: process.env.FUMAROLE_ENDPOINT!, // e.g. https://ams.rpcpool.com
  xToken: process.env.FUMAROLE_X_TOKEN!,
  maxDecodingMessageSizeBytes: 100 * 1024 * 1024,
});
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="TypeScript" %}

```typescript
const request: SubscribeRequest = {
  commitment: CommitmentLevel.PROCESSED,
  accounts: {
    token: {
      account: [],
      owner: [TOKEN_ADDRESS],
      filters: [],
    },
  },
  transactions: {
    token: {
      accountInclude: [TOKEN_ADDRESS],
      accountExclude: [],
      accountRequired: [],
    },
  },
  slots: { test: {} },
  transactionsStatus: {},
  blocks: {},
  blocksMeta: {},
  entry: {},
  blockFooter: {},
  ping: undefined,
  accountsDataSlice: [],
  fromSlot: undefined,
};
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="TypeScript" %}

```typescript
// Create the persistent subscriber on the first run; later runs resume from its cursor.
if ((await client.getConsumerGroupInfo(subscriberName)) === null) {
  await client.createConsumerGroup(subscriberName);
}

const subscription = await client.subscribe(subscriberName, request);

for await (const event of subscription) {
  if (event.type === "data") {
    console.log("Update:", event.update);
  }
}
```

{% endtab %}

{% tab title="Rust" %}
This sample does not create the persistent subscriber. Create `helloworld` first, for example with the Fume CLI (see [Get started](https://docs.triton.one/solana/real-time-streaming/fumarole-persistent-streams#get-started)). `subscribe` fails with `NOT_FOUND` if the subscriber does not exist.

```rust
use {
    futures::StreamExt,
    yellowstone_fumarole_client::{config::FumaroleConfig, FumaroleClient},
    yellowstone_grpc_proto::geyser::{
        CommitmentLevel, SubscribeRequest, SubscribeRequestFilterAccounts,
        subscribe_update::UpdateOneof,
    },
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config: FumaroleConfig = serde_yaml::from_str(&format!(
        "endpoint: {}\nx-token: {}",
        std::env::var("FUMAROLE_ENDPOINT")?,
        std::env::var("FUMAROLE_X_TOKEN")?,
    ))?;
    let mut client = FumaroleClient::connect(config).await?;

    let mut accounts = std::collections::HashMap::new();
    accounts.insert(
        "token".to_string(),
        SubscribeRequestFilterAccounts {
            account: vec![],
            owner: vec!["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA".into()],
            filters: vec![],
            ..Default::default()
        },
    );

    let request = SubscribeRequest {
        accounts,
        commitment: Some(CommitmentLevel::Processed.into()),
        ..Default::default()
    };

    let subscription = client
        .subscribe("helloworld", request)
        .await?;

    let (_sink, source) = subscription.split();
    let mut source = source.like_dragonsmouth();
    while let Some(update) = source.next().await {
        if let Some(UpdateOneof::Account(acc)) = update?.update_oneof {
            println!("Account update at slot {}", acc.slot);
        }
    }

    Ok(())
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="Deshred" %}
**What we're doing:** subscribe to the `SubscribeDeshred` gRPC stream (a separate method in the same client library as Dragon's Mouth), filter out vote transactions, and log every transaction signature with its slot.

Deshred delivers transactions reconstructed from shreds ***before*** the node executes them, so you see them earlier than on a Dragon's Mouth `transactions` stream at processed.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import Client, {
  SubscribeDeshredRequest,
} from "@triton-one/yellowstone-grpc";

const client = new Client(
  "https://<your-endpoint>.mainnet.rpcpool.com",
  "<your-token>",
  undefined
);

await client.connect();
const stream = await client.subscribeDeshred();

stream.on("data", (data) => {
  console.log("data", data);
});

const request: SubscribeDeshredRequest = {
  slots: {},
  deshredTransactions: {
    client: {
      vote: false,
      accountInclude: [],
      accountExclude: [],
      accountRequired: [],
    },
  },
  ping: undefined,
};

await new Promise<void>((resolve, reject) => {
  stream.write(request, (err) =>
    err ? reject(err) : resolve()
  );
});
```

{% endtab %}

{% tab title="Rust" %}

```rust
use {
    futures::{sink::SinkExt, stream::StreamExt},
    solana_signature::Signature,
    std::collections::HashMap,
    tonic::transport::channel::ClientTlsConfig,
    yellowstone_grpc_client::GeyserGrpcClient,
    yellowstone_grpc_proto::prelude::{
        subscribe_update_deshred::UpdateOneof, SubscribeDeshredRequest,
        SubscribeRequestFilterDeshredTransactions, SubscribeRequestPing,
    },
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let endpoint = std::env::var("ENDPOINT")
        .unwrap_or("https://<your-endpoint>".into());
    let x_token = std::env::var("X_TOKEN").ok();

    let mut client = GeyserGrpcClient::build_from_shared(endpoint)?
        .x_token(x_token)?
        .tls_config(ClientTlsConfig::new().with_native_roots())?
        .http2_adaptive_window(true)
        .initial_connection_window_size(8 * 1024 * 1024)
        .initial_stream_window_size(4 * 1024 * 1024)
        .connect()
        .await?;

    let request = SubscribeDeshredRequest {
        deshred_transactions: HashMap::from([(
            "deshred".into(),
            SubscribeRequestFilterDeshredTransactions {
                vote: Some(false),
                account_include: vec![],
                account_exclude: vec![],
                account_required: vec![],
                ..Default::default()
            },
        )]),
        ping: None,
        ..Default::default()
    };

    let (mut tx, mut stream) =
        client.subscribe_deshred_with_request(Some(request)).await?;

    while let Some(msg) = stream.next().await {
        match msg?.update_oneof {
            Some(UpdateOneof::DeshredTransaction(update)) => {
                let info = update.transaction.as_ref().unwrap();
                let sig = Signature::try_from(info.signature.as_slice())?;
                println!("slot={} sig={sig} vote={}", update.slot, info.is_vote);
            }
            Some(UpdateOneof::Ping(_)) => {
                tx.send(SubscribeDeshredRequest {
                    ping: Some(SubscribeRequestPing { id: 1 }),
                    ..Default::default()
                })
                .await?;
            }
            Some(UpdateOneof::Pong(_)) => {}
            Some(UpdateOneof::Slot(_)) => {}
            // Other update types, such as update parents, arrive only if you opt in
            Some(_) => {}
            None => break,
        }
    }

    Ok(())
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## 3. Verify your stream

{% tabs %}
{% tab title="TypeScript" %}
Save the TypeScript code blocks for your service from step 2, in order, as `main.ts`.

```bash
npx tsx main.ts
```

{% endtab %}

{% tab title="Rust" %}
Save the Rust code blocks for your service from step 2, in order, as `src/main.rs`.

```bash
cargo run
```

{% endtab %}
{% endtabs %}

Then walk through this checklist:

1. **Confirm the stream is open.** Dragon's Mouth sends a slot update within a few slots; other filters send an update when a match occurs. For WebSocket, you'll see a subscription-ID confirmation first: `{ "jsonrpc": "2.0", "result": 42, "id": 1 }`.
2. **Watch matching events flow.** If nothing arrives, your filter is probably too narrow.
3. **Keep long-lived connections alive.** Idle WebSocket connections are closed after about 60 seconds. Send `{"jsonrpc":"2.0","method":"ping"}` (no `id`) periodically. Dragon's Mouth streams can also be closed when idle, since some cloud providers, such as Cloudflare, close idle streams, so send a periodic ping. See [Sending pings](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc#sending-pings).
4. **Widen the filter to test, then tighten back.** Subscribe to all transactions or all writes for a busy program (e.g. SPL Token) to confirm data is reaching you. Once you see traffic, narrow the filter to what your app actually needs.

### Expected first message

{% tabs %}
{% tab title="Dragon’s Mouth" %}
A Protobuf-decoded `SubscribeUpdate`. Each message has the matching filter labels and one payload, such as `account`, `slot`, `transaction`, `transactionStatus`, `block`, `blockMeta`, `entry`, `blockFooter`, `ping`, or `pong`. With this request, expect `slot` and `account` updates. Slot updates carry a `status` (`SLOT_PROCESSED`, `SLOT_CONFIRMED`, or `SLOT_FINALIZED`), so stream at processed and track confirmed and finalized from these updates in your client. The Rust sample prints the same fields in Debug format. Account-update example:

```
data {
  filters: [ 'usdc' ],
  account: {
    account: {
      pubkey: <Buffer ...>,
      lamports: '...',
      owner: <Buffer ...>,
      executable: false,
      rentEpoch: '18446744073709551615',
      data: <Buffer ...>,
      writeVersion: '...'
    },
    slot: '275123456',
    isStartup: false
  }
}
```

{% endtab %}

{% tab title="WebSocket" %}
First, a subscription-ID confirmation:

```json
{ "jsonrpc": "2.0", "result": 42, "id": 1 }
```

Then JSON-RPC notifications matching the standard Solana WebSocket API. Account-notification example:

```json
{
  "jsonrpc": "2.0",
  "method": "accountNotification",
  "params": {
    "result": {
      "context": { "slot": 275123456 },
      "value": {
        "lamports": 1169280,
        "owner": "Sysvar1111111111111111111111111111111111111",
        "data": ["9AAG2zomYcUVKQfondw13yz193crQ5R5...", "base58"],
        "executable": false,
        "rentEpoch": 18446744073709551615
      }
    },
    "subscription": 42
  }
}
```

{% endtab %}

{% tab title="Fumarole" %}
A Protobuf `SubscribeUpdate` delivered through the persistent subscriber. The first event is whatever's at the subscriber's cursor (latest, in this example). Reconnecting with the same subscriber name resumes from your last committed position. Delivery is at-least-once, so you can receive recent events again, and event order across reconnects is not guaranteed. The TypeScript sample logs each update, for example a transaction update; the Rust sample prints one `Account update at slot <slot>` line per account write:

```
Update: {
  filters: [ 'token' ],
  transaction: {
    transaction: {
      signature: <Buffer ...>,
      isVote: false,
      transaction: {...},
      meta: {...}
    },
    slot: '275123456'
  }
}
```

{% endtab %}

{% tab title="Deshred" %}
The Rust sample prints one line per pre-execution transaction, with slot, signature, and vote flag. The TypeScript sample logs each raw update object. These transactions have not yet been executed by the validator; they may still fail or land on a dead fork. For status, logs, balance changes, or compute units, run a normal Dragon's Mouth `transactions` subscription at processed, on a separate connection:

```
slot=275123456 sig=5j7s4Hk3...QmZ9xT vote=false
slot=275123456 sig=2pK8nLm9...VbY3wQ vote=false
slot=275123457 sig=8aRf6dGj...XwE5pN vote=false
```

{% endtab %}
{% endtabs %}

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-tower-broadcast">:tower-broadcast:</i> <strong>Dragon's Mouth gRPC</strong></td><td>Sub-slot real-time updates for accounts, transactions, slots, and blocks via gRPC.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc">Dragon's Mouth gRPC</a></td></tr><tr><td><i class="fa-fire">:fire:</i> <strong>Deshred Transactions gRPC</strong></td><td>Pre-execution transactions reconstructed from raw shreds.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/deshred-transactions">Deshred Transactions gRPC</a></td></tr><tr><td><i class="fa-rotate-right">:rotate-right:</i> <strong>WebSocket</strong></td><td>Triton's Solana WebSocket API for browsers and frontends, served from Dragon's Mouth gRPC, with <code>transactionSubscribe</code>.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/whirligig-websockets">WebSocket</a></td></tr><tr><td><i class="fa-layer-group">:layer-group:</i> <strong>Fumarole Persistent gRPC</strong></td><td>Redundant streaming layer with 4 days of stored data and built-in cursor resume.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/fumarole-persistent-streams">Fumarole Persistent gRPC</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Dragon's Mouth gRPC

Dragon's Mouth is Triton's Yellowstone gRPC stream, with Subscribe filters, replay, and reconnect for Solana account, transaction, slot, and block updates.

Dragon's Mouth (or Yellowstone gRPC) taps the validator's Geyser plugin directly, so you get account, transaction, slot, and block updates as the validator processes them, ahead of JSON-RPC polling.

## Use cases

Dragon's Mouth is the gRPC stream for backend services that need low-latency `processed` updates.

* **Trading, MEV, market making, and bots.** Low-latency reads of pool state, oracles, AMM accounts, and price-impacting transactions.
* **DeFi backends.** Live pool, order-book, and account state for services that react to the chain in real time.
* **Real-time UIs (backend).** Live balances, transaction feeds, and account state for backends that proxy to wallets and explorers.

{% hint style="info" %}
**When not to use it:**

* Browsers and frontends cannot speak gRPC. Use [WebSocket](https://docs.triton.one/solana/real-time-streaming/whirligig-websockets) instead.
* If your pipeline cannot miss a block (indexing, analytics, compliance), use [Fumarole](https://docs.triton.one/solana/real-time-streaming/fumarole-persistent-streams), which guarantees at-least-once delivery and auto-backfills up to 4 days of data on reconnect.
  {% endhint %}

## Features and benefits

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-timer">:timer:</i> <strong>Sub-slot latency</strong></td><td>Intra-slot updates arrive ahead of JSON-RPC polling. You receive multiple account updates within the current slot.</td><td></td></tr><tr><td><i class="fa-filter">:filter:</i> <strong>Server-side filtering</strong></td><td>Filter by pubkey, program owner, signature, memcmp, datasize, lamports, or token-account state, all server-side.</td><td></td></tr><tr><td><i class="fa-right-left">:right-left:</i> <strong>Bi-directional streams</strong></td><td>Modify subscriptions on the fly without reconnecting. Send a new request, server swaps your filter set.</td><td></td></tr><tr><td><i class="fa-feather">:feather:</i> <strong>Compact Protobuf payloads</strong></td><td>Binary serialization cuts bandwidth and CPU.</td><td></td></tr><tr><td><i class="fa-compress">:compress:</i> <strong>Compressed account filters</strong></td><td>Track millions of accounts with a Cuckoo-filter set instead of a raw pubkey list, cutting subscription payloads ~10x.</td><td></td></tr><tr><td><i class="fa-arrows-rotate">:arrows-rotate:</i> <strong>Reconnect with bank recovery</strong></td><td>The Rust and TS clients can reconnect a stream for you, replay from the last confirmed slot seen, and flag partly delivered banks to discard.</td><td></td></tr></tbody></table>

## How it works

You open a gRPC stream, send a `SubscribeRequest` describing the accounts, transactions, slots, blocks, or entries you want, and matching updates arrive as protobuf messages at your chosen commitment level (`processed`, `confirmed`, or `finalized`).

The same stream accepts updated requests, the service answers one-shot unary calls, and on reconnect you can replay from a recent slot (`from_slot`) within the server's replay window.

```mermaid
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#F2EDF6','primaryBorderColor':'#7A4BA0','primaryTextColor':'#171717','lineColor':'#956FB3','secondaryColor':'#E4DBEC','tertiaryColor':'#D7C9E3','edgeLabelBackground':'#F2EDF6'},'flowchart':{'nodeSpacing':20,'rankSpacing':35,'curve':'linear'}}}%%
flowchart LR
    v["Validator<br/>(Geyser plugin)"] --> dm["Dragon's Mouth<br/>Yellowstone gRPC"] --> app["Your app"]
    app -.->|"SubscribeRequest (filters)"| dm
    style app fill:#D6EAF8,stroke:#259DD0
```

## Supported methods

{% tabs %}
{% tab title="Streaming subscriptions" %}

| Stream                    | What you receive                                                                                                                                                                                         |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Account writes            | Updates whenever a matching account's data, lamports, or owner changes                                                                                                                                   |
| Transactions              | Every transaction matching your filter, with full `meta` (logs, status, balance deltas)                                                                                                                  |
| Deshred Transactions gRPC | Transactions reconstructed from shreds *before* execution. Separate `SubscribeDeshred` method. See [Deshred Transactions gRPC](https://docs.triton.one/solana/real-time-streaming/deshred-transactions). |
| Entries                   | Solana ledger entries (low-level, rare use case)                                                                                                                                                         |
| Block notifications       | Full blocks as they're produced, optionally with their transactions and accounts                                                                                                                         |
| Block metadata            | Block headers only, without the transaction payload                                                                                                                                                      |
| Slot notifications        | Slot-status events (processed/confirmed/finalized plus intra-slot lifecycle)                                                                                                                             |
| {% endtab %}              |                                                                                                                                                                                                          |

{% tab title="Unary operations" %}

| Method                | Returns                                                              |
| --------------------- | -------------------------------------------------------------------- |
| `getLatestBlockhash`  | The latest blockhash + last valid block height at a commitment level |
| `getBlockHeight`      | The current block height at a commitment level                       |
| `getSlot`             | The current slot at a commitment level                               |
| `isBlockhashValid`    | Whether a given blockhash is still valid                             |
| `subscribeReplayInfo` | Earliest slot still available for stream replay                      |
| `getVersion`          | The Geyser gRPC plugin and Solana version                            |
| `ping`                | Liveness check; the server replies with a `pong`                     |
| {% endtab %}          |                                                                      |
| {% endtabs %}         |                                                                      |

## Subscribe request

Every stream subscription is a single `SubscribeRequest` message. It has fields that apply across all stream types, as well as a per-stream filter map.

You send it once when you open the stream; then you can send it again at any time to modify it (the new request fully replaces the old one).

{% tabs %}
{% tab title="commitment" %}
Commitment level for buffering. Optional. Defaults to `processed`.

| Value           | Meaning                                                                                                     |
| --------------- | ----------------------------------------------------------------------------------------------------------- |
| `PROCESSED` (0) | Highest slot seen, possibly on a fork. Lowest latency.                                                      |
| `CONFIRMED` (1) | Same state as `FINALIZED` on Alpenglow.                                                                     |
| `FINALIZED` (2) | On Alpenglow there are no vote towers or lockouts: a slot is finalized by certificates of aggregated votes. |

Alpenglow has been active on Solana mainnet since epoch 1064 (21 Oct 2026). `CONFIRMED` and `FINALIZED` updates arrive together.

Stream at `processed` and track `confirmed` and `finalized` yourself, rather than asking the server to buffer by commitment. The pattern:

1. Subscribe to [slot notifications](#slots) alongside your data stream, and leave `filter_by_commitment` unset so all three statuses arrive.
2. Buffer incoming events by slot and `bank_id`.
3. When you see a slot status change to `confirmed` or `finalized`, release the buffer with the same slot and `bank_id`. On `finalized`, also drop the buffered events of the slot's other banks.
4. A bank's events always arrive *before* its commitment update. See [event order per bank](#event-order-per-bank).

{% hint style="info" %}
**The server fills in missing commitment updates.** The validator does not send a commitment status for every slot. When a slot reaches `confirmed` or `finalized`, Dragon's Mouth also sends that status for each ancestor slot that has not reached it yet.
{% endhint %}
{% endtab %}

{% tab title="ping" %}
Sends a periodic keepalive to prevent idle-stream drops by upstream cloud providers (e.g. Cloudflare). Server replies with `pong`. Optional but recommended for long-running streams.

See [pings](#sending-pings).
{% endtab %}

{% tab title="accountsDataSlice" %}
Truncates account data payloads to a byte range, reducing bandwidth. Optional. Empty array means full payload.

Example: `[{ "offset": 32, "length": 40 }]` returns 40 bytes starting at byte 32.
{% endtab %}

{% tab title="fromSlot" %}
Replay buffered updates starting from this slot, then continue live on the same stream. Optional. Used for reconnection after short disconnections.

See [replay from a slot](#replay-from-a-slot).
{% endtab %}
{% endtabs %}

### Multiplexing in one connection

{% hint style="warning" %}
**Multiplexing over a single gRPC connection is not ideal for performance.** Concurrent streams on one TCP connection fragment and contend through head-of-line blocking.
{% endhint %}

Several named filters in one `SubscribeRequest` share one stream. The warning above is about opening several streams on one connection.

A single gRPC connection can carry many subscriptions. Add multiple named entries to any filter map (for example `accounts`, `transactions`, `slots`, `blocks`, `blocksMeta`, `entry`) and they all stream over the same connection. Each match is tagged with the filter name(s) that produced it, so you can route updates downstream.

The canonical multiplex example is the [Multiple programs Accounts subscription](#accounts), two named owner filters under `accounts`, one connection. The same pattern works across stream types: subscribe to accounts AND transactions AND slots in one request.

### Filter configuration

Each `SubscribeRequest` has a map per stream type. The key is a label you choose (returned with each match so you can route it); the value is the filter spec.

<details>

<summary>Account filters</summary>

| Parameter | Type               | Required | Description                                                                                                                                          |
| --------- | ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account` | `string[]`         | -        | List of pubkeys to subscribe to directly. Each must be a base58-encoded address.                                                                     |
| `owner`   | `string[]`         | -        | List of program owners. Subscribes to every account owned by these programs.                                                                         |
| `filters` | `AccountsFilter[]` | -        | Content-based filters on the account data. Each filter is one of: `memcmp`, `datasize`, `tokenAccountState`, or `lamports`. Combined as logical AND. |

</details>

<details>

<summary>Transaction filters</summary>

| Parameter          | Type       | Required | Description                                                                               |
| ------------------ | ---------- | -------- | ----------------------------------------------------------------------------------------- |
| `vote`             | `bool`     | -        | Include or exclude vote transactions. `false` excludes votes. Alpenglow blocks have none. |
| `failed`           | `bool`     | -        | Include or exclude failed transactions. `false` excludes failures.                        |
| `signature`        | `string`   | -        | Match one transaction by its signature.                                                   |
| `account_include`  | `string[]` | -        | Accounts mentioned anywhere in the transaction.                                           |
| `account_exclude`  | `string[]` | -        | Exclude transactions mentioning these accounts.                                           |
| `account_required` | `string[]` | -        | Accounts that MUST all be mentioned (every one of them).                                  |

</details>

<details>

<summary>Block filters</summary>

| Parameter              | Type       | Required | Description                                                             |
| ---------------------- | ---------- | -------- | ----------------------------------------------------------------------- |
| `account_include`      | `string[]` | -        | Only deliver transactions and accounts in the block that mention these. |
| `include_transactions` | `bool`     | -        | Include the block's transactions.                                       |
| `include_accounts`     | `bool`     | -        | Include accounts updated during the block.                              |
| `include_entries`      | `bool`     | -        | Include the block's entries.                                            |

</details>

<details>

<summary>Slot filters</summary>

| Parameter              | Type   | Required | Description                                                                                                                                          |
| ---------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filter_by_commitment` | `bool` | -        | If `true`, only receive updates matching the request's `commitment`. If `false`, receive `processed`, `confirmed`, and `finalized` updates.          |
| `interslot_updates`    | `bool` | -        | If `true`, also receive the intra-slot statuses. Has no effect when `filter_by_commitment` is `true`. See [intra-slot updates](#intra-slot-updates). |

</details>

### Filter logic

Within a single filter category (e.g. one transaction filter), values are combined as follows:

* **Within an array, OR**, except `account_required`. `account_include: [A, B]` matches transactions mentioning A *or* B.
* **`account_required` needs every listed account.** `account_required: [A, B]` matches transactions mentioning both A *and* B.
* **Across fields, AND.** `vote: false, account_include: [A]` matches non-vote transactions mentioning A.

For transactions specifically:

```
match = (accountInclude OR empty) AND (accountRequired AND all) AND NOT accountExclude
```

Across multiple named filters in the same category (e.g. two transaction filters), you receive matches from any of them. Each match comes tagged with the filter name(s) that produced it, so you can route updates downstream.

### Excluded programs

Account updates owned by Light Protocol / ZK Compression (`compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq`) are not delivered on any Dragon's Mouth stream. To consume that data, use the [Photon indexer](https://github.com/helius-labs/photon).

## Subscribing to each stream type

The examples below use gRPC JSON for the request body and TypeScript for the client. Other languages use the same shape. Each example assumes you've already created and connected a `Client` (see [clients and SDKs](#clients-and-sdks)).

The latest protobuf files live in the [yellowstone-grpc repo](https://github.com/rpcpool/yellowstone-grpc/tree/master/yellowstone-grpc-proto/proto). For Rust, use the [yellowstone-grpc-proto crate](https://crates.io/crates/yellowstone-grpc-proto).

### Accounts

{% tabs %}
{% tab title="By pubkey" %}
Subscribe to one or more specific accounts. The label `wsol/usdc` is yours, it comes back on each match for routing.

{% tabs %}
{% tab title="gRPC" %}

```json
{
  "slots": { "slots": {} },
  "accounts": {
    "wsol/usdc": {
      "account": ["8BnEgHoWFysVcuFFX7QztDmzuH8r5ZFvyP3sYwn1XTh6"]
    }
  },
  "transactions": {},
  "blocks": {},
  "blocks_meta": {},
  "accounts_data_slice": [],
  "commitment": 0
}
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
import { CommitmentLevel } from "@triton-one/yellowstone-grpc";

const request = {
  slots: { slots: {} },
  accounts: {
    "wsol/usdc": {
      account: ["8BnEgHoWFysVcuFFX7QztDmzuH8r5ZFvyP3sYwn1XTh6"],
    },
  },
  transactions: {},
  blocks: {},
  blocksMeta: {},
  accountsDataSlice: [],
  commitment: CommitmentLevel.PROCESSED,
};
```

{% endtab %}

{% tab title="Rust" %}

```rust
use {
    std::collections::HashMap,
    yellowstone_grpc_proto::prelude::{
        CommitmentLevel, SubscribeRequest, SubscribeRequestFilterAccounts,
        SubscribeRequestFilterSlots,
    },
};

let mut accounts = HashMap::new();
accounts.insert(
    "wsol/usdc".to_string(),
    SubscribeRequestFilterAccounts {
        account: vec!["8BnEgHoWFysVcuFFX7QztDmzuH8r5ZFvyP3sYwn1XTh6".to_string()],
        owner: vec![],
        filters: vec![],
        ..Default::default()
    },
);

let mut slots = HashMap::new();
slots.insert("client".to_string(), SubscribeRequestFilterSlots::default());

let request = SubscribeRequest {
    accounts,
    slots,
    commitment: Some(CommitmentLevel::Processed.into()),
    ..Default::default()
};
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="By owner" %}
Subscribe to every account owned by a program. The example tracks all Solend accounts.

{% tabs %}
{% tab title="gRPC" %}

```json
{
  "slots": { "slots": {} },
  "accounts": {
    "solend": {
      "owner": ["So1endDq2YkqhipRh3WViPa8hdiSpxWy6z3Z6tMCpAo"]
    }
  },
  "transactions": {},
  "blocks": {},
  "blocks_meta": {},
  "accounts_data_slice": [],
  "commitment": 0
}
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
import { CommitmentLevel } from "@triton-one/yellowstone-grpc";

const request = {
  slots: { slots: {} },
  accounts: {
    solend: {
      owner: ["So1endDq2YkqhipRh3WViPa8hdiSpxWy6z3Z6tMCpAo"],
    },
  },
  transactions: {},
  blocks: {},
  blocksMeta: {},
  accountsDataSlice: [],
  commitment: CommitmentLevel.PROCESSED,
};
```

{% endtab %}

{% tab title="Rust" %}

```rust
use {
    std::collections::HashMap,
    yellowstone_grpc_proto::prelude::{
        CommitmentLevel, SubscribeRequest, SubscribeRequestFilterAccounts,
        SubscribeRequestFilterSlots,
    },
};

let mut accounts = HashMap::new();
accounts.insert(
    "solend".to_string(),
    SubscribeRequestFilterAccounts {
        account: vec![],
        owner: vec!["So1endDq2YkqhipRh3WViPa8hdiSpxWy6z3Z6tMCpAo".to_string()],
        filters: vec![],
        ..Default::default()
    },
);

let mut slots = HashMap::new();
slots.insert("client".to_string(), SubscribeRequestFilterSlots::default());

let request = SubscribeRequest {
    accounts,
    slots,
    commitment: Some(CommitmentLevel::Processed.into()),
    ..Default::default()
};
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="Multiple programs" %}
Combine multiple programs in one filter, or use separate filters for different routing tags.

Both programs in one filter:

```json
{
  "slots": { "slots": {} },
  "accounts": {
    "programs": {
      "owner": [
        "So1endDq2YkqhipRh3WViPa8hdiSpxWy6z3Z6tMCpAo",
        "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin"
      ]
    }
  },
  "transactions": {},
  "blocks": {},
  "blocks_meta": {},
  "accounts_data_slice": []
}
```

Separate filters with different tags:

```json
{
  "slots": { "slots": {} },
  "accounts": {
    "solend": { "owner": ["So1endDq2YkqhipRh3WViPa8hdiSpxWy6z3Z6tMCpAo"] },
    "serum":  { "owner": ["9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin"] }
  },
  "transactions": {},
  "blocks": {},
  "blocks_meta": {},
  "accounts_data_slice": []
}
```

{% endtab %}

{% tab title="Advanced filters + data slice" %}
Filter by content (memcmp, token account state) and trim the returned payload to save bandwidth. The example tracks USDC token accounts and returns only 40 bytes starting at offset 32 (owner + amount).

{% tabs %}
{% tab title="gRPC" %}

```json
{
  "accounts": {
    "usdc": {
      "owner": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
      "filters": [
        { "token_account_state": true },
        {
          "memcmp": {
            "offset": 0,
            "base58": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
          }
        }
      ]
    }
  },
  "accounts_data_slice": [{ "offset": 32, "length": 40 }]
}
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
import { CommitmentLevel } from "@triton-one/yellowstone-grpc";

const request = {
  slots: {},
  accounts: {
    usdc: {
      owner: ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
      filters: [
        { tokenAccountState: true },
        {
          memcmp: {
            offset: "0",
            base58: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
          },
        },
      ],
    },
  },
  transactions: {},
  blocks: {},
  blocksMeta: {},
  entry: {},
  commitment: CommitmentLevel.PROCESSED,
  accountsDataSlice: [{ offset: "32", length: "40" }],
};
```

{% endtab %}

{% tab title="Rust" %}

```rust
use {
    std::collections::HashMap,
    yellowstone_grpc_proto::prelude::{
        subscribe_request_filter_accounts_filter::Filter,
        subscribe_request_filter_accounts_filter_memcmp::Data,
        CommitmentLevel, SubscribeRequest, SubscribeRequestAccountsDataSlice,
        SubscribeRequestFilterAccounts, SubscribeRequestFilterAccountsFilter,
        SubscribeRequestFilterAccountsFilterMemcmp,
    },
};

let mut accounts = HashMap::new();
accounts.insert(
    "usdc".to_string(),
    SubscribeRequestFilterAccounts {
        account: vec![],
        owner: vec!["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA".to_string()],
        filters: vec![
            SubscribeRequestFilterAccountsFilter {
                filter: Some(Filter::TokenAccountState(true)),
            },
            SubscribeRequestFilterAccountsFilter {
                filter: Some(Filter::Memcmp(SubscribeRequestFilterAccountsFilterMemcmp {
                    offset: 0,
                    data: Some(Data::Base58(
                        "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v".to_string(),
                    )),
                })),
            },
        ],
        ..Default::default()
    },
);

let request = SubscribeRequest {
    accounts,
    accounts_data_slice: vec![SubscribeRequestAccountsDataSlice {
        offset: 32,
        length: 40,
    }],
    commitment: Some(CommitmentLevel::Processed.into()),
    ..Default::default()
};
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="Compressed filters" %}
For subscriptions tracking thousands of accounts, the explicit pubkey list dominates the payload (1M pubkeys = \~44 MB per resend). Compressed account filters carry your tracked set as a [Cuckoo filter](https://en.wikipedia.org/wiki/Cuckoo_filter), a probabilistic data structure storing small fingerprints instead of full 32-byte pubkeys, cutting payload size \~10x.

| Tracked accounts | Compressed filter | Explicit pubkey list |
| ---------------: | ----------------: | -------------------: |
|            1,000 |           \~4 KiB |              \~44 KB |
|           10,000 |          \~32 KiB |             \~440 KB |
|          100,000 |         \~256 KiB |             \~4.4 MB |
|        1,000,000 |           \~4 MiB |              \~44 MB |
|        2,000,000 |           \~8 MiB |              \~84 MB |

Inserts and removes on the filter are O(1), so account-set mutations skip a full filter rebuild. And because it uses SipHash-2-4, a TypeScript client and a Rust client emit identical filter bytes for the same pubkey set, so one tracked set works across languages and Rust compiler versions.

**Tradeoffs:**

* **False positives** stay under 1%. Your client should keep an exact tracked set and drop incoming updates whose pubkey isn't in it. A `HashSet` check is the standard pattern; the probabilistic part lives only on the wire.
* **One-time build cost.** A 2M-account filter takes \~390 ms on a release build. Every subsequent insert, remove, and resend is cheap.
* **Request size limit on shared mainnet endpoints.** The server rejects a `SubscribeRequest` larger than 8 MiB (8,388,608 bytes). A filter built for 2,000,000 accounts is exactly 8 MiB before the rest of the request, so it is rejected. A filter built for about 1.99 million accounts or fewer is 4 MiB or smaller and fits.

Available in the Rust and TypeScript clients (TypeScript from `@triton-one/yellowstone-grpc` v5.0.9). The Rust API builds a `CompressedAccountFilterSet` and attaches it to your `SubscribeRequest`:

```rust
use yellowstone_grpc_proto::cuckoo::CompressedAccountFilterSet;

let mut accounts = CompressedAccountFilterSet::with_capacity(2_000_000)?;
for pk in my_tracked_pubkeys() {
    accounts.insert(*pk)?;
}

let mut req = SubscribeRequest::default();
accounts.insert_into_subscribe_request(&mut req, "tracked");
```

Mutate and resend when the set changes:

```rust
accounts.insert(new_pubkey)?;
accounts.remove(old_pubkey);
accounts.insert_into_subscribe_request(&mut req, "tracked");
```

Drop false positives against your local exact set:

```rust
if accounts.contains(incoming_pubkey) {
    // one of your tracked accounts
}
```

Full deep-dive: [Compressed filters for Yellowstone gRPC](https://blog.triton.one/compressed-filters-for-yellowstone-grpc-track-millions-of-accounts-with-10x-less-overhead).
{% endtab %}
{% endtabs %}

### Transactions

Use the `transactions` subscription to receive executed transactions at your chosen commitment level; `processed` delivers them as soon as the node processes them, while `confirmed` and `finalized` add latency. To receive transactions before the node executes them, use [Deshred Transactions gRPC](https://docs.triton.one/solana/real-time-streaming/deshred-transactions), a separate gRPC method on the same service. It delivers transactions reconstructed from shreds.

{% tabs %}
{% tab title="All non-vote, non-failed" %}
Subscribe to every successful, non-vote transaction at `processed` commitment.

{% tabs %}
{% tab title="gRPC" %}

```json
{
  "slots": { "slots": {} },
  "accounts": {},
  "transactions": {
    "alltxs": { "vote": false, "failed": false }
  },
  "blocks": {},
  "blocks_meta": {},
  "accounts_data_slice": [],
  "commitment": 0
}
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
import { CommitmentLevel } from "@triton-one/yellowstone-grpc";

const request = {
  slots: { slots: {} },
  accounts: {},
  transactions: {
    alltxs: { vote: false, failed: false },
  },
  blocks: {},
  blocksMeta: {},
  accountsDataSlice: [],
  commitment: CommitmentLevel.PROCESSED,
};
```

{% endtab %}

{% tab title="Rust" %}

```rust
use {
    std::collections::HashMap,
    yellowstone_grpc_proto::prelude::{
        CommitmentLevel, SubscribeRequest, SubscribeRequestFilterTransactions,
    },
};

let mut transactions = HashMap::new();
transactions.insert(
    "alltxs".to_string(),
    SubscribeRequestFilterTransactions {
        vote: Some(false),
        failed: Some(false),
        ..Default::default()
    },
);

let request = SubscribeRequest {
    transactions,
    commitment: Some(CommitmentLevel::Processed.into()),
    ..Default::default()
};
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="Mentioning an account" %}
Subscribe to non-vote transactions that mention a specific account anywhere.

{% code title="gRPC" %}

```json
{
  "transactions": {
    "serum": {
      "vote": false,
      "account_include": ["9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin"]
    }
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="Excluding accounts" %}
Drop transactions that mention any of the listed accounts.

{% code title="gRPC" %}

```json
{
  "transactions": {
    "serum": {
      "account_exclude": [
        "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
        "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
      ]
    }
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="Combined include + exclude" %}
Combine include + exclude in one filter. The example matches transactions mentioning a Serum program but excludes any that also touch a specific account.

{% code title="gRPC" %}

```json
{
  "transactions": {
    "serum": {
      "account_include": ["9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin"],
      "account_exclude": ["9wFFyRfZBsuAha4YcuxcXLKwMxJR43S7fPfQLusDBzvT"]
    }
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="By signature" %}
Subscribe to one transaction by its signature.

{% code title="gRPC" %}

```json
{
  "transactions": {
    "sign": {
      "signature": "5rp2hL9b6kexex11Mugfs3vfU9GhieKruj4CkFFSnu52WLxiGn4VcLLwsB62XURhMmT1j4CZiXT6FFtYbXsLq2Zs"
    }
  }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

For the wire format of each transaction update, see [`geyser.proto`](https://github.com/rpcpool/yellowstone-grpc/blob/master/yellowstone-grpc-proto/proto/geyser.proto) (search for `SubscribeUpdateTransaction`).

### Slots

Subscribe to slot status changes. No filter parameters needed beyond a label.

{% tabs %}
{% tab title="gRPC" %}

```json
{
  "slots": { "incoming_slots": {} },
  "accounts": {},
  "transactions": {},
  "blocks": {},
  "blocks_meta": {},
  "accounts_data_slice": []
}
```

{% endtab %}

{% tab title="Rust" %}

```rust
use {
    std::collections::HashMap,
    yellowstone_grpc_proto::prelude::{SubscribeRequest, SubscribeRequestFilterSlots},
};

let mut slots = HashMap::new();
slots.insert(
    "incoming_slots".to_string(),
    SubscribeRequestFilterSlots::default(),
);

let request = SubscribeRequest {
    slots,
    ..Default::default()
};
```

{% endtab %}
{% endtabs %}

Each update carries a `SlotStatus` enum. See [intra-slot updates](#intra-slot-updates) for all statuses and [event order per bank](#event-order-per-bank).

### Blocks

{% tabs %}
{% tab title="All blocks" %}
Receive every block as it's produced, with full transaction payload.

{% tabs %}
{% tab title="gRPC" %}

```json
{
  "slots": {},
  "accounts": {},
  "transactions": {},
  "blocks": { "blocks": {} },
  "blocks_meta": {},
  "accounts_data_slice": []
}
```

{% endtab %}

{% tab title="Rust" %}

```rust
use {
    std::collections::HashMap,
    yellowstone_grpc_proto::prelude::{SubscribeRequest, SubscribeRequestFilterBlocks},
};

let mut blocks = HashMap::new();
blocks.insert(
    "blocks".to_string(),
    SubscribeRequestFilterBlocks::default(),
);

let request = SubscribeRequest {
    blocks,
    ..Default::default()
};
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="Customize payload" %}
Trim the block payload by toggling `include_transactions` / `include_accounts`.

{% code title="gRPC" %}

```json
{
  "blocks": {
    "blocks": {
      "include_transactions": false,
      "include_accounts": true
    }
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="Filtered by account" %}
Restrict the block's transactions and accounts to those mentioning specific addresses.

{% code title="gRPC" %}

```json
{
  "blocks": {
    "blocks": {
      "account_include": ["So1endDq2YkqhipRh3WViPa8hdiSpxWy6z3Z6tMCpAo"]
    }
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="Block metadata only" %}
Get block headers without the transaction payload (much smaller messages).

{% code title="gRPC" %}

```json
{
  "blocks": {},
  "blocks_meta": { "blockmetadata": {} }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Entries

Subscribe to ledger entries (groups of transactions that make up a slot). No filter parameters are required; subscribe by adding any named entry filter.

{% tabs %}
{% tab title="gRPC" %}

```json
{
  "entry": { "all": {} }
}
```

{% endtab %}

{% tab title="Rust" %}

```rust
use {
    std::collections::HashMap,
    yellowstone_grpc_proto::prelude::{SubscribeRequest, SubscribeRequestFilterEntry},
};

let mut entry = HashMap::new();
entry.insert("all".to_string(), SubscribeRequestFilterEntry::default());

let request = SubscribeRequest {
    entry,
    ..Default::default()
};
```

{% endtab %}
{% endtabs %}

## Modifying and unsubscribing

The subscribe stream is bi-directional. Send a new `SubscribeRequest` at any time to update filters. It fully replaces the previous subscription, so your client must keep a local copy of the full config it wants.

To unsubscribe from everything but keep the connection open:

{% code title="gRPC" %}

```json
{
  "slots": {},
  "accounts": {},
  "transactions": {},
  "blocks": {},
  "blocks_meta": {}
}
```

{% endcode %}

## Sending pings

Some cloud providers (e.g. Cloudflare) close idle streams. To avoid this, you need to keep sending pings to the server. The server sends its own `ping` every 10 seconds; when you send a ping with an `id`, it replies with a `pong` carrying the same `id`.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
const PING_INTERVAL_MS = 10_000;

const pingRequest = {
  ping: { id: 1 },
  accounts: {},
  accountsDataSlice: [],
  transactions: {},
  transactionsStatus: {},
  blocks: {},
  blocksMeta: {},
  blockFooter: {},
  entry: {},
  slots: {},
};

setInterval(async () => {
  await new Promise<void>((resolve, reject) => {
    stream.write(pingRequest, (err) =>
      err ? reject(err) : resolve()
    );
  });
}, PING_INTERVAL_MS);

stream.on("data", (data) => {
  if (data.pong) {
    console.log("Received pong");
  }
});
```

{% endtab %}

{% tab title="Rust" %}
A maintained Rust example that sends pings and handles the server's ping and pong updates: [subscribe-ping.rs in rpcpool/yellowstone-grpc](https://github.com/rpcpool/yellowstone-grpc/blob/master/examples/rust/src/bin/subscribe-ping.rs).
{% endtab %}
{% endtabs %}

## Replay from a slot

Dragon's Mouth can replay recently buffered updates by setting `from_slot` on `SubscribeRequest`. The server replays buffered updates from that slot, then continues live on the same stream.

Use it for short-disconnection recovery:

1. Track the latest slot your application has processed.
2. On disconnect, reconnect and resubscribe with `from_slot` set to that slot.
3. If the slot is no longer available, fall back to a fresh live subscription or your own backfill path.

{% tabs %}
{% tab title="gRPC" %}

```json
{
  "slots": { "incoming_slots": {} },
  "accounts": {},
  "transactions": {
    "alltxs": { "vote": false, "failed": false }
  },
  "blocks": {},
  "blocks_meta": {},
  "accounts_data_slice": [],
  "from_slot": 382001234
}
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
const request = {
  slots: { incoming_slots: {} },
  accounts: {},
  transactions: {
    alltxs: { vote: false, failed: false, accountInclude: [], accountExclude: [], accountRequired: [] },
  },
  transactionsStatus: {},
  entry: {},
  blocks: {},
  blocksMeta: {},
  blockFooter: {},
  accountsDataSlice: [],
  fromSlot: "382001234",
};
```

{% endtab %}
{% endtabs %}

To discover the earliest replayable slot, call the unary `subscribeReplayInfo` RPC:

{% code title="TypeScript" %}

```typescript
const info = await client.subscribeReplayInfo();
console.log(info.firstAvailable);
```

{% endcode %}

{% hint style="info" %}

* Replay only covers the server's retained replay window: about 1,000 slots on shared mainnet endpoints and about 300 slots on shared devnet. On dedicated nodes the window varies, so contact support for yours.
* If `from_slot` is older than the earliest available, the request fails. Retry with a newer slot.
* Replay uses the same filters and commitment level as the live subscription.
* Replay starts at a slot boundary, so you may receive duplicate updates from your last-processed slot. Dedupe them.
  {% endhint %}

{% hint style="info" %}
For teams self-hosting a Yellowstone gRPC server, replay is on by default (`replay_stored_slots` defaults to `150`); set it to `0` to disable replay.
{% endhint %}

### Reconnect with bank recovery

Ordinary subscriptions don't reconnect. The Rust methods `subscribe`, `subscribe_with_request`, and `subscribe_once`, and the TypeScript methods `subscribe()` and `subscribeDeshred()`, end at the first disconnect, even if you set a reconnect config.

To have the client reconnect for you, open the stream with `subscribe_with_reconnect` (Rust, `yellowstone-grpc-client` 17.0.0 and later) or `subscribeWithReconnect()` (TypeScript, `@triton-one/yellowstone-grpc` 10.0.0 and later). Earlier versions have a different reconnect API.

The request:

* can use any commitment level;
* can set `from_slot`: the first connection replays from it, and the server ignores `from_slot` in later requests;
* must not name a filter `__reconn` (`RECONNECT_FILTER_KEY`). The client adds its own block meta and slot filters under that name and hides updates that only they match. The Rust client overwrites a filter with that name; the TypeScript client rejects the request.

The client must not request a startup snapshot (`x-request-snapshot`); otherwise opening the stream fails with `FAILED_PRECONDITION`.

To change the filters, send a new `SubscribeRequest` on the sink (Rust) or write it to the stream (TypeScript). The change applies to the current connection and to every reconnect.

When the connection fails with a retryable status (`UNAVAILABLE`, `INTERNAL`, `UNKNOWN`, `CANCELLED`, `DEADLINE_EXCEEDED`, `RESOURCE_EXHAUSTED`, `ABORTED`, or `DATA_LOSS`), or the server ends it, the stream:

1. Emits one `Disconnected` event that lists the banks you received only in part.
2. Waits the backoff delay, then resubscribes with the latest request and the `from_slot` the reconnect policy picks.
3. Drops whatever a later connection sends of a listed bank that the replay doesn't resend.

The reconnect policy (`ReconnectConfig::policy` in Rust, `policy` in TypeScript) picks where the new connection starts:

* **`Replay`** (the default) replays from `slots_behind` slots before the last confirmed slot the stream saw. `slots_behind` defaults to `0`.
  * Before the stream sees a confirmed slot, it replays from the first request's `from_slot`, or resumes at the live tip if there is none.
  * The replay resends banks you already received whole. Skip those duplicates.
  * A replayed bank carries only the latest write of each account, so it can have fewer account updates than the same bank delivered live. The final state of each account is the same.
  * The replay slot must be inside the server's [replay window](#replay-from-a-slot); otherwise the reconnect fails and the stream ends with an error.
* **`NoReplay`** resumes at the live tip. Updates sent during the outage are lost.

The backoff (`ReconnectConfig::backoff` in Rust, `backoff` in TypeScript) is a retry budget:

* The default is 10 ms, doubling, with 3 retries.
* Each reconnect spends one retry and waits first: the initial interval for the first reconnect, multiplied by the multiplier for each next one.
* A connection that delivers a Block, block footer, or block meta, including one from the client's own `__reconn` filter, refills the budget. A ping or a slot status alone doesn't.
* With the budget spent, the next disconnect ends the stream with its error. With 0 retries, the stream never reconnects.
* Within one reconnect, the client retries a failed connect up to the same number of times, with the same delays.

The stream returns an error and ends when the status isn't retryable, a reconnect fails, or the retry budget is spent. Open a new subscription.

Your code handles two event types:

* **`Update`** carries a `SubscribeUpdate`, as an ordinary subscription delivers it.
* **`Disconnected`** marks a dropped connection. Every update after it comes from the new connection.
  * `partial_banks` (`partialBanks` in TypeScript) lists, in slot order and by `slot` and `bank_id`, the banks you received content of (account writes, transactions, transaction statuses, entries, or `CreatedBank`) but not their Block, block footer, or block meta. Discard their state.
  * A replay resends the listed banks at or above `replay_from_slot` whole.
  * `replay_from_slot` (`replayFromSlot`) is the slot the new connection replays from, or `None` (`null`) when it resumes at the live tip.

{% tabs %}
{% tab title="Rust" %}
{% code title="Cargo.toml" %}

```toml
[dependencies]
yellowstone-grpc-client = "17"
yellowstone-grpc-proto = "14"
tokio = { version = "1", features = ["full"] }
futures = "0.3"
tonic = { version = "0.14", features = ["tls-native-roots", "tls-ring"] } # TLS roots and crypto provider
anyhow = "1"
```

{% endcode %}

{% code title="src/main.rs" %}

```rust
use {
    futures::StreamExt,
    std::{
        collections::{BTreeSet, HashMap},
        time::Duration,
    },
    yellowstone_grpc_client::{
        Backoff, BankRef, ClientTlsConfig, GeyserGrpcClient, ReconnectConfig, ReconnectEvent,
        ReconnectPolicy,
    },
    yellowstone_grpc_proto::prelude::{
        subscribe_update::UpdateOneof, CommitmentLevel, SubscribeRequest,
        SubscribeRequestFilterBlocksMeta, SubscribeRequestFilterTransactions,
    },
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut client =
        GeyserGrpcClient::build_from_shared("https://<your-endpoint>.mainnet.rpcpool.com:443")?
            .x_token(Some("<your-token>"))?
            .tls_config(ClientTlsConfig::new().with_native_roots())?
            .http2_adaptive_window(true)
            // Optional. The defaults are 10 ms, doubling, 3 retries, and Replay { slots_behind: 0 }.
            .set_reconnect_config(
                ReconnectConfig::default()
                    .with_backoff(Backoff::new(Duration::from_millis(100), 2.0, 10))
                    .with_policy(ReconnectPolicy::Replay { slots_behind: 0 }),
            )
            .connect()
            .await?;

    let request = SubscribeRequest {
        transactions: HashMap::from([(
            "pool".to_string(),
            SubscribeRequestFilterTransactions {
                vote: Some(false),
                failed: Some(false),
                account_include: vec!["8BnEgHoWFysVcuFFX7QztDmzuH8r5ZFvyP3sYwn1XTh6".to_string()],
                ..Default::default()
            },
        )]),
        // On one connection, a bank's block meta arrives after all of its content
        blocks_meta: HashMap::from([(
            "blocks".to_string(),
            SubscribeRequestFilterBlocksMeta::default(),
        )]),
        commitment: Some(CommitmentLevel::Processed.into()),
        ..Default::default()
    };

    // A request sent on the sink changes the filters, now and after every reconnect
    let (_sink, mut stream) = client.subscribe_with_reconnect(Some(request)).await?;

    // Transactions per bank in progress, and the banks already complete
    let mut in_progress: HashMap<BankRef, usize> = HashMap::new();
    let mut complete: BTreeSet<BankRef> = BTreeSet::new();

    while let Some(event) = stream.next().await {
        match event {
            Ok(ReconnectEvent::Update(update)) => match update.update_oneof {
                Some(UpdateOneof::Transaction(tx)) => {
                    let bank = BankRef { slot: tx.slot, bank_id: tx.bank_id };
                    // A replay resends complete banks: skip them
                    if !complete.contains(&bank) {
                        *in_progress.entry(bank).or_default() += 1;
                    }
                }
                Some(UpdateOneof::BlockMeta(meta)) => {
                    let bank = BankRef { slot: meta.slot, bank_id: meta.bank_id };
                    if complete.insert(bank) {
                        let count = in_progress.remove(&bank).unwrap_or_default();
                        println!("slot={} bank_id={} complete: {count} transactions", bank.slot, bank.bank_id);
                    }
                    while complete.len() > 4096 {
                        complete.pop_first();
                    }
                }
                _ => {}
            },
            Ok(ReconnectEvent::Disconnected(disconnected)) => {
                // Drop the banks received in part
                for bank in &disconnected.partial_banks {
                    in_progress.remove(bank);
                }
                println!("reconnecting, replay from slot {:?}", disconnected.replay_from_slot);
            }
            Err(status) => {
                // Not retryable, the reconnect failed, or the retry budget is spent.
                // The stream has ended: open a new subscription.
                eprintln!("stream ended: {status}");
                break;
            }
        }
    }

    Ok(())
}
```

{% endcode %}
{% endtab %}

{% tab title="TypeScript" %}

```typescript
import Client, {
  CommitmentLevel,
  type ReconnectEvent,
  type SubscribeRequest,
} from "@triton-one/yellowstone-grpc";

async function main() {
  // The optional fourth argument configures subscribeWithReconnect().
  // The defaults are 10 ms, doubling, 3 retries, and policy "Replay" with slotsBehind 0.
  const client = new Client(
    "https://<your-endpoint>.mainnet.rpcpool.com",
    "<your-token>",
    undefined,
    {
      backoff: { initialIntervalMs: 100, multiplier: 2, maxRetries: 10 },
      policy: "Replay",
      slotsBehind: 0,
    },
  );
  await client.connect();

  const request: SubscribeRequest = {
    accounts: {},
    slots: {},
    transactions: {
      pool: {
        vote: false,
        failed: false,
        accountInclude: ["8BnEgHoWFysVcuFFX7QztDmzuH8r5ZFvyP3sYwn1XTh6"],
        accountExclude: [],
        accountRequired: [],
      },
    },
    transactionsStatus: {},
    blocks: {},
    // On one connection, a bank's block meta arrives after all of its content
    blocksMeta: { blocks: {} },
    entry: {},
    blockFooter: {},
    accountsDataSlice: [],
    commitment: CommitmentLevel.PROCESSED,
  };

  // Write a SubscribeRequest to the stream to change the filters, now and after every reconnect
  const stream = await client.subscribeWithReconnect(request);

  // Transactions per bank in progress, and the banks already complete, keyed "slot/bankId"
  const inProgress = new Map<string, number>();
  const complete = new Set<string>();

  stream.on("data", (event: ReconnectEvent) => {
    if (event.type === "Disconnected") {
      // Drop the banks received in part
      for (const bank of event.partialBanks) {
        inProgress.delete(`${bank.slot}/${bank.bankId}`);
      }
      console.log(`reconnecting, replay from slot ${event.replayFromSlot ?? "none (live tip)"}`);
      return;
    }
    const { transaction, blockMeta } = event.update;
    if (transaction) {
      const bank = `${transaction.slot}/${transaction.bankId}`;
      // A replay resends complete banks: skip them
      if (!complete.has(bank)) {
        inProgress.set(bank, (inProgress.get(bank) ?? 0) + 1);
      }
    } else if (blockMeta) {
      const bank = `${blockMeta.slot}/${blockMeta.bankId}`;
      if (!complete.has(bank)) {
        complete.add(bank);
        console.log(`bank ${bank} complete: ${inProgress.get(bank) ?? 0} transactions`);
        inProgress.delete(bank);
      }
      for (const old of complete) {
        if (complete.size <= 4096) break;
        complete.delete(old);
      }
    }
  });

  // Not retryable, the reconnect failed, or the retry budget is spent.
  // The stream has ended: open a new subscription.
  stream.on("error", (error) => console.error("stream ended:", error));
}

main().catch(console.error);
```

`slot`, `bankId`, and `replayFromSlot` are decimal strings. The fourth constructor argument takes `backoff` (`initialIntervalMs`, `multiplier`, `maxRetries`), `policy` (`"Replay"` or `"NoReplay"`), and `slotsBehind`. The client rejects `slotsBehind` with `"NoReplay"`, and rejects `enabled` and `slotRetention`.
{% endtab %}
{% endtabs %}

For a startup snapshot, use an ordinary subscription and resume it yourself: track the last slot you processed, and resubscribe with `from_slot` as described in [Replay from a slot](#replay-from-a-slot).

## Intra-slot updates

Subscribers can listen for "intra-slot" lifecycle events that show what's happening inside a slot, from the first shred received to a fully replayed bank.

These statuses are only delivered when your slots filter sets `interslot_updates: true`. Without it, a slots subscription receives only the processed, confirmed, and finalized statuses.

```protobuf
enum SlotStatus {
  // ... standard commitment statuses ...
  SLOT_FIRST_SHRED_RECEIVED = 3;
  SLOT_COMPLETED            = 4;
  SLOT_CREATED_BANK         = 5;
  SLOT_DEAD                 = 6;
}
```

| Status                      | What it means                                                                                                                                                     |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SLOT_FIRST_SHRED_RECEIVED` | The RPC node has received the first shred of this slot. Not yet replayed. Occurs in the [retransmit stage](https://docs.anza.xyz/validator/tvu#retransmit-stage). |
| `SLOT_CREATED_BANK`         | A bank for this slot has been created on the node. Banks are isolated execution contexts in a fork graph. A slot can have several competing banks.                |
| `SLOT_COMPLETED`            | All shreds for this slot received. Not necessarily replayed yet.                                                                                                  |
| `SLOT_DEAD`                 | The slot was rejected (invalid signature, bad PoH, wrong entry count). It's discarded by the network. Can happen at any point, even after `SLOT_COMPLETED`.       |

### Event order per bank

Every block is produced by a bank, identified by a `bank_id`. A slot usually has one bank, but it can have several competing ones.

Order within one bank on a `processed` stream:

```mermaid
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#F2EDF6','primaryBorderColor':'#7A4BA0','primaryTextColor':'#171717','lineColor':'#956FB3','secondaryColor':'#E4DBEC','tertiaryColor':'#D7C9E3','edgeLabelBackground':'#F2EDF6'},'flowchart':{'nodeSpacing':20,'rankSpacing':35,'curve':'linear'}}}%%
flowchart LR
    C["<b>1. Content</b><br/>any order<br/><br/>CreatedBank, entries,<br/>transactions,<br/>account updates"] --> F["<b>2. Block footer</b><br/><br/>at most one per bank<br/>Alpenglow clusters only"] --> M["<b>3. BlockMeta</b><br/><br/>end of the<br/>bank's block"] --> U["<b>4. Commitment updates</b><br/><br/>Processed → Confirmed<br/>→ Finalized"]
```

1. **Content**, in any order: the `SLOT_CREATED_BANK` status (CreatedBank), entries (`SubscribeUpdateEntry`), transactions (`SubscribeUpdateTransaction`), and account updates (`SubscribeUpdateAccount`), including the sysvars Clock, SlotHashes, SlotHistory, and RecentBlockhashes. Clock and SlotHashes can arrive before `SLOT_CREATED_BANK`.
2. **Block footer** (`SubscribeUpdateBlockFooter`): at most one per bank, on Alpenglow clusters only.
3. **BlockMeta** (`SubscribeUpdateBlockMeta`): marks the end of the bank's block.
4. **Commitment updates** (`SubscribeUpdateSlot`): `SLOT_PROCESSED`, then `SLOT_CONFIRMED`, then `SLOT_FINALIZED`. On Alpenglow clusters, `SLOT_CONFIRMED` and `SLOT_FINALIZED` arrive back to back.

On a `processed` subscription, nothing about a bank's content arrives after its BlockMeta, and no commitment update for that bank arrives before it. Besides the server's own `ping` updates, you receive only the update types your request subscribes to.

## Clients and SDKs

We provide SDKs in Rust and TypeScript, plus example clients in Go and Python. Sample clients for each live in the [yellowstone-grpc/examples](https://github.com/rpcpool/yellowstone-grpc/tree/master/examples) directory; match your client to the current proto version.

{% tabs %}
{% tab title="Rust" %}
The repo's [yellowstone-grpc/examples/rust](https://github.com/rpcpool/yellowstone-grpc/tree/master/examples/rust) directory ships a `client` binary that exercises the subscribe and unary methods against any endpoint.

Subscribe to account updates:

```shell
cargo run --bin client -- \
  -e https://<your-endpoint>.mainnet.rpcpool.com \
  --x-token <your-token> \
  subscribe \
  --accounts \
  --accounts-account <Pubkey>
```

Subscribe to slots (with commitment override):

```shell
cargo run --bin client -- \
  -e https://<your-endpoint>.mainnet.rpcpool.com \
  --x-token <your-token> \
  --commitment processed \
  subscribe \
  --slots
```

Subscribe to non-vote, non-failed transactions touching an account:

```shell
cargo run --bin client -- \
  -e https://<your-endpoint>.mainnet.rpcpool.com \
  --x-token <your-token> \
  subscribe \
  --transactions \
  --transactions-vote false \
  --transactions-failed false \
  --transactions-account-include <Pubkey>
```

Subscribe to deshred transactions:

```shell
cargo run --bin client -- \
  -e https://<your-endpoint>.mainnet.rpcpool.com \
  --x-token <your-token> \
  subscribe-deshred \
  --vote false \
  --account-include <Pubkey>
```

Unary calls (`ping`, `get-latest-blockhash`, `get-block-height`, `get-slot`, `is-blockhash-valid`, `get-version`):

```shell
cargo run --bin client -- \
  -e https://<your-endpoint>.mainnet.rpcpool.com \
  --x-token <your-token> \
  get-slot
# response: GetSlotResponse { slot: 196214563 }
```

{% hint style="info" %}
Triton endpoints serve `subscribe-deshred`. Self-hosted, it needs `yellowstone-grpc-geyser` 14.1.1 or later on a validator that emits deshred transaction notifications. Versions before 14.0.0 return `UNIMPLEMENTED`. Versions 14.0.0 and 14.1.0 do not resolve ALT addresses.
{% endhint %}
{% endtab %}

{% tab title="TypeScript / NodeJS" %}
Since `5.0.1`, the TypeScript SDK runs on a Rust NAPI backend. Triton's benchmark measured about 400% more data throughput than the grpc-js version. [More on the NAPI rewrite](https://blog.triton.one/grpc-js-alternative-napi-rust/).

Install:

```bash
npm install --save @triton-one/yellowstone-grpc
```

The examples use top-level `await`. Set up the project as in the [streaming quickstart](https://docs.triton.one/solana/real-time-streaming/quickstart) (`type=module`, `moduleResolution` bundler).

Initialize:

```typescript
import Client from "@triton-one/yellowstone-grpc";

const client = new Client(
  "https://<your-endpoint>.mainnet.rpcpool.com:443",
  "<your-token>",
  undefined
);

await client.connect();

const version = await client.getVersion();
console.log(version);
```

Open a subscription stream:

```typescript
import { SubscribeRequest } from "@triton-one/yellowstone-grpc";

const stream = await client.subscribe();

stream.on("data", (data) => {
  console.log("data", data);
});

const request: SubscribeRequest = { /* see Subscribe request */ };

await new Promise<void>((resolve, reject) => {
  stream.write(request, (err) =>
    err == null ? resolve() : reject(err)
  );
});
```

Full example: [yellowstone-grpc/examples/typescript](https://github.com/rpcpool/yellowstone-grpc/tree/master/examples/typescript).
{% endtab %}

{% tab title="grpcurl" %}
`grpcurl` is good for testing. You need the corresponding Protobuf `.proto` files (starting with `geyser.proto` and its dependencies) so `grpcurl` can describe the protocol.

```shell
./grpcurl \
  -proto geyser.proto \
  -d '{"slots": { "slots": {} }, "accounts": { "usdc": { "account": ["9wFFyRfZBsuAha4YcuxcXLKwMxJR43S7fPfQLusDBzvT"] } }, "transactions": {}, "blocks": {}, "blocks_meta": {}}' \
  -H "x-token: <your-token>" \
  <your-endpoint>.mainnet.rpcpool.com:443 \
  geyser.Geyser/Subscribe
```

Self-hosters can drop the `x-token` header.
{% endtab %}

{% tab title="Go" %}
Requires Go 1.24. Clone the repo and run the sample client from `examples/golang`:

```shell
git clone https://github.com/rpcpool/yellowstone-grpc
cd yellowstone-grpc/examples/golang
go run ./cmd/grpc-client/ \
  -endpoint https://<your-endpoint>.mainnet.rpcpool.com:443 \
  -x-token <your-token> \
  -slots
```

Updating proto files needs `protoc` plus the Go plugins:

```shell
go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.35.1
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.5.1
```

Run `make` in `examples/golang` to regenerate. Full source: [yellowstone-grpc/examples/golang](https://github.com/rpcpool/yellowstone-grpc/tree/master/examples/golang).

{% hint style="info" %}
The Go example may lag the latest stable proto version. For production-ready code, the Rust client is the reference implementation.
{% endhint %}
{% endtab %}

{% tab title="Python" %}
The repo's [yellowstone-grpc/examples/python](https://github.com/rpcpool/yellowstone-grpc/tree/master/examples/python) directory ships `helloworld_geyser.py`. It sends the `x-token` as call metadata over TLS, then calls a unary method:

```python
import grpc
import geyser_pb2, geyser_pb2_grpc

class TritonAuth(grpc.AuthMetadataPlugin):
    def __init__(self, x_token):
        self.x_token = x_token

    def __call__(self, context, callback):
        # metadata is a 1-tuple; the trailing comma is required
        callback((("x-token", self.x_token),), None)

ssl_creds = grpc.ssl_channel_credentials()
call_creds = grpc.metadata_call_credentials(TritonAuth("<your-token>"))
creds = grpc.composite_channel_credentials(ssl_creds, call_creds)

with grpc.secure_channel("<your-endpoint>.mainnet.rpcpool.com:443", creds) as channel:
    stub = geyser_pb2_grpc.GeyserStub(channel)
    print(stub.GetSlot(geyser_pb2.GetSlotRequest()))
```

Install `grpcio`, `grpcio-tools`, and `protobuf`, and generate `geyser_pb2` from the proto files first.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
If you're experiencing errors, you can sanity-check your endpoint with Triton's prebuilt `client-linux-amd64` test binary (x86-64 Linux), no code required. See [Verify your gRPC endpoint](https://docs.triton.one/solana/faq/error-handling/verify-your-grpc-endpoint).
{% endhint %}

## Pricing

On shared infrastructure, Dragon's Mouth is billed by the bandwidth you stream. See [pricing](https://triton.one/pricing).

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-fire">:fire:</i> <strong>Deshred Transactions gRPC</strong></td><td>Transactions reconstructed from shreds before execution.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/deshred-transactions">Deshred Transactions gRPC</a></td></tr><tr><td><i class="fa-rotate-right">:rotate-right:</i> <strong>WebSocket</strong></td><td>Triton's Solana WebSocket API for browsers and frontends, served from Dragon's Mouth gRPC, with <code>transactionSubscribe</code>.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/whirligig-websockets">WebSocket</a></td></tr><tr><td><i class="fa-layer-group">:layer-group:</i> <strong>Fumarole Persistent gRPC</strong></td><td>Redundant streaming layer with 4 days of stored data and built-in cursor resume.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/fumarole-persistent-streams">Fumarole Persistent gRPC</a></td></tr><tr><td><i class="fa-compass">:compass:</i> <strong>Streaming overview</strong></td><td>Compare Dragon's Mouth, Riptide, Shred Streaming, Deshred, Preconfirmations, WebSocket, and Fumarole.</td><td><a href="https://docs.triton.one/solana/real-time-streaming">Real-time streaming</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Riptide

Dragon's Mouth gRPC at riptide.rpcpool.com, a lower-latency path for shared subscriptions, with connection details, 403 errors, and reconnect handling.

Riptide is a separate endpoint for the existing [Dragon's Mouth gRPC service](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc). It provides the same streams, unary methods, protocol, and SDK support through a lower-latency network path.

If you use Dragon's Mouth through a shared subscription, point your client at `https://riptide.rpcpool.com:443`. Your shared-subscription token, SDK, Protobuf version, subscription requests, and filters continue to work.

## Connection details

| Setting        | Value                                                           |
| -------------- | --------------------------------------------------------------- |
| Endpoint       | `https://riptide.rpcpool.com:443`                               |
| Availability   | Shared subscriptions — see [Availability](#availability)        |
| Authentication | Your shared-subscription token in the `x-token` metadata header |
| Protocol       | Dragon's Mouth / Yellowstone gRPC over TLS                      |
| Network        | Mainnet                                                         |
| Routing        | Automatic to the nearest location via `riptide.rpcpool.com`     |

Riptide serves Dragon's Mouth gRPC. Use your standard RPC endpoint for JSON-RPC and WebSocket requests. For client setup, subscription filters, and request examples, see the [Dragon's Mouth documentation](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc).

## Availability

Riptide is available on shared Dragon's Mouth subscriptions, and usage is billed as part of the shared service. Dedicated-node tokens do not work on `riptide.rpcpool.com`.

If your account has dedicated nodes and no shared subscription, you have two options:

* Add a shared gRPC subscription to your account for immediate access. Shared-service billing applies.
* Contact our support team — over your dedicated support channel, or at <support@triton.one> — to ask whether a dedicated Riptide setup is available for your own nodes.

{% hint style="info" %}
A `403 Access forbidden` response with empty `x-ratelimit-*` headers means the token you are sending is not enabled for this endpoint. Check that the token value is correct, use your shared-subscription token, or contact our support team to enable access.
{% endhint %}

## Connection resets and reconnection

Riptide's failover operates at the connection level: it directs new connections to healthy backends but cannot move an existing gRPC stream between them. Because the network path can change during normal operation, a dropped connection may arrive as a TCP reset (`RST`) rather than a graceful close. Your client should:

1. Detect stream errors, end-of-stream events, and TCP resets.
2. Reconnect automatically, using exponential backoff with jitter for repeated failures.
3. Create a new stream and send the complete subscription request again after reconnecting.
4. Track the last fully processed slot and use [`from_slot`](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc#replay-from-a-slot) to recover buffered updates after a short interruption. Deduplicate updates from the replayed slot.

Ordinary subscriptions in the Dragon's Mouth Rust and TypeScript clients don't reconnect, so build these steps into your client. `subscribe_with_reconnect` (Rust) and `subscribeWithReconnect()` (TypeScript) reconnect, resubscribe, and replay for you, and your code drops the partly delivered banks each `Disconnected` event lists. See [Reconnect with bank recovery](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc#reconnect-with-bank-recovery).

Riptide does not replace or deprecate your existing Dragon's Mouth endpoint. It provides the same features over a faster path, and the reconnection handling above applies to both endpoints, so if you use a shared subscription, we recommend moving your gRPC traffic to Riptide.

## What's next

* [Dragon's Mouth gRPC](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc) — filters, subscription requests, and client examples
* [Real-time streaming overview](https://docs.triton.one/solana/real-time-streaming) — compare Triton's streaming interfaces
* [Real-time streaming best practices](https://docs.triton.one/solana/real-time-streaming/best-practices) — reconnection and throughput guidance

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Shred Streaming

Shred Streaming sends a full, deduplicated feed of raw Solana shreds to your own IPs from five locations, before blocks are assembled.

{% hint style="info" %}
Triton Shred Streaming is available on request. Contact us through the [Customer Portal](https://customers.triton.one/) to have it enabled on your account.
{% endhint %}

Shred Streaming delivers Solana shreds at the earliest point the data exists on the network: before a block is assembled, before it is replayed, and before it appears in any RPC or gRPC stream.

Shreds are the fragments a leader breaks its block into and fans out across the network.

* **Used for:** trading systems, MEV searchers, market makers, and any latency-sensitive backend that reconstructs blocks itself.
* **Key feature:** a **full shred feed, deduplicated**. You receive every shred we see, and you typically receive each one only once.

## Is Shred Streaming for me?

Processing raw shreds is an advanced feature and requires custom software development on your end. It offers no filtering, and relies on forward error correction to handle any dropped or missed packets.

An alternative to raw shreds is the [SubscribeDeshred](https://docs.triton.one/solana/real-time-streaming/deshred-transactions) gRPC subscription, available on our Riptide and regular gRPC endpoints. SubscribeDeshred uses the same shred sources as Shred Streaming, but processes the shreds back into transactions for you and offers filtering.

## How to use Shred Streaming

You need to run software on your end that can decode and process raw shreds. To get you started, this repository has a full working code sample that reassembles incoming shreds into transactions:

{% embed url="<https://github.com/rpcpool/deshred-example>" %}

Use it to verify that your shred stream is working, and as a starting point for your own receiver code.

## Where you can receive shreds

Shred Streaming is available in five locations:

| Region | Location  |
| ------ | --------- |
| US     | New York  |
| EU     | London    |
| EU     | Amsterdam |
| EU     | Frankfurt |
| AP     | Tokyo     |

You can receive shreds in any of these locations, each independently of the others. Each organization starts with one destination (an IP address and port in one datacenter); contact support to raise the limit.

## Where the shreds come from

Shred Streaming aggregates shreds from several sources, so you are not dependent on a single vantage point into the network:

* **Triton validators:** shreds observed directly by the validators we operate.
* **DoubleZero Edge:** through a partnership with DoubleZero, we receive shreds from their Edge network.
* **Partner validators:** additional validators we work with, spread across the network.
* **Turbine:** for any validator we do not partner with and which is not sending its shreds through DoubleZero Edge, we receive its shreds via Turbine.

Because the same shred usually arrives from more than one of these sources, the feed is deduplicated before it reaches you: whichever copy arrives first is the one you get, and later duplicates are discarded.

## How it works

Shred Streaming runs on a custom network built specifically for shred distribution.

* **Shortest-path ingestion.** Our receivers are positioned so that shreds reach our network over the shortest available path from the leader, rather than over whatever route the public Internet happens to pick.
* **Custom low-latency path.** Once a shred is inside our network, we distribute it between datacenters over Triton's own path instead of the public Internet.
* **Multicast distribution.** Within each datacenter, shreds are distributed over multicast to the hosts that forward them to your destinations.
* **Dedicated network ports.** We use dedicated shred distribution hosts with multiple dedicated network ports to reduce distribution latency.

The result is that a shred picked up in one location is available to subscribers in every other location very shortly after we first see it.

## Getting started

{% stepper %}
{% step %}

### Request access

Contact customer support through the [Customer Portal](https://customers.triton.one/) and ask to have Shred Streaming enabled on your account.
{% endstep %}

{% step %}

### Configure your destinations

Once it is enabled, a "Shred stream IPs" card appears on your mainnet-shared subscription page in the Customer Portal. Click "Add shred stream IP" and enter the **IP address and port** you want shreds delivered to (a public IPv4 address; the port defaults to `8002`), optionally add a label, select the datacenter, and click "Add IP". Add a destination for each datacenter you want to receive in, up to your limit. Shortly after you add them, shreds start arriving from our source IP, `67.209.53.15`.
{% endstep %}

{% step %}

### Start receiving

Make sure the hosts you list can accept the traffic: the destination IPs must be reachable and the ports open. If you have an ingress firewall, allow traffic from `67.209.53.15`.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
A full shred feed is high-bandwidth and bursty. Provision the receiving hosts and their network capacity accordingly, and place them as close as possible to the location you subscribe from.
{% endhint %}

## Questions

For help with sizing, location selection, or anything else about Shred Streaming, reach out through your Triton CS channel or the [Customer Portal](https://customers.triton.one/).

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Deshred Transactions gRPC

SubscribeDeshred streams Solana transactions rebuilt from shreds before execution, with vote and account filters and best-effort ALT resolution.

Deshred is the `SubscribeDeshred` method on the same gRPC service as Dragon's Mouth `Subscribe`.

## Use cases

Deshred is for strategies that act before the node replays transactions:

* **HFT and arbitrage** that react to transaction intent the moment entries form from shreds.
* **MEV and market making** that need an early view of price-impacting transactions.
* **Copy-trading and liquidations** that follow specific accounts as soon as they act.

**What not to use it for.** If you need execution results (status, balance changes, logs) or any confirmation guarantee, use the [Dragon's Mouth](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc) `transactions` stream instead, or run it in parallel on its own connection and join on `signature`. Stream Dragon's Mouth at `processed` and track `confirmed` and `finalized` on the client from [slot notifications](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc#slots). Deshred shows intent, not outcome: a transaction may fail, land on a dead fork, or never confirm.

## Features and benefits

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-eye">:eye:</i> <strong>Pre-execution stream</strong></td><td>Transactions reconstructed from shreds, before the node replays them.</td><td></td></tr><tr><td><i class="fa-code-fork">:code-fork:</i> <strong>Same gRPC interface</strong></td><td>Same client library, separate method. Open a separate connection for each stream, including your Dragon's Mouth stream.</td><td></td></tr><tr><td><i class="fa-tags">:tags:</i> <strong>Resolved ALT addresses</strong></td><td>Includes writable and readonly addresses resolved from Address Lookup Tables.</td><td></td></tr></tbody></table>

## How it works

Unlike the standard `Subscribe` transaction stream, deshred updates are emitted **before** Replay. You receive the decoded transaction earlier, but without execution context.

The lead over Dragon's Mouth varies per transaction. Measure it against the `transactions` stream at `processed`, not `confirmed` or `finalized`, which arrive later. Run both streams on separate connections and join on `signature`. Subtract the `processed` arrival time from the Deshred arrival time, so a negative value means Deshred arrived first. Compare P50 and P99 of that difference. P99 is the slow tail, the transactions where Deshred arrived latest relative to `processed`. Real-time workloads care about that tail.

```mermaid
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#F2EDF6','primaryBorderColor':'#7A4BA0','primaryTextColor':'#171717','lineColor':'#956FB3','secondaryColor':'#E4DBEC','tertiaryColor':'#D7C9E3','edgeLabelBackground':'#F2EDF6'},'flowchart':{'nodeSpacing':20,'rankSpacing':35,'curve':'linear'}}}%%
flowchart LR
    s["Shreds"] --> r["Reconstruct<br/>transactions"]
    r --> e["Execute + replay"] --> g["Regular gRPC"]
    r --> d["Deshred Transactions gRPC<br/>(pre-execution)"]
    style d fill:#D6EAF8,stroke:#259DD0
```

## Filter configuration

`SubscribeDeshred` matches transactions on four filter fields, combined as logical AND, and has one opt-in flag:

| Parameter               | Type       | Required | Description                                                                                                                                                                                                         |
| ----------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vote`                  | `bool`     | No       | `true` returns vote transactions. `false` returns non-vote transactions. Omitted returns both. Alpenglow blocks have none.                                                                                          |
| `account_include`       | `string[]` | No       | Match transactions that mention any of these accounts, including ALT addresses the node resolves at its root slot. Empty list: no restriction.                                                                      |
| `account_exclude`       | `string[]` | No       | Exclude transactions mentioning any of these accounts, including ALT addresses the node resolves at its root slot. A transaction that reaches an excluded account only through an unresolved table is not excluded. |
| `account_required`      | `string[]` | No       | Accounts that MUST all be mentioned (every one of them), including ALT addresses the node resolves at its root slot.                                                                                                |
| `include_update_parent` | `bool`     | No       | Also send `SubscribeUpdateDeshredUpdateParent` updates. Omitted or `false`: transactions are sent, update parents are not.                                                                                          |

For the full request and update fields, see the [SubscribeDeshred method reference](https://docs.triton.one/solana/rpc-methods/real-time-streaming/yellowstone-grpc/deshred).

## Subscribe and consume

The latest protobuf files live in the [yellowstone-grpc repo](https://github.com/rpcpool/yellowstone-grpc/tree/master/yellowstone-grpc-proto/proto). For Rust, use the [yellowstone-grpc-client](https://crates.io/crates/yellowstone-grpc-client) and [yellowstone-grpc-proto](https://crates.io/crates/yellowstone-grpc-proto) crates.

{% tabs %}
{% tab title="TypeScript" %}
The examples use top-level `await`. Set up the project as in the [streaming quickstart](https://docs.triton.one/solana/real-time-streaming/quickstart) (`type=module`, `moduleResolution` bundler).

```typescript
import Client, {
  SubscribeDeshredRequest,
} from "@triton-one/yellowstone-grpc";

const client = new Client(
  "https://<your-endpoint>.mainnet.rpcpool.com",
  "<your-token>",
  undefined
);

await client.connect();
const stream = await client.subscribeDeshred();

stream.on("data", (data) => {
  console.log("data", data);
});

const request: SubscribeDeshredRequest = {
  slots: {},
  deshredTransactions: {
    client: {
      vote: false,
      accountInclude: [],
      accountExclude: [],
      accountRequired: [],
    },
  },
  ping: undefined,
};

await new Promise<void>((resolve, reject) => {
  stream.write(request, (err) =>
    err ? reject(err) : resolve()
  );
});
```

{% endtab %}

{% tab title="Rust" %}
{% code title="Cargo.toml" %}

```toml
[dependencies]
yellowstone-grpc-client = "17"
yellowstone-grpc-proto = "14"
solana-signature = "3"
tokio = { version = "1", features = ["full"] }
futures = "0.3"
tonic = { version = "0.14", features = ["tls-native-roots", "tls-ring"] } # TLS roots and crypto provider
anyhow = "1"
```

{% endcode %}

{% code title="src/main.rs" %}

```rust
use {
    futures::{sink::SinkExt, stream::StreamExt},
    solana_signature::Signature,
    std::collections::HashMap,
    yellowstone_grpc_client::{ClientTlsConfig, GeyserGrpcClient},
    yellowstone_grpc_proto::prelude::{
        subscribe_update_deshred::UpdateOneof, SubscribeDeshredRequest,
        SubscribeRequestFilterDeshredTransactions, SubscribeRequestPing,
    },
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let endpoint = std::env::var("ENDPOINT")
        .unwrap_or("https://<your-endpoint>.mainnet.rpcpool.com:443".into());
    let x_token = std::env::var("X_TOKEN").ok();

    let mut client = GeyserGrpcClient::build_from_shared(endpoint)?
        .x_token(x_token)?
        .tls_config(ClientTlsConfig::new().with_native_roots())?
        .http2_adaptive_window(true)
        .initial_connection_window_size(8 * 1024 * 1024) // 8 MiB
        .initial_stream_window_size(4 * 1024 * 1024) // 4 MiB
        .connect()
        .await?;

    let request = SubscribeDeshredRequest {
        deshred_transactions: HashMap::from([(
            "deshred".into(),
            SubscribeRequestFilterDeshredTransactions {
                vote: Some(false),
                account_include: vec![],
                account_exclude: vec![],
                account_required: vec![],
                ..Default::default()
            },
        )]),
        ping: None,
        ..Default::default()
    };

    let (mut tx, mut stream) =
        client.subscribe_deshred_with_request(Some(request)).await?;

    while let Some(msg) = stream.next().await {
        match msg?.update_oneof {
            Some(UpdateOneof::DeshredTransaction(update)) => {
                let info = update.transaction.as_ref().unwrap();
                let sig = Signature::try_from(info.signature.as_slice())?;
                println!("slot={} sig={sig} vote={}", update.slot, info.is_vote);
            }
            Some(UpdateOneof::Ping(_)) => {
                tx.send(SubscribeDeshredRequest {
                    ping: Some(SubscribeRequestPing { id: 1 }),
                    ..Default::default()
                }).await?;
            }
            Some(UpdateOneof::Pong(_)) => {}
            Some(UpdateOneof::Slot(_)) => {}
            // Other update types, such as update parents, are sent when you opt in
            Some(_) => {}
            None => break,
        }
    }

    Ok(())
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Response payload example

A `SubscribeUpdateDeshred` update carries a `deshred_transaction` with a single transaction reconstructed from shreds. This is a simplified shape of that field.

Clients return `signature`, `signatures`, `account_keys`, `recent_blockhash`, `loaded_writable_addresses` and `loaded_readonly_addresses` as raw bytes. The example shows them base58-encoded and with proto snake\_case names. The TypeScript client returns camelCase names, such as `deshredTransaction` and `isVote`.

```json
{
  "slot": 275123456,
  "transaction": {
    "signature": "5j7s4Hk3QmZ9xT2pK8nLm9VbY3wQ8aRf6dGjXwE5pN1",
    "is_vote": false,
    "transaction": {
      "signatures": ["5j7s4Hk3..."],
      "message": {
        "header": { "...": "..." },
        "account_keys": ["...", "..."],
        "recent_blockhash": "GpJjHvT...",
        "instructions": [{ "...": "..." }]
      }
    },
    "loaded_writable_addresses": ["..."],
    "loaded_readonly_addresses": []
  }
}
```

The `loaded_writable_addresses` and `loaded_readonly_addresses` fields contain addresses the node resolves from Address Lookup Tables (ALTs) at its root slot, so deshred filters match static account keys and, when resolution succeeds, dynamically loaded addresses. When resolution fails, both fields are empty and only static account keys match.

## Limitations

Deshred carries the raw transaction, captured before execution, so what it returns differs from the standard `transactions` stream:

| What you get             | Standard transactions (Dragon's Mouth)                                 | Deshred                                                  |
| ------------------------ | ---------------------------------------------------------------------- | -------------------------------------------------------- |
| Timing                   | At `processed`: after execution and replay                             | Pre-execution, from shreds                               |
| Transaction              | Full transaction                                                       | Full transaction                                         |
| ALT addresses            | Resolved                                                               | Resolved (writable and readonly)                         |
| Execution context        | Full: status, balance changes, inner instructions, logs, compute units | None: intent, not outcome                                |
| Confirmation or finality | Yes: track `confirmed` and `finalized` from slot notifications         | None: a transaction may fail, fork off, or never confirm |

If your pipeline needs status, logs, or balance deltas, run a parallel Dragon's Mouth `transactions` subscription on a separate connection and join on `signature`.

For architecture and tradeoffs, see [Deshred transactions on the Triton blog](https://blog.triton.one/deshred-transactions-the-fastest-path-to-solana-data/).

## Availability

* `SubscribeDeshred` runs on Triton One gRPC servers.
* Self-hosted, it needs Agave 4.1 or later and a `yellowstone-grpc-geyser` release built for your Agave version, 14.1.1 or later.
* On Agave 4.1 and 4.2, start the validator with `--full-rpc-api` and an RPC port (`--rpc-port`), or it does not emit deshred transaction notifications.

## Pricing

For rates, see the [pricing page](https://triton.one/pricing). For how billing works across Triton services, see [Plans and billing](https://docs.triton.one/account-and-billing/plans-and-billing).

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-tower-broadcast">:tower-broadcast:</i> <strong>Dragon's Mouth gRPC</strong></td><td>Sub-slot real-time updates for accounts, transactions, slots, and blocks via gRPC.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc">Dragon's Mouth gRPC</a></td></tr><tr><td><i class="fa-newspaper">:newspaper:</i> <strong>Deshred blog post</strong></td><td>Architecture, tradeoffs, and how Deshred fits the Solana shred pipeline.</td><td><a href="https://blog.triton.one/deshred-transactions-the-fastest-path-to-solana-data/">https://blog.triton.one/deshred-transactions-the-fastest-path-to-solana-data/</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Preconfirmations gRPC

Triton Preconfs streams preconfirmed Solana transactions over gRPC from Harmonic and BAM, with x-token auth, Rust quick start and grpcurl steps.

## What a preconfirmation is

On Solana one validator is the [leader](https://docs.anza.xyz/consensus/leader-rotation) for each [slot](https://solana.com/docs/references/terminology#slot) and builds the block for it. A transaction you send travels to that leader; the leader executes it, packs it into entries, splits the entries into shreds and broadcasts them; every other node receives the shreds, replays the block and then reports the transaction, first at `processed` [commitment](https://solana.com/docs/rpc#configuring-state-commitment), later at `confirmed` and `finalized`. Everything you can observe through an RPC node, a WebSocket or a Geyser stream sits at the end of that path.

A preconfirmation is a message emitted at the start of it. The party assembling the block, the builder or the leader itself, tells you the moment a transaction has been executed or committed into the slot under construction, before any shred exists. You learn what the block will contain while it is still being built. The message carries the raw transaction bytes exactly as the block will, plus the slot and, depending on the feed, the execution outcome and the position in the block.

{% hint style="warning" %}
A preconfirmation is a statement by the block producer, not a confirmation by the cluster. The slot can still be skipped, the block can land on a fork that is abandoned, and a leader can restart a slot. A preconfirmed transaction can still fail to land: act on it as an early signal, and treat `confirmed` and `finalized` as settlement.
{% endhint %}

## How each feed produces one

[**Harmonic**](https://docs.harmonic.gg/) runs block builders next to leaders that run the Harmonic validator client. Transactions reach the builder, which executes them and fixes their order for the block. As it does so it streams the executed transactions to subscribers in batches, numbered from zero within each slot and delivered in order, with a start and an end marker per slot. Each transaction carries the outcome the builder observed: success, execution failure (committed, fees charged, state reverted) or fees only (failed to load, the fee is charged). The leader then executes the same transactions again, in parallel; Harmonic states that the resulting state is equivalent to executing them serially in batch order, so the outcome you receive is normally the outcome that lands. A Harmonic preconfirmation therefore means: this transaction was executed with this result and sits in the block being built.

[**BAM**](https://bam.dev/docs/bam/bam-overview/), Jito's Block Assembly Marketplace, sits between transaction senders and leaders that run the BAM validator client. A BAM node schedules the transactions it receives, first in first out with respect to the accounts they lock, and hands them to the leader; the leader executes them and acknowledges each one back to the node, which streams it to subscribers. Each transaction carries the node it came through, its position in the scheduler's sequence (transactions sharing a sequence were bundled together), its position inside that bundle, whether the bundle reverts on error, and the outcome the leader reported to the node: success or execution failure. BAM does not separate a transaction that failed to load from one that failed to execute; both arrive as an execution failure. A node that does not report the outcome leaves it unset. A BAM preconfirmation therefore means: this transaction was committed by the leader into the slot, with the outcome the leader reported.

Triton subscribes to both systems in every region they publish from and delivers the same bytes to you over one endpoint, filtered to the accounts, signers, instructions and signatures you ask for.

## Harmonic and BAM side by side

|                          | Harmonic                                             | BAM                                                                   |
| ------------------------ | ---------------------------------------------------- | --------------------------------------------------------------------- |
| who produces the preconf | the block builder, before the leader executes        | the BAM node, after the leader executes and acknowledges              |
| what it asserts          | executed with this outcome, in the block being built | committed by the leader into the slot                                 |
| execution outcome        | success, execution failure, fees only                | success or execution failure, as the leader reported it; may be unset |
| ordering information     | batch number within the slot                         | scheduler sequence, bundle position, revert on error                  |
| slot framing             | `SlotStart` and `SlotEnd` per slot                   | none, each transaction names its slot                                 |
| regions                  | 7                                                    | 15                                                                    |

## What the feeds cover, and what they do not

The feeds are not a copy of the chain. Three things decide what a stream carries.

**Slots led by a validator running that client.** Harmonic preconfirms the slots of leaders on the Harmonic client; BAM preconfirms the slots of leaders on the BAM client. A slot led by any other validator has no preconfirmation on either feed, from any region. The share of slots each feed covers follows the stake running its client and changes as validators switch. Neither feed sees the other's slots, so subscribing to both is how you cover the most slots.

**Static account keys.** Filters match the accounts written in the transaction message. Accounts a v0 transaction reaches through an address lookup table are not matched; legacy and v1 transactions carry every account inline and are matched in full. A filter can therefore see fewer transactions than expected; see [Address lookup tables](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/filters#address-lookup-tables).

**One region, one stream, and the regions near you.** Each regional stream carries the slots of the leaders that region serves, not a copy of the whole feed. A far region's preconfirmations arrive after the people located there have acted on them. See [Choosing regions](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/feeds-and-regions#choosing-regions).

## Endpoint

`https://preconfs.rpcpool.com`

The address is anycast: the connection lands on the closest point of presence, one of the servers behind that address; every point of presence serves every region of both feeds. Every request carries an `x-token`, a token of your subscription once preconfs has been enabled on it (see [Access](#access)).

Each subscription may receive up to a share of a feed's traffic in each region. Over it, matching transactions are withheld and the count is announced on the stream; nothing is ever dropped silently. See [Coverage](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/coverage-billing-and-limits#coverage).

`GetVersion` tells you which point of presence took your connection; see [Which point of presence answered](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/feeds-and-regions#which-point-of-presence-answered).

## Access

{% hint style="info" %}
Preconfs is enabled per subscription, on request. It is not included in any plan by default, and a token that works for other Triton services, such as a mainnet RPC token, is not entitled to it until we enable it for that subscription. [Contact us](https://triton.one/contact) before you set up billing for it: we confirm which feeds you need and which regions suit your servers, and enable the feeds on your subscription.
{% endhint %}

Each feed is enabled and metered separately: a token is entitled to the feeds enabled on its subscription, and a request for one feed does not enable another. Every region of an enabled feed is open to the subscription.

### Token

Every request, `GetVersion` and health checks included, carries an `x-token`: a token of a subscription with at least one preconfs feed enabled. It is the same token you use for other Triton gRPC services on that subscription; there is no separate preconfs token. Send the token's value, not its name.

Enabling a feed on a subscription reaches the servers within a few minutes. Turning a feed off closes the open streams of that subscription's tokens on that feed with `PERMISSION_DENIED`.

### When a token is refused

| status              | message                               | meaning                                                                                                                 |
| ------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `UNAUTHENTICATED`   | `x-token required`                    | the call carried no `x-token`                                                                                           |
| `UNAUTHENTICATED`   | `x-token not entitled to preconfs`    | the token is unknown, or no preconfs feed is enabled on its subscription; returned on every call, `GetVersion` included |
| `UNAUTHENTICATED`   | `x-token not entitled to this feed`   | the subscription has a preconfs feed, but not the one you subscribed to                                                 |
| `PERMISSION_DENIED` | `subscription disabled for this feed` | the feed was turned off on the subscription while the stream was open                                                   |

These are the expected answers for a token without the entitlement, not a connectivity or client problem; the client treats them as fatal and does not retry.

## Client

The Rust client and the protobuf definitions are on [GitHub](https://github.com/rpcpool/preconfs-client) as the `triton-preconfs-client` and `triton-preconfs-proto` crates. The client needs Rust 1.89 or later. Other languages use the proto directly, see [Other languages](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/other-languages).

## Quick start

{% stepper %}
{% step %}

### Add the client

{% code title="Cargo.toml" %}

```toml
[dependencies]
triton-preconfs-client = "0.4"
solana-pubkey = "4"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
```

{% endcode %}
{% endstep %}

{% step %}

### Subscribe and print what arrives

Subscribe to Harmonic in Amsterdam for transactions touching the SPL token program and print what arrives:

{% code title="src/main.rs" %}

```rust
use solana_pubkey::Pubkey;
use triton_preconfs_client::{Connector, Event, Feed, Filter, Filters, Region, parse};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Connector::new("https://preconfs.rpcpool.com")
        .x_token(Some(std::env::var("PRECONFS_TOKEN")?))
        .connect()
        .await?;

    let token_program: Pubkey = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA".parse()?;
    let region = Region::parse(Feed::Harmonic, "ams")?;
    let filters = Filters::single(Filter::new().accounts([token_program]));

    let mut stream = client.subscribe_harmonic(region, filters).await?;
    while let Some(event) = stream.next().await {
        match event? {
            Event::Transaction(matched) => {
                let signature = parse::parse_signature(&matched.transaction.transaction)?;
                println!("slot {} {signature}", matched.transaction.slot);
            }
            Event::SlotEnd { slot } => println!("slot {slot} complete"),
            Event::Reconnected { attempts } => println!("reconnected after {attempts} attempts"),
            _ => {}
        }
    }
    Ok(())
}
```

{% endcode %}
{% endstep %}

{% step %}

### Run it

```bash
PRECONFS_TOKEN=<your token> cargo run
```

`Event` is non-exhaustive, so keep the `_` arm. The same shape works for BAM with `Feed::Bam` and `subscribe_bam`.
{% endstep %}
{% endstepper %}

### The example CLI

The repository ships `preconfs-subscribe`, which subscribes and logs every event. From a clone of the repository:

```bash
cargo run -p preconfs-example -- --x-token $TOKEN --region harmonic:ams \
    --account TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
```

`--region bam:fra`, `--require`, `--exclude`, `--signer`, `--exclude-signer`, `--instruction`, `--data-size`, `--signature`, `--result`, `--dial` and `--no-reconnect` cover the other options; `--help` lists them. The token can also come from the `PRECONFS_TOKEN` environment variable. Every transaction invoking Meteora DBC `create_config`, from any creator:

```bash
cargo run -p preconfs-example -- --x-token $TOKEN --region bam:fra \
    --instruction dbcij3LWUppWqq96dh6gJWwBifmcGfLSB5D4DuSMaqN:0:c9cff3724b6f2fbd
```

### Trying it with grpcurl

Download `preconfs.proto` from the repository, then subscribe:

```bash
curl -sO https://raw.githubusercontent.com/rpcpool/preconfs-client/main/preconfs-proto/proto/preconfs.proto

grpcurl -import-path . -proto preconfs.proto \
  -H "x-token: $TOKEN" \
  -d '{"harmonic_region":"HARMONIC_REGION_FRA","transactions":{"t":{"account_include":["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"]}}}' \
  preconfs.rpcpool.com:443 preconfs.Harmonic/Subscribe
```

For BAM call `preconfs.BAM/Subscribe` with `"bam_region":"BAM_REGION_FRA"`.

## In this section

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Feeds and regions</strong></td><td>The Harmonic and BAM regions, and how to choose the ones near your servers.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/feeds-and-regions">Feeds and regions</a></td></tr><tr><td><strong>Filters</strong></td><td>Select transactions by account, signer, instruction, signature and outcome.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/filters">Filters</a></td></tr><tr><td><strong>Stream and message format</strong></td><td>Stream events, slot framing and the fields on every transaction.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/stream-and-message-format">Stream and message format</a></td></tr><tr><td><strong>Coverage, billing and limits</strong></td><td>The per-region coverage share, billing, and limits on filters and streams.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/coverage-billing-and-limits">Coverage, billing and limits</a></td></tr><tr><td><strong>Errors and reconnection</strong></td><td>Error types, status codes and the client's reconnect behavior.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/errors-and-reconnection">Errors and reconnection</a></td></tr><tr><td><strong>Other languages</strong></td><td>Use the gRPC API from any language through preconfs.proto.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/other-languages">Other languages</a></td></tr><tr><td><strong>Preconfirmations FAQ</strong></td><td>Answers to the questions we get most often.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/faq">Preconfirmations FAQ</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Feeds and regions

Harmonic and BAM region codes for Preconfirmations gRPC, how to choose regions near your servers, and which point of presence answered GetVersion.

Three things carry the word region; they are not the same thing.

```
Solana leaders                        Solana leaders
      │                                     │
      ▼                                     ▼
Harmonic builders                       BAM nodes
ams ewr fra lon tyo sgp slc             ams dfw dub ewr fra hkg iad lax
                                        lon pit sea sin slc sqq tyo
      │                                     │
      └─────────────────┬───────────────────┘
                        ▼
          Triton points of presence
          ams1 fra1 lon1 nyc1 ...   each relays every region
                        │
                        ▼
          https://preconfs.rpcpool.com   anycast picks the closest
                        │
                        ▼
          your stream: one feed, one region
```

**Feed regions** are the ones in the proto (`HarmonicRegion`, `BamRegion`) and in the subscribe request. Harmonic runs a block builder in each of its regions and BAM runs a node in each of its; a leader is served by one of them, and that location's stream carries the slots of the leaders it serves. The regional streams are not copies of each other: `harmonic:ams` and `harmonic:fra` deliver different slots. Subscribe to the ones near your servers; see [Choosing regions](#choosing-regions). The locations in the table below are where the feed operators run their builders and nodes. They are not Triton points of presence.

**Origin on each transaction**: `region` on a Harmonic transaction and `node` on a BAM transaction name the builder or node it came through. On a single region stream it matches what you subscribed; it is there so transactions stay self describing when you merge streams.

**Points of presence** are Triton's servers, named after their site (`ams1`, `fra1`, `lon1`, `nyc1` and so on). The anycast address lands you on the closest one and every point of presence relays every feed region, so where you connect never limits what you can subscribe to. `Client::version` returns the one that answered in its `region` field.

A stream serves one feed in one region. A region of the other feed is refused.

## Regions

| Location             | Harmonic region | BAM region |
| -------------------- | --------------- | ---------- |
| Amsterdam            | `ams`           | `ams`      |
| Dallas               | -               | `dfw`      |
| Dublin               | -               | `dub`      |
| New York (Newark)    | `ewr`           | `ewr`      |
| Frankfurt            | `fra`           | `fra`      |
| Hong Kong            | -               | `hkg`      |
| Washington (Ashburn) | -               | `iad`      |
| Los Angeles          | -               | `lax`      |
| London               | `lon`           | `lon`      |
| Pittsburgh           | -               | `pit`      |
| Seattle              | -               | `sea`      |
| Singapore            | `sgp`           | `sin`      |
| Salt Lake City       | `slc`           | `slc`      |
| Siauliai             | -               | `sqq`      |
| Tokyo                | `tyo`           | `tyo`      |

## Harmonic

The builder executes the transaction and reports the outcome: success, execution failure or fees only. Streams are framed per slot (see [Slot framing](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/stream-and-message-format#slot-framing)).

## BAM

The leader commits the transaction and reports to the node whether it succeeded; a node that does not report it leaves the outcome unset. There is no slot framing: each transaction names its slot.

## Choosing regions

Pick the regions near you. Do not subscribe to all of them.

A preconfirmation is worth what its lead over the landed block is worth, and that lead is spent on the wire. Cables do not run in straight lines: a round trip between Tokyo and Frankfurt takes around 250 ms on a normal route, so a slot preconfirmed in Tokyo reaches a server in Frankfurt more than 100 ms after it reached a server in Tokyo. By then a trader sitting in Tokyo has acted on it. On a far region you still come second every time. This is not a limit we impose; it is geography.

So: subscribe to the regions whose builders and nodes sit in your own data center or metro, one stream per region. Someone in Frankfurt subscribes to `harmonic:fra` and `bam:fra`, maybe `ams` and `lon` next to them; someone in New York to `harmonic:ewr` and `bam:ewr`, maybe `bam:iad` and `bam:pit`. Subscribe to a region elsewhere when you have a server placed there. The streams of the regions you pick share one connection.

If you do open several, merge them. Each stream carries different slots, so there is nothing to deduplicate between regions of the same feed, and framing is per stream: a `SlotEnd` on `ams` says nothing about `fra`. In Rust, `select_all` polls whichever region has an event ready:

```rust
use futures::stream::{StreamExt, select_all};
use solana_pubkey::Pubkey;
use triton_preconfs_client::{Connector, Event, Feed, Filter, Filters, Region, parse};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Connector::new("https://preconfs.rpcpool.com")
        .x_token(Some(std::env::var("PRECONFS_TOKEN")?))
        .connect()
        .await?;

    let token_program: Pubkey = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA".parse()?;
    let filter = Filter::new().accounts([token_program]);

    // The regions next to this server, one stream each, on one connection,
    // tagged with the region name so the merged output stays self describing.
    let mut streams = Vec::new();
    for name in ["fra", "ams", "lon"] {
        let region = Region::parse(Feed::Harmonic, name)?;
        let stream = client
            .subscribe_harmonic(region, Filters::single(filter.clone()))
            .await?;
        streams.push(stream.map(move |event| (name, event)).boxed());
    }

    let mut merged = select_all(streams);
    while let Some((region, event)) = merged.next().await {
        match event? {
            Event::Transaction(matched) => {
                let signature = parse::parse_signature(&matched.transaction.transaction)?;
                println!("{region} slot {} {signature}", matched.transaction.slot);
            }
            Event::SlotEnd { slot } => println!("{region} slot {slot} complete"),
            Event::Clip { transactions } => println!("{region} clipped {transactions}"),
            Event::Reconnected { attempts } => println!("{region} reconnected after {attempts}"),
            _ => {}
        }
    }
    Ok(())
}
```

Add `futures = "0.3"` for `select_all`, next to the dependencies from the [Quick start](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc#quick-start). The same shape with `Feed::Bam` and `subscribe_bam` covers the BAM regions near you; the two feeds have different event types, so merge them separately or map both into your own type first. Each stream reconnects on its own, so a point of presence restart shows up as one `Reconnected` per region.

When you open several streams:

* Each feed and region has its own coverage share; see [Coverage](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/coverage-billing-and-limits#coverage).
* Streams on the same feed and region draw on that share together at one point of presence; each point of presence measures on its own. Streams on other regions or on the other feed do not.
* A wide filter reaches the share quickly.
* The share is meant for filters that select what you actually use.
* Streams are counted against a cap of 1000 per account, both feeds together; see [Limits](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/coverage-billing-and-limits#limits).
* The cap is far above what any placement needs.

## In the client

```rust
let region = Region::parse(Feed::Harmonic, "ams")?;
let region: Region = "bam:fra".parse()?;
Feed::Bam.regions(); // the names above
```

To pin one point of presence instead of letting anycast choose, call `.dial("host:port")` on the `Connector` with that point of presence's address. The TCP connection goes to that address, while TLS still verifies `preconfs.rpcpool.com`, so the endpoint and token stay the same. `Client::version` returns the server version and the point of presence answering, which confirms the pin:

```rust
use triton_preconfs_client::Connector;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // The TCP connection goes to the pinned address; TLS still verifies
    // preconfs.rpcpool.com, so the endpoint stays the same.
    let client = Connector::new("https://preconfs.rpcpool.com")
        .x_token(Some(std::env::var("PRECONFS_TOKEN")?))
        .dial("<point-of-presence-ip>:443")
        .connect()
        .await?;

    let version = client.version().await?;
    println!("point of presence {} (server {})", version.region, version.version);
    Ok(())
}
```

`.dial()` works with `connect_lazy()` too. Every stream opened from the client, resubscribes included, goes to the pinned address.

## Which point of presence answered

`GetVersion` returns the server version and the point of presence that took your connection, and needs the token like every other call. With `preconfs.proto` in the current directory (see [Trying it with grpcurl](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc#trying-it-with-grpcurl)):

```bash
grpcurl -import-path . -proto preconfs.proto -H "x-token: $TOKEN" \
  preconfs.rpcpool.com:443 preconfs.Harmonic/GetVersion
```

```json
{
  "version": "0.6.2",
  "region": "fra1"
}
```

The version changes with every server release. The same call is `Client::version()` in the Rust client.

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Filters

Preconfirmations gRPC filters: account\_include, signer\_include, instructions, signature and execution\_results, and how address lookup tables affect matching.

A subscribe request carries one or more named filters. A transaction is delivered when it matches at least one, and every delivered transaction names the filters it matched.

A transaction matches a filter when it satisfies every condition the filter sets:

| condition                                  | matches when the transaction                                         |
| ------------------------------------------ | -------------------------------------------------------------------- |
| `account_include`                          | references any of these accounts                                     |
| `account_required`                         | references all of these accounts                                     |
| `account_exclude`                          | references none of these accounts                                    |
| `signer_include`                           | is signed by any of these accounts                                   |
| `signer_exclude`                           | is signed by none of these accounts                                  |
| `instructions`                             | has a top-level instruction passing any of these instruction filters |
| `signature` (Rust client: `.signatures()`) | has one of these first signatures                                    |
| `execution_results`                        | has one of these outcomes, as its feed reported it                   |

Every filter must select something with `account_include`, `account_required`, `signer_include`, `instructions` or `signature`; the full feed cannot be subscribed. `account_exclude`, `signer_exclude` and `execution_results` only narrow a selection, so a filter made of them alone is refused.

"References" means the account is a static account key of the transaction message. Accounts loaded through address lookup tables do not count, for includes and for excludes alike, see [Address lookup tables](#address-lookup-tables).

`execution_results` works on both feeds. A transaction whose outcome was not reported, such as one from a BAM node that does not send it, never matches it, and BAM never reports fees only.

The number of filters and instruction filters per stream, accounts per list and signatures per filter is limited; see [Limits](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/coverage-billing-and-limits#limits).

## Excluding accounts

`account_exclude` drops a transaction that references any of the listed accounts, after the rest of the filter matched. It is the "give me A, skip anything that also touches B" filter from Yellowstone gRPC and LaserStream: follow a pool without the bot that trades it all day, or a program without a spam account.

```rust
Filter::new().accounts([pool]).exclude_accounts([spammer])
```

An account a v0 transaction loads through a lookup table is not seen by the exclusion either, so a spammer reaching the account that way still gets through.

## Signers

The signers of a transaction are the first `num_required_signatures` static account keys of its message: the fee payer first, then every other account that signed, cosigners included. `signer_include` matches a transaction signed by any of the listed accounts and `signer_exclude` drops one signed by any of them. An account that is only referenced, for example the recipient of a transfer, is not a signer and does not match.

```rust
Filter::new().signers([wallet]);                          // everything the wallet signed
Filter::new().signers([wallet]).accounts([program]);      // its transactions on one program
Filter::new().instructions([swap]).exclude_signers([me]); // everyone's swaps except your own
```

## Instructions

An instruction filter names a program and, optionally, conditions on the instruction's data, the same shape as the `getProgramAccounts` filters applied to instruction data:

* `program_id`: the program the instruction invokes, required
* `memcmp`: bytes the data must hold at an offset, up to four, all must hold
* `data_size`: the exact length of the data

A transaction matches when one of its top-level instructions passes every condition of any of the listed instruction filters. Only top-level instructions exist before execution: an instruction a program invokes through CPI is not part of the transaction bytes and is not seen. Data shorter than a memcmp's end does not match.

Anchor programs start the data with an 8 byte discriminator, the first 8 bytes of `sha256("global:<instruction name>")`. Every Meteora Dynamic Bonding Curve `create_config`, from any creator and without the swaps on the same program:

```rust
let dbc: Pubkey = "dbcij3LWUppWqq96dh6gJWwBifmcGfLSB5D4DuSMaqN".parse()?;
Filter::new().instructions([
    InstructionFilter::new(dbc).memcmp(0, [201, 207, 243, 114, 75, 111, 47, 189]),
])
```

SPL Token instructions start with a one byte tag, and `data_size` pins the layout. `TransferChecked` is tag 12, an 8 byte amount and a 1 byte decimals:

```rust
Filter::new().instructions([InstructionFilter::new(token_program).memcmp(0, [12]).data_size(10)])
```

`InstructionFilter::new(program)` with no conditions matches transactions that invoke the program. `account_include` with the program id also matches transactions that only pass it as an account.

## In the client

```rust
use triton_preconfs_client::proto::preconfs::ExecutionResult;
use triton_preconfs_client::{Filter, Filters, InstructionFilter};

let create_config = [201, 207, 243, 114, 75, 111, 47, 189];
let filters = Filters::new()
    .with("token", Filter::new().accounts([token_program]))
    .with("mine", Filter::new().accounts([token_program]).require([my_account]))
    .with("clean", Filter::new().accounts([pool]).exclude_accounts([spammer]))
    .with("wallet", Filter::new().signers([wallet]))
    .with("configs", Filter::new().instructions([InstructionFilter::new(dbc).memcmp(0, create_config)]))
    .with("landed", Filter::new().accounts([my_account]).execution_results([ExecutionResult::Success]));
```

`Filters::single(filter)` names a lone filter `default`. The [client README](https://github.com/rpcpool/preconfs-client#recipes) has more recipes.

## Address lookup tables

One transaction message format hides accounts:

| format                                                                                                                                          | accounts                                                                                                                                              | lookup tables |
| ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| legacy                                                                                                                                          | every account written in the message                                                                                                                  | no            |
| v0                                                                                                                                              | static accounts in the message, plus indexes into on-chain [address lookup tables](https://solana.com/developers/cookbook/transactions/lookup-tables) | yes           |
| v1 ([SIMD-0385](https://github.com/solana-foundation/solana-improvement-documents/blob/main/proposals/0385-transaction-v1.md), the 4 KB format) | every account written in the message, up to 64                                                                                                        | no            |

For legacy and v1 transactions the bytes name every account, so a filter sees all of them. The gap is v0: its bytes carry only the table address and an index for each looked-up account, and turning those into addresses means reading the table's current state on chain.

Preconfirmations are the raw transaction bytes, emitted before the block exists. Neither Harmonic nor BAM sends resolved lookup-table addresses, and Triton does not resolve them. So for v0 transactions, filters match the static keys only. The client parses all three formats; `parse::parse_static_parts` returns exactly the keys a filter sees.

What this means in practice:

* The program id of a top-level instruction is always a static key, in every format. A filter on the SPL token program, a DEX program or pump.fun matches every transaction that invokes it at top level.
* Pools, positions, vaults and user token accounts that a v0 transaction loads through a table are not matched: a filter on such an account misses that transaction. Legacy and v1 transactions touching the same account match normally.
* The same v0 transaction seen through Deshred or Dragon's Mouth (Geyser) has its tables resolved. That is why a side by side comparison of "transactions touching account X" shows more on those streams than on the preconf stream.

If your accounts are mostly behind tables, filter on the program and on the static accounts that always accompany your transactions, and select the rest on your side. v1 transactions have no tables, so filters match all of their accounts.

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Stream and message format

Preconfirmations gRPC stream events (SlotStart, SlotEnd, Clip), Harmonic slot framing, raw transaction bytes, and every Harmonic and BAM transaction field.

`subscribe_harmonic` and `subscribe_bam` return a stream of `Event`s.

| event                      | meaning                                                                                                                                                            |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SlotStart { slot }`       | a leader began streaming preconfs for this slot (Harmonic)                                                                                                         |
| `Transaction(matched)`     | a matching transaction; `matched.filters` names the filters, `matched.transaction` is the feed's message with the raw bytes                                        |
| `SlotEnd { slot }`         | no further transactions for this slot will arrive, unless the leader restarts it (Harmonic)                                                                        |
| `Clip { transactions }`    | matching transactions were withheld, see [Coverage](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/coverage-billing-and-limits#coverage) |
| `Reconnected { attempts }` | the stream dropped and was resubscribed; the data produced in between is gone                                                                                      |

A `Clip` is a count of the matching transactions withheld on that stream since the previous notice. It names no filter, signature, account or slot. Withheld transactions are not replayed; recover them from the landed block.

The server pings every 10 seconds to keep quiet streams open, and the client consumes the pings. A stream with no slot in its region for a while simply yields no events.

If you use the proto directly instead of the Rust client, the messages are described in [Other languages](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/other-languages#updates).

## Slot framing

On Harmonic every transaction sits between its slot's `SlotStart` and `SlotEnd`. After `SlotEnd` for a slot you hold everything your filters matched for it, minus what a `Clip` reports. A stream that subscribes while a slot is open joins at the next `SlotStart`, so the first slot you see is always complete. Slot boundaries arrive whether or not your filters matched anything in that slot.

Every pending `Clip` arrives before the `SlotEnd` of the slot it hit, so a slot with no `Clip` between its `SlotStart` and `SlotEnd` is complete for your filters. There is no signal before `SlotEnd` that a slot is complete so far.

Rarely, on about 0.25% of slots, a leader restarts a slot: a second `SlotStart` for a slot that already ended, followed by its definitive transactions and a new `SlotEnd`. Rebuild your view of that slot from the new frame; the last `SlotEnd` wins.

BAM has no framing and no completion signal. Each transaction names its slot.

## Transaction bytes

`matched.transaction.transaction` holds the raw transaction bytes. The client parses what filtering needs without you writing a decoder:

```rust
let signature = parse::parse_signature(&bytes)?;
let (signature, account_keys) = parse::parse_static_parts(&bytes)?;
```

Legacy, v0 and v1 message formats are supported. `parse::parse` returns the whole decoded `VersionedTransaction`.

## Transaction fields

Harmonic (`HarmonicTransaction`):

| field         | meaning                                                                                                                |
| ------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `transaction` | raw transaction bytes                                                                                                  |
| `slot`        | slot the transaction was preconfirmed in                                                                               |
| `result`      | the builder's outcome: success, execution failure or fees only; unset if Harmonic reports one the schema does not know |
| `region`      | Harmonic region it was received from                                                                                   |
| `seq`         | preconf delivery batch within the slot, numbered from 0 and delivered in order; not an entry                           |

BAM (`BamTransaction`):

| field                | meaning                                                                                                                                                                               |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transaction`        | raw transaction bytes                                                                                                                                                                 |
| `slot`               | slot the transaction was preconfirmed in                                                                                                                                              |
| `node`               | BAM node it was received from                                                                                                                                                         |
| `sequence`           | scheduler order over the life of that node process, with gaps for transactions your filters did not match or a `Clip` withheld; transactions sharing a sequence were bundled together |
| `bundle_position`    | execution order within that bundle                                                                                                                                                    |
| `is_revert_on_error` | the bundle reverts on error (bundle intent, not an outcome)                                                                                                                           |
| `result`             | the outcome the leader reported to the node: success or execution failure; unset when it was not reported                                                                             |

Read the outcome with `execution_result()`, which returns `None` when it is unset or unknown.

```rust
use triton_preconfs_client::proto::preconfs::ExecutionResult;

match matched.transaction.execution_result() {
    Some(ExecutionResult::Success) => println!("succeeded"),
    Some(other) => println!("failed: {other:?}"),
    None => println!("outcome not reported"),
}
```

{% hint style="warning" %}
The generated `result()` returns `Success` for an unset value, so do not use it to decide whether a transaction succeeded.
{% endhint %}

The BAM schema is still changing upstream; expect fields to be added or trimmed.

## Slow consumers

A stream that cannot keep up ends with an explicit status: `RESOURCE_EXHAUSTED` when your client does not read fast enough and the outbound queue fills, `DATA_LOSS` when the stream falls too far behind the feed and the server drops its position. Both statuses are retried by the client's reconnect, which is on by default; the gap is gone.

`RESOURCE_EXHAUSTED` also ends a stream that stays over its coverage share, see [Errors and reconnection](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/errors-and-reconnection#status-codes).

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Coverage, billing and limits

Preconfirmations gRPC coverage share per region, the RESOURCE\_EXHAUSTED cooloff, what Harmonic and BAM count for billing, and limits on filters and streams.

## Coverage

Each subscription may receive up to a share of a feed's traffic in each region. This is a condition agreed with the feed operators: the share is what keeps anyone from rebuilding the full firehose through Triton. It is not a rate limit on the server; a narrow filter never hits it.

How it is measured:

* The default share is **33%** of what a feed publishes in the region you subscribe, counted over a sliding **60 second** window. It counts transactions delivered to you, after all your filters including `execution_results`. Harmonic and BAM are counted separately. The percentage is agreed with the feed operators and can change; this page states the current default.
* It belongs to the **subscription and the region**: every token, connection and stream of your subscription on one region draws on that region's share. Opening more streams on a region or rotating filters does not widen it, and each region you subscribe has a share of its own, so streams on `ams` and `fra` do not eat into each other.
* A **burst cap** holds instantaneous delivery to half the feed's current rate, so a spike cannot take the whole window's share in a second.
* Each point of presence measures on its own.

What happens over the share:

{% stepper %}
{% step %}

### Matching transactions are withheld

The count arrives as a `Clip` event, at most once a second on a timer and, on Harmonic, always before the affected slot's `SlotEnd`, so a completed slot is never silently short.
{% endstep %}

{% step %}

### The stream ends after 30 seconds over the share

If your subscription stays over the share for **30 seconds** without recovering, the stream ends with `RESOURCE_EXHAUSTED` and the message `account exceeded its coverage limit for this region, cooling off`. Every other open stream of the subscription on that region ends the same way at its next matching transaction during the cooloff.
{% endstep %}

{% step %}

### Subscribing again is refused for 60 seconds

Subscribing again to that region is refused for **60 seconds** with `account is cooling off after exceeding its coverage limit for this region, retry in <N>s`. With reconnect on, a stream that was ended this way keeps retrying on its own and resumes after the cooloff; a new subscribe call during the cooloff returns the error. Your other regions are not affected.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Staying under it: subscribe to what you act on rather than to whole programs. A filter on a busy program such as the SPL token program can reach the share quickly; the same program narrowed to one instruction with `instructions`, to your pools or wallets with `account_required` or `signer_include`, or with the spam removed by `account_exclude`, does not. If your use needs a larger share, ask through support; the share can be set per subscription and feed.
{% endhint %}

## Billing

Two quantities are counted per subscription and per feed:

| quantity   | counts                                                                                                                                    |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `messages` | transactions delivered on your streams                                                                                                    |
| `slots`    | Harmonic: every slot whose `SlotEnd` reaches your streams, matched or not. BAM: only slots with at least one transaction delivered to you |

Pay-as-you-go prices are on the [pricing page](https://triton.one/pricing). Your daily usage is in the customer panel. For how billing works across Triton services, see [Plans and billing](https://docs.triton.one/account-and-billing/plans-and-billing).

Not counted as messages: `SlotStart`, `SlotEnd`, pings, `Clip` notices, transactions your filters did not match, and transactions withheld by coverage.

Messages add up across streams: two streams whose filters overlap receive, and are counted for, the same transactions twice. A transaction matching several filters on one stream is delivered and counted once.

Slots are counted once per subscription and feed on each point of presence. More streams on a region, or a reconnect to the same point of presence, don't count a slot again. Regions carry different slots, so each region you add counts the slots it carries. Streams that land on different points of presence each count it.

## Limits

| limit                                            | value             |
| ------------------------------------------------ | ----------------- |
| filters per stream                               | 64                |
| accounts per account or signer list              | 10000             |
| signatures per filter (`signature`)              | 1000              |
| filter name                                      | 64 bytes          |
| instruction filters per stream, over all filters | 32                |
| memcmps per instruction filter                   | 4                 |
| bytes per memcmp                                 | 1 to 128          |
| memcmp end and `data_size`                       | within 4096 bytes |
| concurrent streams per account                   | 1000              |

The client checks every limit but the last before sending, so a request over a limit fails locally with a `FilterError`; the server refuses the same request with `INVALID_ARGUMENT`. Clients before 0.4.1 check 16 instruction filters per stream; upgrade to use up to 32. A memcmp that ends past its own `data_size` could never match and is refused the same way. The stream limit is counted per point of presence across both feeds. How each condition matches is described in [Filters](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/filters).

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Errors and reconnection

Preconfirmations gRPC error types and status codes (UNAUTHENTICATED, RESOURCE\_EXHAUSTED, DATA\_LOSS), and how the Rust client reconnects a dropped stream.

## Error types

| type             | from                                  | when                                                                                                                                               |
| ---------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ConnectError`   | `Connector::connect`, `connect_lazy`  | bad endpoint URI, token not ascii, TLS setup; `connect` also fails on connection refused or timed out                                              |
| `SubscribeError` | `subscribe_harmonic`, `subscribe_bam` | region of the wrong feed, filters over a limit, or the server refused the subscribe (bad token, region not served, feed not entitled, cooling off) |
| `StreamError`    | a stream item                         | the server ended the stream with a status, or closed it                                                                                            |

`RegionError` and `FilterError` are the smaller types behind `SubscribeError`. `ParseError` is returned separately by the `parse` helpers. For one top-level type wrap them with `anyhow` or `Box<dyn Error>`.

## Status codes

| status                | message                                                                                                                                                                                                          | meaning                                                                                                                                                                                                  | what to do                                                                                                                                |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `UNAUTHENTICATED`     | `x-token required`, `x-token not entitled to preconfs`, `x-token not entitled to this feed`                                                                                                                      | no token, an unknown token or one with no preconfs feed, or a token without this feed; see [Access](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc#access)                     | send the token's value and check the feed is enabled                                                                                      |
| `PERMISSION_DENIED`   | `subscription disabled for this feed`                                                                                                                                                                            | the feed was disabled on the subscription while the stream was open                                                                                                                                      | the stream is closed; re-enable the feed                                                                                                  |
| `INVALID_ARGUMENT`    | for example `harmonic_region is required; one stream serves one region`, or `filter <name>: …`                                                                                                                   | region missing, unspecified or of the other feed; a filter over a limit, with no selector, or with a value that does not parse                                                                           | fix the request                                                                                                                           |
| `FAILED_PRECONDITION` | `region <name> is not served here; served: {…}`                                                                                                                                                                  | the region is not served by this deployment                                                                                                                                                              | use one of the regions in [Feeds and regions](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/feeds-and-regions) |
| `RESOURCE_EXHAUSTED`  | `account exceeded its coverage limit for this region, cooling off`, `account is cooling off after exceeding its coverage limit for this region, retry in <N>s`, `subscriber cannot keep up, outbound queue full` | over the [coverage](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/coverage-billing-and-limits#coverage) share for 30 seconds, still cooling off, or the client cannot keep up | narrow the filters, read faster, retry after the cooloff                                                                                  |
| `DATA_LOSS`           | `subscriber lagged <N> events behind`                                                                                                                                                                            | the stream fell so far behind the feed that the server dropped its position                                                                                                                              | reconnect; the gap is gone                                                                                                                |
| `UNAVAILABLE`         | `service shutting down`                                                                                                                                                                                          | the point of presence is restarting                                                                                                                                                                      | reconnect; anycast lands on another                                                                                                       |

## Reconnect

Points of presence restart on every deploy, so a long-lived stream will drop. By default the Rust client resubscribes the stream with the same request after a backoff and yields `Event::Reconnected`.

{% hint style="warning" %}
Preconfs produced in between are gone; on Harmonic, framing restarts at the next `SlotStart`.
{% endhint %}

| Not retried: errors that retrying cannot fix end the stream | Retried             |
| ----------------------------------------------------------- | ------------------- |
| `Unauthenticated`                                           | `Unavailable`       |
| `PermissionDenied`                                          | `DataLoss`          |
| `InvalidArgument`                                           | `ResourceExhausted` |
| `FailedPrecondition`                                        | `Internal`          |
| `NotFound`                                                  | `Unknown`           |
| `AlreadyExists`                                             | `Aborted`           |
| `OutOfRange`                                                | `Cancelled`         |
| `Unimplemented`                                             | `DeadlineExceeded`  |
|                                                             | A closed stream     |

A stream reconnects once it is open: the first `subscribe_harmonic` or `subscribe_bam` call is not retried, and its error is yours to handle.

The default schedule waits 100ms, then doubles up to 10s between attempts, and never gives up. Tune or disable it on the connector:

```rust
use std::time::Duration;
use triton_preconfs_client::{Connector, Reconnect};

let client = Connector::new(endpoint)
    .reconnect(
        Reconnect::default()
            .initial_interval(Duration::from_millis(250))
            .multiplier(2.0)
            .max_interval(Duration::from_secs(30))
            .max_retries(Some(20)),
    )
    .connect()
    .await?;

let client = Connector::new(endpoint).no_reconnect().connect().await?;
```

With reconnect off the stream yields the error and ends.

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Other languages

Call Preconfirmations gRPC from any language with preconfs.proto: Harmonic and BAM services, x-token metadata, Subscribe request fields and updates.

The wire contract is `preconfs.proto` in the [client repository](https://github.com/rpcpool/preconfs-client) (`preconfs-proto/proto/preconfs.proto`); the same file is exported by the Rust proto crate as `PROTO_SOURCE`. Generate a client for your language from it. Triton publishes no TypeScript or Python client. To try the API without writing code, see [Trying it with grpcurl](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc#trying-it-with-grpcurl).

## Calls

| service                 | rpc                                                           |                                                              |
| ----------------------- | ------------------------------------------------------------- | ------------------------------------------------------------ |
| `preconfs.Harmonic`     | `Subscribe(SubscribeRequest) returns (stream HarmonicUpdate)` | the Harmonic stream                                          |
| `preconfs.Harmonic`     | `GetVersion(VersionRequest) returns (VersionResponse)`        | server version and point of presence region; needs the token |
| `preconfs.BAM`          | `Subscribe(SubscribeRequest) returns (stream BamUpdate)`      | the BAM stream                                               |
| `preconfs.BAM`          | `GetVersion(VersionRequest) returns (VersionResponse)`        |                                                              |
| `grpc.health.v1.Health` | `Check`                                                       | standard health service; needs the token                     |

## Authentication

Send the token as gRPC metadata on every call, `GetVersion` and health checks included. Key: `x-token`. Value: the token's value, not its name. A call without one is refused with `UNAUTHENTICATED` and `x-token required`; a token that is not entitled to at least one feed is refused with `x-token not entitled to preconfs`. Other refusals are listed in [When a token is refused](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc#when-a-token-is-refused).

## Request

`SubscribeRequest` has two fields:

* `transactions`: a map from filter name to `TransactionFilter`: `account_include`, `account_required`, `account_exclude`, `signer_include`, `signer_exclude`, `signature` and `execution_results`, accounts and signatures as base58 strings, and `instructions`, each an `InstructionFilter` with `program_id` (base58), `memcmp` (`offset` and `bytes`) and an optional `data_size`. The Rust client's `.signatures()` in [Filters](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/filters) sets the `signature` field in the proto.
* `region`: exactly one of `harmonic_region` or `bam_region`, matching the service called. Unspecified or the other feed's region is `INVALID_ARGUMENT`; a region the server does not serve is `FAILED_PRECONDITION`.

The [limits](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/coverage-billing-and-limits#limits) apply. A request over a filter limit (filters, accounts, signatures, name length, instruction conditions) is `INVALID_ARGUMENT`. [Filters](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/filters) describes how each condition matches and which filters are refused; status codes are in [Errors and reconnection](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/errors-and-reconnection). In the JSON form grpcurl uses, `bytes` is base64. From the directory holding `preconfs.proto`, every Meteora DBC `create_config` on BAM Frankfurt:

```bash
grpcurl -import-path . -proto preconfs.proto -H "x-token: $TOKEN" \
  -d '{"bam_region":"BAM_REGION_FRA","transactions":{"configs":{"instructions":[{"program_id":"dbcij3LWUppWqq96dh6gJWwBifmcGfLSB5D4DuSMaqN","memcmp":[{"offset":0,"bytes":"yc/zcktvL70="}]}]}}}' \
  preconfs.rpcpool.com:443 preconfs.BAM/Subscribe
```

## Updates

`HarmonicUpdate` and `BamUpdate` carry `filters` (the names that matched, empty for slot boundaries, pings and clips) and one payload: `transaction`, `ping`, `clip`, and on Harmonic `slot_start` and `slot_end`. The contract in [Stream and message format](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/stream-and-message-format) holds as described; pings arrive every 10 seconds and can be ignored.

{% hint style="warning" %}
`result` on `HarmonicTransaction` and `BamTransaction` is an `optional` field. Check that it is set before reading it, and treat a value your generated code does not know as unknown: the enum's zero value is `EXECUTION_RESULT_SUCCESS`, so an unset field read as its default reports a success that never happened.
{% endhint %}

Transactions carry the raw bytes in `transaction`, in the wire format of their message version. Legacy and v0 transactions start with a compact-u16 signature count and the signatures, so their first signature is the 64 bytes after the count. v1 transactions (SIMD-0385) carry the message first and the signatures after it. Decode them with a Solana SDK that knows all three rather than reading fixed offsets.

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Preconfirmations FAQ

Preconfirmations gRPC FAQ for Harmonic and BAM: missing transactions, coverage limit, filters, regions, Clip, seq, bundles, execution\_results and slot counts.

For how to get access and what each token error means, see [Access](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc#access).

## Missing transactions

<details>

<summary>I filter on my accounts and see far fewer transactions than Geyser shows for the same accounts. Why?</summary>

There are two causes, in this order.

First, filters only match static account keys, so accounts a v0 transaction reaches through an address lookup table aren't matched. See [Address lookup tables](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/filters#address-lookup-tables).

Second, only slots led by validators on the Harmonic or BAM client exist on the feeds. Other leaders' slots have no preconfirmation anywhere. See [What the feeds cover](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc#what-the-feeds-cover-and-what-they-do-not).

</details>

<details>

<summary>A validator runs the Harmonic or BAM client but its slots never show up. Why?</summary>

Running the client is not enough. Harmonic preconfirms only the slots its builder builds, and BAM only the slots its node schedules.

</details>

<details>

<summary>A region sends no <code>SlotStart</code> for minutes. Is that a fault?</summary>

Not necessarily. A region carries only the slots of the leaders it serves, so it is quiet between their windows. Check the leader schedule before assuming a fault.

</details>

## Coverage and tokens

<details>

<summary>Can I get the whole feed?</summary>

No. Every filter must select something, by accounts, signers, instructions or signatures, and the coverage share caps what one subscription receives: 33% of a region's feed. This is the condition under which the feeds are offered. See [Coverage](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/coverage-billing-and-limits#coverage).

</details>

<details>

<summary>Why was my stream closed with "account exceeded its coverage limit for this region, cooling off"?</summary>

Your filters, usually a whole program, stayed over the 33% share of that region's feed for 30 seconds without recovering. Narrow them with `account_required`, `signer_include`, an instruction filter or `account_exclude`. Then resubscribe after the 60-second cooloff; with reconnect on, the client does this itself. Only that region is affected.

If your use needs a larger share, ask through support. See [Coverage](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/coverage-billing-and-limits#coverage).

</details>

<details>

<summary>Does the coverage share apply per region?</summary>

Yes. Each region you subscribe to has its own share, measured against what the feed publishes there, and all your streams on that region share it. Subscribing to four nearby regions gives you four shares, not one split four ways.

</details>

<details>

<summary>Can several servers use one token?</summary>

Yes. On one point of presence, all tokens, connections and streams of a subscription on one region of a feed draw on that region's coverage share.

</details>

## Regions

<details>

<summary>Should I subscribe to all regions?</summary>

No. Subscribe to the regions next to your servers, one stream each. Each region you subscribe to adds the transactions it delivers to your message count. A preconfirmation from a far region reaches you after people located there have acted on it, so it arrives late. To use other regions, place servers there. See [Choosing regions](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/feeds-and-regions#choosing-regions).

</details>

<details>

<summary>Where exactly are the builders and nodes?</summary>

In the cities listed under [Feeds and regions](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/feeds-and-regions). The data center is the feed operator's. The region you subscribe to decides which slots you get, not where you connect.

</details>

<details>

<summary>Which point of presence am I on?</summary>

`GetVersion` (`Client::version()` in the Rust client) tells you, and it needs your token. Anycast picks the closest; `.dial()` on the connector pins one. See [Which point of presence answered](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/feeds-and-regions#which-point-of-presence-answered).

</details>

## Filters

<details>

<summary>How do I use the signature filter if signatures are only known once I send?</summary>

It's for following transactions you already know: the ones you just sent, or a list you track. A stream's filters are fixed for its lifetime, so to follow new signatures, open a stream with the new list and close the old one. Several streams can share one connection.

To see everything a wallet sends without knowing the signatures in advance, filter on the wallet with `signer_include`.

</details>

<details>

<summary>Can I change the filters of an open stream?</summary>

No. Unlike Yellowstone gRPC, you can't send a new request on an open stream: the request that opens the stream sets the filters. Open a stream with the new filters, then close the old one.

The swap doesn't count a slot again on the same point of presence. Transactions delivered on both streams while they overlap are counted twice as messages.

</details>

<details>

<summary>Is there an <code>account_exclude</code> like other providers have?</summary>

Yes, as a further condition on a filter that already selects something: include A, minus B. It doesn't allow subscribing to the whole feed except some accounts. See [Excluding accounts](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/filters#excluding-accounts).

</details>

<details>

<summary>Can I filter on an instruction instead of accounts?</summary>

Yes, on top-level instructions. You can match the program, bytes at offsets in the data, and the data's exact size, which is enough to pick out one instruction by its discriminator. Instructions invoked through CPI only exist after execution, so they aren't seen. See [Instructions](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/filters#instructions).

</details>

<details>

<summary>Does a filter on a program match a transaction that calls the program through CPI, for example from a router?</summary>

An `account_include` filter on the program matches when the program's address is a static account key of the transaction. A program called through CPI is always among the transaction's accounts, so the transaction matches, unless it is a v0 transaction that loads the program's address through an address lookup table. See [Address lookup tables](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/filters#address-lookup-tables).

An instruction filter never matches a CPI call: it sees top-level instructions only. See [Instructions](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/filters#instructions).

</details>

<details>

<summary>Can I get only the transactions my wallet signed, not every one that mentions it?</summary>

Yes, with `signer_include`. See [Signers](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/filters#signers).

</details>

## Stream and message format

<details>

<summary>What does a <code>Clip</code> tell me?</summary>

Only how many matching transactions were withheld on that stream since the previous notice. It names no filter, signature, account or slot.

On Harmonic every pending `Clip` is sent before the `SlotEnd` of the slot it hit. A slot with no `Clip` between its `SlotStart` and `SlotEnd` is complete for your filters; a slot with one or more is short by the sum of their counts. Withheld transactions aren't replayed; recover them from the landed block. See [Slot framing](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/stream-and-message-format#slot-framing) and [Coverage](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/coverage-billing-and-limits#coverage).

</details>

<details>

<summary>Is there a signal before <code>SlotEnd</code> that a slot is complete so far?</summary>

No. A Harmonic slot is complete at its `SlotEnd`. BAM has no slot framing and no completion signal. See [Slot framing](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/stream-and-message-format#slot-framing).

</details>

<details>

<summary>What is the Harmonic <code>seq</code>?</summary>

A delivery batch: a throughput coalescing window on the way to the validator, numbered from 0 within each slot and delivered in order. It is not a bundle or an entry. See [Transaction fields](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/stream-and-message-format#transaction-fields).

</details>

<details>

<summary>Why does the BAM <code>sequence</code> have gaps?</summary>

It follows the scheduler order of the BAM node over the life of the node process, and your filters drop every transaction they don't match. Transactions that share a `sequence` were bundled together.

</details>

<details>

<summary>Can I see bundle boundaries or which strategy the Harmonic builder uses?</summary>

On BAM, for the transactions you receive: transactions that share a `sequence` were bundled together, `bundle_position` is the order inside the bundle, and `is_revert_on_error` says whether the bundle reverts on error. You receive only the transactions your filters match, and a `Clip` can withhold some of those, so a bundle can arrive in part. On Harmonic, no: the stream carries no bundle boundaries. See [Transaction fields](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/stream-and-message-format#transaction-fields).

The strategy of each Harmonic leader is on chain: at the start of its window the leader runs a crank (the Jito tip payment program instructions `ChangeTipReceiver` and `ChangeBlockBuilder`) with a memo naming the strategy.

</details>

<details>

<summary>Does BAM tell me whether a transaction succeeded?</summary>

Yes. Each BAM transaction carries the outcome the leader reported: success or execution failure. A transaction that failed to load also shows as an execution failure. A node that doesn't report the outcome leaves it unset, and such transactions never match an `execution_results` filter.

In Rust, read it with `execution_result()`, not `result()`. See [Transaction fields](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/stream-and-message-format#transaction-fields).

</details>

<details>

<summary>Does the stream tell me when a preconfirmed transaction did not land?</summary>

No. On the wire, a Harmonic stream carries transactions, `SlotStart`, `SlotEnd`, `Clip` and pings. A BAM stream carries transactions, `Clip` and pings. None of them reports a skipped slot, an abandoned fork or a transaction that did not land.

The one revision is a Harmonic slot restart: a second `SlotStart` for a slot that already ended, after which you rebuild that slot from the new frame. See [Slot framing](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/stream-and-message-format#slot-framing).

To check that a preconfirmed transaction landed, look up its signature at `confirmed` or `finalized`.

</details>

<details>

<summary>Can I backrun a preconfirmed transaction through the stream?</summary>

The stream is read-only; it has no call for sending transactions. A preconfirmed transaction already has its place in the block, so anything you send can only land after it, in the same slot or a later one. The slot can still be skipped, so make a backrun safe without the transaction it follows.

</details>

## Billing and access

<details>

<summary>Are slots with no matching transactions counted?</summary>

On Harmonic, yes: every slot whose `SlotEnd` reaches your stream is counted, matched or empty. On BAM, no: BAM has no slot framing, so a slot is counted only when at least one of its transactions is delivered to you. Pay-as-you-go prices are on the [pricing page](https://triton.one/pricing).

On one point of presence, a slot is counted once per subscription, however many of your streams were open for it. Pings and slot markers aren't counted as messages. See [Billing](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/coverage-billing-and-limits#billing).

</details>

<details>

<summary>Are transactions removed by the <code>execution_results</code> filter counted?</summary>

No, on either feed. Transactions it filters out are never delivered and never counted as messages. On Harmonic, every slot whose `SlotEnd` reaches your stream is still counted.

</details>

<details>

<summary>Is anything counted while a feed is down?</summary>

No. Your stream stays open and receives nothing, and nothing is counted.

</details>

<details>

<summary>Does a BAM subscription elsewhere give me BAM preconfirmations through Triton?</summary>

No. Access is per Triton subscription: the feed is enabled on your subscription and used with your Triton token. See [Access](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc#access).

</details>

## Latency and clients

<details>

<summary>How much earlier than shreds or Geyser is a preconfirmation?</summary>

It depends on your host and the region. Measure it on your own servers, against the same clock.

</details>

<details>

<summary>Is there a TypeScript or Python client?</summary>

No TypeScript or Python client is published. Generate one from `preconfs.proto`, which ships with the Rust proto crate. See [Other languages](https://docs.triton.one/solana/real-time-streaming/preconfirmations-grpc/other-languages).

</details>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# WebSocket

Subscribe to accounts, programs, logs, signatures, slots, blocks, and transactions over wss\:// with the Solana WebSocket API, backed by Dragon's Mouth gRPC.

Connect at `wss://<your-endpoint>.mainnet.rpcpool.com/<your-token>`.

{% hint style="info" %}
The WebSocket service runs on Whirligig, Triton's WebSocket server for Dragon's Mouth gRPC. Usage pages and invoices list WebSocket traffic as Whirligig. The older `/whirligig` path reaches the same service.
{% endhint %}

## Use cases

* **Real-time browser apps and browser extensions.** Browsers don't support gRPC. Subscribe over `wss://` with the standard Solana WebSocket API.
* **Backends.** If you can run a gRPC client, use [Dragon's Mouth](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc). If your backend already uses a Solana WebSocket client, use the WebSocket API.

## Features

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-bolt">:bolt:</i> <strong>transactionSubscribe</strong></td><td>A full-transaction subscription, a Triton extension, with account include, exclude, and required filters.</td><td></td></tr><tr><td><i class="fa-gauge-high">:gauge-high:</i> <strong>Intra-slot updates</strong></td><td>At <code>processed</code> commitment, <code>accountSubscribe</code> and <code>programSubscribe</code> notify on every account write as the stream delivers it, within the slot.</td><td></td></tr><tr><td><i class="fa-code">:code:</i> <strong>jsonParsed encoding</strong></td><td><code>accountSubscribe</code> and <code>programSubscribe</code> return structured objects for parsable programs instead of raw byte arrays, with resolved mint metadata on token accounts.</td><td></td></tr><tr><td><i class="fa-cube">:cube:</i> <strong>blockSubscribe</strong></td><td>New blocks over <code>wss://</code>. Needs <code>confirmed</code> or <code>finalized</code> commitment.</td><td></td></tr></tbody></table>

## How it works

The WebSocket server reads a Dragon's Mouth gRPC stream, matches the updates to each client's subscriptions, and sends them as standard Solana WebSocket notifications.

```mermaid
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#F2EDF6','primaryBorderColor':'#7A4BA0','primaryTextColor':'#171717','lineColor':'#956FB3','secondaryColor':'#E4DBEC','tertiaryColor':'#D7C9E3','edgeLabelBackground':'#F2EDF6'},'flowchart':{'nodeSpacing':20,'rankSpacing':35,'curve':'linear'}}}%%
flowchart LR
    dm["Dragon's Mouth<br/>gRPC stream"] --> w["WebSocket server<br/>gRPC to WebSocket"] --> you["Your client<br/>(standard Solana WS API)"]
    style you fill:#D6EAF8,stroke:#259DD0
```

## Supported methods

The methods follow the [Solana WebSocket API](https://solana.com/docs/rpc/websocket). Parameters and results are in [WebSocket methods](https://docs.triton.one/solana/rpc-methods/real-time-streaming/whirligig-websocket), except for `rootSubscribe`, `voteSubscribe`, and `slotsUpdatesSubscribe`, which have no reference page.

| Method                  | Returns                                                                            |
| ----------------------- | ---------------------------------------------------------------------------------- |
| `accountSubscribe`      | An account's data, on change                                                       |
| `blockSubscribe`        | New blocks                                                                         |
| `logsSubscribe`         | Transaction logs mentioning an address                                             |
| `programSubscribe`      | Accounts owned by a program, on change                                             |
| `signatureSubscribe`    | A signature's confirmation status                                                  |
| `slotSubscribe`         | Each new slot                                                                      |
| `rootSubscribe`         | Each new root (the highest finalized slot)                                         |
| `voteSubscribe`         | Votes from committed vote transactions (none on Alpenglow; unstable Solana method) |
| `slotsUpdatesSubscribe` | Detailed slot-status updates (unstable Solana method)                              |
| `transactionSubscribe`  | Full transactions matching a filter. Triton extension to the Solana WebSocket API  |

Each subscribe method returns a subscription `id` and has a matching unsubscribe (see [Unsubscribe](#unsubscribe)).

## Connection options

{% tabs %}
{% tab title="JavaScript (web3.js)" %}
Set `wsEndpoint` to your `wss://` endpoint URL. Standard Solana WebSocket clients usually need no other change.

```javascript
import { Connection, PublicKey } from "@solana/web3.js";

const connection = new Connection(
  "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>",
  {
    wsEndpoint: "wss://<your-endpoint>.mainnet.rpcpool.com/<your-token>",
    commitment: "processed",
  }
);

const subscriptionId = connection.onAccountChange(
  new PublicKey("<account-pubkey>"),
  (accountInfo, context) => {
    console.log("slot:", context.slot, "lamports:", accountInfo.lamports);
  },
  "processed"
);

// When done:
// await connection.removeAccountChangeListener(subscriptionId);
```

{% endtab %}

{% tab title="Rust" %}
Uses the standard [`solana-pubsub-client`](https://docs.rs/solana-pubsub-client) crate.

{% code title="Cargo.toml" %}

```toml
[dependencies]
solana-pubsub-client = "~4.4"
solana-rpc-client-types = "~4.4"
solana-account-decoder-client-types = "~4.4"
solana-pubkey = "4"
solana-commitment-config = "3"
tokio = { version = "1", features = ["full"] }
futures = "0.3"
serde_json = "1"
rustls = { version = "0.23", default-features = false, features = ["ring"] } # TLS crypto provider for wss://
```

{% endcode %}

{% code title="src/main.rs" %}

```rust
use futures::StreamExt;
use solana_account_decoder_client_types::UiAccountEncoding;
use solana_commitment_config::CommitmentConfig;
use solana_pubkey::Pubkey;
use solana_pubsub_client::nonblocking::pubsub_client::PubsubClient;
use solana_rpc_client_types::config::RpcAccountInfoConfig;
use std::str::FromStr;

#[tokio::main]
async fn main() {
    let client = PubsubClient::new("wss://<your-endpoint>.mainnet.rpcpool.com/<your-token>")
        .await
        .expect("connect");

    let pubkey = Pubkey::from_str("<account-pubkey>").expect("valid pubkey");
    let config = RpcAccountInfoConfig {
        encoding: Some(UiAccountEncoding::JsonParsed),
        commitment: Some(CommitmentConfig::processed()),
        data_slice: None,
        min_context_slot: None,
    };

    let (mut stream, unsubscribe) = client
        .account_subscribe(&pubkey, Some(config))
        .await
        .expect("subscribe");

    while let Some(update) = stream.next().await {
        println!("{}", serde_json::to_string(&update).unwrap());
    }

    drop(stream);
    drop(unsubscribe);
    client.shutdown().await.expect("shutdown");
}
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript (raw WebSocket)" %}
Required for `transactionSubscribe`, which returns full transaction data in a single call and is not available in `@solana/web3.js`.

```javascript
const ws = new WebSocket("wss://<your-endpoint>.mainnet.rpcpool.com/<your-token>");

ws.addEventListener("open", () => {
  // Keep alive: idle connections are closed after 60 s
  setInterval(() => ws.send(JSON.stringify({ jsonrpc: "2.0", method: "ping" })), 30_000);

  ws.send(JSON.stringify({
    jsonrpc: "2.0", id: 1,
    method: "transactionSubscribe",
    params: [
      { vote: false, failed: false },
      {
        commitment: "processed",
        encoding: "jsonParsed",
        transactionDetails: "full",
        maxSupportedTransactionVersion: 1,
      },
    ],
  }));
});

ws.addEventListener("message", ({ data }) => {
  const msg = JSON.parse(data);
  if (msg.method === "transactionNotification") {
    console.log("tx:", msg.params.result.value.transaction.transaction.signatures[0]);
  }
});
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Connections idle for over 60 seconds are closed, so keep them alive by sending `{"jsonrpc":"2.0","method":"ping"}`.
{% endhint %}

Run your client close to a Triton region to lower latency.

### Commitment levels

Set the commitment level per subscription in the `config` argument. `blockSubscribe` accepts `confirmed` or `finalized`, not `processed`.

| Level       | Meaning                                                                                                                                                                        | Update sent                            |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- |
| `processed` | The node has processed the transaction or account write; its slot can still be in progress. Not yet `confirmed` or `finalized`; the block can still be skipped by the cluster. | Without waiting for its slot to finish |
| `confirmed` | The highest slot voted on by a supermajority of the cluster. On Alpenglow, `confirmed` and `finalized` updates arrive together.                                                | After its slot reaches `confirmed`     |
| `finalized` | The highest slot that is final. On Alpenglow, a block becomes final about 150 ms after the leader proposes it.                                                                 | After its slot reaches `finalized`     |

The WebSocket server subscribes to Dragon's Mouth at `processed`.

{% hint style="info" %}
For the lowest latency, subscribe at `processed` and track `confirmed` and `finalized` yourself. `slotsUpdatesSubscribe` sends `optimisticConfirmation` when a slot is confirmed and `root` when it is finalized.
{% endhint %}

## Subscribe request

### accountSubscribe

{% tabs %}
{% tab title="Request" %}

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "accountSubscribe",
  "params": [
    "SysvarC1ock11111111111111111111111111111111",
    {
      "encoding": "base58",
      "commitment": "processed"
    }
  ]
}

```

{% endtab %}

{% tab title="Response" %}

```json
{
  "jsonrpc": "2.0",
  "method": "accountNotification",
  "params": {
    "result": {
      "context": {
        "slot": 206122916
      },
      "value": {
        "data": [
          "9AAG2zomYcUVKQfondw13yz193crQ5R5zmzdEojhMPXiyYEjD8viLrb",
          "base58"
        ],
        "executable": false,
        "lamports": 1169280,
        "owner": "Sysvar1111111111111111111111111111111111111",
        "rentEpoch": 361,
        "space": 40
      }
    },
    "subscription": 0
  }
}
```

{% endtab %}
{% endtabs %}

### blockSubscribe

{% tabs %}
{% tab title="Request" %}

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "blockSubscribe",
  "params": [
    "all",
    {
      "commitment": "finalized",
      "maxSupportedTransactionVersion": 1,
      "showRewards": false,
      "transactionDetails": "none"
    }
  ]
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "jsonrpc": "2.0",
  "method": "blockNotification",
  "params": {
    "result": {
      "context": {
        "slot": 206125999
      },
      "value": {
        "block": {
          "blockHeight": 188652385,
          "blockTime": 1689709529,
          "blockhash": "74iqy9xdFvenLkFizkoBkkLRWTyygEeCiiN3B8Z8ma2D",
          "parentSlot": 206125998,
          "previousBlockhash": "Cq5nfgu9Y5KF47J9qj5CTYmt8D5CxBpw8HCRqQZ7o7i9"
        },
        "err": null,
        "slot": 206125999
      }
    },
    "subscription": 0
  }
}
```

{% endtab %}
{% endtabs %}

### logsSubscribe

{% tabs %}
{% tab title="Request" %}

```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "logsSubscribe",
  "params": [
    {
      "mentions": ["8BnEgHoWFysVcuFFX7QztDmzuH8r5ZFvyP3sYwn1XTh6"]
    },
    {
      "commitment": "processed"
    }
  ]
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "jsonrpc": "2.0",
  "method": "logsNotification",
  "params": {
    "result": {
      "context": {
        "slot": 206126709
      },
      "value": {
        "err": null,
        "logs": [
          "Program FC81tbGt6JWRXidaWYFXxGnTk4VgobhJHATvTRVMqgWj invoke [1]",
          "Program log: process_instruction: FC81tbGt6JWRXidaWYFXxGnTk4VgobhJHATvTRVMqgWj: 3 accounts, data=[12]",
          "Program log: Instruction: UpdateLendingPool",
          "Program log: current_borrow_rate: 73081853393945351",
          "Program FC81tbGt6JWRXidaWYFXxGnTk4VgobhJHATvTRVMqgWj consumed 23800 of 1000000 compute units",
          "Program FC81tbGt6JWRXidaWYFXxGnTk4VgobhJHATvTRVMqgWj success",
          "Program FC81tbGt6JWRXidaWYFXxGnTk4VgobhJHATvTRVMqgWj invoke [1]",
          "Program log: process_instruction: FC81tbGt6JWRXidaWYFXxGnTk4VgobhJHATvTRVMqgWj: 3 accounts, data=[12]",
          "Program log: Instruction: UpdateLendingPool",
          "Program log: current_borrow_rate: 82164236984041212",
          "Program FC81tbGt6JWRXidaWYFXxGnTk4VgobhJHATvTRVMqgWj consumed 28159 of 976200 compute units",
          "Program FC81tbGt6JWRXidaWYFXxGnTk4VgobhJHATvTRVMqgWj success",
          "Program 2nAAsYdXF3eTQzaeUQS3fr4o782dDg8L28mX39Wr5j8N invoke [1]",
          "Program log: Instruction: LiquidateUnstakeLp",
          "Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA invoke [2]",
          "Program log: Instruction: Transfer",
          "Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA consumed 4740 of 879873 compute units",
          "Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA success",
          "Program 2nAAsYdXF3eTQzaeUQS3fr4o782dDg8L28mX39Wr5j8N consumed 79765 of 948041 compute units",
          "Program 2nAAsYdXF3eTQzaeUQS3fr4o782dDg8L28mX39Wr5j8N success",
          "Program 2nAAsYdXF3eTQzaeUQS3fr4o782dDg8L28mX39Wr5j8N invoke [1]",
          "Program log: Instruction: RemoveLiquidity",
          "Program 2nAAsYdXF3eTQzaeUQS3fr4o782dDg8L28mX39Wr5j8N consumed 24767 of 868276 compute units",
          "Program 2nAAsYdXF3eTQzaeUQS3fr4o782dDg8L28mX39Wr5j8N success",
          "Program 2nAAsYdXF3eTQzaeUQS3fr4o782dDg8L28mX39Wr5j8N invoke [1]",
          "Program log: Instruction: SwapAndWithdraw",
          "Program log: withdraw_type: 2,\\n            user_info.pending_repay_0: 0,\\n            user_info.pending_repay_1: 0,\\n            user_info.tkn_0: 0,\\n            user_info.tkn_1: 0,\\n            ",
          "Program log: swap_direction: 0,\\n            amount_in: 0\\n            ",
          "Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA invoke [2]",
          "Program log: Instruction: Transfer",
          "Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA consumed 4785 of 815778 compute units",
          "Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA success",
          "Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA invoke [2]",
          "Program log: Instruction: Transfer",
          "Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA consumed 4831 of 807689 compute units",
          "Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA success",
          "Program 2nAAsYdXF3eTQzaeUQS3fr4o782dDg8L28mX39Wr5j8N consumed 47497 of 843509 compute units",
          "Program 2nAAsYdXF3eTQzaeUQS3fr4o782dDg8L28mX39Wr5j8N success"
        ],
        "signature": "5UPB2AEWgUafVDEw2xTkup8CUedxCMNL4k7EMuxtcyi1WnYLmpXeYUfBANpnPnpSz6LRwwLnBQf7tViKSFT7ojiB"
      }
    },
    "subscription": 0
  }
}
```

{% endtab %}
{% endtabs %}

### programSubscribe

{% tabs %}
{% tab title="Request" %}

```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "programSubscribe",
  "params": [
    "srmqPvymJeFKQ4zGQed1GFppgkRHL9kaELCbyksJtPX",
    {
      "encoding": "base64+zstd",
      "commitment": "processed"
    }
  ]
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "jsonrpc": "2.0",
  "method": "programNotification",
  "params": {
    "result": {
      "context": {
        "slot": 206127070
      },
      "value": {
        "account": {
          "data": [
            "KLUv/QBYDQEAkHNlcnVtQQABAAQAcGFkZGluZwUA03+gI0CxQgAYeABG",
            "base64+zstd"
          ],
          "executable": false,
          "lamports": 457104960,
          "owner": "srmqPvymJeFKQ4zGQed1GFppgkRHL9kaELCbyksJtPX",
          "rentEpoch": 0,
          "space": 65548
        },
        "pubkey": "5qRKrGPYaQmazdtMnia1iC3gFbpgW4CT7KPrHq9nJGm5"
      }
    },
    "subscription": 0
  }
}
```

{% endtab %}
{% endtabs %}

### signatureSubscribe

{% tabs %}
{% tab title="Request" %}

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "signatureSubscribe",
  "params": [
    "2EBVM6cB8vAAD93Ktr6Vd8p67XPbQzCJX47MpReuiCXJAtcjaxpvWpcg9Ege1Nr5Tk3a2GFrByT7WPBjdsTycY9b",
    {
      "commitment": "processed"
    }
  ]
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "jsonrpc": "2.0",
  "method": "signatureNotification",
  "params": {
    "result": {
      "context": {
        "slot": 206127070
      },
      "value": {
        "err": null
      }
    },
    "subscription": 24006
  }
}
```

{% endtab %}
{% endtabs %}

### slotSubscribe

{% tabs %}
{% tab title="Request" %}

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "slotSubscribe"
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "jsonrpc": "2.0",
  "method": "slotNotification",
  "params": {
    "result": {
      "parent": 206128153,
      "root": 206128115,
      "slot": 206128154
    },
    "subscription": 0
  }
}
```

{% endtab %}
{% endtabs %}

### transactionSubscribe

A Triton extension to the Solana WebSocket API. One subscription returns the full transaction, including metadata, log messages, token balances, and compute units, replacing a `signatureSubscribe` + `getTransaction` loop. Takes a `filter` object (all fields optional) and an optional `config` with the same fields as [`RpcBlockSubscribeConfig`](https://docs.rs/solana-client/latest/solana_client/rpc_config/struct.RpcBlockSubscribeConfig.html), except `transactionDetails: "none"`, which is refused.

{% tabs %}
{% tab title="Request" %}

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "transactionSubscribe",
  "params": [
    {
      "vote": false,
      "failed": false,
      "signature": "2EBVM6cB8vAAD93Ktr6Vd8p67XPbQzCJX47MpReuiCXJAtcjaxpvWpcg9Ege1Nr5Tk3a2GFrByT7WPBjdsTycY9b",
      "accounts": {
        "include": ["5qRKrGPYaQmazdtMnia1iC3gFbpgW4CT7KPrHq9nJGm5"],
        "exclude": ["srmqPvymJeFKQ4zGQed1GFppgkRHL9kaELCbyksJtPX"],
        "required": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"]
      }
    },
    {
      "commitment": "processed",
      "encoding": "base64",
      "transactionDetails": "full",
      "showRewards": false,
      "maxSupportedTransactionVersion": 1
    }
  ]
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "jsonrpc": "2.0",
  "method": "transactionNotification",
  "params": {
    "result": {
      "context": {
        "slot": 241068727
      },
      "value": {
        "slot": 241068727,
        "transaction": {
          "meta": {
            "computeUnitsConsumed": 27426,
            "err": null,
            "fee": 5000,
            "innerInstructions": [
              {
                "index": 3,
                "instructions": [
                  {
                    "accounts": [
                      7,
                      3,
                      11
                    ],
                    "data": "3DTZbgwsozUF",
                    "programIdIndex": 15,
                    "stackHeight": null
                  },
                  {
                    "accounts": [
                      9,
                      8,
                      11
                    ],
                    "data": "3DTZbgwsozUF",
                    "programIdIndex": 15,
                    "stackHeight": null
                  }
                ]
              }
            ],
            "loadedAddresses": {
              "readonly": [],
              "writable": []
            },
            "logMessages": [
              "Program ComputeBudget111111111111111111111111111111 invoke [1]",
              "Program ComputeBudget111111111111111111111111111111 success",
              "Program GDDMwNyyx8uB6zrqwBFHjLLG3TBYk2F8Az4yrQC5RzMp invoke [1]",
              "Program log: Sequence in order | sequence_num=755609 | last_known=755608",
              "Program GDDMwNyyx8uB6zrqwBFHjLLG3TBYk2F8Az4yrQC5RzMp consumed 3398 of 300000 compute units",
              "Program GDDMwNyyx8uB6zrqwBFHjLLG3TBYk2F8Az4yrQC5RzMp success",
              "Program srmqPvymJeFKQ4zGQed1GFppgkRHL9kaELCbyksJtPX invoke [1]",
              "Program srmqPvymJeFKQ4zGQed1GFppgkRHL9kaELCbyksJtPX consumed 3820 of 296602 compute units",
              "Program srmqPvymJeFKQ4zGQed1GFppgkRHL9kaELCbyksJtPX success",
              "Program srmqPvymJeFKQ4zGQed1GFppgkRHL9kaELCbyksJtPX invoke [1]",
              "Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA invoke [2]",
              "Program log: Instruction: Transfer",
              "Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA consumed 4740 of 285091 compute units",
              "Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA success",
              "Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA invoke [2]",
              "Program log: Instruction: Transfer",
              "Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA consumed 4740 of 277786 compute units",
              "Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA success",
              "Program srmqPvymJeFKQ4zGQed1GFppgkRHL9kaELCbyksJtPX consumed 20208 of 292782 compute units",
              "Program srmqPvymJeFKQ4zGQed1GFppgkRHL9kaELCbyksJtPX success"
            ],
            "postBalances": [
              10194778999,
              1224960,
              457104960,
              2039280,
              23357760,
              1825496640,
              3591360,
              2039280,
              2039280,
              2039280,
              457104960,
              0,
              1,
              1141440,
              1141440,
              934087680
            ],
            "postTokenBalances": [
              {
                "accountIndex": 3,
                "mint": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
                "owner": "ASx1wk74GLZsxVrYiBkNKiViPLjnJQVGxKrudRgPir4A",
                "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
                "uiTokenAmount": {
                  "amount": "4973704995974757",
                  "decimals": 5,
                  "uiAmount": 49737049959.74757,
                  "uiAmountString": "49737049959.74757"
                }
              },
              {
                "accountIndex": 7,
                "mint": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
                "owner": "3oQLKk1TyyXMT14p2i8p95v5jKqsQ5qzZGwxZCTnFC7p",
                "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
                "uiTokenAmount": {
                  "amount": "3167826900000000",
                  "decimals": 5,
                  "uiAmount": 31678269000,
                  "uiAmountString": "31678269000"
                }
              },
              {
                "accountIndex": 8,
                "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
                "owner": "ASx1wk74GLZsxVrYiBkNKiViPLjnJQVGxKrudRgPir4A",
                "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
                "uiTokenAmount": {
                  "amount": "148629334218",
                  "decimals": 6,
                  "uiAmount": 148629.334218,
                  "uiAmountString": "148629.334218"
                }
              },
              {
                "accountIndex": 9,
                "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
                "owner": "3oQLKk1TyyXMT14p2i8p95v5jKqsQ5qzZGwxZCTnFC7p",
                "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
                "uiTokenAmount": {
                  "amount": "5797710875",
                  "decimals": 6,
                  "uiAmount": 5797.710875,
                  "uiAmountString": "5797.710875"
                }
              }
            ],
            "preBalances": [
              10194783999,
              1224960,
              457104960,
              2039280,
              23357760,
              1825496640,
              3591360,
              2039280,
              2039280,
              2039280,
              457104960,
              0,
              1,
              1141440,
              1141440,
              934087680
            ],
            "preTokenBalances": [
              {
                "accountIndex": 3,
                "mint": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
                "owner": "ASx1wk74GLZsxVrYiBkNKiViPLjnJQVGxKrudRgPir4A",
                "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
                "uiTokenAmount": {
                  "amount": "4973704995974757",
                  "decimals": 5,
                  "uiAmount": 49737049959.74757,
                  "uiAmountString": "49737049959.74757"
                }
              },
              {
                "accountIndex": 7,
                "mint": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
                "owner": "3oQLKk1TyyXMT14p2i8p95v5jKqsQ5qzZGwxZCTnFC7p",
                "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
                "uiTokenAmount": {
                  "amount": "3167826900000000",
                  "decimals": 5,
                  "uiAmount": 31678269000,
                  "uiAmountString": "31678269000"
                }
              },
              {
                "accountIndex": 8,
                "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
                "owner": "ASx1wk74GLZsxVrYiBkNKiViPLjnJQVGxKrudRgPir4A",
                "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
                "uiTokenAmount": {
                  "amount": "148629334218",
                  "decimals": 6,
                  "uiAmount": 148629.334218,
                  "uiAmountString": "148629.334218"
                }
              },
              {
                "accountIndex": 9,
                "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
                "owner": "3oQLKk1TyyXMT14p2i8p95v5jKqsQ5qzZGwxZCTnFC7p",
                "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
                "uiTokenAmount": {
                  "amount": "5797710875",
                  "decimals": 6,
                  "uiAmount": 5797.710875,
                  "uiAmountString": "5797.710875"
                }
              }
            ],
            "rewards": null,
            "status": {
              "Ok": null
            }
          },
          "transaction": [
            "AY6n3kLw0z...Q2xB1CA==",
            "base64"
          ],
          "version": "legacy"
        }
      }
    },
    "subscription": 0
  }
}
```

{% endtab %}
{% endtabs %}

## Unsubscribe

Every subscribe request returns the subscription `id` on success:

```json
{ "jsonrpc": "2.0", "result": 42, "id": 1 }
```

Pass that `id` to the matching unsubscribe method (`accountUnsubscribe`, `slotUnsubscribe`, and so on):

```json
{ "id": 1, "jsonrpc": "2.0", "method": "slotUnsubscribe", "params": [42] }
```

The result is `true` if the subscription was active and removed:

```json
{ "jsonrpc": "2.0", "result": true, "id": 1 }
```

An `id` that does not exist on the connection returns error `-32602`, `Invalid subscription id.`

## Client

You can find a reference CLI client on GitHub: [WebSocket CLI client](https://github.com/rpcpool/yellowstone-whirligig-client).

## Pricing

WebSocket traffic is billed by the bandwidth it streams, on shared and dedicated endpoints. By default, a dedicated endpoint's WebSocket connections are served by Triton's shared servers, not by your node. See the [pricing page](https://triton.one/pricing).

WebSocket frames are not compressed (no `permessage-deflate`).

To stream less:

* Filter your subscriptions: `filters` on `programSubscribe`, account filters on `transactionSubscribe`.
* Use the `base64+zstd` encoding when bandwidth is limited, not by default. It compresses the account data field, not the whole message, and costs CPU on the server and on your client.

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-tower-broadcast">:tower-broadcast:</i> <strong>Dragon's Mouth gRPC</strong></td><td>Sub-slot real-time updates for accounts, transactions, slots, and blocks via gRPC.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc">Dragon's Mouth gRPC</a></td></tr><tr><td><i class="fa-list-check">:list-check:</i> <strong>Real-time streaming best practices</strong></td><td>Filtering, reconnect, and commitment guidance across the streaming services.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/best-practices">Real-time streaming best practices</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Fumarole Persistent gRPC

How Fumarole persistent gRPC streams resume from a server-side cursor with 4-day replay, using the Fume CLI or Rust and TypeScript clients.

Fumarole is reliable, persistent gRPC streaming for pipelines that can't miss a block: disconnect and resume from your last committed position, with anything you missed backfilled automatically from a 4-day rolling cache.

## Use cases

Fumarole fits pipelines that value completeness and reliability over raw speed:

* **Indexers** that must process every block.
* **Analytics and accounting** systems that cannot tolerate data gaps.
* **Compliance and monitoring** tools that need a complete record.

Don't use it for latency-first workloads. If you need data as fast as possible for trading, look into [Dragon's Mouth gRPC](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc) instead.

## Features and benefits

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-arrows-rotate">:arrows-rotate:</i> <strong>High availability</strong></td><td>Multi-node aggregation with automatic failover. A Dragon's Mouth node restart or upgrade doesn't interrupt your stream.</td><td></td></tr><tr><td><i class="fa-database">:database:</i> <strong>Persistence</strong></td><td>Server-side cursor with 4 days of rolling retention. Go offline for hours or days and resume from your last committed position.</td><td></td></tr><tr><td><i class="fa-circle-check">:circle-check:</i> <strong>At-least-once delivery</strong></td><td>Whole blocks are served, with full block data arriving before slot status. A reconnect backfills what you missed.</td><td></td></tr><tr><td><i class="fa-equals">:equals:</i> <strong>Consistent data</strong></td><td>Inside a region, clients with the same filters and commitment level get the same data for a slot, and blocks are scheduled for download in the same order. Network differences can complete downloads in a different order, so after a reconnect you may not receive events in the same order.</td><td></td></tr><tr><td><i class="fa-layer-group">:layer-group:</i> <strong>Parallel downloads</strong></td><td>The Rust client downloads block data over several gRPC connections at once (4 by default), so one slow transfer doesn't hold up the rest.</td><td></td></tr><tr><td><i class="fa-code-fork">:code-fork:</i> <strong>Dragon's Mouth compatible</strong></td><td>Fumarole uses the same types as Dragon's Mouth. Fumarole ignores some <code>SubscribeRequest</code> fields, including the <code>blocks</code> filter, <code>accounts_data_slice</code>, <code>from_slot</code>, <code>interslot_updates</code>, and compressed filters.</td><td></td></tr></tbody></table>

## How it works

1. Fumarole aggregates multiple Dragon's Mouth nodes, merging and deduplicating their updates into one stream.
2. It persists your read position as a server-side cursor, with 4 days of rolling retention.
3. You stream from a named persistent subscriber at your own pace. If you disconnect, reconnecting with the same name resumes from your last committed position, anywhere in the 4-day window.

```mermaid
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#F2EDF6','primaryBorderColor':'#7A4BA0','primaryTextColor':'#171717','lineColor':'#956FB3','secondaryColor':'#E4DBEC','tertiaryColor':'#D7C9E3','edgeLabelBackground':'#F2EDF6'},'flowchart':{'nodeSpacing':20,'rankSpacing':35,'curve':'linear'}}}%%
flowchart LR
    n1["Dragon's Mouth"] --> f
    n2["Dragon's Mouth"] --> f
    n3["Dragon's Mouth"] --> f["Fumarole<br/>merge + dedupe + cursor<br/>(4-day retention)"]
    f --> you["Your app"]
    style you fill:#D6EAF8,stroke:#259DD0
```

## Client methods

Don't call Fumarole's gRPC methods directly. Use the Rust client, the TypeScript client, or the Fume CLI, which call them for you. The client APIs call a persistent subscriber a consumer group.

| Task                                                     | Rust client                                                                | TypeScript client                                                   |
| -------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Create a persistent subscriber                           | `create_consumer_group`                                                    | `createConsumerGroup`                                               |
| List, inspect, and delete persistent subscribers         | `list_consumer_groups`, `get_consumer_group_info`, `delete_consumer_group` | `listConsumerGroups`, `getConsumerGroupInfo`, `deleteConsumerGroup` |
| Stream from a persistent subscriber                      | `subscribe`, `subscribe_with_config`                                       | `subscribe`, `subscribeWithConfig`                                  |
| Read the stream's tip, available slot range, and version | `get_chain_tip`, `get_slot_range`, `version`                               | `getChainTip`, `getSlotRange`, `version`                            |

## Get started

Fumarole works with your existing mainnet subscription token, no separate access request needed.

**1. Pick a regional endpoint.** Connect directly to the cluster closest to your backend (see [Regional endpoints](#regional-endpoints)): `ams.rpcpool.com` (EU) or `nyc.rpcpool.com` (US). Persistent subscribers are stateful per cluster, so avoid the shared `*.mainnet.rpcpool.com` endpoints.

**2. Authenticate with your token.** Pass your existing mainnet token as the `x-token`.

**3. Install a client.** Use the Fume CLI to try Fumarole and to create a persistent subscriber; the Rust and TypeScript SDKs are also available.

{% tabs %}
{% tab title="Fume CLI" %}

```bash
cargo install yellowstone-fumarole-cli
```

Save your endpoint and token in `~/.fumarole/config.yaml`:

```yaml
endpoint: https://ams.rpcpool.com
x-token: <your-token>
```

Create the persistent subscriber with the `fume` command. It starts at the latest slot.

```bash
fume create --name my-subscriber
```

{% endtab %}

{% tab title="Rust" %}

```toml
[dependencies]
yellowstone-fumarole-client = "0.9"
yellowstone-grpc-proto = "14"
serde_yaml = "0.9"
tokio = { version = "1", features = ["full"] }
futures = "0.3"
```

{% endtab %}

{% tab title="TypeScript" %}
The TypeScript client requires Node.js 22 or later.

```bash
npm install @triton-one/yellowstone-fumarole-client
```

{% endtab %}
{% endtabs %}

**4. Create a persistent subscriber, then stream from it.** The subscriber tracks your position server-side, so reconnecting with the same name resumes from your last committed position.

{% tabs %}
{% tab title="Rust" %}

```rust
use futures::StreamExt;
use std::collections::HashMap;
use yellowstone_fumarole_client::{FumaroleClient, config::FumaroleConfig, stream::FumaroleEvent};
use yellowstone_grpc_proto::geyser::{
    SubscribeRequest, SubscribeRequestFilterSlots, SubscribeRequestFilterTransactions,
};

#[tokio::main]
async fn main() {
    let config: FumaroleConfig = serde_yaml::from_str(
        "endpoint: https://ams.rpcpool.com\nx-token: <your-token>",
    )
    .expect("valid config");

    let mut client = FumaroleClient::connect(config).await.expect("connect");

    // No commitment is set, so the stream runs at processed.
    // The slot filter delivers the confirmed and finalized statuses as slot updates.
    let request = SubscribeRequest {
        transactions: HashMap::from([(
            "f1".to_owned(),
            SubscribeRequestFilterTransactions::default(),
        )]),
        slots: HashMap::from([("s1".to_owned(), SubscribeRequestFilterSlots::default())]),
        ..Default::default()
    };

    // "my-subscriber" is a persistent subscriber you created (e.g. with the Fume CLI).
    let subscription = client
        .subscribe("my-subscriber".to_string(), request)
        .await
        .expect("subscribe failed");

    let (_sink, stream) = subscription.split();
    let mut slot_stream = stream.slot_sequential();

    while let Some(item) = slot_stream.next().await {
        match item.expect("stream error") {
            FumaroleEvent::Data { slot, update, .. } => println!("slot {slot}: {update:?}"),
            FumaroleEvent::SlotEnded { slot, .. } => println!("slot {slot} complete"),
        }
    }
}
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
import {
  FumaroleClient,
  SubscribeRequest,
  CommitmentLevel,
} from "@triton-one/yellowstone-fumarole-client";

const client = await FumaroleClient.connect({
  endpoint: "https://ams.rpcpool.com",
  xToken: "<your-token>",
});

// Create the persistent subscriber once; reuse the name to resume.
const subscriberName = "my-subscriber";
if ((await client.getConsumerGroupInfo(subscriberName)) === null) {
  await client.createConsumerGroup(subscriberName);
}

// Stream at processed. The slot filter delivers the confirmed and finalized statuses as slot updates.
const request: SubscribeRequest = {
  commitment: CommitmentLevel.PROCESSED,
  accounts: {},
  transactions: { f1: { accountInclude: [], accountExclude: [], accountRequired: [] } },
  slots: { s1: {} },
  transactionsStatus: {},
  blocks: {},
  blocksMeta: {},
  entry: {},
  blockFooter: {},
  accountsDataSlice: [],
};

const subscription = await client.subscribeWithConfig(subscriberName, request, {
  commitIntervalMs: 5_000,
});

for await (const event of subscription) {
  if (event.type === "slotEnded") {
    console.log(`slot ${event.slot} complete`);
  } else {
    console.log(`slot ${event.slot}:`, event.update);
  }
}
```

{% endtab %}
{% endtabs %}

**Commitment level.** Stream at `processed` and track `confirmed` and `finalized` in your own code from the slot updates. If you set a higher `commitment` on the request, the client waits for a block to reach that level before it downloads the block.

**Block footers.** Add a `block_footer` filter to the request to receive Alpenglow block footers. A footer arrives once per block, and only where Alpenglow is active. On the raw stream it comes right before the block's meta update; in slot-sequential mode the meta update is delivered immediately and can arrive before the footer. Set `include_certificates: true` on the filter to also receive the certificates. The footer's `bank_id` is set by Fumarole per block, so it joins the block's other updates; it is not the validator's `bank_id`. In the Fume CLI, `--include footer` prints footers and `--footer-certs` adds the certificates (`yellowstone-fumarole-cli` 0.8.0 or later).

For the full Fume CLI walkthrough, read the [launch post](https://blog.triton.one/introducing-yellowstone-fumarole); for the complete API, see the [Rust and TypeScript SDKs](https://github.com/rpcpool/yellowstone-fumarole).

## Streaming modes

The Rust client streams in three modes:

* **Slot-sequential.** Data updates one slot at a time. Slot status and block meta updates pass through as they arrive, even while another slot is active.
* **Block stream.** Whole blocks as single payloads, for logic that processes entire blocks at once.
* **Raw stream.** Events as the client runtime produces them, with no slot grouping or reordering.

Any mode can be paired with manual cursor commits, and all three use parallel shard downloads. Rust is the primary client; the TypeScript and Python clients don't support all three modes yet.

By default the Rust client commits your cursor automatically. Set `auto_commit: false` to decide exactly when the cursor moves: write to your database first, then commit receipt after the write succeeds.

## Migrating from Dragon's Mouth

If you already have code built for our gRPC streams in Dragon's Mouth, you can move to Fumarole for additional reliability with minimal code changes, because Fumarole uses the same types as Dragon's Mouth.

The main difference is that you need to manage a **persistent subscriber**, and alter your subscribe request slightly.

For the full walkthrough, follow the [Dragon's Mouth to Fumarole migration guide](https://docs.triton.one/solana/quickstart/streaming/migrate-from-dragons-mouth-to-fumarole). For the complete API, see the [yellowstone-fumarole-client docs](https://docs.rs/yellowstone-fumarole-client/latest/yellowstone_fumarole_client/).

## Regional endpoints

Fumarole runs as **independent regional clusters**. We currently operate:

| Region | Endpoint          | Location  |
| ------ | ----------------- | --------- |
| EU     | `ams.rpcpool.com` | Amsterdam |
| US     | `nyc.rpcpool.com` | New York  |

### Choosing an endpoint

For Fumarole, connect directly to a **regional endpoint** rather than shared `*.mainnet.rpcpool.com` endpoints. Pick the region closest to your backend infrastructure to minimize latency.

{% hint style="warning" %}
Shared `*.mainnet.rpcpool.com` endpoints are **not recommended for Fumarole**. See below for why.
{% endhint %}

### Why direct regional endpoints matter

The shared endpoints (`*.mainnet.rpcpool.com`) route traffic to the nearest Triton point of presence over Anycast. For stateless RPC calls this is ideal: any region can serve any request.

### Persistent subscribers are stateful per cluster

A persistent subscriber and the slot offsets it tracks live locally on the cluster where it was created and **do not replicate across regions**.

If you connect through a shared endpoint, your traffic can be routed to a region where your persistent subscriber does not exist, for example after a routing change, a network event, or a change in your backend's network path. When that happens, your subscriber will not be found on the new cluster and you will need to recreate it. Pointing your Fumarole client directly at a regional endpoint avoids this entirely.

### Switching regions

To move a persistent subscriber from one regional cluster to another (e.g., EU to US):

{% stepper %}
{% step %}

### Recreate your persistent subscriber

Create it on the new cluster: subscribers do not carry over between regional clusters.
{% endstep %}

{% step %}

### Point your client to the new regional endpoint

{% endstep %}

{% step %}

### Reconnect

Your existing token continues to work; no token changes are required.
{% endstep %}
{% endstepper %}

### Cross-region redundancy (customer-managed)

With multiple regional clusters available, you can implement cross-region redundancy on the client side. If one cluster experiences a major issue, you can fail over to another region by recreating the persistent subscriber **from the last slot you observed on the failing cluster**. Fumarole tracks the last **full** slot you consumed.

This pattern is fully customer-managed:

* Your client tracks the last-seen slot per cluster.
* Your client detects the failure and triggers the cutover.
* Triton does not synchronize subscriber state, track last-seen slots, or orchestrate failover between clusters.

If you need this level of redundancy, plan your slot bookkeeping and failover logic accordingly. For the full step-by-step detection, failover, and failback procedure, follow the [Fumarole cluster failover guide](https://docs.triton.one/solana/quickstart/streaming/fumarole-cluster-failover).

## Limits

* Each subscription can have 15 persistent subscribers on each regional cluster.
* Every persistent subscriber counts until you delete it, including a stale one that fell behind the 4-day window.
* Creating a subscriber past the limit fails with `FAILED_PRECONDITION` and the message `Reached consumer groups limit of 15`.
* To free a slot, run `fume list`, then `fume delete --name <name>`.

## Pricing

On shared infrastructure, Fumarole is billed on the data sent. For current rates, see [triton.one/pricing](https://triton.one/pricing).

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-tower-broadcast">:tower-broadcast:</i> <strong>Dragon's Mouth gRPC</strong></td><td>Sub-slot real-time updates for accounts, transactions, slots, and blocks via gRPC.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc">Dragon's Mouth gRPC</a></td></tr><tr><td><i class="fa-list-check">:list-check:</i> <strong>Best practices</strong></td><td>Filtering, reconnect, and commitment guidance across the streaming services.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/best-practices">Real-time streaming best practices</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Real-time streaming best practices

Choose between Dragon's Mouth, WebSocket, Fumarole and Deshred, then tune distance, filters, connections, commitment and reconnects for Solana streaming.

## Pick the right stream

| Stream                                                                                          | Use it for                                                                     | How it works                                                                                                                                                                                                                                                                                                           |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Dragon's Mouth (gRPC)](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc) | Low latency on a backend                                                       | Account and transaction updates are pushed over a persistent connection as the node processes them, giving a head start over a polling client. Stream at `processed` and track `confirmed` and `finalized` yourself (see [Handle commitment client-side](#handle-commitment-client-side)).                             |
| [WebSocket](https://docs.triton.one/solana/real-time-streaming/whirligig-websockets)            | Browsers and frontends                                                         | Browsers don't support gRPC, so the WebSocket API serves Dragon's Mouth data over `wss://`. Account updates at `processed` commitment arrive intra-slot. `transactionSubscribe` sends each transaction that matches your filter as its own message. `blockSubscribe` sends whole blocks at `confirmed` or `finalized`. |
| [Fumarole](https://docs.triton.one/solana/real-time-streaming/fumarole-persistent-streams)      | Reliability-first pipelines (accounting, analytics, indexing, compliance)      | Adds persistence, redundancy, and 4 days of replay on top of Dragon's Mouth, which trades completeness for latency. Use the Rust or TypeScript client. Don't call Fumarole's gRPC methods directly.                                                                                                                    |
| [Deshred](https://docs.triton.one/solana/real-time-streaming/deshred-transactions)              | Transactions before they execute (arbitrage, market making, liquidations, HFT) | Reconstructs transactions from shreds before execution, so no confirmation guarantee; pair it with the `transactions` stream when you need finality.                                                                                                                                                                   |

## Provision the subscriber

* **Run your subscriber as close to a Triton region as you can.** Keep round-trip time (RTT) to the endpoint at or below 50 ms; the table below lists approximate values by distance. See [Endpoints, regions, and routing](https://docs.triton.one/using-your-endpoint/endpoints-regions-routing) for regions.
* **Provision 5 Gbps minimum for large subscriptions, 10 Gbps for full-chain** (accounts plus transactions). The full feed can spike to \~1.3 to 1.8 Gbps, and cloud instances are often capped at \~1 Gbps by default.
* **Use the latest `@triton-one/yellowstone-grpc` release for high-volume streams.** Vanilla Node.js is too slow for Solana. Since 5.0.1, the client runs the gRPC engine in Rust through NAPI-as-an-Engine (NaaE). Triton's benchmark measured about 400% more data throughput than the previous pure-JavaScript version ([blog post](https://blog.triton.one/grpc-js-alternative-napi-rust/)). After you create the client, call `client.connect()` and use camelCase channel options. The [Go client](https://github.com/rpcpool/yellowstone-grpc/tree/master/examples/golang) is an example that can lag the latest proto; the Rust client is the production-ready reference.
* **Solve frequent disconnects early and rule out a client-side problem** (a weak or under-provisioned setup) before assuming a server fault. Start with [Streams disconnecting](https://docs.triton.one/solana/faq/error-handling/streams-disconnecting). [Learn more](https://blog.triton.one/solana-grpc-streaming-optimisation-and-troubleshooting-2026-guide/).

{% hint style="warning" %}
**Run subscribers on a persistent server (VPS or bare metal), not serverless functions** like AWS Lambda. Serverless functions don't suit streaming connections and can leave many open connections on the server, which can degrade service.
{% endhint %}

## Stay on the tip during high load

When your client cannot keep up, data backs up in buffers, you drift from the tip, and the server drops the connection. Most drift is client-side, and is usually caused by one of these:

<details>

<summary>You are too far from a Triton region</summary>

Distance is the biggest driver of RTT. With adaptive window sizing, the HTTP/2 stack in the Rust and TypeScript clients (hyper) grows the window to at most 16 MiB, which puts the ceiling for full-chain streaming near 16 MiB / 2 Gbps, \~67 ms, so target 50 ms or less. Measure it from the machine that runs your subscriber with `ping <your-endpoint-hostname>`, and run close to a Triton region:

| Scenario                   | Typical distance | Expected RTT  |
| -------------------------- | ---------------- | ------------- |
| Same city or metro         | under 50 km      | 1 to 5 ms     |
| Regional, two data centers | 200 to 500 km    | 5 to 15 ms    |
| Cross-country (US)         | \~4,500 km       | 60 to 80 ms   |
| Transatlantic              | \~6,000 km       | 70 to 100 ms  |
| Transpacific               | \~9,000+ km      | 140 to 200 ms |

</details>

<details>

<summary>You receive data you don't use</summary>

Narrow the subscription: filter precisely and trim account data with `accounts_data_slice`. See [Filters and connections](#filters-and-connections).

</details>

<details>

<summary>You subscribe at <code>confirmed</code> or <code>finalized</code></summary>

The server sends each block's content in one batch after the block reaches that level, which adds latency and makes bandwidth bursty. Stream at `processed` and [track commitment in your client](#handle-commitment-client-side).

</details>

<details>

<summary>The flow-control window is smaller than your bandwidth-delay product (BDP)</summary>

gRPC runs on HTTP/2, which only lets the server send a window's worth of data before it waits for an acknowledgement. The volume you need in flight is the BDP, `bandwidth × RTT` (2 Gbps at 10 ms RTT is \~2.38 MiB). A window below the BDP leaves bandwidth idle. Let the client size the window automatically (adaptive window sizing), which Rust client 13.3.0 and later turn on by default in `from_shared`:

```rust
use yellowstone_grpc_client::GeyserGrpcBuilder;

// Client 13.3.0 and later enable adaptive window sizing in from_shared; this call makes it explicit.
let builder = GeyserGrpcBuilder::from_shared("https://<your-endpoint>")?
    .http2_adaptive_window(true);
```

</details>

<details>

<summary>You process inside the receive loop</summary>

If one thread receives a message, parses it, writes it to a database, and only then reads the next, it fills buffers and disconnects under load. Decouple ingestion from processing: the receive loop should only push each message onto a queue or channel, and a worker pool handles parsing and writes.

</details>

<details>

<summary>Your bandwidth is limited, or you are still far from a region after the steps above</summary>

Zstd compression can help, but use it sparingly: it adds latency and CPU on both ends, and adds load on Triton's servers. To enable it in the Rust client:

```rust
use yellowstone_grpc_proto::tonic::codec::CompressionEncoding;

let builder = GeyserGrpcBuilder::from_shared("https://<your-endpoint>")?
    .accept_compressed(CompressionEncoding::Zstd);
```

</details>

Verify with the `client-linux-amd64` test client (x86-64 Linux; see [Verify your gRPC endpoint](https://docs.triton.one/solana/faq/error-handling/verify-your-grpc-endpoint)), using the exact flags and filters you will run in production:

```bash
./client-linux-amd64 \
  --http2-adaptive-window true \
  --commitment processed \
  --endpoint https://<your-endpoint> \
  --x-token <your-token> \
  subscribe --transactions --accounts --stats
```

Add `--compression zstd` only if you use Zstd in production.

{% hint style="success" %}
A ping every \~10 seconds and a total of 60-80 Mbps (full-chain feed) mean you are holding the tip.
{% endhint %}

{% hint style="warning" %}
A ping every 12 seconds or more, or none at all, means you are falling behind, so narrow the subscription or fix the causes above.
{% endhint %}

If the stream still disconnects, go through [Streams disconnecting](https://docs.triton.one/solana/faq/error-handling/streams-disconnecting).

## Filters and connections

* **Filter precisely:** subscription fields are logical AND and array values logical OR; include or exclude vote and failed transactions.
* **Expect no vote transactions on Alpenglow clusters.** Blocks contain no vote transactions, so `vote: true` matches nothing and `vote: false` excludes nothing. User activity is unchanged.
* **Trim payloads with `accounts_data_slice`** to receive only the bytes you need.
* **For blocks, exclude transactions or scope to specific accounts**, or use the block-meta subscription when you only need block-processed notifications.
* **Open one connection per Dragon's Mouth, Riptide, or Deshred stream.** A stream is one `subscribe` call; several named filters in one subscribe request are still one stream. With two or more such streams, give each stream its own gRPC connection. Streams on one gRPC connection share one TCP connection and one HTTP/2 flow-control window, so a lost packet or a full window delays all of them, and some setups break because of Triton's load balancer.
* **Modify a stream's subscription in place** by sending a new subscribe request on the same bi-directional stream, rather than opening a new stream for each change.

{% hint style="warning" %}
A new subscribe request entirely overwrites the previous one, so **keep a local register of your full subscription config.**
{% endhint %}

## Handle commitment client-side

* **Stream at `processed` and track `confirmed` and `finalized` yourself,** rather than asking the server to buffer by commitment. A `confirmed` or `finalized` subscription receives a block's account, transaction and entry updates only after the block reaches that level; a `processed` subscription receives them as they arrive.
* **Do the work at `processed` and commit once you observe the commitment.**
* **Buffer events per bank, not per slot.** Every block is produced by a bank, identified by a `bank_id`. A slot usually has one bank, but it can have several competing ones. Key the buffer by `(slot, bank_id)`; a bank ID is unique only within one connection.
* **On a `processed` stream, events for one bank arrive in this order:**
  1. Content, in any order: `CreatedBank` (slot status `SLOT_CREATED_BANK`), entries, transactions, and account updates, including the sysvars `Clock`, `SlotHashes`, `SlotHistory` and `RecentBlockhashes` (`Clock` and `SlotHashes` can arrive before `CreatedBank`).
  2. Block footer: at most one per bank, on Alpenglow clusters only.
  3. `BlockMeta`, which marks the end of the bank's block.
  4. Commitment updates: `Processed`, then `Confirmed`, then `Finalized` (slot statuses `SLOT_PROCESSED`, `SLOT_CONFIRMED`, `SLOT_FINALIZED`).
* **Release a bank's buffered events when the `Confirmed` or `Finalized` update for that `bank_id` arrives,** at the level you need. On a `processed` stream, nothing about a bank's content arrives after its `BlockMeta`, and no commitment update for that bank arrives before it.
* **Subscribe to `slots` and leave `filter_by_commitment` unset** to receive all three commitment updates on a `processed` stream.
* **Set `interslot_updates` on the `slots` filter to also receive `SLOT_CREATED_BANK`.** See [Intra-slot updates](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc#intra-slot-updates).
* **Expect commitment updates for ancestor slots too.** When a slot reaches `confirmed` or `finalized`, the server also sends that status for each ancestor slot that has not reached it yet.
* **If you use `subscribe_with_reconnect`, drop the state of the banks each `Disconnected` event lists,** and skip banks a replay resends that you already hold whole. See [Reconnect with bank recovery](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc#reconnect-with-bank-recovery).

## Reconnect and replay

* **Recover from short disconnects with `from_slot`:** track your last processed slot, then reconnect and resubscribe from it. The server replays buffered updates, then continues live.
* **Deduplicate replayed updates** (replay starts at a slot boundary, so the boundary slot may repeat).
* **Check the earliest replayable slot first** via `SubscribeReplayInfo` (`first_available`); if `from_slot` is too old the request fails, so fall back to a fresh live subscription or your own backfill path.
* **Let the client reconnect:** `subscribe_with_reconnect` (Rust, `yellowstone-grpc-client` 17.0.0 and later) and `subscribeWithReconnect()` (TypeScript, `@triton-one/yellowstone-grpc` 10.0.0 and later) reconnect at any commitment level, replay from the last confirmed slot seen by default, and emit a `Disconnected` event listing the partly delivered banks, which your code must drop. Filter changes apply to every reconnect. They don't accept a startup snapshot. Ordinary subscriptions never reconnect. See [Reconnect with bank recovery](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc#reconnect-with-bank-recovery).

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Historical data

Superbank serves Solana ledger history over JSON-RPC: getTransaction, getSignaturesForAddress, getTransactionsForAddress; bulk backfill uses Old Faithful.

Superbank is an [open-source](https://github.com/solana-rpc/superbank) Rust workspace that ingests Solana ledger data into ClickHouse and serves it as Solana-compatible JSON-RPC, adding server-side filters, pagination, and the `getTransactionsForAddress` method.

Existing Solana JSON-RPC clients work against Superbank. On mainnet endpoints, Triton routes the historical methods you already call to Superbank and other purpose-built backends automatically. Devnet and testnet endpoints are not served by Superbank, and dedicated nodes may differ.

The address index behind `getSignaturesForAddress` and `getTransactionsForAddress` skips four addresses: the System Program, the Vote Program, SysvarClock and SysvarSlotHashes.

## Features and benefits

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-gauge-high">:gauge-high:</i> <strong>Faster historical queries</strong></td><td>At p50 against BigTable: 5x faster getSignaturesForAddress, 38x getSignatureStatuses, 3.3x getTransaction.</td><td></td></tr><tr><td><i class="fa-list-check">:list-check:</i> <strong>Address history in one method</strong></td><td>getTransactionsForAddress returns an address's transactions with server-side filters, optional token-account activity, and a pagination cursor.</td><td></td></tr><tr><td><i class="fa-bolt">:bolt:</i> <strong>Sub-1 ms recent reads</strong></td><td>A head cache keeps the newest slots in memory, so recent reads return in under 1 ms.</td><td></td></tr><tr><td><i class="fa-code">:code:</i> <strong>Open source</strong></td><td>Run Superbank yourself under AGPL-3.0. Source and schemas are on GitHub.</td><td></td></tr></tbody></table>

## How it works

You query Superbank with the standard Solana JSON-RPC methods. Behind that, it ingests the full ledger into ClickHouse (a columnar database) and translates each request into SQL tuned to how the data is sorted.

Reads are tiered. A head cache holds the newest, not-yet-finalized slots in memory, so recent reads return in under 1 ms. An optional local disk cache (ClickHouse) serves recent finalized slots from local disk in place of the main ClickHouse store. ClickHouse serves the full history, and a miss at any cache layer falls through to the next one automatically.

```mermaid
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#F2EDF6','primaryBorderColor':'#7A4BA0','primaryTextColor':'#171717','lineColor':'#956FB3','secondaryColor':'#E4DBEC','tertiaryColor':'#D7C9E3','edgeLabelBackground':'#F2EDF6'},'flowchart':{'nodeSpacing':20,'rankSpacing':35,'curve':'linear'}}}%%
flowchart LR
    ledger["Full Solana ledger"] --> ingest["Ingest"] --> ch["ClickHouse<br/>columnar store"] --> q["JSON-RPC<br/>head + disk cache tiers"] --> you["Your app"]
    style you fill:#D6EAF8,stroke:#259DD0
```

For the full architecture (storage layout, materialized views, tiered storage) see [Inside Superbank](https://blog.triton.one/inside-superbank-architecture-breakdown/).

## Supported methods

Superbank implements the methods below and serves ledger history back to the genesis block. Most follow standard Solana JSON-RPC; a few add an optional parameter or extend it.

| Method                                                                                                                                                                                                                               | Returns                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getBlock`, `getBlocks`, `getBlocksWithLimit`, `getBlockTime`, `getBlockHeight`, `getSlot`, `getTransactionCount`, `getLatestBlockhash`, `getFirstAvailableBlock`, `getInflationReward`, `getSignatureStatuses`, `minimumLedgerSlot` | Standard Solana JSON-RPC                                                                                                                                                                                                                                                                                                                                  |
| `getTransaction`                                                                                                                                                                                                                     | Standard, plus Triton's optional `slot` hint (`u64`): skips the ledger-wide signature search by querying that exact slot. The response is `null` if the signature isn't present in that slot                                                                                                                                                              |
| `getSignaturesForAddress`                                                                                                                                                                                                            | Standard, plus Triton's `beforeSlot`/`untilSlot` (`u64`) on shared mainnet endpoints (dedicated nodes may differ): exclusive whole-slot bounds (`slot < beforeSlot`, `slot > untilSlot`), not signature-position cursors. `beforeSlot` can't be combined with `before`, nor `untilSlot` with `until`                                                      |
| `getTransactionsForAddress`                                                                                                                                                                                                          | Triton's extension: an address's transactions (signatures or full) in one method, with server-side filters (by status, slot, block time, and token accounts) and a pagination cursor; each call returns up to 1000 signatures or 100 full transactions. Token-account activity is included only through `filters.tokenAccounts`, which defaults to `none` |

Serving notes:

* JSON-RPC batch envelopes are supported.
* On `getSignaturesForAddress`, if the signature you pass as `before` or `until` can't be found, the call returns JSON-RPC error `-32020` (`Transaction <signature> not found`).
* On shared mainnet endpoints, Superbank's in-memory head cache also serves `processed` commitment on `getTransactionsForAddress` and on `getSignaturesForAddress`, `getTransaction`, and `getBlocks`, which standard Solana JSON-RPC limits to `confirmed` or `finalized`. Dedicated nodes may differ. `getBlock` and `getInflationReward` take only `confirmed` or `finalized`.
* `getInflationReward` accepts up to 100 addresses per request on shared mainnet endpoints. A request with more fails with `-32602`. Dedicated nodes may differ.

## getTransactionsForAddress

`getTransactionsForAddress` returns an address's history in one call, so you don't call `getSignaturesForAddress` and then `getTransaction` for every signature. It's a custom method, not part of standard Solana JSON-RPC, and uses the same request and response envelope.

For the request, options, filters, token-account filtering, response, pagination, and examples, see [getTransactionsForAddress](https://docs.triton.one/solana/rpc-methods/historical-data/gettransactionsforaddress).

## Bulk historical data

Triton serves history over JSON-RPC. For bulk pulls, such as backfilling months or years of blocks, use [Jetstreamer](https://github.com/vaultic-win/jetstreamer) with the public [Old Faithful](https://old-faithful.net/) archive. See [Best practices](https://docs.triton.one/solana/historical-data/best-practices#backfill-large-history-with-streaming).

Jetstreamer writes to ClickHouse or to a Jetstreamer plugin you write, and works with existing Geyser plugins for epochs 157 and later.

## Old Faithful archive

Old Faithful is Triton's open-source archive of Solana ledger history from genesis.

* To run Old Faithful yourself, see its [repository](https://github.com/rpcpool/yellowstone-faithful) and the [JSON-RPC](https://docs.old-faithful.net/references/rpc-methods) and [gRPC](https://docs.old-faithful.net/references/grpc-methods) references.
* The self-hosted gRPC interface adds `StreamTransactions` and `StreamBlocks`, which filter data on the server. See the [streaming examples](https://docs.old-faithful.net/references/grpc-methods/examples#streaming-methods).
* For the July 2024 archive verification report, see [Old Faithful public report](https://docs.triton.one/solana/historical-data/old-faithful-public-report).

## Self-hosting

Superbank is open source under AGPL-3.0, so you can run, audit, and extend it yourself. Its source-agnostic ingest means you can backfill from BigTable or an existing archive and then switch to a live stream.

* Documentation, built from Superbank's `main` branch: [solana-rpc.github.io/superbank](https://solana-rpc.github.io/superbank/), with every setting on the [configuration page](https://solana-rpc.github.io/superbank/config.html)
* Source and schemas: [github.com/solana-rpc/superbank](https://github.com/solana-rpc/superbank)
* Walkthrough: [Index Solana history with Superbank](https://docs.triton.one/solana/quickstart/how-tos/index-solana-history-with-superbank)
* The `getTransactionsForAddress` token-account filters need the token-owner activity table populated.

Prefer not to operate it? Triton runs Superbank as a managed, globally distributed service. [Get an endpoint](https://customers.triton.one/onboarding).

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-play">:play:</i> <strong>Quickstart</strong></td><td>Page through an address's history back to genesis with getTransactionsForAddress.</td><td><a href="https://docs.triton.one/solana/historical-data/quickstart">Historical data quickstart</a></td></tr><tr><td><i class="fa-list-check">:list-check:</i> <strong>Best practices</strong></td><td>Pull address history with one method, filter and paginate server-side, and backfill large history with streaming.</td><td><a href="https://docs.triton.one/solana/historical-data/best-practices">Historical data best practices</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Historical data quickstart

Fetch a Solana transaction with getTransaction and its slot hint, then page an address history with getTransactionsForAddress filters and paginationToken.

On shared mainnet endpoints, Triton routes historical methods to Superbank and other backends automatically.

## 0. Prerequisites

* An active Triton subscription
* Your endpoint URL and secret token from the [customer dashboard](https://customers.triton.one)
* `curl` or any Solana JSON-RPC client

## 1. Fetch a transaction

`getTransaction` returns the full, decoded transaction for a single signature. Take a signature from your app or an explorer.

{% tabs %}
{% tab title="curl" %}

```bash
curl "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>" -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getTransaction",
    "params": ["YOUR_SIGNATURE", { "encoding": "jsonParsed", "maxSupportedTransactionVersion": 1 }]
  }'
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
const res = await fetch("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "getTransaction",
    params: ["YOUR_SIGNATURE", { encoding: "jsonParsed", maxSupportedTransactionVersion: 1 }],
  }),
});
console.log((await res.json()).result);
```

{% endtab %}

{% tab title="Response" %}
The full transaction, decoded. Trimmed:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "slot": 250000123,
    "blockTime": 1700000000,
    "meta": { "err": null, "fee": 5000, "preBalances": [ ... ], "postBalances": [ ... ] },
    "transaction": { "message": { ... }, "signatures": [ "5wHu1qwD4kLpXnR7e8oP..." ] }
  },
  "id": 1
}
```

{% endtab %}
{% endtabs %}

If you already know the transaction's slot, pass Triton's optional `slot` hint. Superbank then queries that exact slot instead of searching the whole ledger for the signature:

```bash
curl https://<your-endpoint>.mainnet.rpcpool.com/<your-token> -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getTransaction",
    "params": ["YOUR_SIGNATURE", { "encoding": "jsonParsed", "maxSupportedTransactionVersion": 1, "slot": 250000123 }]
  }'
```

The response is `null` if the signature isn't present in that slot. `getTransactionsForAddress` below returns each item's `slot`, so its output feeds the hint directly.

## 2. Page through the history

`getTransactionsForAddress` is Triton's extension that combines the list-then-fetch pattern (`getSignaturesForAddress`, then `getTransaction` per signature) into a single request. Set `transactionDetails` to `full` and it returns the transactions directly, with no per-signature follow-up.

{% tabs %}
{% tab title="curl" %}

```bash
curl https://<your-endpoint>.mainnet.rpcpool.com/<your-token> -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getTransactionsForAddress",
    "params": ["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", { "transactionDetails": "full", "sortOrder": "desc", "limit": 5, "maxSupportedTransactionVersion": 1 }]
  }'
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
const res = await fetch("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "getTransactionsForAddress",
    params: ["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", { transactionDetails: "full", sortOrder: "desc", limit: 5, maxSupportedTransactionVersion: 1 }],
  }),
});
console.log((await res.json()).result);
```

{% endtab %}

{% tab title="Response" %}
A `data` array of transactions plus a `paginationToken`, all in one response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "data": [
      {
        "slot": 430533342,
        "transactionIndex": 1198,
        "blockTime": 1783086706,
        "transaction": { ... },
        "meta": { ... },
        "version": 0
      }
    ],
    "paginationToken": "XHLKq2uNiGAJs3YhjnmnwT7LuJoTkGDqf1k4WJsnUd4A6e9bfB26vHr4dKLfMqwZuPmuXDHih4RaojCSt61os33"
  },
  "id": 1
}
```

{% endtab %}
{% endtabs %}

Filters apply server-side and pagination uses a single cursor. For example, successful transactions within a slot range:

```bash
curl https://<your-endpoint>.mainnet.rpcpool.com/<your-token> -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getTransactionsForAddress",
    "params": ["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", { "transactionDetails": "full", "limit": 5, "maxSupportedTransactionVersion": 1, "filters": { "status": "succeeded", "slot": { "gte": 450000000, "lt": 451000000 } } }]
  }'
```

Pass the `paginationToken` from the response in the next request to keep scanning. It's an opaque cursor (currently a signature or `slot:position`), so pass it back unchanged.

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-clock-rotate-left">:clock-rotate-left:</i> <strong>Historical data</strong></td><td>Superbank: the Solana ledger from genesis over JSON-RPC.</td><td><a href="https://docs.triton.one/solana/historical-data">Historical data</a></td></tr><tr><td><i class="fa-list-check">:list-check:</i> <strong>Historical data best practices</strong></td><td>Address history in one method, server-side filters, pagination, and large backfills.</td><td><a href="https://docs.triton.one/solana/historical-data/best-practices">Historical data best practices</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Historical data best practices

Query Solana history efficiently: getTransactionsForAddress, slot hints, server-side filters, pagination, and Jetstreamer backfills from Old Faithful.

## Pull address history with one method

* **Use `getTransactionsForAddress` instead of the `getSignaturesForAddress` + `getTransaction` two-step.** The standard pattern is N+1 (one call to list signatures, then one per signature); `getTransactionsForAddress` with `transactionDetails: "full"` returns the transactions in a single request.

| Parameter                        | Set it to                 | Why                                                                                                                                                                                                               |
| -------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transactionDetails`             | `"full"`                  | Returns full transactions. The default, `signatures`, returns one entry per transaction (`signature`, `slot`, `transactionIndex`, `err`, `memo`, `blockTime`, `confirmationStatus`) without the transaction body. |
| `maxSupportedTransactionVersion` | `1`, together with `full` | Without it, a page that holds a v0 or v1 transaction fails with error `-32015`.                                                                                                                                   |
| `filters.tokenAccounts`          | `all` or `balanceChanged` | Captures token activity. The default `none` returns only transactions where the address appears directly, not transactions involving token accounts it owns.                                                      |

## Filter and paginate server-side

| Method                      | Filters and pagination                                                                                                                                                                                     | Speed                                                                                                                                                                                                                                                                                                                                                                                       |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getTransactionsForAddress` | Carries the full filter set. Pass the `slot`, `blockTime`, `signature`, `status`, and `tokenAccounts` filters so you receive only the slice you need, and page with the returned `paginationToken`.        | Bound deep scans with a slot range (`filters.slot: { gte, lt }`).                                                                                                                                                                                                                                                                                                                           |
| `getSignaturesForAddress`   | Paginates with `before`/`until` signature cursors, plus, on shared mainnet endpoints, Triton's `beforeSlot`/`untilSlot` whole-slot bounds when you already know the slot range. It has no content filters. | The `beforeSlot`/`untilSlot` bounds skip the signature-to-slot lookup the standard cursors force on the server. Dedicated nodes may not support them.                                                                                                                                                                                                                                       |
| `getTransaction`            | No filters or pagination.                                                                                                                                                                                  | Pass the `slot` hint when you know it. A signature carries no timing information, so without a hint the server first looks up the slot that holds the signature, then reads the transaction. On shared mainnet endpoints, Triton's optional `slot` field in the config object (the second parameter) narrows the lookup to that one slot, so the server skips the signature-to-slot lookup. |

{% hint style="info" %}
`minContextSlot` is a consistency guard, not a speed lever. It fails the request if the server has not yet reached that slot, protecting you from stale reads. Recent reads are fast on their own: the newest slots are served from the in-memory head cache in under 1 ms.
{% endhint %}

## Backfill large history with streaming

Polling `getBlock` and `getTransaction` over HTTP for months of history is the slow path, suited to small slot ranges. For heavy or full-chain backfills, we recommend streaming instead:

* **Jetstreamer + the public Old Faithful archive.** [Jetstreamer](https://github.com/vaultic-win/jetstreamer), an open-source backfilling toolkit, streams from [Old Faithful](https://old-faithful.net/), the open-source archive of Solana blocks and transactions from genesis.
* **Jetstreamer replays history in parallel.** It writes into ClickHouse, your own Jetstreamer plugin, or an existing Geyser plugin (Geyser plugins work for epochs 157 and later).
* **Jetstreamer reads the public archive, not a Triton endpoint.** The archive is `files.old-faithful.net`.
* **`files.old-faithful.net` pauses the heaviest downloaders when its shared bandwidth runs high.** A paused client gets `HTTP 429` for 30 minutes, and for longer on a repeat. Retry later with fewer parallel downloads.
* **Use the `jetstreamer` crate 0.7.0 or later.** `files.old-faithful.net` returns `HTTP 403` to the user agents `jetstreamer/v0.4.*`, `jetstreamer/v0.5.*` and `jetstreamer/v0.6.*`, which versions 0.4 to 0.6 send.
* **Jetstreamer parses legacy, v0 and v1 transactions.** This holds for the `jetstreamer` crate 0.8.1 and later.
* **Self-hosted Superbank.** To ingest Old Faithful history up to the Alpenglow genesis slot into your own Superbank, see [Index Solana history with Superbank](https://docs.triton.one/solana/quickstart/how-tos/index-solana-history-with-superbank).

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# AccountsDB storage file shrinking

How Agave AccountsDB shrinking works (--accounts-shrink-ratio, shrink\_collect) and why snapshots can lack old account versions.

Shrinking is a process that Agave executes periodically. Its goal is to remove accounts from storage files that are no longer valid because a newer version of the account exists.

This matters if you read Solana snapshots directly: **the shrinking process means a snapshot carries no guarantee that superseded account data is still present.** It might be there, or it might have been compacted away.

## Configuration

Shrinking runs on a hardcoded one-second interval:

```rust
const SHRINK_INTERVAL: Duration = Duration::from_secs(1);
```

Two flags control its behavior:

```bash
--accounts-shrink-ratio                 # defaults to 0.8
--accounts-shrink-optimize-total-space  # defaults to true
```

| Flag                                     | Default | Effect                                                                                                                                                                                                                                                     |
| ---------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--accounts-shrink-ratio`                | `0.8`   | Ratio of live bytes to total bytes. When `--accounts-shrink-optimize-total-space` is true, shrinking stops once the ratio across all candidate files is above this value. When false, a file is a shrink candidate when its own ratio is below this value. |
| `--accounts-shrink-optimize-total-space` | `true`  | When true, shrinking is evaluated globally across all candidates. When false, every candidate file is shrunk individually with no global context in each iteration.                                                                                        |

## How it works

Each second, the bank — inside the `AccountsBackgroundService` — calls `shrink_candidate_slots()`, which:

1. Checks the list of files marked as candidates for shrinking. By default, a file is a candidate when it contains any dead bytes. When `--accounts-shrink-optimize-total-space` is false, a file is a candidate only when its live-byte ratio is below `--accounts-shrink-ratio`.
2. If `--accounts-shrink-optimize-total-space` is true, calculates total live account bytes over total account bytes across the candidates.
3. If true, orders the candidate list by live-byte ratio, starting with the most sparse files.
4. If true, iterates, shrinking files until the overall live-byte ratio rises above `--accounts-shrink-ratio`.

When true, a file that was not shrunk stays in the queue only if its own live-byte ratio is below `--accounts-shrink-ratio`. When false, steps 2-4 are skipped and every candidate is shrunk.

For each shrunk file:

* `shrink_collect()` takes the accounts read from a storage file and returns the ones that are still alive.
* **Shrinking does not modify the original file.** It generates a new file containing only the valid accounts, then repoints to the updated one.

### How an account is determined to be dead

As of Agave v4.3.0, `shrink_collect()` applies these steps in order:

1. **Obsolete-accounts check.** When a newer version of an account is flushed to storage, or when old roots are cleaned, Agave records the old version's offset in that storage file's obsolete-accounts list (`AccountStorageEntry::obsolete_accounts`). Every account whose offset is on the list is filtered out.
2. **Zero-lamport tombstones.** Accounts recorded as tombstones are filtered out too. Tombstones in slots newer than the latest full snapshot are carried forward into the new file, so an incremental snapshot can still propagate the deletion.
3. **Index check.** `load_accounts_index_for_shrink()` looks up each remaining account in `AccountsDb::accounts_index`. The entry must point at the slot being shrunk; this is an assertion, not a filter. A zero-lamport account with a single reference is dropped at this step (and kept as a tombstone if its slot is newer than the latest full snapshot).

## Consequence for snapshot consumers

**Discard every version of an account except the last one before trusting any data read from a snapshot.**

## Source

* [`accounts_background_service.rs`](https://github.com/anza-xyz/agave/blob/v4.3.0/runtime/src/accounts_background_service.rs) — `SHRINK_INTERVAL`, `shrink_candidate_slots()`
* [`accounts_db.rs`](https://github.com/anza-xyz/agave/blob/v4.3.0/accounts-db/src/accounts_db.rs) — `shrink_collect()`, `load_accounts_index_for_shrink()`, `store_accounts_for_flush()`

## What's next

* [Historical data](https://docs.triton.one/solana/historical-data) — Triton's archival and historical services
* [Historical data best practices](https://docs.triton.one/solana/historical-data/best-practices) — working with archives at scale

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Old Faithful public report

Triton's July 2024 Old Faithful report: copying the Solana ledger archive into CAR files and verifying it, including the Epoch 208 gap.

{% hint style="info" %}
This is a historical record, published **13 July 2024**. It documents the completion of the initial phases of the Old Faithful project. The report below has only formatting and link fixes. It is not a description of current service status. The "What's next" section at the end is not part of the report.
{% endhint %}

## Introduction

Triton One Limited ("Triton") has completed the initial phases of the Old Faithful project to make Solana's ledger history widely available to the community through decentralized means. We have validated the archive's integrity from Solana's genesis and uploaded copies to S3-compatible storage. With this completion of the initial phase of the Old Faithful project, Solana now has widely available copies of ledger history and new tooling required to verify the archive's integrity.

While conducting our work, we learned of missing data files ("snapshots") for less than five hundred blocks, representing four minutes and eighteen seconds. Engineers successfully verified the correctness of these slots by developing new verification tooling.

This document discusses the Old Faithful project for a general audience and a proof to demonstrate the complete validity of the Solana archive using this new method. See the footnotes below for more detailed information, including an open-sourcing of all tooling and work related to Old Faithful and ledger verification.

## Solana archive and Google BigTable

In the early days of Solana development, RPC nodes ran on Google Cloud. Cloud hosting provided convenience and simplicity for developers focused on iterating a new codebase. Solana generates more ledger data than can be easily stored on a single computing instance, so the developers used Google BigTable for ledger storage. Trent Nelson from Anza says, "Every bad decision was the right decision at the time." Using BigTable for ledger storage made sense because the RPCs were in Google Cloud, and network traffic between RPC and BigTable was free. Over time, RPCs moved to bare metal servers outside Google Cloud, and network egress from BigTable to external servers became very expensive. Access to the archives became a pain point for the developer community.

## Old Faithful

Blockchain research projects require access to historical data. Independent researchers struggled to gain affordable access to Solana ledger history since the Archives were only available in BigTable through a handful of entities. To solve this problem, Linus Kendall, Triton Co-Founder, and Richard Patel, currently with the Jump Crypto Firedancer team, brainstormed possible solutions. The two of them thought that Content Addressable aRchive ("CAR") files would provide a scalable file format that can be saved long-term on various storage platforms, such as any S3-compatible storage platform.

The objective of The Old Faithful project, financially supported by The Solana Foundation, is to copy the entire Solana archive into CAR files accessible by the community. As part of the project, we also independently verified the archive's integrity from its genesis.

## Snapshot warehouse

In the Solana Labs (now "Anza") client, the term "account snapshots" or just "snapshot" refers to the capture of the account state at a given slot. Since storing snapshots is computationally expensive, they are written at fixed, somewhat infrequent intervals. In addition to account snapshots, these nodes keep backup copies of the Solana ledger data produced by the node. The collection of snapshot and ledger files is called "the warehouse."

The warehouse files are saved in cloud storage (Anza uses Google Cloud Storage/GCS, and Triton One uses Backblaze B2 for this storage) for later retrieval and processing.

Asynchronously, an RPC node uploads new blocks to BigTable. The RPC also regularly creates a snapshot of the then-current account state and backfills the BigTable as needed for each epoch.

Solana Labs managed the original snapshot warehouse and shared it with external parties when requested. Over time, multiple ecosystem players, including Triton, copied the files to create and maintain independent warehouses. Triton and several other ecosystem participants also received a copy of the BigTable archive to maintain independent database instances. At this time, there are a handful of independent BigTable instances.

## Missing Proof-of-History entries

Our research discovered that warehouse ledger backup files were missing for less than five hundred slots, representing four minutes and eighteen seconds, in Epoch 208 (August 3, 2021). The BigTable database included all transactions for the slots, but the warehouse files were missing. The source warehouse files are needed because BigTable does not include the Proof-of-History tick data or the entry batches ("entries") required to verify the block hashes using the existing tooling. An alternative proof would be required to show that the BigTable ledger history was valid.

## Alternative proof

One of Solana's unique features is that it includes redundant hashes to verify account state and history. Every block has a "block hash," which includes the hash from the previous block as input. Validators reference the "bank hash" for a slot when they vote to confirm blocks and resolve forks. Each validator's vote contains the bank hash for the slot they are voting for. A vote for a block N is implicitly a vote for any block that is a parent of N. The bank hashes are included in the votes, and the votes are included in the blocks. Therefore, PoH is generally not needed to verify state transitions — it is possible to prove the validity of ledger history using the votes.

Engineers from Anza led the effort to create the tooling required for an alternative, cryptographically valid proof. At a high level, the proof: 1) starts with a known and verified block hash and bank hash immediately preceding the gap. Then, within the gap, 2) replay transactions from BigTable for each slot to determine the bank hash, 3) confirm that a supermajority of validators voted for the bank hash, and finally, 4) compare the final bank hash at the end of the gap to the votes from known blocks immediately after the gap.

Anza engineers created the alternative proof by replaying transactions and analyzing votes. They also created tooling to show that the transaction history is valid. Triton has independently verified the alternative proof, and we can confirm the Solana transaction history is complete and valid.

We encourage others in the community to verify the alternative proof. Links to documentation and tooling appear in the Footnotes section below.

## Summary

Triton has completed the initial phases of the Old Faithful project to make Solana ledger history widely available. We have uploaded copies of the CAR files to S3-compatible storage. We will also continue the project with the support of The Solana Foundation. With this completion of the initial phase of the Old Faithful project, Solana now has widely available copies of ledger history and the tooling required to verify the archive's integrity.

## Footnotes

Links for further research:

* [Old Faithful website](https://old-faithful.net/)
* [Old Faithful Git repository](https://github.com/rpcpool/yellowstone-faithful)
* [Old Faithful technical documentation](https://docs.old-faithful.net/)
* [Anza Ledger Tool](https://github.com/anza-xyz/agave/tree/master/ledger-tool)
* [Anza BigTable Git repository](https://github.com/solana-labs/solana-bigtable)

Major contributors:

* Linus Kendall, Co-Founder, Triton One Limited
* Slavomir Balsan, Software Engineer, Triton One Limited
* Steve Czabaniuk, Software Engineer, Anza
* Tyera Eulberg, Technical Project Leader, Anza
* Richard Patel, Firedancer Core Contributor, Jump Crypto

## What's next

* [Historical data](https://docs.triton.one/solana/historical-data) — historical ledger queries with Superbank
* [Index Solana history with Superbank](https://docs.triton.one/solana/quickstart/how-tos/index-solana-history-with-superbank) — run Superbank on one node to index the full Solana ledger

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Sending transactions

Send Solana transactions with sendTransaction, /sendtx or the Jet TPU client, with SWQoS, percentile priority fees, Shield MEV protection and trading APIs.

You build and sign a transaction, then submit it so a validator includes it in a block. Landing reliably under load comes down to a few things:

* **Direct delivery.** Sending to the current and upcoming leaders from Triton's own sending infrastructure, separate from the RPC nodes that serve your reads.
* **Stake-weighted quality of service (SWQoS).** Prioritizing your transactions for higher landing rates under congestion. On by default for mainnet sends at no extra cost, with nothing to request. Devnet sends are not staked.
* **Priority fees.** Attaching a fee that reflects the real market rate without overpaying, on any send path.
* **Protection.** Optionally restricting which validators can process your transaction, to avoid harmful MEV.

## Pick your send path

Every `sendTransaction` and `/sendtx` request to a Triton mainnet endpoint is handled by **Jet**, Triton's SWQoS-powered specialized sending engine: it tracks the leader schedule and forwards your transaction directly to the TPUs of the current and upcoming leaders.

You can submit through two managed routes depending on your use case, or self-host the Jet TPU client for full client-side control.

* [**`sendTransaction`**](https://docs.triton.one/solana/rpc-methods/sending-transactions/sendtransaction) is the standard Solana JSON-RPC method. We route it through Jet and apply SWQoS on mainnet.
* [**`/sendtx`**](https://docs.triton.one/solana/rpc-methods/sending-transactions/sendtx) is a direct HTTP submission endpoint that takes the same delivery path as `sendTransaction`. It takes the transaction as a raw, base58, or base64 body and skips the JSON-RPC envelope, so there is no JSON to build or parse and the payload is smaller. A `text/plain` body with no custom headers also skips the browser CORS preflight. It needs no RPC client library.
* [**Jet TPU client**](https://docs.triton.one/solana/quickstart/sending-transactions/yellowstone-jet-tpu-client) is the open-source Rust crate [`yellowstone-jet-tpu-client`](https://crates.io/crates/yellowstone-jet-tpu-client), which you embed in your own application for full client-side control. It sends your transactions straight to validator TPUs over QUIC, with a callback that reports whether each transaction was sent, failed, or dropped, custom destinations and blocklists, and Yellowstone Shield support behind the `shield` feature flag. It needs an RPC endpoint and a Yellowstone gRPC endpoint.

|                                                   |        `sendTransaction`       |              `/sendtx`             |       Jet TPU client (self-hosted)      |
| ------------------------------------------------- | :----------------------------: | :--------------------------------: | :-------------------------------------: |
| **Use case**                                      |       broad compatibility      |       browsers, HFT backends       |           bots, custom routers          |
| **Interface**                                     |         Solana JSON-RPC        |              HTTP POST             |               Rust library              |
| **Ease of use**                                   |         any Solana SDK         | a single HTTP POST, no RPC library |          you operate the client         |
| **Client to run**                                 |              none              |                none                |                   yes                   |
| **Reaches the TPU via**                           |   your endpoint (server-side)  |     your endpoint (server-side)    |           your client (direct)          |
| **SWQoS by default on mainnet (no extra charge)** |                ✓               |                  ✓                 | ✗ (only if your own identity is staked) |
| **`skipPreflight` option**                        |                ✓               |     ✗ (always skips preflight)     |      ✗ (direct send, no preflight)      |
| **Shield policy**                                 | `forwardingPolicies` parameter | `Solana-ForwardingPolicies` header |          `shield` feature flag          |

{% hint style="info" %}
With `skipPreflight: false` (the default), Triton simulates the transaction before it forwards it. `/sendtx` always skips preflight.
{% endhint %}

## Priority fees and protection

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-arrow-trend-up">:arrow-trend-up:</i> <strong>Priority fees API</strong></td><td>Percentile-based fee estimates that price against the real market rate instead of the minimum. Triton's extension of the <code>getRecentPrioritizationFees</code> method.</td><td><a href="https://docs.triton.one/solana/sending-transactions/priority-fees-api">Priority fees API</a></td></tr><tr><td><i class="fa-shield">:shield:</i> <strong>Shield Protection</strong></td><td>Attach an on-chain validator allowlist or blocklist so only validators you trust process your transaction.</td><td><a href="https://docs.triton.one/solana/sending-transactions/shield-mev-protection">Shield Protection</a></td></tr></tbody></table>

## Trading APIs

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-route">:route:</i> <strong>Titan Swap API</strong></td><td>Real-time streaming quotes over WebSocket, liquidity meta-aggregation, and DART on-chain routing at the time of execution.</td><td><a href="https://docs.triton.one/solana/sending-transactions/3rd-party-apis/titan-swap-api">Titan Swap API</a></td></tr><tr><td><i class="fa-box">:box:</i> <strong>Jito Bundle Simulation</strong></td><td>Simulate atomic bundles on Triton's Jito-enabled RPC.</td><td><a href="https://docs.triton.one/solana/sending-transactions/3rd-party-apis/jito-bundles">Jito Bundle Simulation</a></td></tr></tbody></table>

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-play">:play:</i> <strong>Quickstart</strong></td><td>Send a transaction with <code>/sendtx</code> and with <code>sendTransaction</code>.</td><td><a href="https://docs.triton.one/solana/sending-transactions/quickstart">Sending transactions quickstart</a></td></tr><tr><td><i class="fa-list-check">:list-check:</i> <strong>Best practices</strong></td><td>Land your transactions fast and reliably.</td><td><a href="https://docs.triton.one/solana/sending-transactions/best-practices">Sending transactions best practices</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Sending transactions quickstart

Send a Solana transaction with POST /sendtx or JSON-RPC sendTransaction, then confirm it with getSignatureStatuses.

`/sendtx` is available on every Triton mainnet endpoint. It and `sendTransaction` both go through our Jet engine, with SWQoS applied on mainnet.

## 0. Prerequisites

* An active Triton subscription.
* Your endpoint URL and secret token from the [customer dashboard](https://customers.triton.one).
* A funded keypair and a way to build and sign a transaction (`@solana/web3.js`, `@solana/kit`, or your SDK of choice).
* The samples use `@solana/web3.js` 1.x: `npm i @solana/web3.js@1 bs58`.
* The TypeScript samples use top-level `await`: set `"type": "module"` in `package.json`.

## 1. Build and sign a transaction

Build and sign as usual, then serialize it to raw bytes. The signature is deterministic, so you can read it from the signed transaction before you send.

```ts
import {
  Connection, Keypair, PublicKey, SystemProgram, Transaction,
} from "@solana/web3.js";
import bs58 from "bs58";

const connection = new Connection("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>", "confirmed");
const payer = Keypair.fromSecretKey(Uint8Array.from(JSON.parse(process.env.SECRET_KEY!))); // 64-byte secret key

const tx = new Transaction().add(
  SystemProgram.transfer({
    fromPubkey: payer.publicKey,
    toPubkey: new PublicKey("RecipientAddressBase58"),
    lamports: 1000,
  }),
);
tx.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
tx.feePayer = payer.publicKey;
tx.sign(payer);

const wire = tx.serialize();           // raw bytes
const expectedSignature = bs58.encode(tx.signature!); // base58 signature, known before you send
```

## 2. Submit it

{% tabs %}
{% tab title="/sendtx" %}
{% tabs %}
{% tab title="TypeScript" %}

```ts
const res = await fetch(
  "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>/sendtx?response=signature",
  {
    method: "POST",
    headers: { "Content-Type": "application/octet-stream" },
    body: new Uint8Array(wire), // plain Uint8Array copy: TypeScript's fetch BodyInit type rejects a Buffer
  },
);

console.log("Signature:", await res.text());
```

{% endtab %}

{% tab title="curl (raw bytes)" %}

```bash
curl -X POST 'https://<your-endpoint>.mainnet.rpcpool.com/<your-token>/sendtx?response=signature' \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @transaction.bin
```

{% endtab %}

{% tab title="curl (base64)" %}

```bash
curl -X POST 'https://<your-endpoint>.mainnet.rpcpool.com/<your-token>/sendtx?encoding=base64&response=signature' \
  -H 'Content-Type: text/plain' \
  -d 'BASE64_SIGNED_TX'
```

{% endtab %}
{% endtabs %}

Query parameters:

* `encoding`: `base58` (default) or `base64`, for text bodies. Rejected with `application/octet-stream`.
* `response=signature`: returns the signature on success. Without it, the response body is empty.
* `max_retries`: accepted, but it adds no retries. Triton doesn't retry on the server, so rebroadcast the same signed bytes from your client until the transaction confirms or its blockhash expires.

Optional header: `Solana-ForwardingPolicies` takes comma-separated [Yellowstone Shield](https://docs.triton.one/solana/sending-transactions/shield-mev-protection) policy addresses to apply when forwarding.

{% hint style="warning" %}
`/sendtx` always skips preflight, so `skipPreflight: false` and simulation are not supported on it, and it serves no other RPC methods. Use `sendTransaction` if you need preflight, though we recommend running `simulateTransaction` as a separate call either way.
{% endhint %}

On success, `/sendtx` returns HTTP 200. With `response=signature`, the body is the transaction signature as plain text, not JSON:

```
5j7s4Hk3vQmPq8nLZ9xTe8oP...
```

An invalid request returns HTTP 400 with a plain-text error message, and methods other than POST return HTTP 405, except the CORS preflight `OPTIONS` request. Rate limiting and server errors return other 4xx or 5xx statuses.
{% endtab %}

{% tab title="sendTransaction" %}
{% tabs %}
{% tab title="TypeScript" %}

```ts
const signature = await connection.sendRawTransaction(wire);
console.log("Signature:", signature);
```

{% endtab %}

{% tab title="curl" %}

```bash
curl https://<your-endpoint>.mainnet.rpcpool.com/<your-token> -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "sendTransaction",
    "params": ["BASE64_SIGNED_TX", { "encoding": "base64" }]
  }'
```

{% endtab %}
{% endtabs %}

The JSON-RPC result is the transaction signature:

```json
{ "jsonrpc": "2.0", "result": "5j7s4Hk3vQmPq8nLZ9xTe8oP...", "id": 1 }
```

{% endtab %}
{% endtabs %}

`/sendtx` skips the JSON-RPC envelope, so there is no JSON parsing and the request body is smaller. See the [sendTx](https://docs.triton.one/solana/rpc-methods/sending-transactions/sendtx) reference for CORS behavior, parameters, headers, and responses, and [sendTransaction](https://docs.triton.one/solana/rpc-methods/sending-transactions/sendtransaction) for the standard JSON-RPC interface.

## 3. Verify it landed

{% tabs %}
{% tab title="curl" %}

```bash
curl https://<your-endpoint>.mainnet.rpcpool.com/<your-token> -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getSignatureStatuses",
    "params": [["YOUR_SIGNATURE"], { "searchTransactionHistory": true }]
  }'
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "jsonrpc": "2.0",
  "result": {
    "context": { "slot": 460215362 },
    "value": [
      { "slot": 460215360, "confirmations": null, "err": null, "status": { "Ok": null }, "confirmationStatus": "finalized" }
    ]
  },
  "id": 1
}
```

{% endtab %}
{% endtabs %}

A `confirmationStatus` of `confirmed` or `finalized` means it landed, and `"err": null` means it also succeeded. If the status is still `null`, resend the same `wire` bytes until it lands or its blockhash expires; don't re-sign while the original can still land. See [Handle retries yourself](https://docs.triton.one/solana/sending-transactions/best-practices#handle-retries-yourself).

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-paper-plane">:paper-plane:</i> <strong>Yellowstone Jet TPU client</strong></td><td>Send transactions straight to leaders over QUIC from Rust, with leader tracking and per-transaction callbacks.</td><td><a href="https://docs.triton.one/solana/quickstart/sending-transactions/yellowstone-jet-tpu-client">Yellowstone Jet TPU client</a></td></tr><tr><td><i class="fa-arrow-trend-up">:arrow-trend-up:</i> <strong>Priority fees API</strong></td><td>getRecentPrioritizationFees with a percentile parameter, to choose a priority fee.</td><td><a href="https://docs.triton.one/solana/sending-transactions/priority-fees-api">Priority fees API</a></td></tr><tr><td><i class="fa-list-check">:list-check:</i> <strong>Sending transactions best practices</strong></td><td>Simulation, retries, /sendtx, confirmation, and Shield.</td><td><a href="https://docs.triton.one/solana/sending-transactions/best-practices">Sending transactions best practices</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Priority fees API

Solana priority fees API: getRecentPrioritizationFees with a Triton percentile parameter returns fee estimates at that percentile instead of the minimum.

Solana's default `getRecentPrioritizationFees` returns the **minimum** priority fee paid in recent blocks. That number is often zero, so it is a poor signal for the competitive fee.

Triton's `getRecentPrioritizationFees` accepts a `percentile` parameter (50th for the median, 90th for a high-end estimate) to get an actionable estimate based on recent on-chain activity.

The method name is unchanged. `percentile` is an integer from 1 to 10,000, representing 0.01% to 100.00%, so `5000` is the 50th percentile (median); values above 10,000 are rejected. If you omit it, the method falls back to the standard behavior and returns the minimum fee.

For each recent block, Triton takes the compute-unit prices paid by its non-vote transactions and returns the value at your percentile. If you pass account addresses, it also takes that percentile over the transactions that write-lock each account, and returns the highest of these values.

## Sending a request

```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "getRecentPrioritizationFees",
  "params": [
    ["RNXnAJV1DeBt6Lytjz4wYzvS3d6bhsfidS5Np4ovwZz"],
    { "percentile": 5000 }
  ]
}
```

## Expected response

The response format matches the standard Solana RPC method: one entry per recent block (up to 150), where `prioritizationFee` is a compute-unit price in micro-lamports at the requested percentile instead of the minimum.

```json
{
  "jsonrpc": "2.0",
  "result": [
    { "slot": 348126, "prioritizationFee": 1000 },
    { "slot": 348127, "prioritizationFee": 500 }
  ],
  "id": "1"
}
```

## Client integration

This is a Triton extension, so it may not be in standard SDKs. This [example repository](https://github.com/rpcpool/solana-prioritization-fees-api/) includes utility functions that you can drop into a JavaScript or TypeScript codebase.

{% hint style="info" %}
Running your own nodes or another RPC service? Triton publishes the patch that enables percentile fees: the [`v1.17.23-getrpf` tag](https://github.com/rpcpool/solana-public/tree/v1.17.23-getrpf) of `rpcpool/solana-public`, plus Agave [issue #3332](https://github.com/anza-xyz/agave/issues/3332) and [PR #217](https://github.com/anza-xyz/agave/pull/217). Learn more: [For RPC providers](https://docs.triton.one/solana/sending-transactions/priority-fees-api/for-rpc-providers).
{% endhint %}

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-play">:play:</i> <strong>Quickstart</strong></td><td>Send a transaction via Triton endpoints in a few minutes.</td><td><a href="https://docs.triton.one/solana/sending-transactions/quickstart">Sending transactions quickstart</a></td></tr><tr><td><i class="fa-list-check">:list-check:</i> <strong>Best practices</strong></td><td>Land your transactions fast and reliably.</td><td><a href="https://docs.triton.one/solana/sending-transactions/best-practices">Sending transactions best practices</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# For RPC providers

How to serve the percentile parameter of getRecentPrioritizationFees on your own Solana RPC nodes, using Triton's getrpf patch (Agave issue #3332, PR #217).

The `percentile` parameter of `getRecentPrioritizationFees` is not part of a stock Agave build. To serve it on your own RPC nodes, apply a patch to your Solana validator.

{% hint style="warning" %}
**Check the base version before you build.** The reference tag below is based on Solana `v1.17.23`, which is several major releases behind current Agave. Treat it as a reference implementation of the change rather than a version to deploy directly, and contact us before rolling it out on a modern validator.
{% endhint %}

## The patch

* [`rpcpool/solana-public` at `v1.17.23-getrpf`](https://github.com/rpcpool/solana-public/tree/v1.17.23-getrpf) — Triton's reference tag carrying the change.

## Upstream status

The change is not in Agave:

* [anza-xyz/agave issue #3332 — "Improve priority fee RPC call"](https://github.com/anza-xyz/agave/issues/3332) — open feature request for a standard fee-estimate RPC call.
* [anza-xyz/agave PR #217 — "rpc: add `percentile` to `getRecentPrioritizationFees`"](https://github.com/anza-xyz/agave/pull/217) — the upstream attempt, closed without being merged.

## What's next

* [Priority fees API](https://docs.triton.one/solana/sending-transactions/priority-fees-api) — how the API behaves for consumers
* [`getRecentPrioritizationFees`](https://docs.triton.one/solana/rpc-methods/sending-transactions/getrecentprioritizationfees) — the method reference
* [Sending transactions](https://docs.triton.one/solana/sending-transactions) — the wider transaction-sending stack

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Shield Protection

Yellowstone Shield MEV protection: on-chain validator allowlist or blocklist, attached with forwardingPolicies or the Solana-ForwardingPolicies header.

Yellowstone Shield lets you control which validators handle your Solana transactions. You create an on-chain policy listing validators you trust (an allowlist) or do not trust (a blocklist), attach the policy when you send, and your transaction only goes to validators that match.

Solana's leader schedule is deterministic, so you often know which validator will process your transaction. If that leader runs sandwich attacks (inserting transactions before and after yours to extract value), frontrunning (copying and executing your transaction idea before you), or other harmful MEV, a normal send still routes to them. Shield is how you opt out. Background: [Introducing Yellowstone Shield](https://blog.triton.one/introducing-yellowstone-shield).

## Use cases

* **Trading apps and wallets** protecting swaps from sandwich attacks and frontrunning by never sending to validators known for them.
* **Senders that route only to vetted validators**: top validators by stake, geographically distributed sets, or performance-based allowlists.
* **RPC providers and transaction forwarders** enforcing policy-based routing for their users.

## Features and benefits

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-filter">:filter:</i> <strong>Allowlist or blocklist</strong></td><td>Two strategies: forward only to validators on your allowlist, or never to validators on your blocklist.</td><td></td></tr><tr><td><i class="fa-bolt">:bolt:</i> <strong>Out of the box on Triton</strong></td><td>Attach your policy to any send through Triton: <code>forwardingPolicies</code> on <code>sendTransaction</code>, or the <code>Solana-ForwardingPolicies</code> header on <code>/sendtx</code>. No extra infrastructure.</td><td></td></tr><tr><td><i class="fa-cube">:cube:</i> <strong>On-chain and transparent</strong></td><td>Each policy is a Program Derived Address anyone can inspect, and anyone who knows the address can use it.</td><td></td></tr><tr><td><i class="fa-key">:key:</i> <strong>Token-gated management</strong></td><td>A Token Extensions asset controls each policy. Hold a token to manage it; mint more to share control with the team.</td><td></td></tr><tr><td><i class="fa-users">:users:</i> <strong>Community policies</strong></td><td>Reuse maintained allow and deny lists from the policy explorer instead of curating your own.</td><td></td></tr><tr><td><i class="fa-database">:database:</i> <strong>Cached enforcement</strong></td><td>Policies are cached and checked in the sender via the shield store, with atomic updates and thread-safe checks.</td><td></td></tr></tbody></table>

## How it works

1. **Create a policy**: an on-chain list of identities (typically validators) with an `allow` or `deny` strategy. The policy lives at a Program Derived Address, paired with an SPL token (Token Extensions): creating it mints you 1 token and keeps you the mint authority.
2. **Attach the policy address to your transactions**, either as the `forwardingPolicies` parameter on `sendTransaction` (JSON-RPC), or as the `Solana-ForwardingPolicies` HTTP header when you send through `/sendtx`. The header is only read on `/sendtx`: on a JSON-RPC `sendTransaction` call it is ignored, and the transaction goes out without Shield protection.
3. **The sender checks your policy on each send that carries it**, against every leader it would forward to (the current leader and the next one or two), and skips any leader that fails. If none pass, the transaction isn't forwarded, held or queued, although you still get its signature back.

```mermaid
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#F2EDF6','primaryBorderColor':'#7A4BA0','primaryTextColor':'#171717','lineColor':'#956FB3','secondaryColor':'#E4DBEC','tertiaryColor':'#D7C9E3','edgeLabelBackground':'#F2EDF6'},'flowchart':{'nodeSpacing':20,'rankSpacing':35,'curve':'linear'}}}%%
flowchart LR
    you["Your app"] -->|"tx + policy address"| rpc["Triton RPC / Jet"]
    rpc --> check["Policy check<br/>against upcoming leaders"]
    check -->|"leader allowed"| val["Validator"]
    check -->|"leader blocked"| drop["Skipped<br/>(not queued)"]
    style you fill:#D6EAF8,stroke:#259DD0
```

Ownership follows the token. Anyone holding a policy's token can manage it (add or remove validators), and because the token is fungible and mintable, you can mint and send tokens to share policy management with others.

The policy itself is public: anyone who knows its address can use it in their transactions.

{% hint style="info" %}
Shield only works with Shield-enabled senders (Triton RPC, or the Jet TPU client). A standard Solana RPC ignores the policy parameter and forwards the transaction as usual.
{% endhint %}

## Finding and using an existing policy

Browse the policy explorer at [validators.app/yellowstone-shield](https://www.validators.app/yellowstone-shield?network=mainnet) to see all existing policies, which validators each includes or excludes, and when it was last updated, then copy the policy address for your transactions. Common policy types:

* **Allow lists**: top validators by stake, geographically distributed validators, performance-based selection.
* **Block lists (deny lists)**: validators known for sandwich attacks or frontrunning, poor performers, community-flagged validators.

Attach the policy to your sends through Triton:

{% tabs %}
{% tab title="JSON-RPC" %}

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sendTransaction",
  "params": [
    "<base64_encoded_transaction>",
    {
      "encoding": "base64",
      "skipPreflight": true,
      "forwardingPolicies": ["<your_policy_pda>"]
    }
  ]
}
```

{% endtab %}

{% tab title="HTTP header" %}
For `/sendtx` only (JSON-RPC `sendTransaction` ignores this header). Separate multiple policies with commas:

```
Solana-ForwardingPolicies: <your_policy_pda>,<your_policy_pda2>
```

{% endtab %}

{% tab title="TypeScript" %}
The standard web3.js `sendTransaction` wrapper does not pass the policy parameter, so make the RPC call directly:

```typescript
import { Transaction } from "@solana/web3.js";
import bs58 from "bs58";

const transaction = new Transaction().add(/* your instructions */);
const signedTx = await wallet.signTransaction(transaction);
const serializedTx = bs58.encode(signedTx.serialize());

const response = await fetch("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "sendTransaction",
    params: [
      serializedTx,
      {
        encoding: "base58",
        skipPreflight: true,
        forwardingPolicies: ["<your_policy_pda>"],
      },
    ],
  }),
});

const result = await response.json();
const signature = result.result;
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Running your own RPC and want to support Shield?

* **Yellowstone Jet**: Shield support is built in.
* **Custom integration**: use the [yellowstone-shield-store](https://crates.io/crates/yellowstone-shield-store) crate to cache policies locally with atomic updates, check validators against policies thread-safely, and integrate the checks with your transaction forwarding logic.
  {% endhint %}

## Creating your own policy

You need the Solana CLI installed and configured, SOL for transaction fees, and a list of validator addresses.

{% stepper %}
{% step %}

### Install the Shield CLI

Build the CLI from the [yellowstone-shield repository](https://github.com/rpcpool/yellowstone-shield):

```bash
git clone https://github.com/rpcpool/yellowstone-shield
cd yellowstone-shield
cargo build --release --bin yellowstone-shield-cli
```

The build writes the binary to `./target/release/yellowstone-shield-cli`. Add that folder to your `PATH`, or run the binary by that path in the commands below.
{% endstep %}

{% step %}

### Prepare metadata

Create a JSON file describing your policy, upload it to IPFS or Arweave, and save the URL:

```json
{
  "name": "My Validator Policy",
  "symbol": "MVP",
  "description": "Blocks validators known for sandwich attacks",
  "image": "https://your-image-url.com/image.png",
  "external_url": "https://your-website.com",
  "attributes": []
}
```

{% endstep %}

{% step %}

### Create the policy

`--strategy deny` blocks the listed validators; `--strategy allow` permits only the listed validators.

```bash
yellowstone-shield-cli policy create \
  --strategy deny \
  --name "My Validator Policy" \
  --symbol "MVP" \
  --uri "https://your-metadata-url.json"
```

The CLI prints two addresses, Policy (the policy PDA) and Mint: save both. Use the Mint with `--mint` in the CLI commands below, and pass the Policy PDA in `forwardingPolicies` when you send. If you pass the mint instead, Shield can't find the policy and the transaction is never forwarded to a leader, even though you get a signature back. You receive 1 token and retain mint authority, so you can mint more tokens later to share policy management.
{% endstep %}

{% step %}

### Add validators

Create a text file with one validator address per line, then:

```bash
yellowstone-shield-cli identities add \
  --mint <your_mint_address> \
  --identities-path validators.txt
```

{% endstep %}
{% endstepper %}

**Managing the policy.** You must hold at least 1 policy token to manage it; if you transfer all your tokens away, you lose the ability to manage the policy.

```bash
# Replace the entire validator list
yellowstone-shield-cli identities update \
  --mint <mint_address> \
  --identities-path new_validators.txt

# Remove specific validators
yellowstone-shield-cli identities remove \
  --mint <mint_address> \
  --identities-path validators_to_remove.txt

# View policy details
yellowstone-shield-cli policy show --mint <mint_address>
```

## Limitations

Shield is a filter, not a guarantee of protection from sandwich attacks or transaction failures.

* **Policies need active maintenance.** New validators can join at any time and a bad actor can appear at any time. A blocklist only protects against what is on it, so the quality of protection depends entirely on how current the list is kept.
* **Strict policies can drop time-sensitive transactions.** When no eligible leader is available the transaction is dropped, not queued. Be careful pairing a tight allowlist with arbitrage or liquidations.
* **Check your policy addresses.** Triton skips an entry that isn't a valid public key, so the send goes out without that policy.
* **A valid address that isn't a policy fails the check.** This includes the policy's mint and a mistyped address that still decodes to a valid key. Triton skips each leader whose check reaches that address, so the transaction may not be forwarded.
* **Only Shield-enabled senders enforce policies.** A standard Solana RPC ignores `forwardingPolicies`, and the standard web3.js `sendTransaction` wrapper does not pass it: make direct RPC calls as shown in the TypeScript tab above.

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-shield">:shield:</i> <strong>Protect transactions from MEV with Shield</strong></td><td>The full walkthrough: choose RPC or TPU-client enforcement, pick a policy, and protect your sends.</td><td><a href="https://docs.triton.one/solana/quickstart/sending-transactions/protect-transactions-with-shield">Protect transactions from MEV with Shield</a></td></tr><tr><td><i class="fa-play">:play:</i> <strong>Sending transactions quickstart</strong></td><td>Send a transaction via Triton endpoints in a few minutes.</td><td><a href="https://docs.triton.one/solana/sending-transactions/quickstart">Sending transactions quickstart</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Trading APIs

Titan Swap API for streaming Solana mainnet swap quotes, and simulateBundle for simulating Jito bundles on Triton's Jito-enabled RPC.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-bolt">:bolt:</i> <strong>Titan Swap API</strong></td><td>Stream swap quotes over WebSocket, or poll over HTTPS, on the <code>/titan</code> path of your Solana mainnet endpoint. Meta-aggregation by Titan's Argos routing engine, with DART on-chain routing.</td><td><a href="https://docs.triton.one/solana/sending-transactions/3rd-party-apis/titan-swap-api">Titan Swap API</a></td></tr><tr><td><i class="fa-cubes">:cubes:</i> <strong>Jito Bundle Simulation</strong></td><td>Triton supports the <code>simulateBundle</code> method on Jito-enabled RPC, so you can test atomic transaction bundles before you submit them to the Jito Block Engine.</td><td><a href="https://docs.triton.one/solana/sending-transactions/3rd-party-apis/jito-bundles">Jito Bundle Simulation</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Titan Swap API

Stream or poll Titan swap quotes over WebSocket or HTTPS on the /titan path of your Triton Solana mainnet endpoint.

Titan is Titan Exchange's swap-routing service, available through your Triton Solana mainnet endpoint.

## Use cases

* Trading interfaces that need live price updates
* Price-monitoring dashboards
* Trading bots that need low-latency price feeds
* Wallets with live swap pricing

## Features and benefits

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-layer-group">:layer-group:</i> <strong>Meta-aggregation</strong></td><td>Titan sources routes from Argos, external aggregators and RFQ sources, simulates each route, and returns executable routes.</td><td></td></tr><tr><td><i class="fa-route">:route:</i> <strong>DART on-chain routing</strong></td><td>Dynamically Allocated Real-Time routing re-optimizes how your volume splits across pools on-chain at execution, on selected pairs.</td><td></td></tr><tr><td><i class="fa-tower-broadcast">:tower-broadcast:</i> <strong>Live quote streaming</strong></td><td>A single WebSocket channel pushes continuous quotes, each with route data and swap instructions. Quotes can also include a ready-to-sign transaction for your wallet.</td><td></td></tr><tr><td><i class="fa-coins">:coins:</i> <strong>Bandwidth billing</strong></td><td>Billed on bandwidth, with no per-request charge.</td><td></td></tr></tbody></table>

## Getting started

Titan is enabled by default on Triton's Solana mainnet endpoints for every active Solana subscription, on both shared RPC pools and dedicated nodes. Add the `/titan` path to your endpoint URL (find it in your [customer dashboard](https://customers.triton.one)), followed by Titan's API path:

* **Stream** (recommended): connect over `wss://` to `/titan/api/v1/ws` and receive continuous quote updates, faster than polling and without repeated HTTP requests.
* **Poll**: request quotes over `https://` with `GET /titan/api/v1/quote/swap`.

Stream messages are MessagePack, not JSON. The TypeScript SDK below handles the stream encoding for you; it doesn't make REST calls. Poll responses also default to MessagePack, so decode them with a MessagePack library such as `@msgpack/msgpack`, or send `Accept: application/json` with `GET /titan/api/v1/quote/swap` to get JSON instead.

```url
wss://<your-endpoint>.mainnet.rpcpool.com/<your-token>/titan/api/v1/ws
```

### Example connection

```typescript
import { V1Client } from "@titanexchange/sdk-ts";
import bs58 from "bs58";

const client = await V1Client.connect(
  "wss://<your-endpoint>.mainnet.rpcpool.com/<your-token>/titan/api/v1/ws",
);

const { stream } = await client.newSwapQuoteStream({
  swap: {
    inputMint: bs58.decode("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"), // USDC
    outputMint: bs58.decode("So11111111111111111111111111111111111111112"), // wrapped SOL
    amount: 1_000_000, // raw amount: 1 USDC
  },
  transaction: {
    userPublicKey: bs58.decode("<your-wallet-public-key>"),
  },
});

for await (const update of stream) {
  for (const [provider, route] of Object.entries(update.quotes)) {
    console.log(provider, route.outAmount, route.instructions.length);
  }
}
```

### Executing a swap

{% stepper %}
{% step %}

#### Connect

Open the WebSocket as shown above.
{% endstep %}

{% step %}

#### Request quotes

Send a `NewSwapQuoteStream` request with your swap parameters (the SDK's `newSwapQuoteStream()`).
{% endstep %}

{% step %}

#### Receive the stream

Get continuous updates, each a map of provider ID to route. Not every provider appears in every update.
{% endstep %}

{% step %}

#### Select a quote

Choose by your criteria, such as price or provider.
{% endstep %}

{% step %}

#### Execute

Quotes are built for the `userPublicKey` you send. Each `SwapRoute` carries the instructions and address lookup tables to build your own transaction, and can also carry a ready-to-sign `transaction`. Sign and submit whichever you use.
{% endstep %}
{% endstepper %}

For the request and response format and the full execution flow, see the [Titan Swap API reference](https://titan-exchange.gitbook.io/titan/developer-doc/swap-api/reference). Titan's [DART overview](https://titan-exchange.gitbook.io/titan/developer-doc/dart-swap-api/overview) documents a standalone DART API with its own endpoint, separate from `/titan`. The example uses the TypeScript SDK, [@titanexchange/sdk-ts](https://www.npmjs.com/package/@titanexchange/sdk-ts).

Triton's launch post, [Titan Prime API for Solana Swaps on Triton](https://blog.triton.one/titan-prime-api-for-solana-swaps-is-live-on-triton/), covers the service under the name Titan Prime and its WebSocket quote streaming. The post's launch pricing no longer applies; see [pricing](https://triton.one/pricing).

## Pricing

Titan is billed on bandwidth, including polls. See [pricing](https://triton.one/pricing).

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Jito Bundle Simulation

Test Jito bundles with simulateBundle on Triton's Jito-enabled RPC before you send them with sendBundle to the Jito Block Engine.

Triton supports Jito's `simulateBundle` method on every plan, so you can test atomic transaction bundles on a Jito-enabled RPC before submitting them. For more information, see the [Jito searcher examples](https://github.com/jito-labs/searcher-examples) and [Jito's low-latency transactions documentation](https://docs.jito.wtf/lowlatencytxnsend).

{% hint style="warning" %}
**Triton simulates Jito bundles but does not forward them.** `simulateBundle` runs on Triton's Jito-enabled RPC nodes. Submitting a bundle for inclusion uses `sendBundle`, a Jito-exclusive call that needs a direct, active connection to the Jito Block Engine.
{% endhint %}

## simulateBundle

Simulates a bundle of signed transactions against one bank and returns a result for each transaction. Send it as a JSON-RPC `POST` to your Triton endpoint.

### Parameters

| Position               | Type   | Description                                                                                                                                                              |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `params[0]` (required) | object | `{ "encodedTransactions": [...] }`: the bundle, up to 20 signed transactions, each base64-encoded. Duplicate transactions are rejected.                                  |
| `params[1]`            | object | Optional `RpcSimulateBundleConfig` controlling the simulation. If you pass it, `preExecutionAccountsConfigs` and `postExecutionAccountsConfigs` are required. See below. |

### Example request

```bash
curl https://<your-endpoint>.mainnet.rpcpool.com/<your-token> -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "simulateBundle",
    "params": [
      { "encodedTransactions": ["BASE64_SIGNED_TX_1", "BASE64_SIGNED_TX_2"] },
      {
        "preExecutionAccountsConfigs": [null, null],
        "postExecutionAccountsConfigs": [null, { "addresses": ["ACCOUNT_ADDRESS"] }]
      }
    ]
  }'
```

Each entry in `preExecutionAccountsConfigs` and `postExecutionAccountsConfigs` belongs to the transaction at the same position: `null` returns no accounts for it, and `{ "addresses": [...] }` returns those accounts' state before or after it runs, base64-encoded.

### Response

The JSON-RPC `result` is `{ "context": { "slot": ... }, "value": ... }`, where `value` matches this Rust struct. JSON field names are camelCase (for example `transactionResults` and `unitsConsumed`), and `summary` is either `"succeeded"` or `{ "failed": { "error": ..., "tx_signature": ... } }`.

```rust
pub struct RpcSimulateBundleResult {
    pub summary: RpcBundleSimulationSummary,
    pub transaction_results: Vec<RpcSimulateBundleTransactionResult>,
}

pub enum RpcBundleSimulationSummary {
    // Error and offending transaction signature, if applicable.
    Failed {
        error: RpcBundleExecutionError,
        tx_signature: Option<String>,
    },
    Succeeded,
}

pub struct RpcSimulateBundleTransactionResult {
    pub err: Option<TransactionError>,
    pub logs: Option<Vec<String>>,
    pub pre_execution_accounts: Option<Vec<UiAccount>>,
    pub post_execution_accounts: Option<Vec<UiAccount>>,
    pub units_consumed: Option<u64>,
    pub loaded_accounts_data_size: Option<u32>,
    pub return_data: Option<UiTransactionReturnData>,
    // Set when replace_recent_blockhash is true: the blockhash the simulation used.
    pub replacement_blockhash: Option<RpcBlockhash>,
    pub fee: Option<u64>,
    pub pre_balances: Option<Vec<u64>>,
    pub post_balances: Option<Vec<u64>>,
    pub pre_token_balances: Option<Vec<UiTransactionTokenBalance>>,
    pub post_token_balances: Option<Vec<UiTransactionTokenBalance>>,
    pub loaded_addresses: Option<UiLoadedAddresses>,
}
```

<details>

<summary>RpcBundleExecutionError variants</summary>

```rust
pub enum RpcBundleExecutionError {
    BankProcessingTimeLimitReached,         // hit the max allotted processing time
    BundleLockError,                        // a transaction is malformed
    BundleExecutionTimeout,                 // bundle execution timed out
    ExceedsCostModel,                       // the bundle exceeds the cost model
    InvalidPreOrPostAccounts,               // invalid pre or post accounts
    PohRecordError(String),
    TipError(String),
    TransactionFailure(Signature, String),  // a transaction failed to execute
}
```

</details>

<details>

<summary>RpcSimulateBundleConfig</summary>

```rust
pub struct RpcSimulateBundleConfig {
    // Accounts to return before/after each transaction runs: one entry (or null) per
    // transaction. Required whenever you pass a config.
    pub pre_execution_accounts_configs: Vec<Option<RpcSimulateTransactionAccountsConfig>>,
    pub post_execution_accounts_configs: Vec<Option<RpcSimulateTransactionAccountsConfig>>,
    // Encoding of the contained transactions. Only base64 is accepted.
    pub transaction_encoding: Option<UiTransactionEncoding>,
    // Which bank to simulate against. Default: confirmed commitment.
    pub simulation_bank: Option<SimulationSlotConfig>,
    // Skip sig-verify for faster performance. Default: false.
    pub skip_sig_verify: bool,
    // Replace the recent blockhash to simulate old transactions without re-signing.
    // Requires skip_sig_verify: true. Default: false.
    pub replace_recent_blockhash: bool,
}

pub struct RpcSimulateTransactionAccountsConfig {
    pub encoding: Option<UiAccountEncoding>, // base64 only
    pub addresses: Vec<String>,
}
```

`simulationBank` accepts `{ "commitment": { "commitment": "processed" } }` (any commitment level), `{ "slot": <slot> }` for a specific slot's bank, or `"tip"` for the RPC's highest slot, the working bank.

</details>

## Billing

Simulating bundles on Triton's Jito-enabled RPC is billed as standard RPC. Current rates are on the [pricing page](https://triton.one/pricing). Submitting a bundle goes directly to the Jito Block Engine and is not billed by Triton.

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-play">:play:</i> <strong>Quickstart</strong></td><td>Send a transaction via Triton endpoints in a few minutes.</td><td><a href="https://docs.triton.one/solana/sending-transactions/quickstart">Sending transactions quickstart</a></td></tr><tr><td><i class="fa-list-check">:list-check:</i> <strong>Best practices</strong></td><td>Land your transactions fast and reliably.</td><td><a href="https://docs.triton.one/solana/sending-transactions/best-practices">Sending transactions best practices</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Sending transactions best practices

How to land Solana transactions under congestion: blockhash, compute budget, SWQoS, priority fees, skipPreflight, retries, /sendtx, and 429 handling.

## Build and sign correctly

* **Use a recent blockhash from `confirmed` or `finalized` commitment.** Never use `processed` for blockhashes.
* **Set a tight compute-unit budget.** The default is often too high; an accurate budget helps validators pack your transaction (a simple SOL transfer uses 150 CUs, or 450 with the two compute-budget instructions). See [How to Optimize Compute Requested](https://solana.com/developers/cookbook/transactions/optimize-compute) on solana.com.

## Leverage priority lanes

* **Send over a staked connection for higher landing rates.** SWQoS is on by default for mainnet sends. Devnet sends are not staked.
* **Pass the `percentile` parameter into `getRecentPrioritizationFees`** (an integer 1 to 10,000, where `5000` is the median) to get a competitive market rate.
* **Pass the accounts your transaction write-locks** as the first parameter to get fees for those accounts. See [Priority fees API](https://docs.triton.one/solana/sending-transactions/priority-fees-api).

## Simulate, then send without preflight

* **Simulate with `simulateTransaction()`, then send with `skipPreflight: true`.** With `skipPreflight: false`, Triton runs the preflight simulation as a separate, blocking step before it forwards your send and fails the send if that simulation can't run.

## Handle retries yourself

{% hint style="warning" %}
**Don't rely on server-side retries.** `maxRetries` has no effect on Triton, and Triton doesn't keep rebroadcasting a transaction until it lands.
{% endhint %}

{% stepper %}
{% step %}

### Rebroadcast the same signed transaction

Rebroadcast it every couple of seconds until it confirms or its blockhash expires. Resending identical bytes is safe: the network processes the same transaction at most once.
{% endstep %}

{% step %}

### Track expiry by block height, not time

Keep the `lastValidBlockHeight` that `getLatestBlockhash` returns with your blockhash. The highest block height the transaction can land at is `lastValidBlockHeight + 1`.
{% endstep %}

{% step %}

### Wait for the original to expire before you re-sign

{% hint style="danger" %}
A transaction re-signed with a new blockhash is a different transaction, so if the original still lands, both execute.
{% endhint %}

Before you re-sign, check that `getBlockHeight` (at the commitment you fetched the blockhash with) is above `lastValidBlockHeight` and that `getSignatureStatuses` shows the original didn't land.
{% endstep %}
{% endstepper %}

## Use `/sendtx` for latency-sensitive sends

* **Prefer `POST /sendtx` over JSON-RPC `sendTransaction` when latency matters.** It skips the JSON-RPC envelope and JSON parsing. It submits transactions; simulate through the normal RPC interface.
* **Send with `Content-Type: application/octet-stream` or `text/plain`** (raw bytes or text).
* **In browsers, a `text/plain` body skips the preflight `OPTIONS` round-trip.** Use base58, or base64 with `encoding=base64`. Raw bytes and the `Solana-ForwardingPolicies` header (see [Shield Protection](https://docs.triton.one/solana/sending-transactions/shield-mev-protection)) trigger one.
* **Don't rely on `max_retries`.** `/sendtx` accepts it, but it has no effect. Rebroadcast the same signed bytes from your client until the transaction confirms or its blockhash expires.
* **Track signatures client-side.** The signature is deterministic and derivable before sending.

## Confirm the landing

* **Treat a transaction as landed at `confirmed` or `finalized`.** A `processed` transaction can still be dropped during minority forks or congestion.

## Protect transactions with Shield

* **Restrict which validators receive your transactions** with Yellowstone Shield. See [Shield Protection](https://docs.triton.one/solana/sending-transactions/shield-mev-protection).

## Simulate Jito bundles on Triton

* **Test bundles on mainnet with `simulateBundle`.** See [Jito Bundle Simulation](https://docs.triton.one/solana/sending-transactions/3rd-party-apis/jito-bundles).

## Stay within limits and reuse connections

* **On HTTP `429`, wait the `Retry-After` time before you retry** (10 seconds for request-rate and connection-rate limits). See [Handle 429 rate-limit errors](https://docs.triton.one/solana/faq/error-handling/handle-429-rate-limit-errors) and [Rate and connection limits](https://docs.triton.one/using-your-endpoint/rate-and-connection-limits).
* **Keep `sendTransaction` under its cap.** On new Solana mainnet shared subscriptions, it's 2,000 requests per 10 seconds per IP, and `/sendtx` has its own counter at the same cap. See [Solana per-method limits](https://docs.triton.one/using-your-endpoint/rate-and-connection-limits#solana-per-method-limits).
* **For high-throughput senders, reuse keep-alive connections** (a global undici `Agent` or `https.Agent`) instead of opening a new connection for every send, to avoid ephemeral-port exhaustion.

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Solana dedicated nodes

Single-tenant bare-metal Solana nodes for Dragon's Mouth gRPC streaming: when to choose dedicated over shared, regions, ordering, and billing.

Dedicated nodes give you isolated capacity for gRPC streaming, with no noisy neighbors. The monthly price of a standard node includes Dragon's Mouth gRPC streaming. Other services, including WebSocket, are billed separately, per usage.

On request, we can also provision other single-purpose clusters (for example, a dedicated DAS or a custom indexing cluster) or enable Geyser plugins. Mixed-purpose nodes (e.g. JSON-RPC + gRPC streaming) are not offered.

## Use cases

* **Sustained gRPC streaming** at high volume, where a fixed price is a priority.
* **Heavy indexing workloads** (DAS/History, on request) that require full, uncontended throughput.
* **Latency-sensitive backends** that require colocation with the data source for predictable speed and low jitter.

{% hint style="warning" %}
Don't use it for front-ends, dashboards, or standard JSON-RPC reads. Use shared infrastructure endpoints for these workloads.
{% endhint %}

## Features and benefits

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-gauge-high">:gauge-high:</i> <strong>Custom rate limits</strong></td><td>We can customize your rate limits to suit your workload. Contact support to review them.</td><td></td></tr><tr><td><i class="fa-globe">:globe:</i> <strong>Your choice of region</strong></td><td>North America, Europe, or Asia Pacific, so you can colocate your backend next to the node.</td><td></td></tr><tr><td><i class="fa-user-shield">:user-shield:</i> <strong>Logging-policy control</strong></td><td>Pick the logging policy your legal or privacy requirements demand: Max Privacy, Enhanced Privacy (default), or GDPR Privacy.</td><td></td></tr><tr><td><i class="fa-arrows-rotate">:arrows-rotate:</i> <strong>Automatic failover</strong></td><td>If your node goes down, traffic fails over to shared backup nodes by default. Reconnect your gRPC client to resume the stream, and again when your node returns.</td><td></td></tr></tbody></table>

## Shared vs dedicated

|                  | Shared infrastructure                                                                                                               | Dedicated node                                                                                                                                               |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Tenancy          | Multi-tenant                                                                                                                        | Single-tenant, bare metal                                                                                                                                    |
| Geo-distribution | On standard mainnet endpoints: 8 cities on 3 continents, routed to the nearest in network terms via Anycast                         | One region of your choice: North America, Europe, or Asia Pacific                                                                                            |
| Auto-failover    | Yes, across data centers                                                                                                            | Yes, to shared backup nodes by default. Reconnect your stream                                                                                                |
| Rate limits      | Flexible, adjustable on request. Rate limits do not affect pricing                                                                  | Can be customized for your workload. Contact support to review them                                                                                          |
| Billing          | Pay-as-you-go (prepaid deposit, valid 12 months, usable across all services) or invoiced. See [pricing](https://triton.one/pricing) | Fixed monthly price per node. Includes Dragon's Mouth gRPC streaming with no overage fees. WebSocket, Fumarole and JSON-RPC are billed separately, per usage |
| JSON-RPC reads   | Served by shared RPC backends                                                                                                       | Routed to the shared cluster and billed separately, per usage                                                                                                |
| WebSocket        | Served by shared WebSocket servers                                                                                                  | Served by shared WebSocket servers by default                                                                                                                |

Compare your monthly streaming cost with a node's fixed price on the [pricing page](https://triton.one/pricing). For how shared and dedicated billing works, see [Plans and billing](https://docs.triton.one/account-and-billing/plans-and-billing#shared-or-dedicated).

{% hint style="info" %}
Pair a dedicated node with shared endpoints: dedicated for gRPC streaming, shared for JSON-RPC and transaction sending.
{% endhint %}

## Getting started

{% stepper %}
{% step %}

### Talk to us

Reach out through [contact sales](https://triton.one/contact), and we'll talk through your options with you.

<a href="https://triton.one/contact" class="button primary" data-icon="briefcase">Contact sales</a>
{% endstep %}

{% step %}

### Scope your node

After learning your streaming volume and preferred region, we'll agree on the specs and the number of nodes to deploy.
{% endstep %}

{% step %}

### Provisioning

Hardware is ordered to spec and set up as a dedicated subscription in your [customer dashboard](https://customers.triton.one).
{% endstep %}

{% step %}

### Connect

Your node has its own endpoint, listed in the [customer dashboard](https://customers.triton.one), for example `https://<your-endpoint>.mainnet.rpcpool.com`. Point your gRPC client at it, and you're good to go!
{% endstep %}
{% endstepper %}

## Best practices

* **Put your Dragon's Mouth gRPC traffic on the dedicated endpoint.** gRPC streams on a shared endpoint are metered, which defeats the point of a fixed-price node.
* **Run your backend close to the node.** gRPC streams are backend-to-backend, so keeping both in the same region reduces latency.
* **Filter to cut volume.** Server-side filters (skip votes, restrict to the accounts and programs you care about) reduce the bandwidth you pull and help you stay on the chain tip under load. See [streaming best practices](https://docs.triton.one/solana/real-time-streaming/best-practices).

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-radio">:radio:</i> <strong>Dragon's Mouth gRPC</strong></td><td>Sub-slot real-time updates for accounts, transactions, slots, and blocks via gRPC.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc">Dragon's Mouth gRPC</a></td></tr><tr><td><i class="fa-list-check">:list-check:</i> <strong>Best practices</strong></td><td>Filtering, reconnect, and commitment guidance across the streaming services.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/best-practices">Real-time streaming best practices</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Solana 2.0 removed RPC methods

Which JSON-RPC methods Solana 2.0 removed, such as getConfirmedBlock and getRecentBlockhash, and the replacement method to call for each.

If your application calls one of these methods and gets an error, use the replacement:

* `confirmTransaction` → `getSignatureStatuses`
* `getSignatureStatus` → `getSignatureStatuses`
* `getSignatureConfirmation` → `getSignatureStatuses`
* `getConfirmedSignaturesForAddress` → `getSignaturesForAddress`
* `getConfirmedSignaturesForAddress2` → `getSignaturesForAddress`
* `getConfirmedBlock` → `getBlock`
* `getConfirmedBlocks` → `getBlocks`
* `getConfirmedBlocksWithLimit` → `getBlocksWithLimit`
* `getConfirmedTransaction` → `getTransaction`
* `getRecentBlockhash` → `getLatestBlockhash`
* `getFees` → `getFeeForMessage`
* `getFeeCalculatorForBlockhash` → `isBlockhashValid` or `getFeeForMessage`
* `getSnapshotSlot` → `getHighestSnapshotSlot`
* `getTotalSupply` → `getSupply`
* `getStakeActivation` → use `getAccountInfo` (see this [Solana Stack Exchange question](https://solana.stackexchange.com/questions/15710) for the approach)
* `getFeeRateGovernor` → `getFeeForMessage`

For the full technical details, see the [Anza Agave v2.0 Transition Guide](https://github.com/anza-xyz/agave/wiki/Agave-v2.0-Transition-Guide).

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Solana quickstart

Get your endpoint sending requests, then pick your next step by product or use case.

Just got your endpoint? This is a good place to start. You'll send your first RPC request, then pick where to go next based on what you're building.

{% stepper %}
{% step %}

### Sign up and make the minimum deposit

Sign up at [customers.triton.one](https://customers.triton.one/onboarding), verify your email, and top up the minimum deposit in USDC. The amount is on the [pricing page](https://triton.one/pricing).
{% endstep %}

{% step %}

### Set up an endpoint

Your endpoints are created at sign-up. If you didn't enter a domain, they start inactive: turn yours on with its switch under **Endpoints**. In the dashboard, open the **Solana Mainnet** subscription (or devnet for testing).

<div data-with-frame="true"><figure><img src="https://3518146065-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ8kil7uF8hL6v3a3hZf%2Fuploads%2Fgit-blob-9b6d9a536488a0cb85d4f56db0212cb693590dfa%2F02-home-subscriptions.png?alt=media" alt="Customer dashboard Home page, Subscriptions table. Callout 1 marks the subscription name. Callout 2 marks the Type column, for example Solana Mainnet." width="563"><figcaption><p>1: click the subscription name. 2: check its <strong>Type</strong>.</p></figcaption></figure></div>

Copy the two things you'll use everywhere:

* **Endpoint URL**: the hostname under **Endpoints**, such as `<your-endpoint>.mainnet.rpcpool.com`
* **Secret token**: under **RPC / gRPC Tokens**, click the token and copy **Secret token**

Keep the token server-side only. Frontend code uses an origin allowlist instead. See [Auth and security](https://docs.triton.one/security/authentication).
{% endstep %}

{% step %}

### Send your first request

Call `getSlot` to confirm the endpoint is live. Pick your stack:

{% tabs %}
{% tab title="curl" %}

```bash
curl "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSlot"}'
```

{% endtab %}

{% tab title="TypeScript" %}

```javascript
import { createSolanaRpc } from "@solana/kit";

const rpc = createSolanaRpc("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>");
const slot = await rpc.getSlot().send();
console.log(slot);
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

r = requests.post(
    'https://<your-endpoint>.mainnet.rpcpool.com/<your-token>',
    json={'jsonrpc': '2.0', 'id': 1, 'method': 'getSlot'},
)
print(r.json()['result'])
```

{% endtab %}

{% tab title="Rust" %}

```rust
use solana_client::rpc_client::RpcClient;

let client = RpcClient::new(
    "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>".to_string(),
);
println!("{}", client.get_slot()?);
```

{% endtab %}
{% endtabs %}

### Expected response

A current slot number means you're connected:

```json
{ "jsonrpc": "2.0", "result": 311340987, "id": 1 }
```

Hitting a 401, 429, timeout, or gRPC 403? See [Error handling](https://docs.triton.one/solana/faq/error-handling) for the full debug flow.
{% endstep %}
{% endstepper %}

## What's next

Two ways in. Pick the tab that fits.

{% tabs %}
{% tab title="By product (I know what I want)" %}
Each product is purpose-built for one job. Pick the category, then the product.

{% tabs %}
{% tab title="Reading state" %}

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-bolt">:bolt:</i> <strong>Standard RPC</strong></td><td>Solana JSON-RPC over HTTPS. Standard methods, served from the regional fleet.</td><td><a href="https://docs.triton.one/solana/reading-account-state">Reading account state</a></td></tr><tr><td><i class="fa-database">:database:</i> <strong>Cloudbreak Accounts</strong></td><td>Fast account and token queries from tailored dynamic indexes and hot paths.</td><td><a href="https://docs.triton.one/solana/reading-account-state/cloudbreak-indexed-accounts">Cloudbreak Accounts</a></td></tr><tr><td><i class="fa-image">:image:</i> <strong>Metaplex DAS API</strong></td><td>Query NFTs, tokens, and compressed assets via the Digital Asset Standard interface.</td><td><a href="https://docs.triton.one/solana/reading-account-state/metaplex-das-api">Metaplex DAS API</a></td></tr><tr><td><i class="fa-arrows-rotate">:arrows-rotate:</i> <strong>Account Sync</strong></td><td>Streaming-backed local cache for faster and cheaper account reads, via the Triton TypeScript and Rust SDKs.</td><td><a href="https://docs.triton.one/solana/reading-account-state/account-sync">Account Sync</a></td></tr></tbody></table>
{% endtab %}

{% tab title="Streaming" %}

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-tower-broadcast">:tower-broadcast:</i> <strong>Dragon's Mouth gRPC</strong></td><td>Sub-slot real-time updates for accounts, transactions, slots, and blocks via gRPC.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc">Dragon's Mouth gRPC</a></td></tr><tr><td><i class="fa-rotate-right">:rotate-right:</i> <strong>WebSocket</strong></td><td>Triton's Solana WebSocket API for browsers and frontends, served from Dragon's Mouth gRPC, with <code>transactionSubscribe</code>.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/whirligig-websockets">WebSocket</a></td></tr><tr><td><i class="fa-layer-group">:layer-group:</i> <strong>Fumarole Persistent gRPC</strong></td><td>Redundant streaming layer with 4 days of stored data and built-in cursor resume.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/fumarole-persistent-streams">Fumarole Persistent gRPC</a></td></tr></tbody></table>
{% endtab %}

{% tab title="History" %}

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-box-archive">:box-archive:</i> <strong>Superbank</strong></td><td>The full Solana ledger from genesis over standard JSON-RPC, plus getTransactionsForAddress, which returns an address's transactions with filters and a pagination cursor in place of getSignaturesForAddress plus getTransaction.</td><td><a href="https://docs.triton.one/solana/historical-data#how-it-works">Historical data</a></td></tr></tbody></table>
{% endtab %}

{% tab title="Sending transactions" %}

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-paper-plane">:paper-plane:</i> <strong>Jet TPU client</strong></td><td>End-to-end integration guide: direct-to-leader forwarding over QUIC with leader scheduling, connection pooling, and retries built in.</td><td><a href="https://docs.triton.one/solana/quickstart/sending-transactions/yellowstone-jet-tpu-client">Yellowstone Jet TPU client</a></td></tr><tr><td><i class="fa-arrow-trend-up">:arrow-trend-up:</i> <strong>Priority Fees API</strong></td><td>Smart fee estimation with tail-aware percentiles. Reliable landing without overpaying.</td><td><a href="https://docs.triton.one/solana/sending-transactions/priority-fees-api">Priority fees API</a></td></tr><tr><td><i class="fa-route">:route:</i> <strong>Titan Swap API</strong></td><td>Live swap quotes and executable routes streamed over WebSocket, with DART on-chain re-optimisation on selected pairs.</td><td><a href="https://docs.triton.one/solana/sending-transactions/3rd-party-apis/titan-swap-api">Titan Swap API</a></td></tr><tr><td><i class="fa-box">:box:</i> <strong>Jito Bundle Simulation</strong></td><td>Jito Bundle Simulation through Triton endpoints. Test bundle ordering before submitting.</td><td><a href="https://docs.triton.one/solana/sending-transactions/3rd-party-apis/jito-bundles">Jito Bundle Simulation</a></td></tr></tbody></table>
{% endtab %}

{% tab title="Dedicated nodes" %}

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-server">:server:</i> <strong>Dedicated gRPC node</strong></td><td>Private node with isolated CPU and its own rate and connection limits. For latency-sensitive or heavy streaming workloads.</td><td><a href="https://docs.triton.one/solana/dedicated-nodes">Solana dedicated nodes</a></td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="By use case (I know what I’m building)" %}
Pick the kind of app you're building. Each card jumps to the matching setup guide.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-coins">:coins:</i> <strong>Trading or market making</strong></td><td>Live prices, direct-to-leader sending, anti-MEV. Stack: Dragon's Mouth, Deshred, Priority Fees, Jet, Shield.</td><td><a href="https://docs.triton.one/solana/quickstart/use-cases/trading-and-market-making">Trading and market making</a></td></tr><tr><td><i class="fa-mobile-screen">:mobile-screen:</i> <strong>Wallet or consumer app</strong></td><td>Balances, history, live updates, and sending SOL and SPL tokens. Stack: Standard RPC, Dragon's Mouth, Priority Fees, Jet.</td><td><a href="https://docs.triton.one/solana/quickstart/use-cases/building-a-wallet">Building a wallet</a></td></tr></tbody></table>
{% endtab %}
{% endtabs %}

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Use cases

Complete RPC, streaming and advanced API integration guides for common Solana applications.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-arrow-trend-up">:arrow-trend-up:</i> <strong>Trading and market making</strong></td><td>Connect to real-time DEX data, get transactions before execution with Deshred, price priority fees, and send transactions through Jet.</td><td><a href="https://docs.triton.one/solana/quickstart/use-cases/trading-and-market-making">Trading and market making</a></td></tr><tr><td><i class="fa-wallet">:wallet:</i> <strong>Building a wallet</strong></td><td>Fetch balances, stream account changes with Dragon's Mouth, pull history, and send SOL and SPL tokens through Jet.</td><td><a href="https://docs.triton.one/solana/quickstart/use-cases/building-a-wallet">Building a wallet</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Trading and market making

Build the full data and transaction stack for a Solana trading or market-making bot.

End-to-end stack for a market-making or trading bot on Solana: real-time DEX data, the earliest Dragon's Mouth signal, priority fees, reliable transaction landing.

## Overview

This guide walks you through setting up Triton's trading infrastructure stack for a market-making or trading bot on Solana. You'll connect to real-time DEX data, get transactions before execution with Deshred, estimate competitive priority fees, and land transactions reliably under congestion.

By the end you'll have a working setup that covers the full path from signal to fill.

## Products used in this guide

Five Triton products work together in this stack. Each card below opens the full product docs, useful when you want to tune defaults, see every option, or troubleshoot something specific to that product.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-radio">:radio:</i> <strong>Dragon's Mouth</strong></td><td>Subscribe to DEX pool account updates and transactions in real time.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc">Dragon's Mouth gRPC</a></td></tr><tr><td><i class="fa-fire">:fire:</i> <strong>Deshred</strong></td><td>Receive transactions from shreds before execution for the earliest signal.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/deshred-transactions">Deshred Transactions gRPC</a></td></tr><tr><td><i class="fa-arrow-trend-up">:arrow-trend-up:</i> <strong>Priority Fee API</strong></td><td>Get a percentile-based fee estimate before building your transaction.</td><td><a href="https://docs.triton.one/solana/sending-transactions/priority-fees-api">Priority fees API</a></td></tr><tr><td><i class="fa-paper-plane">:paper-plane:</i> <strong>Jet</strong></td><td>Send transactions directly to the current leader with built-in SWQoS.</td><td><a href="https://docs.triton.one/solana/sending-transactions">Sending transactions</a></td></tr><tr><td><i class="fa-shield">:shield:</i> <strong>Shield</strong></td><td>(Optional) Block specific validators from processing your transactions.</td><td><a href="https://docs.triton.one/solana/sending-transactions/shield-mev-protection">Shield Protection</a></td></tr></tbody></table>

## Prerequisites

{% stepper %}
{% step %}

#### A Triton account with an active endpoint

You'll need your **endpoint URL** and **token** from the [customer dashboard](https://customers.triton.one).
{% endstep %}

{% step %}

#### Basic familiarity with Solana

Accounts, transactions, compute units.
{% endstep %}
{% endstepper %}

## Step 0: Install the dependencies

{% tabs %}
{% tab title="TypeScript" %}

```bash
npm install @triton-one/yellowstone-grpc bs58 @solana/web3.js@1
```

{% hint style="info" %}
In an ES module project (`"type": "module"`) that TypeScript checks with `"module": "nodenext"`, `new Client(...)` from `@triton-one/yellowstone-grpc` fails type-checking with TS2351 ("This expression is not constructable"). The code still runs. To type-check it, use a CommonJS project or `"moduleResolution": "bundler"`.
{% endhint %}
{% endtab %}

{% tab title="Rust" %}
{% code title="Cargo.toml" %}

```toml
[dependencies]
yellowstone-grpc-client = "17"
yellowstone-grpc-proto = "14"
tokio = { version = "1", features = ["full"] }
futures = "0.3"
bs58 = "0.5"
anyhow = "1"
reqwest = { version = "0.12", features = ["json"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
solana-client = "2"
solana-sdk = "2"
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}

```bash
pip install grpcio grpcio-tools base58 solana httpx

# Generate yellowstone gRPC stubs. Save geyser.proto and solana-storage.proto into ./proto
# (geyser.proto imports solana-storage.proto, so compile both):
# python -m grpc_tools.protoc -I./proto --python_out=. --grpc_python_out=. geyser.proto solana-storage.proto
# Proto files: https://github.com/rpcpool/yellowstone-grpc/tree/master/yellowstone-grpc-proto/proto
```

{% endtab %}
{% endtabs %}

## Step 1: Stream real-time DEX data with Dragon's Mouth

Dragon's Mouth delivers account and transaction updates as the node processes them, at processed commitment. For a trading bot you'll subscribe to the pool accounts and transactions of the DEX programs you're trading on.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import Client, {
  CommitmentLevel,
  SubscribeRequest,
} from "@triton-one/yellowstone-grpc";
import bs58 from "bs58";

const ENDPOINT = "https://<your-endpoint>.mainnet.rpcpool.com";
const TOKEN = "<your-token>";

// Raydium AMM v4 program, replace with the DEX program you're trading
const RAYDIUM_AMM = "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8";

async function streamDexData() {
  const client = new Client(ENDPOINT, TOKEN, {});
  await client.connect();
  const stream = await client.subscribe();

  const request: SubscribeRequest = {
    accounts: {
      pool_accounts: {
        account: [],
        owner: [RAYDIUM_AMM],
        filters: [],
      },
    },
    transactions: {
      dex_transactions: {
        vote: false,
        failed: false,
        accountInclude: [RAYDIUM_AMM],
        accountExclude: [],
        accountRequired: [],
      },
    },
    slots: {},
    transactionsStatus: {},
    entry: {},
    blocks: {},
    blocksMeta: {},
    blockFooter: {},
    commitment: CommitmentLevel.PROCESSED,
    accountsDataSlice: [],
    ping: undefined,
  };

  stream.on("data", (data) => {
    if (data.account) {
      const pubkey = bs58.encode(data.account.account!.pubkey);
      console.log("Pool state updated:", pubkey);
      // Decode and act on the account data here
    }

    if (data.transaction) {
      const sig = bs58.encode(data.transaction.transaction!.signature);
      console.log("Transaction processed:", sig);
      // Parse the transaction and look for arbitrage / copy-trade signals
    }
  });

  stream.on("error", (err) => {
    console.error("Stream error:", err);
  });

  await new Promise<void>((resolve, reject) => {
    stream.write(request, (err) => {
      if (err) reject(err);
      else resolve();
    });
  });

  // Keep stream alive with periodic pings
  setInterval(() => {
    stream.write({ ping: { id: 1 } } as SubscribeRequest, () => {});
  }, 30_000);
}

streamDexData().catch(console.error);
```

{% endtab %}

{% tab title="Rust" %}

```rust
use std::collections::HashMap;
use futures::StreamExt;
use yellowstone_grpc_client::{ClientTlsConfig, GeyserGrpcClient};
use yellowstone_grpc_proto::prelude::{
    subscribe_update::UpdateOneof, CommitmentLevel, SubscribeRequest,
    SubscribeRequestFilterAccounts, SubscribeRequestFilterTransactions,
};

const ENDPOINT: &str = "https://<your-endpoint>.mainnet.rpcpool.com";
const TOKEN: &str = "<your-token>";
const RAYDIUM_AMM: &str = "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8";

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut client = GeyserGrpcClient::build_from_shared(ENDPOINT.to_string())?
        .x_token(Some(TOKEN.to_string()))?
        .tls_config(ClientTlsConfig::new().with_native_roots())?
        .connect()
        .await?;

    let mut accounts = HashMap::new();
    accounts.insert(
        "pool_accounts".to_string(),
        SubscribeRequestFilterAccounts {
            owner: vec![RAYDIUM_AMM.to_string()],
            ..Default::default()
        },
    );

    let mut transactions = HashMap::new();
    transactions.insert(
        "dex_transactions".to_string(),
        SubscribeRequestFilterTransactions {
            vote: Some(false),
            failed: Some(false),
            account_include: vec![RAYDIUM_AMM.to_string()],
            ..Default::default()
        },
    );

    let request = SubscribeRequest {
        accounts,
        transactions,
        commitment: Some(CommitmentLevel::Processed as i32),
        ..Default::default()
    };

    let (_tx, mut stream) = client.subscribe_with_request(Some(request)).await?;

    while let Some(Ok(msg)) = stream.next().await {
        match msg.update_oneof {
            Some(UpdateOneof::Account(acct)) => {
                let pubkey = bs58::encode(acct.account.unwrap().pubkey).into_string();
                println!("Pool state updated: {pubkey}");
            }
            Some(UpdateOneof::Transaction(tx)) => {
                let sig = bs58::encode(tx.transaction.unwrap().signature).into_string();
                println!("Transaction processed: {sig}");
            }
            _ => {}
        }
    }

    Ok(())
}
```

{% endtab %}

{% tab title="Python" %}

```python
import asyncio
import grpc
from grpc import aio
import base58

# Requires yellowstone gRPC Python stubs generated from the proto files.
# After running grpc_tools.protoc (see Step 0), the output includes geyser_pb2.py,
# geyser_pb2_grpc.py and solana_storage_pb2.py in whatever --python_out directory you
# specified. Adjust the imports if you placed them inside a package folder.
from geyser_pb2 import (
    SubscribeRequest,
    SubscribeRequestFilterAccounts,
    SubscribeRequestFilterTransactions,
    CommitmentLevel,
    SubscribeRequestPing,
)
from geyser_pb2_grpc import GeyserStub

ENDPOINT = "<your-endpoint>.mainnet.rpcpool.com:443"
TOKEN = "<your-token>"
RAYDIUM_AMM = "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8"

async def stream_dex_data():
    credentials = grpc.ssl_channel_credentials()
    async with aio.secure_channel(ENDPOINT, credentials) as channel:
        stub = GeyserStub(channel)
        metadata = (("x-token", TOKEN),)

        async def request_iterator():
            yield SubscribeRequest(
                accounts={
                    "pool_accounts": SubscribeRequestFilterAccounts(
                        owner=[RAYDIUM_AMM],
                    )
                },
                transactions={
                    "dex_transactions": SubscribeRequestFilterTransactions(
                        vote=False,
                        failed=False,
                        account_include=[RAYDIUM_AMM],
                    )
                },
                commitment=CommitmentLevel.PROCESSED,
            )
            while True:
                await asyncio.sleep(30)
                yield SubscribeRequest(ping=SubscribeRequestPing(id=1))

        async for update in stub.Subscribe(request_iterator(), metadata=metadata):
            if update.HasField("account"):
                pubkey = base58.b58encode(bytes(update.account.account.pubkey)).decode()
                print(f"Pool state updated: {pubkey}")
            elif update.HasField("transaction"):
                sig = base58.b58encode(bytes(update.transaction.transaction.signature)).decode()
                print(f"Transaction processed: {sig}")

asyncio.run(stream_dex_data())
```

{% endtab %}
{% endtabs %}

**Verify it works:** you should see pool state updates and transactions printing to the console within a few seconds of starting the script. If nothing appears, check your endpoint URL and token.

An account update prints something like:

{% code title="Output" %}

```
Pool state updated: 58oQChx4yWmvKdwLLZzBi4ChoCc2fqCUWBkwMihLYQo2
```

{% endcode %}

This is the pool's public key encoded in base58, the standard human-readable format for Solana addresses. The raw pool state (reserves, fees, prices) is in `data.account.account.data` as raw bytes. To use it in your trading logic, decode it against the program's account layout, for example, the Raydium SDK or the program's Anchor IDL.

A transaction update prints:

{% code title="Output" %}

```
Transaction processed: 5Vk5mYDpFq3vQtXm8ZkRj2PnCwBsHeLfY6gNuoA1T9KdEpRsuW3HqXjc...
```

{% endcode %}

The signature is base58-encoded (64 bytes, up to 88 characters). The full transaction is in `data.transaction` as raw protobuf bytes. To decode it into readable JSON for parsing instructions, accounts, and token balance changes:

```typescript
import { txEncode } from "@triton-one/yellowstone-grpc";

const decoded = txEncode.encode(
  data.transaction.transaction!,  // SubscribeUpdateTransactionInfo (not the outer wrapper)
  txEncode.encoding.JsonParsed,
  255,  // max transaction version
  true  // include rewards
);

// decoded.transaction.message.instructions contains the swap instructions
// decoded.meta.preTokenBalances / postTokenBalances shows what changed
console.log(JSON.stringify(decoded, null, 2));
```

## Step 2: Get the earliest signal with Deshred

Deshred reconstructs transactions from shreds before execution, so they usually arrive ahead of the Dragon's Mouth `processed` stream. The lead varies per transaction. It uses a separate RPC method, `SubscribeDeshred`, on the same endpoint and token as Dragon's Mouth.

{% hint style="warning" %}
**Deshred limitations**

* **No execution metadata**: you receive intent only. There are no logs, balance changes, status, or compute unit data.
* **No finality guarantee**: the transaction may fail, get dropped, or land on a dead fork. Always confirm with your Dragon's Mouth `processed` stream.
  {% endhint %}

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import Client, {
  SubscribeRequestFilterDeshredTransactions,
} from "@triton-one/yellowstone-grpc";
import bs58 from "bs58";

const ENDPOINT = "https://<your-endpoint>.mainnet.rpcpool.com";
const TOKEN = "<your-token>";
const RAYDIUM_AMM = "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8";

async function streamDeshred() {
  const client = new Client(ENDPOINT, TOKEN, {});
  await client.connect();
  const stream = await client.subscribeDeshred();

  const request = {
    deshredTransactions: {
      dex: {
        vote: false,
        accountInclude: [RAYDIUM_AMM],
        accountExclude: [],
        accountRequired: [],
      } as SubscribeRequestFilterDeshredTransactions,
    },
  };

  stream.on("data", (data) => {
    if (data.deshredTransaction) {
      const sig = bs58.encode(
        data.deshredTransaction.transaction!.signature
      );
      console.log("Deshred tx (pre-execution):", sig, "slot:", data.deshredTransaction.slot);
    }
  });

  stream.on("error", (err) => {
    console.error("Deshred stream error:", err);
  });

  await new Promise<void>((resolve, reject) => {
    stream.write(request, (err) => {
      if (err) reject(err);
      else resolve();
    });
  });
}

streamDeshred().catch(console.error);
```

{% endtab %}

{% tab title="Rust" %}

```rust
use std::collections::HashMap;
use futures::StreamExt;
use yellowstone_grpc_client::{ClientTlsConfig, GeyserGrpcClient};
use yellowstone_grpc_proto::prelude::{
    subscribe_update_deshred, SubscribeDeshredRequest, SubscribeRequestFilterDeshredTransactions,
};

const ENDPOINT: &str = "https://<your-endpoint>.mainnet.rpcpool.com";
const TOKEN: &str = "<your-token>";
const RAYDIUM_AMM: &str = "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8";

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut client = GeyserGrpcClient::build_from_shared(ENDPOINT.to_string())?
        .x_token(Some(TOKEN.to_string()))?
        .tls_config(ClientTlsConfig::new().with_native_roots())?
        .connect()
        .await?;

    let mut deshred_transactions = HashMap::new();
    deshred_transactions.insert(
        "dex".to_string(),
        SubscribeRequestFilterDeshredTransactions {
            vote: Some(false),
            account_include: vec![RAYDIUM_AMM.to_string()],
            ..Default::default()
        },
    );

    let request = SubscribeDeshredRequest {
        deshred_transactions,
        ..Default::default()
    };

    let (_sink, mut stream) = client.subscribe_deshred_with_request(Some(request)).await?;

    while let Some(Ok(msg)) = stream.next().await {
        if let Some(subscribe_update_deshred::UpdateOneof::DeshredTransaction(deshred_tx)) =
            msg.update_oneof
        {
            let sig = bs58::encode(deshred_tx.transaction.unwrap().signature).into_string();
            println!("Deshred tx (pre-execution): {} slot: {}", sig, deshred_tx.slot);
        }
    }

    Ok(())
}
```

{% endtab %}

{% tab title="Python" %}

```python
import asyncio
import grpc
from grpc import aio
import base58

from geyser_pb2 import (
    SubscribeDeshredRequest,
    SubscribeRequestFilterDeshredTransactions,
    SubscribeRequestPing,
)
from geyser_pb2_grpc import GeyserStub

ENDPOINT = "<your-endpoint>.mainnet.rpcpool.com:443"
TOKEN = "<your-token>"
RAYDIUM_AMM = "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8"

async def stream_deshred():
    credentials = grpc.ssl_channel_credentials()
    async with aio.secure_channel(ENDPOINT, credentials) as channel:
        stub = GeyserStub(channel)
        metadata = (("x-token", TOKEN),)

        async def request_iterator():
            yield SubscribeDeshredRequest(
                deshred_transactions={
                    "dex": SubscribeRequestFilterDeshredTransactions(
                        vote=False,
                        account_include=[RAYDIUM_AMM],
                    )
                }
            )
            while True:
                await asyncio.sleep(30)
                yield SubscribeDeshredRequest(ping=SubscribeRequestPing(id=1))

        async for update in stub.SubscribeDeshred(request_iterator(), metadata=metadata):
            if update.HasField("deshred_transaction"):
                sig = base58.b58encode(
                    bytes(update.deshred_transaction.transaction.signature)
                ).decode()
                print(f"Deshred tx (pre-execution): {sig} slot: {update.deshred_transaction.slot}")

asyncio.run(stream_deshred())
```

{% endtab %}
{% endtabs %}

**Verify it works:** you should see pre-execution transactions printing, usually before they appear in your Dragon's Mouth stream. To measure the lead, see [Deshred Transactions gRPC](https://docs.triton.one/solana/real-time-streaming/deshred-transactions#how-it-works).

{% code title="Output" %}

```
Deshred tx (pre-execution): 5Vk5mYDpFq3vQtXm8ZkRj2PnCwBsHeLfY6gNuoA1T9Kd... slot: 307152834
```

{% endcode %}

The signature is base58-encoded. The transaction data in `data.deshredTransaction.transaction` contains the instructions and account keys, so you can see exactly which pools and wallets are involved, and in which direction. What you **cannot** see: whether it will succeed, what the balance changes will be, or any logs.

Use this signal to detect incoming order flow and react, for example, detecting a large swap into a pool you're quoting. Always cross-reference with your Dragon's Mouth stream to confirm the transaction actually executed.

## Step 3: Estimate a competitive priority fee

Before building your transaction, call Triton's Priority Fee API to get a fee at your target percentile. This avoids both underbidding (transaction doesn't land) and overbidding (unnecessary cost).

{% tabs %}
{% tab title="TypeScript" %}

```typescript
async function getPriorityFee(
  endpoint: string,
  token: string,
  accounts: string[],
  percentile: number // 1-10000, where 5000 = median, 9000 = 90th percentile
): Promise<number> {
  const response = await fetch(`${endpoint}/${token}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: 1,
      method: "getRecentPrioritizationFees",
      params: [accounts, { percentile }],
    }),
  });

  const { result } = await response.json();
  // result is an array of { slot, prioritizationFee }, take the most recent
  const fees: { slot: number; prioritizationFee: number }[] = result;
  const latest = fees.sort((a, b) => b.slot - a.slot)[0];
  return latest.prioritizationFee; // micro-lamports per compute unit
}

// Example: get the 90th percentile fee for a Raydium swap
const fee = await getPriorityFee(ENDPOINT, TOKEN, [RAYDIUM_AMM], 9000);
console.log("Priority fee (90th pct):", fee, "micro-lamports/CU");
```

{% endtab %}

{% tab title="Rust" %}

```rust
use reqwest::Client;
use serde::Deserialize;

#[derive(Deserialize)]
struct PrioritizationFee {
    slot: u64,
    #[serde(rename = "prioritizationFee")]
    prioritization_fee: u64,
}

#[derive(Deserialize)]
struct RpcResponse {
    result: Vec<PrioritizationFee>,
}

async fn get_priority_fee(
    endpoint: &str,
    token: &str,
    accounts: &[&str],
    percentile: u32, // 1-10000, where 5000 = median, 9000 = 90th percentile
) -> anyhow::Result<u64> {
    let client = Client::new();
    let url = format!("{}/{}", endpoint, token);

    let body = serde_json::json!({
        "jsonrpc": "2.0",
        "id": 1,
        "method": "getRecentPrioritizationFees",
        "params": [accounts, { "percentile": percentile }]
    });

    let mut response: RpcResponse = client
        .post(&url)
        .json(&body)
        .send()
        .await?
        .json()
        .await?;

    response.result.sort_by(|a, b| b.slot.cmp(&a.slot));
    Ok(response.result[0].prioritization_fee)
}
```

{% endtab %}

{% tab title="Python" %}

```python
import httpx

async def get_priority_fee(
    endpoint: str,
    token: str,
    accounts: list[str],
    percentile: int,  # 1-10000, where 5000 = median, 9000 = 90th percentile
) -> int:
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{endpoint}/{token}",
            json={
                "jsonrpc": "2.0",
                "id": 1,
                "method": "getRecentPrioritizationFees",
                "params": [accounts, {"percentile": percentile}],
            },
        )
        fees = response.json()["result"]
        fees.sort(key=lambda x: x["slot"], reverse=True)
        return fees[0]["prioritizationFee"]
```

{% endtab %}
{% endtabs %}

**When to use which percentile** (1-10,000, where 5000 = median, 10000 = 100th percentile):

* **Normal conditions:** 5000-7500
* **Congested network or time-sensitive trade:** 9000-9500
* **Emergency / must-land:** 9900+

**Verify it works:** the call should return a non-zero number. During quiet periods fees are low; during congestion they spike significantly.

{% code title="Output" %}

```
Priority fee (90th pct): 45000 micro-lamports/CU
```

{% endcode %}

The fee is in micro-lamports per compute unit. A typical Raydium swap uses \~200,000 to 400,000 compute units, so 45,000 micro-lamports/CU × 300,000 CU ÷ 1,000,000 = 13,500 lamports (\~0.0000135 SOL) total priority fee, a fraction of a cent at current prices.

You can layer your own strategy on top of this (for example, adding a fixed buffer during high-volatility periods), or pass it directly to `setComputeUnitPrice` in Step 4:

```typescript
ComputeBudgetProgram.setComputeUnitPrice({ microLamports: fee })
```

## Step 4: Send your transaction via Jet

Jet is Triton's transaction relay engine. When you send through your Triton endpoint, Jet automatically routes to the current leader over QUIC, handles connection caching, leader schedule tracking, and leader fanout. SWQoS is included for mainnet sends, with no extra configuration.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import {
  Connection,
  ComputeBudgetProgram,
  Transaction,
} from "@solana/web3.js";

async function sendWithJet(
  serializedTransaction: Buffer,
  endpoint: string,
  token: string
): Promise<string> {
  // Use your Triton endpoint, Jet routing is handled automatically
  const connection = new Connection(`${endpoint}/${token}`, "confirmed");

  const signature = await connection.sendRawTransaction(
    serializedTransaction,
    {
      skipPreflight: true, // simulate separately via simulateTransaction() if needed
      maxRetries: 0,       // Triton doesn't retry or rebroadcast server-side, so your client handles retries
    }
  );

  console.log("Sent:", signature);
  return signature;
}

// Add the priority fee from Step 3 to your transaction
function addPriorityFee(tx: Transaction, microLamportsPerCU: number): void {
  tx.add(
    ComputeBudgetProgram.setComputeUnitPrice({
      microLamports: microLamportsPerCU,
    })
  );
}
```

{% endtab %}

{% tab title="Rust" %}

```rust
use solana_client::rpc_client::RpcClient;
use solana_client::rpc_config::RpcSendTransactionConfig;
use solana_sdk::transaction::Transaction;

fn send_with_jet(
    transaction: &Transaction,
    endpoint: &str,
    token: &str,
) -> anyhow::Result<String> {
    let rpc_url = format!("{}/{}", endpoint, token);
    let client = RpcClient::new(rpc_url);

    let signature = client.send_transaction_with_config(
        transaction,
        RpcSendTransactionConfig {
            skip_preflight: true,
            max_retries: Some(0), // Triton doesn't retry or rebroadcast server-side, so your client handles retries
            ..Default::default()
        },
    )?;

    println!("Sent: {}", signature);
    Ok(signature.to_string())
}
```

{% endtab %}

{% tab title="Python" %}

```python
from solana.rpc.async_api import AsyncClient
from solana.rpc.models import TxOpts

async def send_with_jet(serialized_tx: bytes, endpoint: str, token: str) -> str:
    async with AsyncClient(f"{endpoint}/{token}") as client:
        response = await client.send_raw_transaction(
            serialized_tx,
            opts=TxOpts(skip_preflight=True, max_retries=0),
        )
    signature = str(response.value)
    print(f"Sent: {signature}")
    return signature
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Set `maxRetries: 0` (Triton doesn't retry on the server), then rebroadcast from your client: resend the **same signed transaction** every couple of seconds until it confirms or its blockhash expires. Triton sends go through Jet, which doesn't keep a server-side retry queue (unlike Agave's send-transaction-service, whose queue overflows under congestion), so client-managed rebroadcasts are what land your transaction, and they give your strategy direct control.

Don't re-sign with a new blockhash while the original can still land. A re-signed transaction is a different transaction, so if the original lands too, both execute.
{% endhint %}

**Verify it works:** the signature should appear on-chain within 1-3 slots under normal conditions. Check at solscan.io or via `getSignatureStatuses`.

{% code title="Output" %}

```
Sent: 5Vk5mYDpFq3vQtXm8ZkRj2PnCwBsHeLfY6gNuoA1T9KdEpRsuW3HqXjc...
```

{% endcode %}

This is the transaction signature, base58-encoded, up to 88 characters.

**Rebroadcast until it lands or expires.** Keep the `lastValidBlockHeight` from the `getLatestBlockhash` call whose blockhash you signed with, then resend the same bytes until the transaction confirms or the block height passes that value:

```typescript
import { Connection, TransactionSignature } from "@solana/web3.js";

// Resends the same signed bytes until the transaction confirms or its blockhash expires.
// Returns the signature once confirmed, or null if the blockhash expired first.
async function sendUntilConfirmedOrExpired(
  connection: Connection,
  serializedTransaction: Uint8Array,
  lastValidBlockHeight: number // from the getLatestBlockhash call you signed with
): Promise<TransactionSignature | null> {
  const options = { skipPreflight: true, maxRetries: 0 };
  const signature = await connection.sendRawTransaction(serializedTransaction, options);

  while (true) {
    await new Promise((resolve) => setTimeout(resolve, 2000));

    // Read the block height before the status, so an expiry is never reported
    // for a transaction that landed in between.
    const blockHeight = await connection.getBlockHeight("confirmed");
    const { value } = await connection.getSignatureStatuses([signature]);
    const status = value[0];

    if (status?.confirmationStatus === "confirmed" || status?.confirmationStatus === "finalized") {
      if (status.err) throw new Error(`Landed but failed: ${JSON.stringify(status.err)}`);
      return signature;
    }
    if (blockHeight > lastValidBlockHeight) {
      return null; // expired without landing: now it's safe to re-sign with a new blockhash
    }

    // Same bytes, same transaction: the network processes it at most once
    await connection.sendRawTransaction(serializedTransaction, options);
  }
}
```

Because you set `maxRetries: 0`, retry logic is entirely in your hands. A blockhash expires by block height, not time: the transaction can land until the block height passes `lastValidBlockHeight`, 150 blocks after the blockhash (well under a minute at current mainnet slot times). Only when the function returns `null` should you fetch a new blockhash from `confirmed` or `finalized` commitment, re-sign, and send again. A transaction that landed with an error has already executed: whether to send a new one is a trading decision, not a retry.

## Putting it together

A minimal trading loop combining Steps 1, 3 and 4:

{% code title="Trading loop" lineNumbers="true" %}

```typescript
import Client, { CommitmentLevel } from "@triton-one/yellowstone-grpc";
import {
  ComputeBudgetProgram,
  Connection,
  Keypair,
  Transaction,
  TransactionSignature,
} from "@solana/web3.js";
import bs58 from "bs58";

const ENDPOINT = "https://<your-endpoint>.mainnet.rpcpool.com";
const TOKEN = "<your-token>";
const RAYDIUM_AMM = "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8";
const payer = Keypair.fromSecretKey(bs58.decode(process.env.PAYER_SECRET_KEY!)); // your funded signer

async function getPriorityFee(
  endpoint: string,
  token: string,
  accounts: string[],
  percentile: number
): Promise<number> {
  const response = await fetch(`${endpoint}/${token}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: 1,
      method: "getRecentPrioritizationFees",
      params: [accounts, { percentile }],
    }),
  });
  const { result } = await response.json();
  const fees: { slot: number; prioritizationFee: number }[] = result;
  return fees.sort((a, b) => b.slot - a.slot)[0].prioritizationFee;
}

// From Step 4: resends the same signed bytes until the transaction confirms or its blockhash expires.
async function sendUntilConfirmedOrExpired(
  connection: Connection,
  serializedTransaction: Uint8Array,
  lastValidBlockHeight: number
): Promise<TransactionSignature | null> {
  const options = { skipPreflight: true, maxRetries: 0 };
  const signature = await connection.sendRawTransaction(serializedTransaction, options);

  while (true) {
    await new Promise((resolve) => setTimeout(resolve, 2000));

    const blockHeight = await connection.getBlockHeight("confirmed");
    const { value } = await connection.getSignatureStatuses([signature]);
    const status = value[0];

    if (status?.confirmationStatus === "confirmed" || status?.confirmationStatus === "finalized") {
      if (status.err) throw new Error(`Landed but failed: ${JSON.stringify(status.err)}`);
      return signature;
    }
    if (blockHeight > lastValidBlockHeight) return null;

    await connection.sendRawTransaction(serializedTransaction, options);
  }
}

async function tradingLoop() {
  const connection = new Connection(`${ENDPOINT}/${TOKEN}`, "confirmed");
  const client = new Client(ENDPOINT, TOKEN, {});
  await client.connect();
  const stream = await client.subscribe();

  stream.on("data", async (data) => {
    if (!data.transaction) return;

    // 1. Signal detected, decide if you want to act
    const shouldTrade = analyseTransaction(data.transaction);
    if (!shouldTrade) return;

    try {
      // 2. Get competitive priority fee
      const fee = await getPriorityFee(ENDPOINT, TOKEN, [RAYDIUM_AMM], 9000);

      // 3. Build and sign your transaction
      const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash("confirmed");
      const tx = new Transaction({ feePayer: payer.publicKey, blockhash, lastValidBlockHeight });
      tx.add(ComputeBudgetProgram.setComputeUnitPrice({ microLamports: fee }));
      // ... add your swap instruction here
      tx.sign(payer);

      // 4. Send via Jet and rebroadcast until it lands or expires (Step 4)
      const sig = await sendUntilConfirmedOrExpired(connection, tx.serialize(), lastValidBlockHeight);
      console.log("Result:", sig ?? "expired");
    } catch (err) {
      console.error("Trade failed:", err);
    }
  });

  // Subscribe request (same as Step 1)
  await new Promise<void>((resolve, reject) => {
    stream.write(
      {
        accounts: {},
        transactions: {
          dex_transactions: {
            vote: false,
            failed: false,
            accountInclude: [RAYDIUM_AMM],
            accountExclude: [],
            accountRequired: [],
          },
        },
        slots: {},
        transactionsStatus: {},
        entry: {},
        blocks: {},
        blocksMeta: {},
        commitment: CommitmentLevel.PROCESSED,
        accountsDataSlice: [],
        ping: undefined,
      },
      (err) => {
        if (err) reject(err);
        else resolve();
      }
    );
  });
}

function analyseTransaction(tx: any): boolean {
  // Your signal logic here
  return false;
}

tradingLoop().catch(console.error);
```

{% endcode %}

## Prefer a faster path to market?

If you'd rather go live without building your own routing and quoting logic, Triton's Titan API covers real-time routing across DEXes and RFQ providers, with DART live on-chain re-optimisation and quote streaming over WebSockets, all out of the box.

Two paths for two types of teams:

* **This guide**: build your own signal and execution stack. Full control, lowest latency, more engineering work.
* **Titan: plug in** pre-built liquidity routing and quoting. Fastest time to market, less custom code.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-route">:route:</i> <strong>Titan Swap API</strong></td><td>Live swap quotes and executable routes streamed over WebSocket, with DART on-chain re-optimisation on selected pairs.</td><td><a href="https://docs.triton.one/solana/sending-transactions/3rd-party-apis/titan-swap-api">Titan Swap API</a></td></tr></tbody></table>

## FAQs

<details>

<summary>Do I need all five products?</summary>

Dragon's Mouth and Jet cover the minimum: real-time data in, transactions out. Add Deshred if your strategy depends on acting before the network processes a transaction. Priority Fee API prevents you from overbidding during quiet periods. Shield applies your validator allowlist or blocklist to each send that carries your policy address: `forwardingPolicies` on `sendTransaction`, or the `Solana-ForwardingPolicies` header on `/sendtx`. Sends without a policy go to the upcoming leaders unfiltered.

</details>

<details>

<summary>How do I pick the right percentile?</summary>

Start at 7500 (75th percentile) and monitor landing rate. Increase to 9000+ during congestion or when latency matters more than cost.

</details>

<details>

<summary>Should I configure retries when sending?</summary>

Set `maxRetries: 0` (Triton doesn't retry on the server), then rebroadcast from your application: resend the same signed transaction every couple of seconds until it confirms or its blockhash expires (`lastValidBlockHeight`, see Step 4). Re-sign with a fresh blockhash only after the block height has passed `lastValidBlockHeight` and `getSignatureStatuses` shows the original didn't land; re-signing earlier creates a second transaction that can also execute. Triton sends go through Jet, which doesn't keep a server-side retry queue (unlike Agave's send-transaction-service, whose queue overflows under congestion), so client-managed rebroadcasts are what land your transaction.

</details>

<details>

<summary>Can I use this with Orca or other DEXes?</summary>

Yes, replace the Raydium AMM program address with the program address of any DEX.

Orca Whirlpools: `whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc`

</details>

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-fire">:fire:</i> <strong>Deshred Transactions gRPC</strong></td><td>Pre-execution transactions reconstructed from raw shreds. Earliest intent signal for traders.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/deshred-transactions">Deshred Transactions gRPC</a></td></tr><tr><td><i class="fa-shield">:shield:</i> <strong>Shield MEV protection</strong></td><td>On-chain allowlists or blocklists with local enforcement.</td><td><a href="https://docs.triton.one/solana/sending-transactions/shield-mev-protection">Shield Protection</a></td></tr><tr><td><i class="fa-route">:route:</i> <strong>Titan Swap API</strong></td><td>Live swap quotes and executable routes streamed over WebSocket, with DART on-chain re-optimisation on selected pairs.</td><td><a href="https://docs.triton.one/solana/sending-transactions/3rd-party-apis/titan-swap-api">Titan Swap API</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Building a wallet

Build a Solana wallet backend with Triton, covering balances, account-change streaming, history, and sending SOL and SPL tokens.

## Overview

This guide covers the core building blocks of a Solana wallet backend: fetching live balances, streaming real-time account changes, pulling transaction history, and sending SOL and SPL tokens reliably under network congestion.

By the end you'll have working code for each of these, plus a sending pattern that lands transactions consistently.

## Products used in this guide

| Product          | Role in this guide                                                   |
| ---------------- | -------------------------------------------------------------------- |
| Triton RPC       | Fetch SOL balance, token accounts, and transaction history           |
| Dragon's Mouth   | Subscribe to real-time account changes, no polling required          |
| Priority Fee API | Get a percentile-based fee estimate before sending                   |
| Jet              | Send transactions directly to the current leader with built-in SWQoS |

## Prerequisites

Before starting, make sure you have:

* A Triton account with an active endpoint.
* Your endpoint URL and token.
* Basic familiarity with Solana (accounts, public keys, transactions).

{% tabs %}
{% tab title="TypeScript" %}

```bash
npm install @triton-one/yellowstone-grpc @solana/web3.js@1 @solana/spl-token bs58
```

{% hint style="info" %}
In an ES module project (`"type": "module"`) that TypeScript checks with `"module": "nodenext"`, `new Client(...)` from `@triton-one/yellowstone-grpc` (checked on 9.0.1 and 10.0.0) fails type-checking with TS2351 ("This expression is not constructable"), because the SDK's type declarations resolve as CommonJS there. The code still runs. To type-check it, use a CommonJS project or `"moduleResolution": "bundler"`.
{% endhint %}
{% endtab %}

{% tab title="Rust" %}
{% code title="Cargo.toml" %}

```toml
# Add to Cargo.toml
[dependencies]
yellowstone-grpc-client = "17"
yellowstone-grpc-proto = "14"
tokio = { version = "1", features = ["full"] }
futures = "0.3"
bs58 = "0.5"
anyhow = "1"
reqwest = { version = "0.12", features = ["json"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
solana-client = "3"
solana-sdk = "3"
solana-commitment-config = "3"
solana-compute-budget-interface = "3"
solana-system-interface = "2"
spl-token = "9"
spl-associated-token-account = "8"
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}

```bash
pip install solana solders httpx grpcio grpcio-tools base58

# Generate yellowstone gRPC stubs. Save geyser.proto and solana-storage.proto into ./proto
# (geyser.proto imports solana-storage.proto, so compile both):
# python -m grpc_tools.protoc -I./proto --python_out=. --grpc_python_out=. geyser.proto solana-storage.proto
# Proto files: https://github.com/rpcpool/yellowstone-grpc/tree/master/yellowstone-grpc-proto/proto
```

{% endtab %}
{% endtabs %}

## Quickstart

Get your first response from Triton in under two minutes. Replace the endpoint and token, then run:

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import { Connection } from "@solana/web3.js";

const connection = new Connection("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>");
const slot = await connection.getSlot();
console.log("Connected - current slot:", slot);
```

{% endtab %}

{% tab title="Rust" %}

```rust
use solana_client::rpc_client::RpcClient;

fn main() {
    let client = RpcClient::new("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>");
    let slot = client.get_slot().unwrap();
    println!("Connected - current slot: {}", slot);
}
```

{% endtab %}

{% tab title="Python" %}

```python
import asyncio

from solana.rpc.async_api import AsyncClient


async def main():
    async with AsyncClient("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>") as client:
        slot = (await client.get_slot()).value
        print(f"Connected - current slot: {slot}")


asyncio.run(main())
```

{% endtab %}
{% endtabs %}

{% code title="Output" %}

```
Connected - current slot: 423835852
```

{% endcode %}

If you see a slot number, your endpoint is live and you're ready to go. The slot advances roughly every 200 ms, so if you run it twice you'll see it increment.

{% stepper %}
{% step %}

### Fetch wallet state

Get a wallet's SOL balance and all SPL token holdings in a single block of calls.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import {
  Connection,
  PublicKey,
  LAMPORTS_PER_SOL,
} from "@solana/web3.js";
import { TOKEN_PROGRAM_ID } from "@solana/spl-token";

const ENDPOINT = "https://<your-endpoint>.mainnet.rpcpool.com";
const TOKEN = "<your-token>";

async function getWalletState(walletAddress: string) {
  const connection = new Connection(`${ENDPOINT}/${TOKEN}`);
  const pubkey = new PublicKey(walletAddress);

  // SOL balance
  const lamports = await connection.getBalance(pubkey);
  console.log(`SOL: ${lamports / LAMPORTS_PER_SOL}`);

  // All SPL token accounts owned by this wallet
  const { value: tokenAccounts } = await connection.getParsedTokenAccountsByOwner(
    pubkey,
    { programId: TOKEN_PROGRAM_ID }
  );

  for (const { account } of tokenAccounts) {
    const info = account.data.parsed.info;
    const mint: string = info.mint;
    const amount: number = info.tokenAmount.uiAmount;
    console.log(`Token ${mint}: ${amount}`);
  }
}

getWalletState("YourWalletAddressHere").catch(console.error);
```

{% endtab %}

{% tab title="Rust" %}

```rust
use solana_client::rpc_client::RpcClient;
use solana_client::rpc_request::TokenAccountsFilter;
use solana_sdk::pubkey::Pubkey;
use std::str::FromStr;

const ENDPOINT: &str = "https://<your-endpoint>.mainnet.rpcpool.com";
const TOKEN: &str = "<your-token>";
const TOKEN_PROGRAM_ID: &str = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";

fn get_wallet_state(wallet_address: &str) -> anyhow::Result<()> {
    let client = RpcClient::new(format!("{}/{}", ENDPOINT, TOKEN));
    let pubkey = Pubkey::from_str(wallet_address)?;

    // SOL balance
    let lamports = client.get_balance(&pubkey)?;
    println!("SOL: {:.9}", lamports as f64 / 1_000_000_000.0);

    // SPL token accounts - data comes back as parsed JSON with mint and amount
    let token_program = Pubkey::from_str(TOKEN_PROGRAM_ID)?;
    let accounts = client.get_token_accounts_by_owner(
        &pubkey,
        TokenAccountsFilter::ProgramId(token_program),
    )?;

    for account in &accounts {
        if let solana_client::rpc_response::UiAccountData::Json(ref parsed) = account.account.data {
            let info = &parsed.parsed["info"];
            let mint = info["mint"].as_str().unwrap_or("?");
            let balance = info["tokenAmount"]["uiAmountString"].as_str().unwrap_or("0");
            println!("  mint={} balance={}", mint, balance);
        }
    }

    Ok(())
}
```

{% endtab %}

{% tab title="Python" %}

```python
import asyncio

from solana.rpc.async_api import AsyncClient
from solana.rpc.models import TokenAccountOpts
from solders.pubkey import Pubkey

ENDPOINT = "https://<your-endpoint>.mainnet.rpcpool.com"
TOKEN = "<your-token>"
TOKEN_PROGRAM_ID = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"

async def get_wallet_state(wallet_address: str):
    async with AsyncClient(f"{ENDPOINT}/{TOKEN}") as client:
        pubkey = Pubkey.from_string(wallet_address)

        # SOL balance
        resp = await client.get_balance(pubkey)
        print(f"SOL: {resp.value / 1_000_000_000:.9f}")

        # SPL token accounts
        opts = TokenAccountOpts(program_id=Pubkey.from_string(TOKEN_PROGRAM_ID))
        token_resp = await client.get_token_accounts_by_owner_json_parsed(pubkey, opts)
        for account in token_resp.value:
            info = account.account.data.parsed["info"]
            mint = info["mint"]
            amount = info["tokenAmount"]["uiAmount"]
            print(f"Token {mint}: {amount}")


asyncio.run(get_wallet_state("YourWalletAddressHere"))
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Verify it works:** Replace `YourWalletAddressHere` with any active Solana address. You should see an SOL balance and a list of token mints with their amounts. An empty token list means the wallet has no SPL token accounts.
{% endhint %}

{% code title="Output" %}

```
SOL: 0.0
Token PhiLR4JDZB9z92rYT5xBXKCxmq4pGB1LYjtybii7aiS: 22100.0
Token kukb9fv4Y3MGuG1z6TodQqpctkYZjkGnuXQd91U8r1d: 28.0
Token 259n8rLH1y6J2DuLZFTUDGrpPW4WVF8fzJtwNQZyEDxF: 8.0
Token 2znw8JBTW1w2HBNiRwsTpbunjZVZ3uiGdHUt9M72i2oN: 9.0
Token HhzUT16NUeL93BHqQTTkCpzdRgxryxA9PP7aX2QNfg7B: 34312.0
```

{% endcode %}

Each line is a different SPL token the wallet holds. The address is the **mint**, the unique identifier for that token. `uiAmount` is already decimal-adjusted so you can display it directly.
{% endstep %}

{% step %}

### Stream real-time balance updates with Dragon's Mouth

Rather than making you poll on a timer, Dragon's Mouth pushes an update the moment an account changes, at confirmed commitment, typically within one slot of the transaction landing. Subscribe to your wallet's pubkey to get notified instantly when SOL is received or sent.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import Client, {
  CommitmentLevel,
  SubscribeRequest,
} from "@triton-one/yellowstone-grpc";
import bs58 from "bs58";

const ENDPOINT = "https://<your-endpoint>.mainnet.rpcpool.com";
const TOKEN = "<your-token>";

async function streamWalletUpdates(walletAddress: string) {
  const client = new Client(ENDPOINT, TOKEN, {});
  await client.connect();
  const stream = await client.subscribe();

  const request: SubscribeRequest = {
    accounts: {
      wallet: {
        account: [walletAddress], // watch this specific account
        owner: [],
        filters: [],
      },
    },
    transactions: {},
    slots: {},
    transactionsStatus: {},
    entry: {},
    blocks: {},
    blocksMeta: {},
    blockFooter: {},
    commitment: CommitmentLevel.CONFIRMED,
    accountsDataSlice: [],
    ping: undefined,
  };

  stream.on("data", (data) => {
    if (data.account) {
      const pubkey = bs58.encode(data.account.account!.pubkey);
      const lamports = data.account.account!.lamports;
      const slot = data.account.slot;
      console.log(`Account updated: ${pubkey}`);
      console.log(`  New balance: ${Number(lamports) / 1e9} SOL`);
      console.log(`  Slot: ${slot}`);
    }
  });

  stream.on("error", (err) => console.error("Stream error:", err));

  await new Promise<void>((resolve, reject) => {
    stream.write(request, (err) => {
      if (err) reject(err);
      else resolve();
    });
  });

  // Keep the stream alive
  setInterval(() => {
    stream.write({ ping: { id: 1 } } as SubscribeRequest, () => {});
  }, 30_000);
}

streamWalletUpdates("YourWalletAddressHere").catch(console.error);
```

{% endtab %}

{% tab title="Rust" %}

```rust
use std::collections::HashMap;
use futures::StreamExt;
use yellowstone_grpc_client::{ClientTlsConfig, GeyserGrpcClient};
use yellowstone_grpc_proto::prelude::{
    subscribe_update::UpdateOneof, CommitmentLevel, SubscribeRequest,
    SubscribeRequestFilterAccounts,
};

const ENDPOINT: &str = "https://<your-endpoint>.mainnet.rpcpool.com";
const TOKEN: &str = "<your-token>";

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let wallet_address = "YourWalletAddressHere";

    let mut client = GeyserGrpcClient::build_from_shared(ENDPOINT.to_string())?
        .x_token(Some(TOKEN.to_string()))?
        .tls_config(ClientTlsConfig::new().with_native_roots())?
        .connect()
        .await?;

    let mut accounts = HashMap::new();
    accounts.insert(
        "wallet".to_string(),
        SubscribeRequestFilterAccounts {
            account: vec![wallet_address.to_string()],
            ..Default::default()
        },
    );

    let request = SubscribeRequest {
        accounts,
        commitment: Some(CommitmentLevel::Confirmed as i32),
        ..Default::default()
    };

    let (_tx, mut stream) = client.subscribe_with_request(Some(request)).await?;

    while let Some(Ok(msg)) = stream.next().await {
        if let Some(UpdateOneof::Account(acct)) = msg.update_oneof {
            let lamports = acct.account.as_ref().map(|a| a.lamports).unwrap_or(0);
            let pubkey = bs58::encode(
                acct.account.as_ref().map(|a| a.pubkey.as_slice()).unwrap_or(&[])
            ).into_string();
            println!("Account updated: {}", pubkey);
            println!("  New balance: {:.9} SOL", lamports as f64 / 1e9);
            println!("  Slot: {}", acct.slot);
        }
    }

    Ok(())
}
```

{% endtab %}

{% tab title="Python" %}

```python
import asyncio
import grpc
from grpc import aio
import base58

from geyser_pb2 import (
    SubscribeRequest,
    SubscribeRequestFilterAccounts,
    CommitmentLevel,
    SubscribeRequestPing,
)
from geyser_pb2_grpc import GeyserStub

ENDPOINT = "<your-endpoint>.mainnet.rpcpool.com:443"
TOKEN = "<your-token>"

async def stream_wallet_updates(wallet_address: str):
    credentials = grpc.ssl_channel_credentials()
    async with aio.secure_channel(ENDPOINT, credentials) as channel:
        stub = GeyserStub(channel)
        metadata = (("x-token", TOKEN),)

        async def request_iterator():
            yield SubscribeRequest(
                accounts={
                    "wallet": SubscribeRequestFilterAccounts(
                        account=[wallet_address],
                    )
                },
                commitment=CommitmentLevel.CONFIRMED,
            )
            while True:
                await asyncio.sleep(30)
                yield SubscribeRequest(ping=SubscribeRequestPing(id=1))

        async for update in stub.Subscribe(request_iterator(), metadata=metadata):
            if update.HasField("account"):
                pubkey = base58.b58encode(bytes(update.account.account.pubkey)).decode()
                lamports = update.account.account.lamports
                slot = update.account.slot
                print(f"Account updated: {pubkey}")
                print(f"  New balance: {lamports / 1e9:.9f} SOL")
                print(f"  Slot: {slot}")

asyncio.run(stream_wallet_updates("YourWalletAddressHere"))
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Verify it works:** As soon as the subscription connects, you'll receive the current account state immediately. You'll then see an update within milliseconds whenever the account changes.
{% endhint %}

{% code title="Output" %}

```
Account updated: 58oQChx4yWmvKdwLLZzBi4ChoCc2fqCUWBkwMihLYQo2
  New balance: 4.781558248 SOL
  Slot: 423839570
Account updated: 58oQChx4yWmvKdwLLZzBi4ChoCc2fqCUWBkwMihLYQo2
  New balance: 4.781558248 SOL
  Slot: 423839571
```

{% endcode %}

Updates arrive approximately every slot (\~200 ms) for active accounts. The `filters` field in the raw stream confirms which subscription key matched, here `"wallet"`, matching the key we set in the request.

**Watching token accounts:** The same subscription works for SPL token accounts. Add each token account pubkey to the `account` filter. When a token transfer happens, the account's `data` field changes. Decode it with the SPL Token account layout to read the updated balance:

```typescript
import { AccountLayout } from "@solana/spl-token";

stream.on("data", (data) => {
  if (data.account) {
    const raw = Buffer.from(data.account.account!.data);
    if (raw.length === AccountLayout.span) {
      const decoded = AccountLayout.decode(raw);
      // decoded.amount is a BigInt in atomic units
      // divide by 10 ** decimals to get the display amount
      console.log(`Token balance (atomic): ${decoded.amount}`);
    }
  }
});
```

{% endstep %}

{% step %}

### Fetch transaction history

Pull a wallet's recent transactions with `getSignaturesForAddress`, then fetch the full details of each.

Set `maxSupportedTransactionVersion` to `1`. Mainnet blocks now contain version 1 transactions, and with a lower value the whole request fails with error `-32015` as soon as one of the signatures belongs to a version 1 transaction. `@solana/web3.js` decodes version 1 transactions from 1.99.0.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import {
  Connection,
  PublicKey,
  ParsedTransactionWithMeta,
} from "@solana/web3.js";

const ENDPOINT = "https://<your-endpoint>.mainnet.rpcpool.com";
const TOKEN = "<your-token>";

async function getTransactionHistory(
  walletAddress: string,
  limit: number = 10
): Promise<ParsedTransactionWithMeta[]> {
  const connection = new Connection(`${ENDPOINT}/${TOKEN}`);
  const pubkey = new PublicKey(walletAddress);

  // Most recent signatures first
  const signatures = await connection.getSignaturesForAddress(pubkey, { limit });
  console.log(`Found ${signatures.length} transactions`);

  // Fetch full parsed transaction details
  const transactions = await connection.getParsedTransactions(
    signatures.map((s) => s.signature),
    { maxSupportedTransactionVersion: 1 }
  );

  for (const tx of transactions) {
    if (!tx) continue;
    const sig = tx.transaction.signatures[0];
    const slot = tx.slot;
    const status = tx.meta?.err ? "failed" : "ok";
    const fee = tx.meta?.fee ?? 0;
    console.log(`${sig.slice(0, 20)}... slot=${slot} status=${status} fee=${fee}`);
  }

  return transactions.filter(Boolean) as ParsedTransactionWithMeta[];
}

getTransactionHistory("YourWalletAddressHere").catch(console.error);
```

{% endtab %}

{% tab title="Rust" %}

```rust
// solana-sdk 3.x: CommitmentConfig moved to solana-commitment-config crate;
// the config struct is GetConfirmedSignaturesForAddress2Config (not RpcSignaturesForAddressConfig);
// sig_info.slot is u64 (not Option<u64>).
use solana_client::rpc_client::{GetConfirmedSignaturesForAddress2Config, RpcClient};
use solana_commitment_config::CommitmentConfig;
use solana_sdk::pubkey::Pubkey;
use std::str::FromStr;

const ENDPOINT: &str = "https://<your-endpoint>.mainnet.rpcpool.com";
const TOKEN: &str = "<your-token>";

fn get_transaction_history(wallet_address: &str, limit: usize) -> anyhow::Result<()> {
    let client = RpcClient::new(format!("{}/{}", ENDPOINT, TOKEN));
    let pubkey = Pubkey::from_str(wallet_address)?;

    let config = GetConfirmedSignaturesForAddress2Config {
        limit: Some(limit),
        commitment: Some(CommitmentConfig::finalized()),
        ..Default::default()
    };

    let sigs = client.get_signatures_for_address_with_config(&pubkey, config)?;
    println!("Found {} transactions", sigs.len());

    for sig_info in &sigs {
        let status = if sig_info.err.is_some() { "failed" } else { "ok" };
        println!(
            "{:.20}... slot={} status={}",
            sig_info.signature,
            sig_info.slot,
            status
        );
    }

    Ok(())
}
```

{% endtab %}

{% tab title="Python" %}

```python
import asyncio

from solana.rpc.async_api import AsyncClient
from solders.pubkey import Pubkey

ENDPOINT = "https://<your-endpoint>.mainnet.rpcpool.com"
TOKEN = "<your-token>"

async def get_transaction_history(wallet_address: str, limit: int = 10):
    async with AsyncClient(f"{ENDPOINT}/{TOKEN}") as client:
        pubkey = Pubkey.from_string(wallet_address)

        sigs = await client.get_signatures_for_address(pubkey, limit=limit)
        print(f"Found {len(sigs.value)} transactions")

        for sig_info in sigs.value:
            status = "failed" if sig_info.err else "ok"
            print(f"{str(sig_info.signature)[:20]}... slot={sig_info.slot} status={status}")


asyncio.run(get_transaction_history("YourWalletAddressHere"))
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Verify it works:** Use any active Solana wallet address with transaction history. You should see up to 10 recent signatures with their slot and status.
{% endhint %}

{% code title="Output" %}

```
Found 5 transactions
4x7M5EjrJkuheoRmQCGR... slot=408661772 status=ok
5Be9V7hfrimVyjHz15kb... slot=377756257 status=ok
4KRoLyKGv4sWFDdwtmAj... slot=377749681 status=ok
5PUkggk1qC3KiobK2QHk... slot=377749346 status=ok
qmLhqJhUr4nzv72PMr7D... slot=364454544 status=ok
```

{% endcode %}

**Paginating further back:** Pass `before` to walk back through history:

```typescript
const olderSigs = await connection.getSignaturesForAddress(pubkey, {
  limit: 10,
  before: signatures[signatures.length - 1].signature,
});
```

{% endstep %}

{% step %}

### Send SOL

Build a SOL transfer, attach a priority fee from the Priority Fee API, and send via Jet.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import {
  Connection,
  PublicKey,
  SystemProgram,
  Transaction,
  ComputeBudgetProgram,
  Keypair,
  LAMPORTS_PER_SOL,
} from "@solana/web3.js";

const ENDPOINT = "https://<your-endpoint>.mainnet.rpcpool.com";
const TOKEN = "<your-token>";

async function sendSol(
  sender: Keypair,
  recipientAddress: string,
  amountSol: number
) {
  const connection = new Connection(`${ENDPOINT}/${TOKEN}`);
  const recipient = new PublicKey(recipientAddress);
  const lamports = Math.round(amountSol * LAMPORTS_PER_SOL);

  // 1. Get a competitive priority fee (90th percentile)
  const feeResponse = await fetch(`${ENDPOINT}/${TOKEN}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: 1,
      method: "getRecentPrioritizationFees",
      params: [[sender.publicKey.toBase58()], { percentile: 9000 }],
    }),
  });
  const { result } = await feeResponse.json();
  const priorityFee: number = result.sort(
    (a: { slot: number }, b: { slot: number }) => b.slot - a.slot
  )[0].prioritizationFee;

  // 2. Build the transaction
  const { blockhash } = await connection.getLatestBlockhash();
  const tx = new Transaction();
  tx.recentBlockhash = blockhash;
  tx.feePayer = sender.publicKey;

  tx.add(
    ComputeBudgetProgram.setComputeUnitLimit({ units: 200_000 }),
    ComputeBudgetProgram.setComputeUnitPrice({ microLamports: priorityFee }),
    SystemProgram.transfer({
      fromPubkey: sender.publicKey,
      toPubkey: recipient,
      lamports,
    })
  );

  tx.sign(sender);

  // 3. Send via Jet - skipPreflight + maxRetries: 0 for direct leader delivery
  const sendResponse = await fetch(`${ENDPOINT}/${TOKEN}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: 1,
      method: "sendTransaction",
      params: [
        tx.serialize().toString("base64"),
        { encoding: "base64", skipPreflight: true, maxRetries: 0 },
      ],
    }),
  });

  const { result: signature } = await sendResponse.json();
  console.log("Sent:", signature);
  return signature as string;
}
```

{% endtab %}

{% tab title="Rust" %}

```rust
// solana-sdk 3.x: ComputeBudgetInstruction and system_instruction moved to separate crates.
// Use Keypair::from_base58_string (from_bytes removed in 3.x).
// The percentile param works on Triton endpoints; public devnet RPC ignores it.
use anyhow::anyhow;
use reqwest::Client as HttpClient;
use serde::Deserialize;
use solana_client::rpc_client::RpcClient;
use solana_client::rpc_config::RpcSendTransactionConfig;
use solana_compute_budget_interface::ComputeBudgetInstruction;
use solana_sdk::{
    pubkey::Pubkey,
    signature::{Keypair, Signer},
    transaction::Transaction,
};
use solana_system_interface::instruction as system_instruction;
use std::str::FromStr;

const ENDPOINT: &str = "https://<your-endpoint>.mainnet.rpcpool.com";
const TOKEN: &str = "<your-token>";

#[derive(Deserialize)]
struct PrioritizationFee {
    slot: u64,
    #[serde(rename = "prioritizationFee")]
    prioritization_fee: u64,
}

#[derive(Deserialize)]
struct RpcResponse {
    result: Vec<PrioritizationFee>,
}

async fn get_priority_fee(accounts: &[&str], percentile: u32) -> anyhow::Result<u64> {
    let http = HttpClient::new();
    let url = format!("{}/{}", ENDPOINT, TOKEN);
    let body = serde_json::json!({
        "jsonrpc": "2.0", "id": 1,
        "method": "getRecentPrioritizationFees",
        "params": [accounts, { "percentile": percentile }]
    });
    let mut resp: RpcResponse = http.post(&url).json(&body).send().await?.json().await?;
    resp.result.sort_by(|a, b| b.slot.cmp(&a.slot));
    resp.result.first().map(|f| f.prioritization_fee).ok_or_else(|| anyhow!("no fee data"))
}

async fn send_sol(sender: &Keypair, recipient_address: &str, lamports: u64) -> anyhow::Result<String> {
    let client = RpcClient::new(format!("{}/{}", ENDPOINT, TOKEN));
    let recipient = Pubkey::from_str(recipient_address)?;

    let priority_fee = get_priority_fee(&[&sender.pubkey().to_string()], 9000).await?;
    let blockhash = client.get_latest_blockhash()?;

    let tx = Transaction::new_signed_with_payer(
        &[
            ComputeBudgetInstruction::set_compute_unit_limit(200_000),
            ComputeBudgetInstruction::set_compute_unit_price(priority_fee),
            system_instruction::transfer(&sender.pubkey(), &recipient, lamports),
        ],
        Some(&sender.pubkey()),
        &[sender],
        blockhash,
    );

    let config = RpcSendTransactionConfig {
        skip_preflight: true,
        max_retries: Some(0),
        ..Default::default()
    };

    let sig = client.send_transaction_with_config(&tx, config)?;
    println!("Sent: {}", sig);
    Ok(sig.to_string())
}
```

{% endtab %}

{% tab title="Python" %}

```python
import asyncio
import httpx
from solana.rpc.async_api import AsyncClient
from solana.rpc.models import TxOpts
from solders.keypair import Keypair
from solders.pubkey import Pubkey
from solders.system_program import TransferParams, transfer
from solders.transaction import Transaction as SolTransaction
from solders.message import Message
from solders.compute_budget import set_compute_unit_price, set_compute_unit_limit

ENDPOINT = "https://<your-endpoint>.mainnet.rpcpool.com"
TOKEN = "<your-token>"

async def get_priority_fee(accounts: list[str], percentile: int) -> int:
    async with httpx.AsyncClient() as http:
        resp = await http.post(
            f"{ENDPOINT}/{TOKEN}",
            json={
                "jsonrpc": "2.0", "id": 1,
                "method": "getRecentPrioritizationFees",
                "params": [accounts, {"percentile": percentile}],
            },
        )
        fees = resp.json()["result"]
        fees.sort(key=lambda x: x["slot"], reverse=True)
        return fees[0]["prioritizationFee"]

async def send_sol(sender: Keypair, recipient_address: str, lamports: int, priority_fee: int):
    async with AsyncClient(f"{ENDPOINT}/{TOKEN}") as client:
        recipient = Pubkey.from_string(recipient_address)

        blockhash = (await client.get_latest_blockhash()).value.blockhash

        instructions = [
            set_compute_unit_limit(200_000),
            set_compute_unit_price(priority_fee),
            transfer(TransferParams(
                from_pubkey=sender.pubkey(),
                to_pubkey=recipient,
                lamports=lamports,
            )),
        ]

        msg = Message.new_with_blockhash(instructions, sender.pubkey(), blockhash)
        tx = SolTransaction([sender], msg, blockhash)

        response = await client.send_raw_transaction(
            bytes(tx),
            opts=TxOpts(skip_preflight=True, max_retries=0),
        )
        print(f"Sent: {response.value}")
        return str(response.value)


# send_sol is async: run it with asyncio.run (or await it from your own async code)
# asyncio.run(send_sol(sender, recipient_address, lamports, priority_fee))
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
**`skipPreflight: true` and `maxRetries: 0`** are recommended when sending via Jet. Jet forwards the transaction directly to the current and upcoming leaders using SWQoS. It doesn't retry on the server, so rebroadcast from your client until the transaction confirms or its blockhash expires.
{% endhint %}

{% hint style="info" %}
**Verify it works:** Run with a funded keypair and a valid recipient. This sends a real mainnet transaction that spends SOL and can't be reversed. You should see a signature printed immediately. Confirm it landed with:

```typescript
const status = await connection.getSignatureStatus(signature);
console.log(status.value?.confirmationStatus); // "confirmed" or "finalized"
```

{% endhint %}

The priority fee call returns the current network fee before the transaction is built:

{% code title="Output" %}

```
Priority fee (90th pct): 2740943 micro-lamports/CU
```

{% endcode %}

Then the send returns a signature:

{% code title="Output" %}

```
Sent: 5ofMHS3yeHrLReLkij5V9SvcrTZoKajJYaLw8aos2UeM2cupWtARXp1Jrt9WsAKTCcqPbja2vQv8nyxmcurcvwg1
Status: confirmed ✅
```

{% endcode %}

The response is a base58-encoded transaction signature (88 characters). This is your receipt: use it to look up the transaction in an explorer or poll `getSignatureStatus` to confirm it landed.
{% endstep %}

{% step %}

### Send SPL tokens

The pattern is the same as sending SOL: build a transaction with a priority fee and send via Jet. The instruction is `createTransferCheckedInstruction` from `@solana/spl-token`.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import {
  Connection,
  PublicKey,
  Transaction,
  ComputeBudgetProgram,
  Keypair,
} from "@solana/web3.js";
import {
  getOrCreateAssociatedTokenAccount,
  createTransferCheckedInstruction,
  getMint,
} from "@solana/spl-token";

const ENDPOINT = "https://<your-endpoint>.mainnet.rpcpool.com";
const TOKEN = "<your-token>";

async function sendToken(
  sender: Keypair,
  recipientAddress: string,
  mintAddress: string,
  amount: number,      // in display units, e.g. 1.5 for 1.5 USDC
  priorityFee: number  // micro-lamports/CU from Priority Fee API
) {
  const connection = new Connection(`${ENDPOINT}/${TOKEN}`);
  const recipient = new PublicKey(recipientAddress);
  const mint = new PublicKey(mintAddress);

  // Get mint decimals
  const mintInfo = await getMint(connection, mint);
  const atomicAmount = BigInt(Math.round(amount * 10 ** mintInfo.decimals));

  // Get (or create) associated token accounts for sender and recipient.
  // Pass "confirmed" so the post-creation read uses confirmed finality -
  // without it, the re-fetch can fail on load-balanced RPCs if the creating
  // node and reading node haven't fully synced.
  const senderAta = await getOrCreateAssociatedTokenAccount(
    connection, sender, mint, sender.publicKey, false, "confirmed"
  );
  const recipientAta = await getOrCreateAssociatedTokenAccount(
    connection,
    sender,    // payer for ATA creation if the recipient doesn't have one yet
    mint,
    recipient,
    false,
    "confirmed"
  );

  const { blockhash } = await connection.getLatestBlockhash();
  const tx = new Transaction();
  tx.recentBlockhash = blockhash;
  tx.feePayer = sender.publicKey;

  tx.add(
    ComputeBudgetProgram.setComputeUnitLimit({ units: 300_000 }),
    ComputeBudgetProgram.setComputeUnitPrice({ microLamports: priorityFee }),
    createTransferCheckedInstruction(
      senderAta.address,
      mint,
      recipientAta.address,
      sender.publicKey,
      atomicAmount,
      mintInfo.decimals
    )
  );

  tx.sign(sender);

  const sendResponse = await fetch(`${ENDPOINT}/${TOKEN}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: 1,
      method: "sendTransaction",
      params: [
        tx.serialize().toString("base64"),
        { encoding: "base64", skipPreflight: true, maxRetries: 0 },
      ],
    }),
  });

  const { result: signature } = await sendResponse.json();
  console.log("Sent:", signature);
  return signature as string;
}
```

{% endtab %}

{% tab title="Rust" %}

```rust
// Note: source and destination ATAs must already exist.
// Use spl-associated-token-account = "8" to derive or create them if needed.
// solana-sdk 3.x: ComputeBudgetInstruction moved to solana-compute-budget-interface crate.
// spl-token = "9" is required (v6 uses solana-program 2.x which conflicts with solana-sdk 3.x).
use solana_client::rpc_client::RpcClient;
use solana_client::rpc_config::RpcSendTransactionConfig;
use solana_compute_budget_interface::ComputeBudgetInstruction;
use solana_sdk::{
    pubkey::Pubkey,
    signature::{Keypair, Signer},
    transaction::Transaction,
};
use spl_token::instruction::transfer_checked;

const ENDPOINT: &str = "https://<your-endpoint>.mainnet.rpcpool.com";
const TOKEN: &str = "<your-token>";

fn send_token(
    sender: &Keypair,
    source_ata: &Pubkey,
    dest_ata: &Pubkey,
    mint: &Pubkey,
    amount: u64,      // atomic units
    decimals: u8,
    priority_fee: u64,
) -> anyhow::Result<String> {
    let client = RpcClient::new(format!("{}/{}", ENDPOINT, TOKEN));
    let blockhash = client.get_latest_blockhash()?;

    let transfer_ix = transfer_checked(
        &spl_token::id(),
        source_ata,
        mint,
        dest_ata,
        &sender.pubkey(),
        &[],
        amount,
        decimals,
    )?;

    let tx = Transaction::new_signed_with_payer(
        &[
            ComputeBudgetInstruction::set_compute_unit_limit(300_000),
            ComputeBudgetInstruction::set_compute_unit_price(priority_fee),
            transfer_ix,
        ],
        Some(&sender.pubkey()),
        &[sender],
        blockhash,
    );

    let config = RpcSendTransactionConfig {
        skip_preflight: true,
        max_retries: Some(0),
        ..Default::default()
    };

    let sig = client.send_transaction_with_config(&tx, config)?;
    println!("Sent: {}", sig);
    Ok(sig.to_string())
}
```

{% endtab %}

{% tab title="Python" %}

```python
# spl.token.instructions is included in `pip install solana` - no separate package needed.
import asyncio
from solana.rpc.async_api import AsyncClient
from solana.rpc.models import TxOpts
from solders.keypair import Keypair
from solders.pubkey import Pubkey
from solders.transaction import Transaction as SolTransaction
from solders.message import Message
from solders.compute_budget import set_compute_unit_price, set_compute_unit_limit
from spl.token.instructions import transfer_checked
from spl.token.models import TransferCheckedParams
from spl.token.constants import TOKEN_PROGRAM_ID

ENDPOINT = "https://<your-endpoint>.mainnet.rpcpool.com"
TOKEN = "<your-token>"

async def send_token(
    sender: Keypair,
    source_ata: Pubkey,
    dest_ata: Pubkey,
    mint: Pubkey,
    amount: int,      # atomic units
    decimals: int,
    priority_fee: int,
):
    async with AsyncClient(f"{ENDPOINT}/{TOKEN}") as client:
        blockhash = (await client.get_latest_blockhash()).value.blockhash

        instructions = [
            set_compute_unit_limit(300_000),
            set_compute_unit_price(priority_fee),
            transfer_checked(TransferCheckedParams(
                program_id=TOKEN_PROGRAM_ID,
                source=source_ata,
                mint=mint,
                dest=dest_ata,
                owner=sender.pubkey(),
                amount=amount,
                decimals=decimals,
                signers=[],
            )),
        ]

        msg = Message.new_with_blockhash(instructions, sender.pubkey(), blockhash)
        tx = SolTransaction([sender], msg, blockhash)

        response = await client.send_raw_transaction(
            bytes(tx),
            opts=TxOpts(skip_preflight=True, max_retries=0),
        )
        print(f"Sent: {response.value}")
        return str(response.value)


# send_token is async: run it with asyncio.run (or await it from your own async code)
# asyncio.run(send_token(sender, source_ata, dest_ata, mint, amount, decimals, priority_fee))
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**`getOrCreateAssociatedTokenAccount`** will create the recipient's associated token account if it doesn't exist yet, funded by the sender. To avoid paying for ATA creation, check first with `getAssociatedTokenAddress` and fail early if the account doesn't exist:

```typescript
import { getAssociatedTokenAddress, getAccount } from "@solana/spl-token";

const recipientAta = await getAssociatedTokenAddress(mint, recipient);
try {
  await getAccount(connection, recipientAta); // throws if not found
} catch {
  throw new Error("Recipient has no token account for this mint");
}
```

{% endhint %}

{% hint style="info" %}
**Verify it works:** Run with a funded wallet holding some SPL tokens. This sends a real mainnet transfer that can't be reversed. You should see a signature. If you get a `TokenAccountNotFoundError` after `getOrCreateAssociatedTokenAccount` creates the ATA, the read-back hit a different load-balanced node before it propagated. The `"confirmed"` commitment above prevents this.
{% endhint %}

{% code title="Output" %}

```
Sent: 4M43KqiKonCP86oqmmb6...........................................
Status: confirmed ✅

Sender balance after:    90 tokens
Recipient balance after: 10 tokens
```

{% endcode %}

The token balances update atomically: if the transaction lands, the full amount moved. Check `preTokenBalances` vs `postTokenBalances` in the confirmed transaction to verify the exact amount transferred.
{% endstep %}
{% endstepper %}

## What's next

* **Routing and swaps:** get swap quotes for SPL token pairs through the Titan Swap API on your Triton mainnet endpoint, which meta-aggregates routes from Argos, external aggregators and RFQ sources.

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# How-tos

Short, task-focused guides for specific Solana workflows.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-box-archive">:box-archive:</i> <strong>Index Solana history with Superbank</strong></td><td>Run Superbank on a single node to ingest Solana ledger data into ClickHouse and serve a Solana-compatible JSON-RPC endpoint.</td><td><a href="https://docs.triton.one/solana/quickstart/how-tos/index-solana-history-with-superbank">Index Solana history with Superbank</a></td></tr><tr><td><i class="fa-paper-plane">:paper-plane:</i> <strong>End-to-end transaction pipeline with @solana/kit</strong></td><td>Build, sign, send, and confirm a transaction end to end with @solana/kit, adapted from the Ping Thing client.</td><td><a href="https://docs.triton.one/solana/quickstart/how-tos/transaction-pipeline-solana-kit">End-to-end transaction pipeline with @solana/kit</a></td></tr><tr><td><i class="fa-coins">:coins:</i> <strong>Query token program</strong></td><td>Query SPL token accounts by mint or owner with getProgramAccounts and getTokenAccountsByOwner.</td><td><a href="https://docs.triton.one/solana/quickstart/how-tos/query-token-program">Query token program</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Index Solana history with Superbank

Run Superbank on a single node to index the full Solana ledger into ClickHouse and serve a Solana-compatible JSON-RPC endpoint.

Superbank is an open-source Solana transaction indexer built by Triton. It ingests the full ledger into ClickHouse and exposes a Solana-compatible JSON-RPC endpoint, giving you your own queryable copy of the chain, with no rate limits and sub-millisecond lookups on historical data.

This guide walks through running Superbank on a single node from scratch: ClickHouse setup, DDL, ingestion configuration, and the RPC server. It also covers how to filter the index to only your app's transactions.

## Self-hosting vs Triton managed

Self-host when:

* You need full control over what's indexed (e.g. filter to only your program's transactions)
* You have compliance or data-residency requirements
* Your query volume is high enough that operating your own node is cheaper than per-request pricing
* You want to run custom queries directly against ClickHouse

Use Triton's managed endpoints when:

* You want the fastest path to production, with no ClickHouse operations and no infra
* You don't need to index historical data beyond what Triton retains
* You'd rather not maintain the ingestor and RPC layer yourself

Both options expose the same RPC interface, so you can start managed and migrate to self-hosted later without changing your client code.

## How the components fit together

Superbank has three parts, each running as a separate process:

```
[Dragon's Mouth / Fumarole / RPC]
          ↓
  superbank (ingestor)      ← Rust binary; runs on your host or in a container
          ↓
     ClickHouse             ← runs in Docker (this guide) or native install
          ↑
  superbank-rpc             ← Rust binary; runs on your host or in a container
          ↓
  Your app / JSON-RPC clients
```

* **ClickHouse** is the storage layer. The two binaries connect to it over HTTP (port 8123).
* **`superbank`** reads from your ingestion source and writes rows into ClickHouse.
* **`superbank-rpc`** reads from ClickHouse and serves the Solana-compatible RPC API.

None of the three components need to run on the same machine; they only need to be network-reachable to each other. For a single-node setup, running all three on one host is the simplest approach.

## What Superbank provides

Once running, Superbank serves these RPC methods against your local ClickHouse:

| Method                                                     | Notes                                               |
| ---------------------------------------------------------- | --------------------------------------------------- |
| `getSignaturesForAddress`                                  | Standard + `beforeSlot`/`untilSlot` extensions      |
| `getSignatureStatuses`                                     |                                                     |
| `getTransaction`                                           | Standard + `slot` hint extension                    |
| `getBlock`                                                 |                                                     |
| `getTransactionsForAddress`                                | Custom method: pagination + token account filtering |
| `getBlockHeight`, `getSlot`, `getLatestBlockhash`          | Chain tip queries                                   |
| `getBlockTime`, `getBlocks`, `getBlocksWithLimit`          |                                                     |
| `getHealth`, `getFirstAvailableBlock`, `minimumLedgerSlot` |                                                     |
| `getInflationReward`, `getTransactionCount`                |                                                     |

Adding `processed` commitment (in addition to `confirmed`/`finalized`) requires the optional gRPC head-cache feature, covered at the end of this guide.

## Prerequisites

* **ClickHouse**, 26.x or later. Docker is the fastest way to get one running.
* **Rust** 1.98.1, which the repository's `rust-toolchain.toml` pins (the workspace uses edition 2024). Install via [rustup.rs](https://rustup.rs).
* **A Dragon's Mouth gRPC endpoint or Fumarole subscription**, for live ingestion. Get one at [customers.triton.one](https://customers.triton.one). For backfill only, the JSON-RPC source works with any public endpoint.
* Git and standard build tools (`gcc`, `pkg-config`, `libssl-dev` on Linux / Xcode Command Line Tools on macOS).

## Build and run

{% stepper %}
{% step %}

### Clone and build

```bash
git clone --recurse-submodules https://github.com/solana-rpc/superbank.git
cd superbank

# Build both binaries
cargo build --release -p superbank -p superbank-rpc
```

The build produces `./target/release/superbank` (ingestor) and `./target/release/superbank-rpc` (RPC server).
{% endstep %}

{% step %}

### Start ClickHouse

You have three options.

**Option A: Docker (recommended for getting started)**

The fastest path, with no installation required beyond Docker itself:

```bash
docker run -d \
  --name superbank-clickhouse \
  -p 127.0.0.1:8123:8123 \
  -p 127.0.0.1:9000:9000 \
  --ulimit nofile=262144:262144 \
  -e CLICKHOUSE_DB=default \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD="" \
  -e CLICKHOUSE_SKIP_USER_SETUP=1 \
  clickhouse/clickhouse-server:26.1.2.11
```

This ClickHouse container has no password and is for local development only. Its ports are bound to `127.0.0.1`, so only this machine can reach them.

**Option B: Native install (recommended for production)**

For production servers, install ClickHouse directly on the host for better performance and easier disk/memory tuning. Follow the [official install guide](https://clickhouse.com/docs/en/install) for your OS. Use version 26.x or later.

**Option C: ClickHouse Cloud or Altinity**

If you'd rather not manage ClickHouse infrastructure yourself, both [ClickHouse Cloud](https://clickhouse.cloud) and [Altinity.Cloud](https://altinity.com/cloud-database/) offer hosted ClickHouse. Point `clickhouse-url` at your cloud endpoint and set credentials accordingly.

Check it's up:

```bash
curl -s http://localhost:8123/ping
# → Ok.
```

{% endstep %}

{% step %}

### Apply the DDL

Superbank uses three base tables and several materialized views. Apply the local (single-node) DDL:

```bash
# Base tables
cat ddl/local/transactions.sql    | docker exec -i superbank-clickhouse clickhouse-client --multiquery
cat ddl/local/blocks_metadata.sql | docker exec -i superbank-clickhouse clickhouse-client --multiquery
cat ddl/local/entries.sql         | docker exec -i superbank-clickhouse clickhouse-client --multiquery  # required for the gRPC and Fumarole sources

# Materialized views (derived by ClickHouse at insert time - not by the ingestor)
cat ddl/local/gsfa.sql                | docker exec -i superbank-clickhouse clickhouse-client --multiquery
cat ddl/local/signatures.sql          | docker exec -i superbank-clickhouse clickhouse-client --multiquery
cat ddl/local/token_owner_activity.sql | docker exec -i superbank-clickhouse clickhouse-client --multiquery
```

What each table is for:

| Table/View             | Type              | Contents                                                         |
| ---------------------- | ----------------- | ---------------------------------------------------------------- |
| `transactions`         | Base table        | Every transaction, partitioned by epoch                          |
| `blocks_metadata`      | Base table        | Block-level data: blockhash, height, rewards                     |
| `entries`              | Base table        | PoH entry metadata (Fumarole and gRPC sources only)              |
| `gsfa`                 | Materialized view | Powers `getSignaturesForAddress`, 32-bucket address partitioning |
| `signatures`           | Materialized view | Powers `getSignatureStatuses`, 32-bucket signature partitioning  |
| `token_owner_activity` | Materialized view | Powers token-filtered `getTransactionsForAddress`                |

No filtering happens at the ingest layer. The ingestor writes every transaction from the source as-is into the `transactions` base table. The materialized views are computed by ClickHouse at insert time. This means:

* If an account doesn't appear in a transaction, it won't appear in `gsfa`.
* gSFA exclusions (below) are a DDL concern, not an ingestor concern.
* The base `transactions` table is always the full unfiltered ledger.

#### gSFA default exclusions

By default, four system-level addresses are excluded from the `gsfa` materialized view. They appear in almost every transaction so they'd dominate the index without adding value:

* **System Program**: `11111111111111111111111111111111`
* **Vote Program**: `Vote111111111111111111111111111111111111111`
* **SysvarClock**: `SysvarC1ock11111111111111111111111111111111`
* **SysvarSlotHashes**: `SysvarS1otHashes111111111111111111111111111`

This exclusion is in `ddl/local/gsfa.sql` as the `gsfa_ignored_addresses` array. If you need any of these addresses indexed, remove them from the array before running the DDL:

```sql
-- In ddl/local/gsfa.sql, find this block and remove any address you want to keep:
[
    CAST(base58Decode('11111111111111111111111111111111') AS FixedString(32)),
    CAST(base58Decode('Vote111111111111111111111111111111111111111') AS FixedString(32)),
    CAST(base58Decode('SysvarC1ock11111111111111111111111111111111') AS FixedString(32)),
    CAST(base58Decode('SysvarS1otHashes111111111111111111111111111') AS FixedString(32))
] AS gsfa_ignored_addresses
```

{% endstep %}

{% step %}

### Configure the ingestor

Copy the example config and fill in your endpoint:

```bash
cp superbank.example.yaml superbank.yaml
```

For live ingestion via Dragon's Mouth (gRPC):

```yaml
source: "grpc"

endpoint: "https://<your-endpoint>.mainnet.rpcpool.com:443"
x-token: "<your-token>"
commitment: "finalized"
# "*" = resume from the highest slot already in blocks_metadata on restart (recommended for production).
# 0   = start from the earliest available slot.
dragonsmouth-from-slot: "*"

clickhouse-url: "http://localhost:8123"
clickhouse-database: "default"
clickhouse-user: "default"
clickhouse-password: ""

transactions-table: "default.transactions"
blocks-table: "default.blocks_metadata"
entries-table: "default.entries"
```

For live ingestion via **Fumarole** (persistent consumer group, resumes from where it left off):

```yaml
source: "fumarole"

fumarole-endpoint: "https://ams.rpcpool.com:443"  # regional endpoint; or https://nyc.rpcpool.com:443
fumarole-x-token: "<your-token>"
fumarole-consumer-group: "superbank-mainnet"
fumarole-create-consumer-group: true  # set to false after first run
fumarole-data-plane-tcp-connections: 4       # parallel TCP connections for download; max 20
# fumarole-memory-soft-limit-bytes: 25769803776  # 24 GiB soft limit; set 0 to disable

clickhouse-url: "http://localhost:8123"
clickhouse-database: "default"
clickhouse-user: "default"
clickhouse-password: ""

transactions-table: "default.transactions"
blocks-table: "default.blocks_metadata"
entries-table: "default.entries"
```

On first run you'll see the consumer group created, then data flowing:

```
INFO superbank::ingest::fumarole: starting superbank fumarole ingest source="fumarole" endpoint=https://ams.rpcpool.com:443 consumer_group=superbank-mainnet
INFO superbank::ingest::fumarole: created Fumarole consumer group consumer_group=superbank-mainnet
INFO superbank::clickhouse: clickhouse insert committed table="default.transactions" rows=4051 slot_min=424497433 slot_max=424497435
INFO superbank::clickhouse: clickhouse insert committed table="default.blocks_metadata" rows=3 slot_min=424497433 slot_max=424497435
INFO superbank::clickhouse: clickhouse insert committed table="default.entries" rows=3412 slot_min=424497433 slot_max=424497435
```

After the first run, set `fumarole-create-consumer-group: false`. The group persists on the server and resumes from its last committed position on restart.

Fumarole is generally preferred for production: it uses a persistent consumer group that survives restarts, has at-least-once delivery guarantees, and also populates the `entries` table like the gRPC source. Dragon's Mouth gRPC is simpler for local dev.

For **historical backfill**, there are two approaches depending on scale.

**Large-scale backfill: Jetstreamer + Old Faithful**

For ingesting months or years of history, use the Jetstreamer adapter. By default it reads the public [Old Faithful](https://docs.triton.one/solana/historical-data) archive at `https://files.old-faithful.net`, with no Triton endpoint or token involved. Old Faithful has full history back to genesis and serves data at wire speed, far faster than polling `getBlock` over HTTP. Bound the range with the epoch or slot arguments, and set the trusted bound and commission era shown in the run commands below; see the [Filtering section](#filtering-to-your-own-transactions) for trade-offs if you also want a program filter.

As of Superbank v0.8.0, the adapter uses Agave 4 and records transaction-v1 fields. It backfills only up to the Alpenglow genesis slot, because Jetstreamer doesn't expose the bank and footer data that later blocks need. On mainnet, `getAgGenesisCert` puts that slot at 459,652,999, and the runner clamps a longer range to it. Use the ingestor's `rpc`, Bigtable or gRPC source for later slots; the `rpc` and Bigtable sources also handle transaction-v1 history. The adapter is its own Cargo workspace, outside Superbank's main one, so validate it on a short slot range before a large backfill.

**Small-to-medium backfill: JSON-RPC source**

For shorter ranges (e.g. a few thousand slots), the `rpc` source works well:

```yaml
source: "rpc"

rpc-url: "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>"
rpc-from-slot: 424000000
rpc-slot-count: 10000    # or use rpc-to-slot for an explicit end slot
rpc-max-inflight: 16

clickhouse-url: "http://localhost:8123"
# ... rest same as above
```

Use a Triton HTTP RPC endpoint (available from your [customers.triton.one](https://customers.triton.one) dashboard). Dragon's Mouth is gRPC, so the `rpc` source needs your regular HTTP JSON-RPC endpoint. The `rpc` source calls `getBlock`, which Triton's shared endpoints rate-limit per method (see [Rate and connection limits](https://docs.triton.one/using-your-endpoint/rate-and-connection-limits)), so lower `rpc-max-inflight` (for example to 16) to reduce HTTP 429 errors, or ask support for a higher limit. Triton's endpoints also serve `getBlock` for older slots automatically from their history backends. The public `api.mainnet-beta.solana.com` endpoint rate-limits `getBlock` aggressively; avoid it for any bulk backfill.

#### ClickHouse insert retry

For gRPC, RPC, and Bigtable sources, the ingestor retries failed ClickHouse inserts with exponential backoff. Fumarole is excluded: it manages durability at the consumer-group level.

| Config key             | Env var                           | Default | Description                            |
| ---------------------- | --------------------------------- | ------- | -------------------------------------- |
| `insert-max-retries`   | `CLICKHOUSE_INSERT_MAX_RETRIES`   | `5`     | Maximum retry attempts per batch       |
| `insert-retry-base-ms` | `CLICKHOUSE_INSERT_RETRY_BASE_MS` | `1000`  | Initial retry delay (ms)               |
| `insert-retry-max-ms`  | `CLICKHOUSE_INSERT_RETRY_MAX_MS`  | `30000` | Maximum retry delay after backoff (ms) |
| {% endstep %}          |                                   |         |                                        |

{% step %}

### Start the ingestor

```bash
./target/release/superbank --config superbank.yaml
```

You'll see log lines as blocks are ingested. The ingestor writes to `transactions`, `blocks_metadata`, and `entries`. ClickHouse materializes the views (`gsfa`, `signatures`, `token_owner_activity`) in the background as rows arrive.

Example output (RPC backfill source):

```
INFO superbank: starting name="superbank" version="0.8.0"
INFO superbank::ingest::rpc: starting superbank ingest source="rpc" from_slot=424274200 to_slot=424274209
INFO superbank::clickhouse: clickhouse insert committed table="default.transactions" rows=1582 slot=424274200 progress_percent=100.0
INFO superbank::clickhouse: clickhouse insert committed table="default.blocks_metadata" rows=1 slot=424274200
```

Example output (gRPC / Dragon's Mouth live source):

```
INFO superbank: starting name="superbank" version="0.8.0"
INFO superbank::ingest::grpc: starting superbank ingest source="grpc" endpoint=https://<your-endpoint>.mainnet.rpcpool.com:443
INFO superbank::ingest::grpc: gRPC health check passed status="serving"
INFO superbank::ingest::grpc: subscribed to gRPC stream from_slot=424432530
INFO superbank::clickhouse: clickhouse insert committed table="default.transactions" rows=2387 slot_min=424432637 slot_max=424432638
INFO superbank::clickhouse: clickhouse insert committed table="default.entries" rows=1221 slot_min=424432637 slot_max=424432638
```

The gRPC source also populates the `entries` table (PoH entry metadata); the RPC backfill source does not.

Check that data is landing:

```bash
docker exec superbank-clickhouse clickhouse-client --query "SELECT count() FROM default.transactions"
# → 13950

docker exec superbank-clickhouse clickhouse-client --query "SELECT max(slot) FROM default.transactions"
# → 424274209
```

{% endstep %}

{% step %}

### Start the RPC server

```bash
CLICKHOUSE_URL=http://localhost:8123 \
CLICKHOUSE_DATABASE=default \
CLICKHOUSE_USER=default \
CLICKHOUSE_PASSWORD="" \
CLICKHOUSE_CLUSTER="" \
CLICKHOUSE_GSFA_TABLE=default.gsfa \
CLICKHOUSE_SIGNATURE_STATUSES_TABLE=default.signatures \
CLICKHOUSE_TOKEN_OWNER_ACTIVITY_TABLE=default.token_owner_activity \
CLICKHOUSE_TRANSACTION_TABLE=default.transactions \
CLICKHOUSE_BLOCKS_METADATA_TABLE=default.blocks_metadata \
./target/release/superbank-rpc
```

`CLICKHOUSE_CLUSTER=""` marks the ClickHouse server as a single node with no cluster. Without it, superbank-rpc resolves the default `{cluster}` macro at startup, and startup fails on a single-node server. For a ClickHouse cluster, keep the default or set the cluster name.

By default, all JSON-RPC responses use HTTP `200 OK`, including error bodies. To return HTTP `503 Service Unavailable` on server-side failures (useful for load balancers that route on HTTP status), add `--emit-http-errors` or set `SUPERBANK_RPC_EMIT_HTTP_ERRORS=true`. Only internal errors (`-32603`), timeouts (`-32000`), node unhealthy (`-32005`), and storage unreachable (`-32019`) are promoted to HTTP 503; client and data-condition errors remain 200 OK.

Test it:

```bash
curl -s http://localhost:8899 \
  -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}' | jq .
# → {"jsonrpc":"2.0","result":"ok","id":1}

curl -s http://localhost:8899 \
  -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getFirstAvailableBlock"}' | jq .
# → {"jsonrpc":"2.0","result":424274200,"id":1}

curl -s http://localhost:8899 \
  -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getTransaction","params":["<signature>",{"encoding":"json","maxSupportedTransactionVersion":1}]}' | jq '{slot: .result.slot, blockTime: .result.blockTime, fee: .result.meta.fee}'
# → {"slot": 424274200, "blockTime": 1780588286, "fee": 5000}

curl -s http://localhost:8899 \
  -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getBlock","params":[424274200,{"encoding":"json","maxSupportedTransactionVersion":1,"transactionDetails":"signatures"}]}' | jq '{blockhash: .result.blockhash, blockHeight: .result.blockHeight, numSignatures: (.result.signatures | length)}'
# → {"blockhash": "Hpk2nu2vYpfMVNuW363vtc1JgMWkuCkgkjWVYyKfU14A", "blockHeight": 402357051, "numSignatures": 1582}

# Triton extension - paginated transaction history with full tx data
curl -s http://localhost:8899 \
  -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getTransactionsForAddress","params":["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",{"transactionDetails":"full","limit":3,"maxSupportedTransactionVersion":1}]}' | jq '{count: (.result.data | length), firstSlot: .result.data[0].slot}'
# → {"count": 3, "firstSlot": 424497440}
```

Pass `maxSupportedTransactionVersion` with full transaction results from `getTransactionsForAddress`. Set it to `1` to accept legacy, v0 and transaction-v1 results; each result then includes a `version` field (`"legacy"`, `0`, or `1`). Without it, legacy results omit `version`, and the request fails with error `-32015` if any result is a v0 or v1 transaction.

Your Superbank instance is now serving Solana-compatible RPC at `:8899`.
{% endstep %}
{% endstepper %}

## Filtering to your own transactions

By default, Superbank ingests every transaction on the network. If you want a targeted history, say, only transactions involving your program, there are two approaches with very different trade-offs.

### Recommended: filter by time range, ingest everything

The safest approach is to pick the time window you care about and ingest every transaction in it, without any program filter. This keeps your derived tables (`gsfa`, `token_owner_activity`) and synthesized methods (`getBlock`, `getTransactionsForAddress`, `getSignaturesForAddress`) fully accurate: they depend on having the complete transaction set for every block in the indexed range.

Use the `rpc-from-slot` / `rpc-to-slot` parameters (or the Jetstreamer epoch argument) to bound the range:

```yaml
# superbank.yaml - ingest a specific slot range, no program filter
source: "rpc"
rpc-url: "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>"
rpc-from-slot: 420000000
rpc-to-slot:   425000000
rpc-max-inflight: 16
clickhouse-url: "http://localhost:8123"
```

This is the approach to use for any production instance where downstream consumers will call gSFA, gTFA, or `getBlock`.

### Advanced: filter by program (breaks derived methods)

{% hint style="warning" %}
Filtering by program produces an incomplete transaction set. The following RPC methods will return incorrect or empty results:

* `getSignaturesForAddress`: misses signatures for addresses that appeared in filtered-out transactions
* `getTransactionsForAddress`: same
* `getBlock`: blocks will appear to have fewer transactions than they actually did

Use this only if you are building a purpose-specific index where you control the query surface and explicitly do not need those methods.
{% endhint %}

The Jetstreamer adapter is in `ingest/jetstreamer-clickhouse-plugin/src/lib.rs`. The filter is a 1-2 line addition to the `on_transaction` method.

**Before (current `on_transaction`):**

```rust
fn on_transaction<'a>(
    &'a self,
    thread_id: usize,
    db: Option<Arc<Client>>,
    transaction: &'a TransactionData,
) -> PluginFuture<'a> {
    async move {
        let Some(db) = self.resolve_db(db) else {
            return Ok(());
        };
        self.ensure_legacy_slot(transaction.slot)?;
        let row = TransactionRow::from_transaction(transaction);
        // ... buffers the row for this slot
```

**After: add a program filter at the top of the async block.**

The plugin already has a `parse_pubkey_bytes` helper that decodes a base58 address to `[u8; 32]`. Use that to avoid adding a new dependency:

```rust
// Add near the bottom of lib.rs (outside the impl block, before parse_pubkey_bytes):
fn my_program_id() -> [u8; 32] {
    parse_pubkey_bytes("YourProgramPubkeyHere")
        .expect("valid program pubkey")
}

// In on_transaction, add three lines at the top of the async block:
fn on_transaction<'a>(
    &'a self,
    thread_id: usize,
    db: Option<Arc<Client>>,
    transaction: &'a TransactionData,
) -> PluginFuture<'a> {
    async move {
        // Filter: only ingest transactions that involve our program
        let program = my_program_id();
        if !transaction.transaction.message.static_account_keys().iter().any(|k| k.to_bytes() == program) {
            return Ok(());  // skip this transaction
        }

        let Some(db) = self.resolve_db(db) else {
            return Ok(());
        };
        // ... rest of the function unchanged
```

The `static_account_keys()` slice contains every static account referenced in the transaction: fee payer, program IDs, and all account operands. If your program ID appears anywhere, the transaction passes the filter.

**To filter by multiple programs** (e.g. your program and a token program it interacts with):

```rust
fn is_relevant(transaction: &TransactionData) -> bool {
    const PROGRAMS: &[&str] = &[
        "YourProgramPubkeyHere",
        "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
    ];
    let keys = transaction.transaction.message.static_account_keys();
    PROGRAMS.iter().any(|p| {
        if let Some(bytes) = parse_pubkey_bytes(p) {
            keys.iter().any(|k| k.to_bytes() == bytes)
        } else {
            false
        }
    })
}

// In on_transaction:
if !is_relevant(transaction) {
    return Ok(());
}
```

After adding the filter, rebuild and run:

```bash
cd ingest/jetstreamer-clickhouse-plugin

# Rebuild
cargo build --release

# Required: exactly one trusted historical bound, the slot from getAgGenesisCert
export JETSTREAMER_ALPENGLOW_GENESIS_SLOT=<trusted-genesis-slot>
# or, on a cluster where getAgGenesisCert is still null: JETSTREAMER_PREACTIVATION_THROUGH_SLOT=<recorded-finalized-slot>

# Required: exactly one block reward commission era
export JETSTREAMER_BLOCK_REWARD_COMMISSION_BPS_FROM_SLOT=<trusted-SIMD-0291-slot>
# or, for a range entirely before SIMD-0291: JETSTREAMER_BLOCK_REWARD_COMMISSION_PERCENT=true

# Run for a specific epoch
./target/release/jetstreamer-clickhouse 800

# Or for a specific slot range
./target/release/jetstreamer-clickhouse 424000000:424100000
```

The runner exits at startup if either setting is missing or ambiguous. On mainnet, the SIMD-0291 feature account (`Eg7tXEwMZzS98xaZ1YHUbdRHsaYZiCsSaR6sKgxreoaj`) records activation at slot 433,296,000. See the [plugin README](https://github.com/solana-rpc/superbank/blob/v0.8.0/ingest/jetstreamer-clickhouse-plugin/README.md) for the evidence each setting needs.

## Optional: processed commitment with the gRPC head cache

By default, the RPC server supports `confirmed` and `finalized` commitment. To also serve `processed` commitment (latest tip, sub-slot latency), enable the head cache:

```bash
# Build with the feature enabled
cargo build --release -p superbank-rpc --features grpc-head-cache
```

Then start the RPC server with the head cache pointed at a Dragon's Mouth endpoint, alongside the env vars from the RPC server step:

```bash
HEAD_CACHE_ENABLED=true \
DRAGONSMOUTH_ENDPOINT=https://<your-endpoint>.mainnet.rpcpool.com:443 \
DRAGONSMOUTH_X_TOKEN=<your-token> \
HEAD_CACHE_RETAIN_SLOTS=32 \
HEAD_CACHE_MIN_COMMITMENT=processed \
CLICKHOUSE_URL=http://localhost:8123 \
CLICKHOUSE_DATABASE=default \
CLICKHOUSE_USER=default \
CLICKHOUSE_PASSWORD="" \
CLICKHOUSE_CLUSTER="" \
CLICKHOUSE_GSFA_TABLE=default.gsfa \
CLICKHOUSE_SIGNATURE_STATUSES_TABLE=default.signatures \
CLICKHOUSE_TOKEN_OWNER_ACTIVITY_TABLE=default.token_owner_activity \
CLICKHOUSE_TRANSACTION_TABLE=default.transactions \
CLICKHOUSE_BLOCKS_METADATA_TABLE=default.blocks_metadata \
./target/release/superbank-rpc
```

On startup you'll see the head cache subscribe to Dragon's Mouth:

```
INFO superbank_rpc: starting name="superbank-rpc" version="0.8.0"
INFO superbank_rpc::server: RPC server listening on http://0.0.0.0:8899
INFO superbank_rpc::head_cache::dragonsmouth: head cache: subscribed to DragonsMouth endpoint="https://<your-endpoint>.mainnet.rpcpool.com:443" min_commitment=Processed
```

Test all three commitment levels:

```bash
curl -s http://localhost:8899 \
  -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSlot","params":[{"commitment":"processed"}]}' | jq .result
# → 424467184   (latest tip)

curl -s http://localhost:8899 \
  -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSlot","params":[{"commitment":"confirmed"}]}' | jq .result
# → 424467183   (1 slot behind processed)

curl -s http://localhost:8899 \
  -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSlot","params":[{"commitment":"finalized"}]}' | jq .result
# → 424432638   (from ClickHouse)
```

The cache holds the last `HEAD_CACHE_RETAIN_SLOTS` slots in memory and merges them with ClickHouse results for `getTransaction` and `getSignatureStatuses` queries, plus `getSignaturesForAddress`, `getTransactionsForAddress`, `getBlockHeight`, `getSlot`, `getTransactionCount`, `getLatestBlockhash`, `isBlockhashValid`, `getBlocks`, and `getBlocksWithLimit`. These 11 methods accept `processed`. `getBlock` and `getBlockTime` also read recent blocks from the cache, but `getBlock` still requires `confirmed` or `finalized`.

{% hint style="info" %}
**RAM requirement.** The head cache itself is lightweight: at the default of 32 slots, it holds \~32 × 1,500 mainnet transactions worth of metadata in memory, typically under 500 MB. The dominant memory cost is ClickHouse: for a full mainnet history, plan for at least 32 GB RAM on the ClickHouse host (64 GB+ for comfortable production operation). The `superbank` and `superbank-rpc` binaries themselves each use well under 2 GB.
{% endhint %}

{% hint style="info" %}
The `grpc-head-cache` feature opens a separate live Dragon's Mouth subscription. This is why it's an opt-in compile feature rather than the default.
{% endhint %}

## Optional: gRPC streaming (`grpc-streaming`)

When compiled with `--features grpc-streaming` and enabled at runtime, the RPC server exposes a tonic gRPC endpoint alongside JSON-RPC. The current implementation supports historical `StreamBlocks` and `StreamTransactions` over bounded inclusive slot ranges from ClickHouse.

`StreamBlocks` returns one message per matching block with block metadata, rewards, and transaction payloads. `StreamTransactions` returns one message per matching transaction. `StreamBlocks` filters only on `account_include`. `StreamTransactions` supports account include/exclude/required filters, vote filtering, and failed/success filtering.

Build with the feature:

```bash
cargo build --release -p superbank-rpc --features grpc-streaming
```

Then start with gRPC enabled (add alongside the env vars from the RPC server step):

```bash
SUPERBANK_GRPC_ENABLED=true \
SUPERBANK_GRPC_PORT=10000 \
./target/release/superbank-rpc
```

Configuration:

| Flag                                      | Env var                                 | Default     | Description                                     |
| ----------------------------------------- | --------------------------------------- | ----------- | ----------------------------------------------- |
| `--superbank-grpc-enabled`                | `SUPERBANK_GRPC_ENABLED`                | `false`     | Enable gRPC endpoint at runtime                 |
| `--superbank-grpc-host`                   | `SUPERBANK_GRPC_HOST`                   | `0.0.0.0`   | Bind host                                       |
| `--superbank-grpc-port`                   | `SUPERBANK_GRPC_PORT`                   | `10000`     | Bind port                                       |
| `--superbank-grpc-max-slot-range`         | `SUPERBANK_GRPC_MAX_SLOT_RANGE`         | `100`       | Maximum inclusive slots per stream request      |
| `--superbank-grpc-query-timeout-ms`       | `SUPERBANK_GRPC_QUERY_TIMEOUT_MS`       | `30000`     | Per-chunk ClickHouse range-query timeout (ms)   |
| `--superbank-grpc-chunk-slots`            | `SUPERBANK_GRPC_CHUNK_SLOTS`            | `8`         | Slots fetched from ClickHouse per chunk         |
| `--superbank-grpc-max-send-bytes`         | `SUPERBANK_GRPC_MAX_SEND_BYTES`         | `104857600` | Max encoded gRPC response message size (100 MB) |
| `--superbank-grpc-max-concurrent-streams` | `SUPERBANK_GRPC_MAX_CONCURRENT_STREAMS` | `20`        | HTTP/2 concurrent stream limit                  |

## Optional: disk cache (`disk-cache`)

When compiled with `--features disk-cache` and enabled at runtime, superbank-rpc forwards recent **finalized** slots from the source ClickHouse cluster to a separate ClickHouse instance on localhost. The feature is independent of `grpc-head-cache`. The read tiering becomes:

```
head cache (optional, unfinalized tip) → local ClickHouse cache (finalized, recent slots) → source ClickHouse (full history)
```

At startup, superbank-rpc copies the required schema from the source into a local database that it owns exclusively, then streams `transactions` and `blocks_metadata` into it. Local materialized views build the query indexes, and coverage becomes readable only after it validates. Any miss, hole, local query error, or unavailable local instance falls through to the source cluster.

Methods served from the local cache when covered: `getBlock`, `getBlocks`, `getBlocksWithLimit`, `getBlockTime`, `getTransaction`, `getSignatureStatuses`, `getSignaturesForAddress`, and `getTransactionsForAddress` (including `tokenAccounts` filters).

{% hint style="warning" %}
`DISK_CACHE_RETAIN_SLOTS` is required and has no default. `DISK_CACHE_MAX_BYTES` caps the cache database by evicting complete old partitions. A budget that's too small can purge the newest partition and leave the cache unready.
{% endhint %}

The source ClickHouse user needs read access to the copied tables and their metadata. The local ClickHouse user needs permission to create and drop the dedicated database, create and alter its tables, and read and insert its data. The local endpoint must use `localhost` or a loopback IP; it can use a different port when the source ClickHouse runs on the same host.

```bash
# Build with the independent disk-cache feature
cargo build --release -p superbank-rpc --features disk-cache

# Run with a source cluster and a separate local ClickHouse HTTP endpoint
RPC_HOST=0.0.0.0 RPC_PORT=8899 \
CLICKHOUSE_URL=http://source-clickhouse:8123 CLICKHOUSE_DATABASE=default \
DISK_CACHE_ENABLED=true DISK_CACHE_RETAIN_SLOTS=432000 \
DISK_CACHE_CLICKHOUSE_URL=http://127.0.0.1:8123 \
DISK_CACHE_CLICKHOUSE_DATABASE=superbank_disk_cache \
./target/release/superbank-rpc
```

Key configuration options:

| Option                             | Environment                      | Default                 | Notes                                                                |
| ---------------------------------- | -------------------------------- | ----------------------- | -------------------------------------------------------------------- |
| `--disk-cache-enabled`             | `DISK_CACHE_ENABLED`             | `false`                 | Enable at runtime                                                    |
| `--disk-cache-clickhouse-url`      | `DISK_CACHE_CLICKHOUSE_URL`      | <http://127.0.0.1:8123> | Local ClickHouse HTTP endpoint; loopback only                        |
| `--disk-cache-retain-slots`        | `DISK_CACHE_RETAIN_SLOTS`        | `(none)`                | Finalized slots to retain; required when enabled                     |
| `--disk-cache-max-bytes`           | `DISK_CACHE_MAX_BYTES`           | `0`                     | Byte budget for the cache database; 0 = unlimited                    |
| `--disk-cache-clickhouse-database` | `DISK_CACHE_CLICKHOUSE_DATABASE` | `superbank_disk_cache`  | Dedicated database owned by the cache                                |
| `--disk-cache-required`            | `DISK_CACHE_REQUIRED`            | `false`                 | Require local initialization at startup and local health for /health |
| `--disk-cache-backfill-enabled`    | `DISK_CACHE_BACKFILL_ENABLED`    | `true`                  | Source-to-local forward and repair task                              |

Observability: `superbank_disk_cache_*` metrics cover readiness, local ClickHouse bytes, coverage, read outcomes, forwarding, errors, rebuilds, and partition eviction. The `X-Superbank-Sources` response header reports `disk-cache` when the local tier contributes.

Parity validation and performance comparison scripts are in `tests/k6/scenarios/validation/superbank-rpc-disk-cache-parity.js` and `tests/k6/scenarios/performance/superbank-rpc-disk-cache-compare.js`.

{% hint style="info" %}
The RocksDB settings `DISK_CACHE_PATH`, `DISK_CACHE_BLOCK_CACHE_BYTES`, `DISK_CACHE_WRITE_QUEUE_SLOTS`, and `DISK_CACHE_READ_CONCURRENCY` were removed; setting any of them now fails with a configuration error. By default, local initialization is fail-open: the RPC server starts against the source cluster and retries the local cache in the background. Set `DISK_CACHE_REQUIRED=true` to make initialization and health strict.
{% endhint %}

## Going to production

### Use replicated DDL for HA

For a production multi-node setup, use `ddl/replicated/` instead of `ddl/local/`. This requires ClickHouse Keeper or ZooKeeper and uses `ReplicatedReplacingMergeTree`. The DDL commands follow the same pattern as the local setup:

```bash
cat ddl/replicated/transactions.sql    | docker exec -i superbank-clickhouse clickhouse-client --multiquery
cat ddl/replicated/blocks_metadata.sql | docker exec -i superbank-clickhouse clickhouse-client --multiquery
cat ddl/replicated/gsfa.sql            | docker exec -i superbank-clickhouse clickhouse-client --multiquery
# ... etc for other tables
```

Note: the replicated tables will fail to create if ClickHouse Keeper or ZooKeeper is not configured and reachable. Set up your Keeper cluster before applying this DDL. The `ddl/local/` variant used in this guide does not have this requirement.

### Use Fumarole as the ingestion source

Fumarole is the recommended source for production:

* Persistent consumer groups survive ingestor restarts
* At-least-once delivery with commit checkpoints
* Lower reconnect risk than raw gRPC streaming

Set `source: fumarole` in your YAML and configure `fumarole-consumer-group`. After the first run, set `fumarole-create-consumer-group: false`.

### Metrics

Both binaries expose Prometheus metrics at `/metrics`:

* Ingestor: `http://<host>:9901/metrics`
* RPC server: `http://<host>:9900/metrics`

**Key RPC server metrics:**

| Metric                                              | What it tells you                                                            |
| --------------------------------------------------- | ---------------------------------------------------------------------------- |
| `superbank_rpc_requests_total{method,status}`       | Request count per method: track error rate by filtering `status!="200"`      |
| `superbank_rpc_response_time_seconds{method}`       | Full end-to-end latency histogram: use for p50/p95/p99                       |
| `superbank_rpc_clickhouse_duration_seconds{method}` | Time spent in ClickHouse per method: isolates DB vs overhead                 |
| `superbank_rpc_inflight_requests{method}`           | Concurrent in-flight requests: spike indicates backpressure                  |
| `superbank_rpc_route_total_total{method,outcome}`   | Routing outcomes: watch for `outcome="backend_error"` or `outcome="timeout"` |
| `superbank_head_cache_active`                       | `1` = head cache connected to Dragon's Mouth; `0` = disconnected             |
| `superbank_head_cache_latest_slot`                  | Most recent slot in cache: compare to chain tip to measure lag               |
| `superbank_process_resident_memory_bytes`           | Resident memory used by the RPC process                                      |

**Key ingestor metrics (`:9901`):**

The ingestor tracks insert throughput, batch sizes, and ClickHouse write latency. Watch for any sustained gap between the max ingested slot and the chain tip: this indicates the ingestor is falling behind.

The ingestor also exposes a liveness health check at `http://<host>:9901/health`. It returns `200 OK` while flushing normally, and `503 Service Unavailable` when no successful ClickHouse flush has occurred within `health-stale-secs` seconds (default: 120). Set `health-stale-secs: 0` in your config to disable the staleness check. Add `METRICS_CLUSTER_LABEL` to attach a static `cluster="..."` label to all ingestor metrics, useful for multi-cluster Prometheus setups.

When running the Fumarole source, the following additional gauges and counters are emitted:

| Metric                                                   | Description                                                               |
| -------------------------------------------------------- | ------------------------------------------------------------------------- |
| `superbank_ingest_fumarole_memory_soft_limit_bytes`      | Configured memory soft limit                                              |
| `superbank_ingest_fumarole_buffered_bytes`               | Estimated assembler bytes in memory                                       |
| `superbank_ingest_fumarole_pending_slots`                | Slots waiting to flush                                                    |
| `superbank_ingest_fumarole_rss_bytes`                    | Process RSS sampled by the memory guard                                   |
| `superbank_ingest_fumarole_pressure_flushes_total_total` | Backpressure-triggered flushes (rising counter indicates memory pressure) |

**Example Prometheus queries:**

```promql
# p99 RPC latency per method
histogram_quantile(0.99, sum by (le, method) (rate(superbank_rpc_response_time_seconds_bucket[5m])))

# Error rate across all methods
sum(rate(superbank_rpc_requests_total{status!="200"}[5m]))
  / sum(rate(superbank_rpc_requests_total[5m]))

# ClickHouse query time p95
histogram_quantile(0.95, sum by (le, method) (rate(superbank_rpc_clickhouse_duration_seconds_bucket[5m])))
```

## What's next

* **Kubernetes**: `deploy/k8s/` has manifests for local development with Tilt and Kind, covering ClickHouse, the DDL init job, superbank-rpc, and both ingestion modes.
* **Load testing**: `tests/k6/` has k6 scenarios for all RPC methods, including validation tests that compare your Superbank instance against a reference RPC.
* **Triton hosted**: if you'd rather not operate ClickHouse and the ingestor yourself, Triton runs Superbank as a managed service. Same RPC interface, no infra.

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# End-to-end transaction pipeline with @solana/kit

Build, sign, send, and confirm a Solana transaction end to end with @solana/kit, adapted from the Ping Thing client.

This guide is adapted from the Ping Thing client to show how to perform common operations with the `@solana/kit` SDK (formerly `@solana/web3.js` 2). The Ping Thing is a collection of independent scripts that continuously send transactions to the chain to measure transaction landing time and slot latency.

It sends three types of transactions:

* SOL transfer
* Token transfer (USDC)
* Jupiter swaps (SOL to USDC)

Between them these cover some of the most common codepaths anyone hits when interacting with Solana. The walkthrough below uses the SOL transfer path. The Ping Thing repository has since been archived and is now Rust only, so its current source won't match the TypeScript here. Source: [ping-thing-client on GitHub](https://github.com/Block-Logic/ping-thing-client).

{% hint style="info" %}
`@solana/kit` ships as independent packages to support modular design and tree shakeability. Import only what you use.
{% endhint %}

## Imports

```bash
npm install @solana/kit @solana/transaction-confirmation @solana-program/system @solana-program/compute-budget bs58
```

The snippets use top-level `await`, so run them as an ES module (`"type": "module"` in `package.json`) or as `.mts`.

```typescript
import {
  createTransactionMessage,
  pipe,
  setTransactionMessageFeePayer,
  setTransactionMessageLifetimeUsingBlockhash,
  createKeyPairFromBytes,
  getAddressFromPublicKey,
  createSignerFromKeyPair,
  signTransaction,
  appendTransactionMessageInstructions,
  assertIsTransactionWithinSizeLimit,
  sendTransactionWithoutConfirmingFactory,
  createSolanaRpcSubscriptions_UNSTABLE,
  getSignatureFromTransaction,
  compileTransaction,
  createSolanaRpc,
  type Signature,
} from "@solana/kit";
import { getSetComputeUnitLimitInstruction, getSetComputeUnitPriceInstruction } from "@solana-program/compute-budget";
import { getTransferSolInstruction } from "@solana-program/system";
import { createRecentSignatureConfirmationPromiseFactory } from "@solana/transaction-confirmation";
import bs58 from "bs58";
```

## Shared state

Declare this once, after the imports. Set `RPC_ENDPOINT`, `WS_ENDPOINT` and `WALLET_PRIVATE_KEYPAIR` in the environment.

```typescript
const RPC_ENDPOINT = process.env.RPC_ENDPOINT!; // https://<your-endpoint>.mainnet.rpcpool.com/<your-token>
const WS_ENDPOINT = process.env.WS_ENDPOINT!; // wss://<your-endpoint>.mainnet.rpcpool.com/<your-token>
const PRIORITY_FEE_MICRO_LAMPORTS = 1000;
const abortController = new AbortController();
const gSlotSent = { value: 0n, updated_at: 0 };
let attempts = 0;
let signature: Signature;
```

## Build the pipeline

{% stepper %}
{% step %}

### Create RPC and websocket connections

Establish two connections: one for HTTP RPC calls and one for websocket subscriptions.

```typescript
// RPC connection for HTTP API calls, equivalent to `const c = new Connection(RPC_ENDPOINT)`
const rpcConnection = createSolanaRpc(RPC_ENDPOINT);

// RPC connection for websocket connection
const rpcSubscriptions = createSolanaRpcSubscriptions_UNSTABLE(WS_ENDPOINT);
```

{% endstep %}

{% step %}

### Fetch the latest blockhash

Data-fetching RPC calls use a builder that you finish with `.send()`. Always call `send()` after the method. The transaction in the next steps uses this blockhash as its lifetime.

```typescript
const latestBlockhash = await rpcConnection.getLatestBlockhash().send();
```

{% endstep %}

{% step %}

### Load the keypair from the environment

Load the keypair the pinger uses to sign transactions from an environment variable.

```typescript
const USER_KEYPAIR = await createKeyPairFromBytes(
    bs58.decode(process.env.WALLET_PRIVATE_KEYPAIR!)
);
```

{% endstep %}

{% step %}

### Derive the fee-payer address and signer

The keypair gives you the fee-payer address and the signer for the transactions you create.

```typescript
const feePayer = await getAddressFromPublicKey(USER_KEYPAIR.publicKey);
const signer = await createSignerFromKeyPair(USER_KEYPAIR);
```

{% endstep %}

{% step %}

### Create the transaction

Build a SOL transfer transaction with `pipe`, setting version, fee payer, blockhash, and the instructions. The compute unit limit and price instructions set best-practice compute limits and a priority fee.

```typescript
const transaction = pipe(
  createTransactionMessage({ version: 0 }),
  (tx) => setTransactionMessageFeePayer(feePayer, tx),
  (tx) =>
    setTransactionMessageLifetimeUsingBlockhash(latestBlockhash.value, tx),
  (tx) =>
    appendTransactionMessageInstructions(
      [
        getSetComputeUnitLimitInstruction({
          units: 500,
        }),
        getSetComputeUnitPriceInstruction({ microLamports: BigInt(PRIORITY_FEE_MICRO_LAMPORTS) }),

        // SOL transfer instruction
        getTransferSolInstruction({
          source: signer,
          destination: feePayer,
          amount: 5000,
        }),
      ],
      tx
    )
);
```

{% hint style="info" %}
The Ping Thing follows [best practices for transaction sending](https://docs.triton.one/solana/sending-transactions), including blockhash management and compute limits. See its [blockhash management source](https://github.com/Block-Logic/ping-thing-client/blob/main/src/utils/blockhash.rs).
{% endhint %}
{% endstep %}

{% step %}

### Sign the transaction

Compile the transaction message, sign it with the keypair, check that it fits Solana's transaction size limit, then read the signature off the signed transaction.

```typescript
// Sign the tx
const transactionSignedWithFeePayer = await signTransaction(
  [USER_KEYPAIR],
  compileTransaction(transaction)
);

// The sender factory only accepts transactions checked against the size limit
assertIsTransactionWithinSizeLimit(transactionSignedWithFeePayer);

// Get the tx signature
signature = getSignatureFromTransaction(transactionSignedWithFeePayer);
```

{% endstep %}

{% step %}

### Send the transaction

Create a sender via `sendTransactionWithoutConfirmingFactory`, then send. Factories let you assemble custom sending strategies.

```typescript
// Create a sender factory that sends a transaction and doesn't wait for confirmation
const mSendTransaction = sendTransactionWithoutConfirmingFactory({
  rpc: rpcConnection,
});

// Send the tx
await mSendTransaction(transactionSignedWithFeePayer, {
  commitment: "confirmed",
  maxRetries: 0n,
  skipPreflight: true,
});
```

{% endstep %}

{% step %}

### Confirm the transaction

Create a confirmation promise factory bound to both the RPC and the subscriptions connection, then await confirmation for the signature.

```typescript
// Create a promise factory that has the logic for the tx to be confirmed
const getRecentSignatureConfirmationPromise =
  createRecentSignatureConfirmationPromiseFactory({
    rpc: rpcConnection,
    rpcSubscriptions,
  });

await getRecentSignatureConfirmationPromise({
  signature,
  commitment: "confirmed",
  abortSignal: abortController.signal,
})
```

{% endstep %}
{% endstepper %}

## Subscribing to slot updates

Subscriptions are based on [`AsyncIterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncIterator). This creates a [`slotsUpdatesSubscribe`](https://solana.com/docs/rpc/websocket/slotsupdatessubscribe) subscription and updates a global slot value.

```typescript
// Subscribing to the `slotsUpdatesSubscribe` and update slot number
// https://solana.com/docs/rpc/websocket/slotsupdatessubscribe
const slotNotifications = await rpcSubscriptions
  .slotsUpdatesNotifications()
  .subscribe({ abortSignal: abortController.signal });

// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncIterator
for await (const notification of slotNotifications) {
  if (
    notification.type === "firstShredReceived" ||
    notification.type === "completed"
  ) {
    gSlotSent.value = notification.slot;
    gSlotSent.updated_at = Date.now();
    attempts = 0;
    continue;
  }
}
```

## Why everything is behind factories

Sending and confirming come from factory functions such as `sendTransactionWithoutConfirmingFactory` and `createRecentSignatureConfirmationPromiseFactory`. The reasons:

* Bind multiple RPC interfaces together so you do not pass them separately.
* Assemble the strategy (do x, y, z in a particular order).
* Create a closure that retains state spanning multiple invocations across your app.

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Query token program

Query SPL token accounts by mint or owner with getProgramAccounts.

## Query by mint

You can query all the token accounts by mint using getProgramAccounts.

### Original token program

When querying the original token program it is important to specify dataSize as 165 to ensure that you are querying only valid token accounts.

{% tabs %}
{% tab title="getProgramAccounts" %}

```json
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getProgramAccounts",
    "params": [
      "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
      {
        "filters": [
          {
              "dataSize": 165
          },
          {
            "memcmp": {
              "offset": 0,
              "bytes": "j14XLJZSVMcUYpAfajdZRpnfHUpJieZHS4aPektLWvh"
            }
          }
        ],
        "encoding": "base64"
      }
    ] 
}
```

{% endtab %}
{% endtabs %}

### Token-2022

When querying Token-2022, you do not add the dataSize parameter but instead filter by the byte at offset 165.

{% tabs %}
{% tab title="getProgramAccounts" %}

```json
{
    "jsonrpc":"2.0",
    "id":1,
    "method":"getProgramAccounts",
    "params":[
        "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb",
        {
            "filters": [
                {"memcmp": {"offset":0, "bytes": "FRAGJ157KSDfGvBJtCSrsTWUqFnZhrw4aC8N8LqHuoos"}},
                {"memcmp": {"offset":165,"bytes": "3" }
                }
            ],
            "encoding": "base64",
            "commitment":"confirmed"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Query by owner

The standard method for querying by owner is [`getTokenAccountsByOwner`](https://solana.com/docs/rpc/http/gettokenaccountsbyowner). You can also use getProgramAccounts to query the same data, with the added possibility of more advanced filtering.

### Original token program

{% tabs %}
{% tab title="getTokenAccountsByOwner" %}

```json
{
   "jsonrpc": "2.0",
   "id": 1,
   "method": "getTokenAccountsByOwner",
   "params": [
     "B4aJyVCibxP1J95RccZ57DPJWEfkkzUDbm9DuFD9bonk",
     {
       "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
     },
     {
       "commitment": "finalized",
       "encoding": "jsonParsed"
     }
   ]
}
```

{% endtab %}

{% tab title="getProgramAccounts" %}

```json
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getProgramAccounts",
    "params": [
      "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
      {
        "filters": [
          {
              "dataSize": 165
          },
          {
            "memcmp": {
              "offset": 32,
              "bytes": "B4aJyVCibxP1J95RccZ57DPJWEfkkzUDbm9DuFD9bonk"
            }
          }
        ],
        "encoding": "base64",
        "commitment": "confirmed"
      }
    ] 
}
```

{% endtab %}
{% endtabs %}

### Token-2022

{% tabs %}
{% tab title="getTokenAccountsByOwner" %}

```json
{
   "jsonrpc": "2.0",
   "id": 1,
   "method": "getTokenAccountsByOwner",
   "params": [
     "pumpCmXqMfrsAkQ5r49WcJnRayYRqmXz6ae8H7H9Dfn",
     {
       "programId": "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb"
     },
     {
       "commitment": "finalized",
       "encoding": "jsonParsed"
     }
   ]
}
```

{% endtab %}

{% tab title="getProgramAccounts" %}

```json
{
    "jsonrpc":"2.0",
    "id":1,
    "method":"getProgramAccounts",
    "params":[
        "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb",
        {
            "filters": [
                {"memcmp": {"offset":32, "bytes": "pumpCmXqMfrsAkQ5r49WcJnRayYRqmXz6ae8H7H9Dfn"}},
                {"memcmp": {"offset":165,"bytes": "3" }
                }
            ],
            "encoding": "base64",
            "commitment":"confirmed"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Troubleshooting

On Triton shared endpoints, a `getProgramAccounts` call to the Token or Token-2022 program must include a `memcmp` filter on the owner (offset `32`) or the mint (offset `0`), as in the examples above. Without one, the call is rejected with HTTP `403` and the message "Your IP or provider is blocked from this endpoint".

An endpoint that doesn't index the Token program returns this error instead:

```
TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA excluded from account secondary indexes; this RPC method unavailable for key
```

In both cases, check that your query includes the owner or mint `memcmp` filter and, for the original Token program, `dataSize: 165`. If you are still facing errors, please contact us via our customer support channels.

## Digital Assets API

For a higher level API with better filtering functions, you can also use the Digital Assets API. This API supports both traditional tokens and compressed NFTs within the same interface, allowing you to query the full set of tokens owned by a user.

Read more about the [DAS API](https://docs.triton.one/solana/reading-account-state/metaplex-das-api).

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Streaming

End-to-end guides for streaming Solana data.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-tower-broadcast">:tower-broadcast:</i> <strong>Start streaming with Yellowstone gRPC</strong></td><td>Connect to Dragon's Mouth and subscribe to accounts, transactions, slots, and blocks, with filters, commitment, pings, and replay.</td><td><a href="https://docs.triton.one/solana/quickstart/streaming/stream-solana-with-grpc">Start streaming with Yellowstone gRPC</a></td></tr><tr><td><i class="fa-filter">:filter:</i> How to use Shipstern + gRPC</td><td>Build program-aware Solana data pipelines with Shipstern, fed by Triton's gRPC, Fumarole, or RPC.</td><td><a href="https://docs.triton.one/solana/quickstart/streaming/how-to-use-shipstern-grpc">How to use Shipstern + gRPC</a></td></tr><tr><td><i class="fa-right-left">:right-left:</i> <strong>Migrate from Dragon's Mouth to Fumarole</strong></td><td>Swap a Dragon's Mouth subscriber to Fumarole: persistent subscribers, a 4-day buffer, and at-least-once delivery.</td><td><a href="https://docs.triton.one/solana/quickstart/streaming/migrate-from-dragons-mouth-to-fumarole">How to migrate from Dragon's Mouth to Fumarole</a></td></tr><tr><td><i class="fa-layer-group">:layer-group:</i> <strong>Fumarole cluster failover</strong></td><td>Run a persistent Fumarole subscriber across regions and fail over by resuming from your last consumed slot.</td><td><a href="https://docs.triton.one/solana/quickstart/streaming/fumarole-cluster-failover">Fumarole cluster failover</a></td></tr><tr><td><i class="fa-code">:code:</i> <strong>Generate parsers with Codama</strong></td><td>Generate a Shipstern parser from your program's IDL with Codama and the include_shipstern_parser! macro.</td><td><a href="https://docs.triton.one/solana/quickstart/streaming/generate-parsers-with-codama">Generate parsers with Codama</a></td></tr><tr><td><i class="fa-gauge">:gauge:</i> <strong>Benchmark gRPC endpoints with Thorofare</strong></td><td>Compare two Yellowstone gRPC endpoints side by side with Thorofare.</td><td><a href="https://docs.triton.one/solana/quickstart/streaming/benchmark-grpc-endpoints-with-thorofare">Benchmark gRPC endpoints with Thorofare</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Start streaming with Yellowstone gRPC

Connect to Dragon's Mouth, subscribe to a live stream, and handle accounts, transactions, slots, and blocks over Yellowstone gRPC.

Dragon's Mouth is Triton's Geyser-fed gRPC interface for streaming Solana data: account writes, transactions, slots, blocks, block metadata, and entries. You subscribe once and the node pushes strongly typed Protobuf updates the moment they arrive, bypassing the JSON-RPC HTTP layer. Use it for backend workloads that need the lowest possible latency and fresh, structured data: trading, indexing, analytics, and DeFi. gRPC is unsupported by web browsers, so Dragon's Mouth targets backend software; for browsers, use the [WebSocket API](https://docs.triton.one/solana/real-time-streaming/whirligig-websockets).

## Prerequisites

* A Dragon's Mouth endpoint and an `x-token`.
* A gRPC client. Official sample clients exist for Rust, Go, and NodeJS/TypeScript. You can also test with the generic `grpcurl` client.

For NodeJS/TypeScript, install the client:

{% tabs %}
{% tab title="npm" %}

```bash
npm install --save @triton-one/yellowstone-grpc
```

{% endtab %}

{% tab title="yarn" %}

```bash
yarn add @triton-one/yellowstone-grpc
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The underlying gRPC proto can change, so test with a client matching the current version of the interface. Protobuf files live in the [yellowstone-grpc repo](https://github.com/rpcpool/yellowstone-grpc/tree/master/yellowstone-grpc-proto/proto) or the [`yellowstone-grpc-proto`](https://crates.io/crates/yellowstone-grpc-proto) crate.
{% endhint %}

## Minimal subscriber

Connect, subscribe to one program's account updates plus slots, and log each update.

{% tabs %}
{% tab title="TypeScript" %}
{% code title="index.ts" lineNumbers="true" %}

```typescript
import Client, {
  CommitmentLevel,
  SubscribeRequest,
} from "@triton-one/yellowstone-grpc";

async function main() {
  // Connect to the gRPC endpoint
  const client = new Client("https://<your-endpoint>.mainnet.rpcpool.com", "your-x-token", {
    grpcMaxDecodingMessageSize: 64 * 1024 * 1024, // 64MiB
  });

  await client.connect();

  // Subscribe to events
  const stream = await client.subscribe();

  // Handle stream events
  const streamClosed = new Promise<void>((resolve, reject) => {
    stream.on("error", (error) => {
      reject(error);
      stream.end();
    });
    stream.on("end", resolve);
    stream.on("close", resolve);
  });

  // Process incoming data
  stream.on("data", (data) => {
    if (data.slot) {
      console.log(`Slot: ${data.slot.slot}, Status: ${data.slot.status}`);
    }
    if (data.account) {
      console.log(`Account update at slot: ${data.account.slot}`);
    }
  });

  // Build and send subscription request
  const request: SubscribeRequest = {
    accounts: {
      client: {
        account: [],
        owner: ["675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8"], // Raydium AMM
        filters: [],
      },
    },
    slots: {
      client: { filterByCommitment: true },
    },
    transactions: {},
    transactionsStatus: {},
    entry: {},
    blocks: {},
    blocksMeta: {},
    blockFooter: {},
    commitment: CommitmentLevel.PROCESSED,
    accountsDataSlice: [],
    ping: undefined,
  };

  await new Promise<void>((resolve, reject) => {
    stream.write(request, (err) => (err ? reject(err) : resolve()));
  });

  await streamClosed;
}

main().catch(console.error);
```

{% endcode %}
{% endtab %}

{% tab title="Rust" %}
{% code title="src/main.rs" lineNumbers="true" %}

```rust
use {
    futures::StreamExt,
    std::collections::HashMap,
    yellowstone_grpc_client::{ClientTlsConfig, GeyserGrpcClient},
    yellowstone_grpc_proto::prelude::{
        CommitmentLevel, SubscribeRequest, SubscribeRequestFilterSlots,
        SubscribeRequestFilterAccounts, subscribe_update::UpdateOneof,
    },
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Connect to the gRPC endpoint
    let mut client = GeyserGrpcClient::build_from_shared("https://<your-endpoint>.mainnet.rpcpool.com")?
        .x_token(Some("your-x-token".to_string()))?
        .tls_config(ClientTlsConfig::new().with_native_roots())?
        .connect()
        .await?;

    // Build subscription request
    let mut slots = HashMap::new();
    slots.insert(
        "client".to_string(),
        SubscribeRequestFilterSlots {
            filter_by_commitment: Some(true),
            interslot_updates: Some(false),
        },
    );

    let mut accounts = HashMap::new();
    accounts.insert(
        "client".to_string(),
        SubscribeRequestFilterAccounts {
            account: vec![], // specific account pubkeys
            owner: vec!["675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8".to_string()], // Raydium AMM
            filters: vec![],
            nonempty_txn_signature: None,
            ..Default::default()
        },
    );

    let request = SubscribeRequest {
        slots,
        accounts,
        commitment: Some(CommitmentLevel::Processed as i32),
        ..Default::default()
    };

    // Subscribe and handle updates
    let (mut _tx, mut stream) = client.subscribe_with_request(Some(request)).await?;

    while let Some(message) = stream.next().await {
        match message?.update_oneof {
            Some(UpdateOneof::Slot(slot)) => {
                println!("Slot: {}, Status: {}", slot.slot, slot.status);
            }
            Some(UpdateOneof::Account(account)) => {
                println!("Account update at slot: {}", account.slot);
            }
            _ => {}
        }
    }

    Ok(())
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

The subscribe stream is bi-directional: you receive updates on `data` and send requests by writing to the same stream. The NodeJS client is asynchronous, so run all calls inside an async function.

## Subscribe request shape

Every subscription is a single JSON request object. Each stream type is a map of client-assigned labels to filters; an empty map (`{}`) means that stream is off. Labels (for example `wsol/usdc`) tag the updates you receive, so you can mix accounts, programs, blocks, and slots in one request.

| Stream         | Request key                          | Empty value |
| -------------- | ------------------------------------ | ----------- |
| Account writes | `accounts`                           | `{}`        |
| Transactions   | `transactions`                       | `{}`        |
| Slots          | `slots`                              | `{}`        |
| Blocks         | `blocks`                             | `{}`        |
| Block metadata | `blocks_meta` (NodeJS: `blocksMeta`) | `{}`        |

The examples below show the raw gRPC JSON alongside the NodeJS form. Field names differ between them: gRPC uses snake\_case (`account_include`, `blocks_meta`, `accounts_data_slice`), NodeJS uses camelCase (`accountInclude`, `blocksMeta`, `accountsDataSlice`).

## Subscribe to accounts

Subscribe to a single account by pubkey on `confirmed` commitment. Here `wsol/usdc` is a client-assigned label.

{% tabs %}
{% tab title="gRPC" %}

```json
{"slots": { "slots": {} }, "accounts": { "wsol/usdc": { "account": ["8BnEgHoWFysVcuFFX7QztDmzuH8r5ZFvyP3sYwn1XTh6"] } }, "transactions": {}, "blocks": {}, "blocks_meta": {}, "accounts_data_slice": [], "commitment": 1}
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
import { CommitmentLevel } from "@triton-one/yellowstone-grpc";

const request = {
  "slots": {
    "slots": {}
  },
  "accounts": {
    "wsol/usdc": {
      "account": ["8BnEgHoWFysVcuFFX7QztDmzuH8r5ZFvyP3sYwn1XTh6"]
    }
  },
  "transactions": {},
  "blocks": {},
  "blocksMeta": {},
  "accountsDataSlice": [],
  "commitment": CommitmentLevel.CONFIRMED
};
```

{% endtab %}
{% endtabs %}

To subscribe to all accounts owned by a program, pass `owner`. This example streams Solend account writes on `processed`.

{% tabs %}
{% tab title="gRPC" %}

```json
{"slots": { "slots": {} }, "accounts": { "solend": {  "owner": ["So1endDq2YkqhipRh3WViPa8hdiSpxWy6z3Z6tMCpAo"] } }, "transactions": {}, "blocks": {}, "blocks_meta": {}, "accounts_data_slice": [], "commitment": 0}
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
import { CommitmentLevel } from "@triton-one/yellowstone-grpc";

const request = {
  "slots": {
    "slots": {}
  },
  "accounts": {
    "solend": {
      "owner": ["So1endDq2YkqhipRh3WViPa8hdiSpxWy6z3Z6tMCpAo"]
    }
  },
  "transactions": {},
  "blocks": {},
  "blocksMeta": {},
  "accountsDataSlice": [],
  "commitment": CommitmentLevel.PROCESSED
}
```

{% endtab %}
{% endtabs %}

Add `filters` and `accounts_data_slice` to narrow the match and trim the payload. This subscribes to USDC Tokenkeg accounts and returns only 40 bytes of account data instead of all 165 (`offset` 32 gives `owner` and `amount`).

{% tabs %}
{% tab title="gRPC" %}

```json
{
    "accounts": {
        "usdc": {
            "owner": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
            "filters": [{
                "token_account_state": true
            }, {
                "memcmp": {
                    "offset": 0,
                    "base58": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
                }
            }]
        }
    },
    "accounts_data_slice": [{ "offset": 32, "length": 40 }]
}
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
import { CommitmentLevel } from "@triton-one/yellowstone-grpc";

const request = {
  "slots": {},
  "accounts": {
    "usdc": {
      "owner": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
      "filters": [{
          "tokenAccountState": true
      }, {
          "memcmp": {
              "offset": 0,
              "base58": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
          }
      }]
    }
  },
  "transactions": {},
  "blocks": {},
  "blocksMeta": {},
  "entry": {},
  "commitment": CommitmentLevel.CONFIRMED,
  "accountsDataSlice": [{ "offset": 32, "length": 40 }],
};
```

{% endtab %}
{% endtabs %}

## Subscribe to transactions

If every transaction field is empty, all transactions are broadcast. Otherwise fields work as logical `AND`, and values in arrays as logical `OR`. You can include or exclude vote transactions and failed transactions. Alpenglow blocks contain no vote transactions.

This streams all finalized non-vote, non-failed transactions:

{% tabs %}
{% tab title="gRPC" %}

```json
{"slots": { "slots": {} }, "accounts": {}, "transactions": { "alltxs": { "vote": false, "failed": false }}, "blocks": {}, "blocks_meta": {}, "accounts_data_slice": [], "commitment": 2}
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
import { CommitmentLevel } from "@triton-one/yellowstone-grpc";

const request = {
  "slots": {
    "slots": {}
  },
  "accounts": {},
  "transactions": {
    "alltxs": {
      "vote": false,
      "failed": false
    }
  },
  "blocks": {},
  "blocksMeta": {},
  "accountsDataSlice": [],
  "commitment": CommitmentLevel.FINALIZED
};
```

{% endtab %}
{% endtabs %}

Filter to transactions mentioning specific accounts with `account_include`, exclude with `account_exclude`, and combine the two. This streams non-vote transactions that mention one account but not another:

{% tabs %}
{% tab title="gRPC" %}

```json
{"slots": { "slots": {} }, "accounts": {}, "transactions": { "serum": { "vote": false, "account_include": [ "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin" ], "account_exclude": [ "9wFFyRfZBsuAha4YcuxcXLKwMxJR43S7fPfQLusDBzvT" ] }}, "blocks": {}, "blocks_meta": {}, "accounts_data_slice": []}
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
const request = {
  "slots": {
    "slots": {}
  },
  "accounts": {},
  "transactions": {
    "serum": {
      "vote": false,
      "accountInclude": [
        "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin"
      ],
      "accountExclude": [
        "9wFFyRfZBsuAha4YcuxcXLKwMxJR43S7fPfQLusDBzvT"
      ]
    }
  },
  "blocks": {},
  "blocksMeta": {},
  "accountsDataSlice": []
};
```

{% endtab %}
{% endtabs %}

To watch one transaction by signature, subscribe with `signature`. The update arrives once, at the subscription commitment (`processed` by default); set `commitment` for `confirmed` or `finalized`. Replace the sample signature with the signature of a transaction you are about to send.

{% tabs %}
{% tab title="gRPC" %}

```json
{"slots": {}, "accounts": {}, "transactions": { "sign": { "signature": "5rp2hL9b6kexex11Mugfs3vfU9GhieKruj4CkFFSnu52WLxiGn4VcLLwsB62XURhMmT1j4CZiXT6FFtYbXsLq2Zs"}}, "blocks": {}, "blocks_meta": {}, "accounts_data_slice": [], "commitment": 1}
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
import { CommitmentLevel } from "@triton-one/yellowstone-grpc";

const request = {
  "slots": {},
  "accounts": {},
  "transactions": {
    "sign": {
      // Replace with the signature of a transaction you are about to send
      "signature": "5rp2hL9b6kexex11Mugfs3vfU9GhieKruj4CkFFSnu52WLxiGn4VcLLwsB62XURhMmT1j4CZiXT6FFtYbXsLq2Zs"
    }
  },
  "blocks": {},
  "blocksMeta": {},
  "accountsDataSlice": [],
  "commitment": CommitmentLevel.CONFIRMED
};
```

{% endtab %}
{% endtabs %}

## Subscribe to slots

Slot notifications need only a label.

{% tabs %}
{% tab title="gRPC" %}

```json
{"slots": { "incoming_slots": {} }, "accounts": {}, "transactions": {}, "blocks": {}, "blocks_meta": {}, "accounts_data_slice": []}
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
const request = {
  "slots": {
    "incoming_slots": {}
  },
  "accounts": {},
  "transactions": {},
  "blocks": {},
  "blocksMeta": {},
  "accountsDataSlice": []
};
```

{% endtab %}
{% endtabs %}

## Subscribe to blocks and block metadata

`blocks` returns each block as it is produced, including its transactions by default. Toggle `include_transactions` and `include_accounts`, or filter with `account_include` to receive only blocks where a given account is mentioned.

{% tabs %}
{% tab title="gRPC" %}

```json
{"slots": {}, "accounts": { }, "transactions": {}, "blocks": { "blocks": {"include_transactions": false, "include_accounts": true} }, "blocks_meta": {}, "accounts_data_slice": []}
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
const request = {
  "slots": {},
  "accounts": {},
  "transactions": {},
  "blocks": {
    "blocks": {
      "includeTransactions": false,
      "includeAccounts": true
    }
  },
  "blocksMeta": {},
  "accountsDataSlice": []
};
```

{% endtab %}
{% endtabs %}

For block-completion notifications without the transactions, use `blocks_meta`:

{% tabs %}
{% tab title="gRPC" %}

```json
{"slots": {}, "accounts": {}, "transactions": {}, "blocks": {}, "blocks_meta": { "blockmetadata": {} }, "accounts_data_slice": []}
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
const request = {
  "slots": {},
  "accounts": {},
  "transactions": {},
  "blocks": {},
  "blocksMeta": {
    "blockmetadata": {}
  },
  "accountsDataSlice": []
};
```

{% endtab %}
{% endtabs %}

## Modifying and unsubscribing

The Subscribe method is a bi-directional stream, so you can change your subscription by writing a new request. The new request entirely overwrites the previous one, so keep a local register of the full subscription config you want. To unsubscribe from everything while keeping the connection open, send empty maps for all streams:

{% tabs %}
{% tab title="gRPC" %}

```json
{"slots": {}, "accounts": {}, "transactions": {}, "blocks": {}, "blocks_meta": {}}
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
const request = {
  "slots": {},
  "accounts": {},
  "transactions": {},
  "blocks": {},
  "blocksMeta": {},
  "accountsDataSlice": []
};
```

{% endtab %}
{% endtabs %}

## Managing commitment

Streams run on `processed` commitment by default. You can also request `confirmed` or `finalized`, in which case Dragon's Mouth buffers updates and releases them once they reach that level. For maximum performance, handle commitment client-side instead.

```protobuf
enum CommitmentLevel {
  PROCESSED = 0;
  CONFIRMED = 1;
  FINALIZED = 2;
}
```

Working at `processed` lets you process transactions as soon as they arrive and commit to them only once you know they are confirmed or finalized, so you can surface UI changes faster.

To manage `confirmed` and `finalized` client-side, buffer events by the slot attached to each transaction or account write, then subscribe to slot notifications. Release a slot's buffer when you receive its notification at the commitment level you want. All transaction and account-write notifications for a slot arrive before that slot's confirmed or finalized notification.

{% hint style="info" %}
The validator does not send a commitment status for every slot, so Dragon's Mouth fills in the gaps. When a slot reaches `confirmed` or `finalized`, the server also sends that status for each ancestor slot that has not reached it yet.
{% endhint %}

## Keep-alive pings

Some cloud providers (for example Cloudflare) close idle streams. Send periodic pings to keep the connection open; the server also sends a `ping` every 10 seconds, and answers each ping you send with a `pong`.

```typescript
const PING_INTERVAL_MILLISECONDS = 30000;

// Ping request
const pingRequest: SubscribeRequest = {
    ping: { id: 1 },
    accounts: {},
    accountsDataSlice: [],
    transactions: {},
    transactionsStatus: {},
    blocks: {},
    blocksMeta: {},
    entry: {},
    slots: {},
    blockFooter: {},
};

// Sending pings periodically
setInterval(async () => {
  await new Promise<void>((resolve, reject) => {
    stream.write(pingRequest, (err) => {
      if (err === null || err === undefined) {
        resolve();
      } else {
        reject(err);
      }
    });
  }).catch((reason) => {
    console.error(reason);
    throw reason;
  });
}, PING_INTERVAL_MILLISECONDS);

// Handling pong responses
// This goes in your `data` handler
stream.on("data", (data) => {
if (data.pong) {
    console.log("Received Pong response");
  }
});
```

## Reconnect and replay from a slot

Dragon's Mouth can replay recently buffered updates by setting `from_slot` on the `SubscribeRequest`, mainly to recover from short disconnections. The server first replays buffered updates from that slot, then continues streaming live on the same connection using the same filters and commitment level.

Replay logic:

1. Track the latest slot your application has processed.
2. On disconnect, reconnect and resubscribe with `from_slot` set to that slot.
3. If the requested slot is no longer available, fall back to a fresh live subscription or your own backfill path.

Replay covers only the server's retained replay window: about 1,000 slots (roughly 400 seconds) on shared mainnet endpoints and about 300 slots on shared devnet; on dedicated nodes it varies, so contact support. Replay starts at a slot boundary, so reconnecting from your last processed slot may yield duplicate updates from that slot: deduplicate client-side. To find the earliest replayable slot, call the unary `SubscribeReplayInfo` RPC and read `first_available`; if `from_slot` is older, the request fails and you should retry with a newer slot.

{% tabs %}
{% tab title="gRPC" %}

```json
{
  "slots": {
    "incoming_slots": {}
  },
  "accounts": {},
  "transactions": {
    "alltxs": {
      "vote": false,
      "failed": false
    }
  },
  "blocks": {},
  "blocks_meta": {},
  "accounts_data_slice": [],
  "from_slot": 382001234
}
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
const request: SubscribeRequest = {
  slots: {
    incoming_slots: {}
  },
  accounts: {},
  transactions: {
    alltxs: {
      vote: false,
      failed: false,
      accountInclude: [],
      accountExclude: [],
      accountRequired: []
    }
  },
  transactionsStatus: {},
  entry: {},
  blocks: {},
  blocksMeta: {},
  blockFooter: {},
  accountsDataSlice: [],
  fromSlot: "382001234"
};
```

{% endtab %}
{% endtabs %}

Check replay availability before reconnecting:

```typescript
const info = await client.subscribeReplayInfo();
console.log(info.firstAvailable);
```

{% hint style="info" %}
For teams running their own Yellowstone gRPC server, replay is on by default: `replay_stored_slots` defaults to `150` when unset. The sample `config.json` sets it to `0`, which turns replay off.
{% endhint %}

### Let the client reconnect

Ordinary subscriptions don't reconnect: `subscribe`, `subscribe_with_request`, and `subscribe_once` in Rust, and `subscribe()` in TypeScript, end at the first disconnect. The client can reconnect for you: use `subscribe_with_reconnect` (`yellowstone-grpc-client` 17.0.0 and later) or `subscribeWithReconnect()` (`@triton-one/yellowstone-grpc` 10.0.0 and later). It works at any commitment level, and filter changes you send apply to every reconnect. The client must not request a startup snapshot. After a disconnect, the stream emits a `Disconnected` event that lists the banks you received only in part, then by default replays from the last confirmed slot, which can resend banks you already hold.

```rust
use {
    futures::StreamExt,
    yellowstone_grpc_client::{ClientTlsConfig, GeyserGrpcClient, ReconnectConfig, ReconnectEvent},
};

let mut client = GeyserGrpcClient::build_from_shared(endpoint)?
    .x_token(x_token)?
    .tls_config(ClientTlsConfig::new().with_native_roots())?
    // Optional: the retry budget and the replay policy for subscribe_with_reconnect
    .set_reconnect_config(ReconnectConfig::default())
    .connect()
    .await?;

let (_sink, mut stream) = client.subscribe_with_reconnect(Some(request)).await?;

while let Some(event) = stream.next().await {
    match event {
        Ok(ReconnectEvent::Update(update)) => {
            // Apply the update. A replay can resend banks you already hold whole.
            println!("{:?}", update.update_oneof);
        }
        Ok(ReconnectEvent::Disconnected(disconnected)) => {
            // Drop the state for these banks: you received only part of them.
            println!("discard {:?}", disconnected.partial_banks);
        }
        Err(status) => {
            // The stream has ended: open a new subscription.
            eprintln!("stream ended: {status}");
            break;
        }
    }
}
```

For the request rules, the replay policy, the retry budget, the event fields, and a TypeScript example, see [Reconnect with bank recovery](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc#reconnect-with-bank-recovery).

## Excluded programs

Light Protocol / ZK Compression (`compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq`) is excluded from all Dragon's Mouth gRPC streams and from `getProgramAccounts`. Each update produces a \~10MB blob, several gigabits per second of data, which is impractical to include in standard streams.

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# How to use Shipstern + gRPC

Build program-aware Solana data pipelines with Shipstern, fed by Triton's gRPC, Fumarole, or RPC.

Shipstern is an open-source framework for building program-aware, real-time Solana data pipelines. It provides the core components — runtime, parser definitions, and handler interfaces — needed to transform raw on-chain events into structured, actionable data.

{% hint style="info" %}
**Shipstern was formerly called Yellowstone Vixen.** It runs on your side: you use one of its built-in parsers or write your own, then connect it to a Triton data source. Triton does not operate a hosted parsed-streams service.
{% endhint %}

## How it works

Solana change events, following the Yellowstone gRPC specification, are received from a **source** and routed through pluggable **parsers**. Your **handlers** then log, store, or stream the enriched data for indexing, analytics, and downstream consumption.

Shipstern is built for four things:

* **Cost efficiency.** Share Dragon's Mouth subscriptions and filter only the data you care about.
* **Operational simplicity.** Lightweight setup, with minimal external dependencies.
* **Observability.** Built-in Prometheus metrics for lag, throughput, and error tracking.
* **Composability.** Independent, reusable parser crates that can deserialize complex cross-program interactions (CPI).

## Connect a Triton source

Each source is a Rust crate you configure in your Shipstern pipeline. These connect Shipstern to Triton infrastructure:

| Source crate                            | Triton service                                                                                | Use it for                                                                                                      |
| --------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `shipstern-yellowstone-grpc-source`     | [Dragon's Mouth gRPC](https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc) | Real-time account and transaction streams via the Dragon's Mouth Geyser plugin                                  |
| `shipstern-yellowstone-fumarole-source` | [Fumarole](https://docs.triton.one/solana/real-time-streaming/fumarole-persistent-streams)    | Persistent streams that merge data from multiple nodes, support consumer groups, and resume after interruptions |
| `shipstern-solana-rpc-source`           | [Standard RPC](https://docs.triton.one/solana)                                                | Pulling account data with `getProgramAccounts`                                                                  |
| `shipstern-jetstream-source`            | [Old Faithful](https://docs.triton.one/solana/historical-data)                                | Replaying historical blocks over a slot or epoch range, as the same `SubscribeUpdate` messages as a live stream |

Shipstern also ships a `shipstern-solana-snapshot-source` for loading ledger snapshots offline.

{% hint style="warning" %}
**The RPC source filters on account owners only.** Its prefilter's `accounts` pubkey set and `filters` comparisons (`Memcmp`, `DataSize`, and the rest) are not translated into the RPC request, so a prefilter that narrows on those still fetches every account the owner holds. For fine-grained filtering at the source, use Dragon's Mouth gRPC.
{% endhint %}

Archives hold only finalized history, so slots replayed through `shipstern-jetstream-source` report `SLOT_FINALIZED`. Its folder in the repository is `jetstreamer-source`, but the crate is published as `shipstern-jetstream-source`.

## Built-in parsers

Shipstern ships parsers for these programs:

| Address                                       | Program                | Parser crate                            |
| --------------------------------------------- | ---------------------- | --------------------------------------- |
| `TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA` | Token Program          | `shipstern-spl-token-parser`            |
| `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb` | Token Extensions       | `shipstern-spl-token-extensions-parser` |
| `SPoo1Ku8WFXoNDMHPsrGSTSG1Y47rzgn41SLUNakuHy` | SPL Stake Pool         | `shipstern-stake-pool-parser`           |
| `BPFLoaderUpgradeab1e11111111111111111111111` | BPF Loader Upgradeable | `shipstern-bpf-loader-parser`           |

Two more parsers read block-level updates rather than a program's accounts and instructions: `shipstern-block-meta-parser` for `BlockMeta`, and `shipstern-slot-parser` for `Slot`.

For any other program, generate a type-safe parser directly from its IDL — see [Generate parsers with Codama](https://docs.triton.one/solana/quickstart/streaming/generate-parsers-with-codama).

## Quick start

A minimal pipeline that streams Token Program accounts and instructions from Dragon's Mouth gRPC and logs the parsed values.

{% code title="Cargo.toml" %}

```toml
[dependencies]
shipstern = "0.12"
shipstern-spl-token-parser = "0.12"
shipstern-yellowstone-grpc-source = "0.12"
clap = { version = "4", features = ["derive"] }
rustls = "0.23"
toml = "0.9"
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
```

{% endcode %}

{% code title="src/main.rs" %}

```rust
use std::path::PathBuf;

use clap::Parser;
use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};
use shipstern::Pipeline;
use shipstern_spl_token_parser::{AccountParser, InstructionParser};
use shipstern_yellowstone_grpc_source::YellowstoneGrpcSource;

#[derive(clap::Parser)]
#[command(version, author, about)]
pub struct Opts {
    #[arg(long, short)]
    config: PathBuf,
}

#[derive(Debug)]
pub struct Logger;

impl<V: std::fmt::Debug + Sync, R: Sync> shipstern::Handler<V, R> for Logger {
    async fn handle(&self, value: &V, _raw: &R) -> shipstern::HandlerResult<()> {
        tracing::info!(?value);
        Ok(())
    }
}

fn main() {
    rustls::crypto::aws_lc_rs::default_provider()
        .install_default()
        .expect("Failed to install rustls crypto provider");

    tracing_subscriber::registry()
        .with(tracing_subscriber::EnvFilter::from_default_env())
        .with(tracing_subscriber::fmt::layer())
        .init();

    let Opts { config } = Opts::parse();
    let config = std::fs::read_to_string(config).expect("Error reading config file");
    let config = toml::from_str(&config).expect("Error parsing config");

    shipstern::Runtime::builder()
        .account(Pipeline::new(AccountParser, [Logger]))
        .instruction(Pipeline::new(InstructionParser, [Logger]))
        .build::<YellowstoneGrpcSource>(config)
        .run();
}
```

{% endcode %}

{% code title="Shipstern.toml" %}

```toml
[source]
endpoint = "https://<your-endpoint>.mainnet.rpcpool.com"
x-token = "<your-token>"
timeout = 60
```

{% endcode %}

Run it with that configuration:

```bash
RUST_LOG=info cargo run -- --config "./Shipstern.toml"
```

### Metrics

Metrics are collected into a `prometheus::Registry` that you hand to the runtime with `.metrics(registry)`. The runtime serves no HTTP endpoint of its own, so push the gathered metrics to a Pushgateway. The repository's `docker-compose.yaml` starts a Pushgateway on `:9091` and a Prometheus that scrapes it, so metrics appear at `http://localhost:9090`:

```bash
sudo docker-compose up
```

## Get started

Setup and configuration live in the Shipstern repository:

* [Quick start](https://github.com/solana-rpc/shipstern#quick-start) — build and run your first pipeline.
* [Example configuration](https://github.com/solana-rpc/shipstern/blob/main/Shipstern.example.toml) — a starter `Shipstern.example.toml` for pipeline configuration.
* [Usage examples](https://github.com/solana-rpc/shipstern/tree/main/examples) — example projects for each feature.
* [Generate parsers from IDL](https://github.com/solana-rpc/shipstern/blob/main/docs/codama-parser-generation.md) — the `include_shipstern_parser!` macro, including self-CPI event envelopes.

Point the source at your Triton endpoint and token from the [customer dashboard](https://customers.triton.one/). Shipstern is developed by Jupiter, ABK Labs, and Triton One.

## What's next

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Dragon's Mouth gRPC</strong></td><td>Sub-slot real-time updates for accounts, transactions, slots, and blocks — the most common Shipstern source.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc">Dragon's Mouth gRPC</a></td></tr><tr><td><strong>Generate parsers with Codama</strong></td><td>Build a parser for your own program from its IDL.</td><td><a href="https://docs.triton.one/solana/quickstart/streaming/generate-parsers-with-codama">Generate parsers with Codama</a></td></tr><tr><td><strong>Fumarole</strong></td><td>Persistent streams with an at-least-once delivery guarantee.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/fumarole-persistent-streams">Fumarole Persistent gRPC</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Generate parsers with Codama

Generate a Shipstern parser for any Solana program from its IDL, with Codama and the include\_shipstern\_parser! macro.

[Shipstern](https://github.com/solana-rpc/shipstern) builds a parser for your program at compile time from a [Codama](https://github.com/codama-idl/codama) IDL, through the `include_shipstern_parser!` proc macro. Nothing is written to disk and there is no build script. The generated parser decodes the program's accounts and instructions inside a Shipstern pipeline.

Shipstern (formerly Yellowstone Vixen) is an open-source framework for real-time Solana program data pipelines in Rust. [How to use Shipstern + gRPC](https://docs.triton.one/solana/quickstart/streaming/how-to-use-shipstern-grpc) shows how its sources connect to Triton.

## Prerequisites

* Your program's IDL, as `idl.json`. An Anchor IDL works; so does an IDL already in Codama form.
* Node.js with `npx`, for the one-time conversion step.
* A Rust project for your pipeline.

## 1. Convert the IDL to Codama JSON

The macro also reads an Anchor IDL directly, but this guide uses Codama JSON. Convert the IDL once:

```bash
npx -p codama -p @codama/nodes-from-anchor codama convert idl.json codama.json
```

Name both packages. `codama convert` reads Anchor IDLs through `@codama/nodes-from-anchor`, and outside a Node.js project it doesn't install that package for you. If your IDL is already in Codama form, skip this step.

## 2. Add the dependencies

```toml
[dependencies]
borsh = { version = "1", features = ["derive"] }
shipstern = "0.12"
shipstern-core = "0.12"
shipstern-parser = "0.12"
shipstern-proc-macro = "0.12"
shipstern-yellowstone-grpc-source = "0.12"
rustls = "0.23"
toml = "0.9"
```

The generated code needs `shipstern-core` and Borsh's `derive` feature. To also parse program events, including self-CPI events, enable the `program-events` feature on `shipstern-proc-macro`; it changes the instruction parser's output to carry the events too.

## 3. Generate and run the parser

`include_shipstern_parser!` takes the path to `codama.json`, relative to your crate root. It expands to a module named after the program in snake\_case, with `PROGRAM_ID`, `AccountParser`, `InstructionParser`, and the account and argument types. Use the parsers like any built-in Shipstern parser. This pipeline, for a program named `my_program` in the IDL, streams its accounts and instructions from Dragon's Mouth gRPC and logs them:

```rust
use shipstern::Pipeline;
use shipstern_proc_macro::include_shipstern_parser;
use shipstern_yellowstone_grpc_source::YellowstoneGrpcSource;

include_shipstern_parser!("codama.json");

#[derive(Debug)]
pub struct Logger;

impl<V: std::fmt::Debug + Sync, R: Sync> shipstern::Handler<V, R> for Logger {
    async fn handle(&self, value: &V, _raw: &R) -> shipstern::HandlerResult<()> {
        println!("{value:?}");
        Ok(())
    }
}

fn main() {
    rustls::crypto::aws_lc_rs::default_provider()
        .install_default()
        .expect("Failed to install rustls crypto provider");

    let config = std::fs::read_to_string("Shipstern.toml").expect("Error reading config file");
    let config = toml::from_str(&config).expect("Error parsing config");

    shipstern::Runtime::builder()
        .account(Pipeline::new(my_program::AccountParser, [Logger]))
        .instruction(Pipeline::new(my_program::InstructionParser, [Logger]))
        .build::<YellowstoneGrpcSource>(config)
        .run();
}
```

`Shipstern.toml` holds the source settings: put your Triton gRPC endpoint in `endpoint` and your token in `x-token` under `[source]`. Start from the repository's [`Shipstern.example.toml`](https://github.com/solana-rpc/shipstern/blob/main/Shipstern.example.toml).

The Shipstern repository's [Codama parser generation reference](https://github.com/solana-rpc/shipstern/blob/main/docs/codama-parser-generation.md) covers which IDL nodes the macro reads, discriminators, and event envelopes.

{% hint style="info" %}
The standalone Codama renderer `@codama/renderers-vixen-parser` (last released in October 2025) writes parser crates for the pre-rename framework and has not been released for Shipstern. Use the macro.
{% endhint %}

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>How to use Shipstern + gRPC</strong></td><td>Run your parser against a live Dragon's Mouth gRPC stream.</td><td><a href="https://docs.triton.one/solana/quickstart/streaming/how-to-use-shipstern-grpc">How to use Shipstern + gRPC</a></td></tr><tr><td><i class="fa-tower-broadcast">:tower-broadcast:</i> <strong>Dragon's Mouth gRPC</strong></td><td>Sub-slot real-time updates for accounts, transactions, slots, and blocks via gRPC.</td><td><a href="https://docs.triton.one/solana/real-time-streaming/dragon-s-mouth-grpc">Dragon's Mouth gRPC</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Fumarole cluster failover

Set up Fumarole across regional clusters for automatic streaming failover.

{% hint style="info" %}
This guide shows how to implement cross-region failover for Fumarole from the subscriber side. For an overview of regional clusters and the redundancy model, see [Fumarole Persistent gRPC](https://docs.triton.one/solana/real-time-streaming/fumarole-persistent-streams).
{% endhint %}

Fumarole runs as **independent regional clusters**. Persistent subscriber state does not replicate across regions. This means that if your primary cluster experiences a major outage, you can fail over to another region, but the cutover is fully customer-managed and requires you to recreate your persistent subscriber on the secondary cluster from the last slot you consumed.

This guide walks through the full failover lifecycle: preparation, detection, cutover, and failback.

## Scope and assumptions

This guide assumes:

* You have an active Fumarole integration on one regional cluster (your **primary**).
* You have access to a second regional cluster (your **secondary**); the same token works on both.
* You can implement client-side logic that tracks per-cluster state and reacts to outage signals.

The example throughout this guide uses **EU (`ams.rpcpool.com`)** as primary and **US (`nyc.rpcpool.com`)** as secondary. The procedure is symmetric; it applies in either direction.

{% hint style="warning" %}
Triton does **not** orchestrate failover for you; failover is **customer-managed**. We do not synchronize subscriber state, track your last-consumed slot, or trigger the cutover. Everything described below runs on your side. This page tells you exactly what to do.
{% endhint %}

## Before you start

Failover is only possible if you do the prep work ahead of time. Put these in place during normal operation, not during the outage.

**1. Track the last fully-consumed slot per cluster.**

Your client must keep a record of the highest slot you have successfully processed end-to-end from each cluster. Persist this value durably (e.g. in your database, in Redis, in a file) anywhere that survives a process restart. You will need it to recreate the subscriber on the secondary cluster at the correct position.

Fumarole does not return the last slot you consumed through its API, so record it yourself. The client marks the end of each block (slot and blockhash) with a `SlotEnded` event, and several blocks can exist for the same slot. Record a slot once your processing of its block succeeds.

**2. Build your outage-detection logic.**

Decide what counts as a cluster-level failure for your workload (see Detecting an outage below) and instrument the client to surface it.

**3. Make sure your processing pipeline is idempotent.**

There will be a small overlap window during failover where the same slot may be delivered from both clusters. Your downstream processing must tolerate seeing the same slot twice without producing duplicate side effects.

## Detecting an outage

A failover is only worth the effort when the primary is genuinely down. Transient hiccups should be handled by normal reconnect logic, not failover.

Before triggering a failover, make sure the problem is on the cluster and not on your side. Some signals worth tracking:

* **Stream interruption that does not recover on reconnect.** Fumarole is built to survive normal node restarts and rolling upgrades. If you have been disconnected for more than a few minutes and reconnect attempts keep failing, that is beyond normal recovery.
* **`fume test-config` against the failing endpoint fails or hangs.** This is the most direct check that the cluster is reachable.
* **No new slots advancing.** The `fumarole_offset_lag_from_tip` metric on your client should normally trend toward zero. If it is growing unbounded and your network is healthy, the cluster is not advancing the log.
* **"Not found" or stale errors** for a persistent subscriber you know was healthy minutes ago.

{% hint style="warning" %}
**Check whether the problem is differential.** If only some of your clients are affected but others are fine, the problem is likely on your side: network, host, or deployment. Do not fail over.
{% endhint %}

If `fume test-config` succeeds against the failing endpoint and the subscriber exists, but you are not receiving data, that is worth a CS-channel ping before declaring a full failover.

## Failover procedure

When your detection logic concludes the primary cluster is down, execute the following sequence.

**Step 1: Stop the primary client**

Halt consumption from `ams.rpcpool.com`. Stop reconnect attempts.

**Step 2: Read the last fully-consumed slot for the primary**

Read the value you have been tracking. This is the slot from which the secondary subscriber will resume. Call this `last_primary_slot`.

**Step 3: Create the subscriber on the secondary cluster**

Connect to the secondary cluster and create the persistent subscriber there, starting from `last_primary_slot + 1`.

```bash
fume --config ~/.fumarole/config-us.yaml create \
  --name my-app-failover \
  --from-slot 312500001
```

If a subscriber with that name already exists on the secondary cluster from a previous failover, delete it first:

```bash
fume --config ~/.fumarole/config-us.yaml delete --name my-app-failover
fume --config ~/.fumarole/config-us.yaml create \
  --name my-app-failover \
  --from-slot 312500001
```

The same pattern applies whether you use the Fume CLI or the Rust / TypeScript SDK: create a fresh subscriber pointing at your recovery slot. The recovery slot must be within Fumarole's 4-day buffer. If the cluster no longer stores that slot, the create call does not fail: the subscriber starts at a later slot than the one you asked for, and you miss the gap. Check the stored range first with `fume slot-range` (`get_slot_range` in Rust, `getSlotRange` in TypeScript), and backfill a gap from historical sources.

**Step 4: Begin consuming from the secondary**

Start your client against `nyc.rpcpool.com`. Resume normal processing.

Until the secondary catches up to live tip, you will be receiving historical data. Expect some replay delay proportional to the gap between `last_primary_slot` and the current chain tip.

**Step 5: Confirm forward progress**

Once the secondary is at live tip and slots are advancing normally, your failover is complete. Log the cutover and update your monitoring to track the new active cluster.

## Failing back to the primary

When the primary cluster recovers, you have a choice:

* **Stay on the secondary.** Acceptable if the secondary is geographically reasonable for your workload.
* **Fail back to the primary.** Necessary if the secondary is far from your backend and you accepted the failover only for availability.

If you decide to fail back, run the failover procedure in reverse:

1. Track the last fully-consumed slot on the secondary.
2. Stop the secondary client.
3. Create the primary subscriber starting from `last_secondary_slot + 1` (deleting the existing primary subscriber first if needed).
4. Start consuming from the primary.
5. Confirm forward progress.

{% hint style="warning" %}
Failback is a planned operation, not an emergency one. Schedule it during a low-traffic window and verify the primary has been stable for some time before cutting back.
{% endhint %}

## Common pitfalls

* **Failing over on a transient blip.** A single dropped connection is not a cluster outage. Tune your detection thresholds so normal reconnects do not trip failover.
* **Not persisting the last-consumed slot.** If you only hold it in memory and your process restarts mid-outage, you have lost your resume point. Persist it durably.
* **Forgetting the subscriber starts at `last_slot + 1`.** Starting at `last_slot` itself replays the slot you already processed, which widens the duplicate window.
* **Assuming token-or-permission errors mean an outage.** Authentication failures are not outage signals; they indicate a client configuration problem, not a cluster problem.
* **Leaving unused subscribers behind.** A subscriber on a cluster you no longer use still counts toward that cluster's [limit of 15 persistent subscribers per subscription](https://docs.triton.one/solana/real-time-streaming/fumarole-persistent-streams#limits). Delete it with `fume delete --name <name>`.

## Quick reference

| Phase     | What you do                                                                                                                                                                                                                                                            |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Prep      | Track last-consumed slot per cluster, build detection logic, ensure idempotent processing                                                                                                                                                                              |
| Detect    | Run `fume test-config`, watch the `fumarole_offset_lag_from_tip` metric, and check for "not found" / stale errors on your subscriber. See the [Fume CLI reference](https://github.com/rpcpool/yellowstone-fumarole/blob/main/apps/yellowstone-fumarole-cli/README.md). |
| Cut over  | Stop primary client → read `last_primary_slot` → create subscriber on secondary from `last_primary_slot + 1` → start consuming → confirm progress                                                                                                                      |
| Fail back | Same procedure in reverse, scheduled rather than reactive                                                                                                                                                                                                              |

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# How to migrate from Dragon's Mouth to Fumarole

Move a Dragon's Mouth gRPC subscriber to Fumarole for persistence, resumability, and parallel connections.

Fumarole serves the same Solana data as Dragon's Mouth, with a persistence and delivery layer in front of it: persistent subscribers you can resume after a disconnect, a 4-day data buffer to resume from, parallel gRPC connections that avoid head-of-line blocking, automatic reconnect, and an at-least-once delivery guarantee. The client API is close to `yellowstone-grpc`, so most of the work is swapping the client and choosing how you consume the stream.

## What changes

|             | Dragon's Mouth (`yellowstone-grpc`) | Fumarole (`yellowstone-fumarole-client`)              |
| ----------- | ----------------------------------- | ----------------------------------------------------- |
| Connections | one gRPC stream                     | multiple gRPC connections, avoids HoL blocking        |
| Subscriber  | per-session                         | persistent, reusable across sessions                  |
| Disconnects | client tracks the slot and replays  | resume from your committed position                   |
| Best for    | lowest-latency live feeds           | never-miss workloads: indexing, accounting, analytics |

Fumarole ignores some parts of a Dragon's Mouth `SubscribeRequest`, including the `blocks` filter, `accounts_data_slice`, `from_slot`, `interslot_updates`, and compressed filters. The persistent subscriber's cursor sets where the stream starts, and `block_stream()` emits the updates that match your filters as one `Block` event when its block ends.

## Connect to Fumarole

Add the [`yellowstone-fumarole-client`](https://docs.rs/yellowstone-fumarole-client) crate and build a client from a config. The preferred form is a YAML file read with `serde_yaml`:

```yaml
endpoint: https://ams.rpcpool.com # or nyc.rpcpool.com; connect to a regional cluster directly
x-token: <your-token>
response_compression: zstd
```

{% tabs %}
{% tab title="Rust" %}

```rust
use yellowstone_fumarole_client::FumaroleClient;
use yellowstone_fumarole_client::config::FumaroleConfig;

let config: FumaroleConfig =
    serde_yaml::from_reader(std::fs::File::open("config.yaml")?)?;
let mut client = FumaroleClient::connect(config).await.expect("connect");
```

{% endtab %}
{% endtabs %}

## Fastest path: the Dragon's Mouth adapter

For the smallest change, `dragonsmouth_subscribe` mimics the Dragon's Mouth API, so your existing `SubscribeRequest` and receive loop keep working, now against a named persistent subscriber:

{% tabs %}
{% tab title="Rust" %}

```rust
let session = client.dragonsmouth_subscribe(subscriber_name, request).await?;
let DragonsmouthAdapterSession { sink: _, mut source, mut fumarole_handle } = session;
// consume `source` exactly like a Dragon's Mouth stream
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
The Dragon's Mouth adapter is **deprecated**. Use it to get running quickly, then move to the native API below.
{% endhint %}

## Recommended: the native Fumarole API

The native API streams from a named persistent subscriber and lets you process in slot order. Use `slot_sequential()` for slot-ordered work:

{% tabs %}
{% tab title="Rust" %}

```rust
use futures::StreamExt;
use yellowstone_fumarole_client::stream::FumaroleEvent;

let subscription = client.subscribe(subscriber_name, request).await?;
let (_sink, stream) = subscription.split();
let mut slot_stream = stream.slot_sequential();

while let Some(item) = slot_stream.next().await {
    match item? {
        FumaroleEvent::Data { slot, .. } => { /* process the update */ }
        FumaroleEvent::SlotEnded { slot, .. } => { /* slot complete */ }
    }
}
```

{% endtab %}
{% endtabs %}

For block-oriented processing, use `stream.block_stream()` and match `FumaroleBlockStreamEvent::Block` and `::SlotStatus` instead.

## Scale for high traffic

For heavy or high-latency workloads, open parallel data-plane connections and enable Zstd. Set `response_compression: zstd` in the config (above), then pass a subscribe config:

{% tabs %}
{% tab title="Rust" %}

```rust
let subscribe_config = FumaroleSubscribeConfig {
    num_data_plane_tcp_connections: NonZeroU8::new(4).unwrap(), // e.g. 4 parallel connections
    ..Default::default()
};
let subscription = client
    .subscribe_with_config(subscriber_name, request, subscribe_config)
    .await?;
```

{% endtab %}
{% endtabs %}

## Control when progress commits

Delivery is at-least-once, resuming from your last committed position. The subscriber auto-commits its position by default; to make the guarantee cover your own processing, set `auto_commit: false` and commit only after your slot work succeeds:

{% tabs %}
{% tab title="Rust" %}

```rust
let subscribe_config = FumaroleSubscribeConfig { auto_commit: false, ..Default::default() };
// ...
FumaroleEvent::SlotEnded { .. } => {
    slot_stream.commit(); // commit after processing this slot succeeds
}
```

{% endtab %}
{% endtabs %}

## What's next

* [Fumarole cluster failover](https://docs.triton.one/solana/quickstart/streaming/fumarole-cluster-failover) for cross-region high availability.
* [`yellowstone-fumarole-client` on docs.rs](https://docs.rs/yellowstone-fumarole-client) for the full API, feature flags, and runnable examples.

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Benchmark gRPC endpoints with Thorofare

Compare two Yellowstone gRPC endpoints side by side with Triton's open-source Thorofare tool.

[Thorofare](https://github.com/rpcpool/yellowstone-thorofare) is Triton's open-source tool for benchmarking Solana Geyser gRPC (Yellowstone gRPC) endpoints. It connects to two endpoints at the same time, subscribes to the same data on both, and reports which one delivered each update first, and by how much. Running both streams from one machine at once removes the network and timing differences that make single-endpoint numbers hard to compare.

For the methodology behind it, see the [How to benchmark Solana RPC endpoints](https://blog.triton.one/how-to-benchmark-solana-rpc-endpoints/) blog post.

## What Thorofare measures

* **Slot stages**: when each endpoint reports each of the six slot statuses: first shred received, bank created, completed, processed, confirmed, and finalized.
* **Download and replay time**: download runs from first shred received to completed, replay from bank created to processed.
* **Account update propagation** (optional): for accounts owned by a program you choose, how much later one endpoint delivers the same write than the other.
* **Transaction propagation** (optional): the same comparison for non-vote transactions.
* **Ping latency** to both endpoints.

Subscriptions use `processed` commitment. Every metric is reported as P50, P90, and P99.

## When to run it

* Choosing between gRPC endpoints or providers: run both through the same benchmark, from the same machine.
* Checking a region or endpoint change against the endpoint you use today.
* Seeing which endpoint delivers slots, accounts, and transactions first, and by how much, when both run from the same machine.

## Run a benchmark

Download the prebuilt Linux binary for Ubuntu 22.04 or Ubuntu 24.04 from the [Thorofare releases page](https://github.com/rpcpool/yellowstone-thorofare/releases). The release files are named after the OS (for example `yellowstone-thorofare-ubuntu-24.04`), so make the file executable and rename it to `thorofare` to match the commands below. Or build it from source:

```bash
git clone https://github.com/rpcpool/yellowstone-thorofare.git
cd yellowstone-thorofare
cargo build --release
# The binary is target/release/thorofare
```

Pass both endpoints as full URLs, including `https://`; a bare `host:port` fails with a gRPC transport error. Each endpoint takes its own token:

```bash
thorofare \
  --endpoint1 https://<your-endpoint>.mainnet.rpcpool.com \
  --x-token1 <your-token> \
  --endpoint2 https://<other-endpoint> \
  --x-token2 <other-token> \
  --slots 1000
```

To also compare account and transaction propagation, add the optional flags. `--with-accounts` and `--account-owner` must be used together:

```bash
thorofare \
  --endpoint1 https://<your-endpoint>.mainnet.rpcpool.com --x-token1 <your-token> \
  --endpoint2 https://<other-endpoint> --x-token2 <other-token> \
  --with-accounts --account-owner 675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8 \
  --with-transactions
```

| Flag                                       | Default                  | What it does                                                                  |
| ------------------------------------------ | ------------------------ | ----------------------------------------------------------------------------- |
| `--endpoint1`, `--endpoint2`               | required                 | The two gRPC endpoints to compare.                                            |
| `--x-token1`, `--x-token2`                 | none                     | Token for each endpoint, sent as `x-token`.                                   |
| `--slots`                                  | `1000`                   | Number of slots to collect.                                                   |
| `--with-accounts`, `--account-owner <id>`  | off                      | Compare account writes for accounts owned by this program. Use both together. |
| `--with-transactions`                      | off                      | Compare non-vote transactions.                                                |
| `--endpoint1-richat`, `--endpoint2-richat` | off                      | Use the Richat interface for that endpoint instead of Yellowstone gRPC.       |
| `--config`                                 | `config.toml`            | gRPC client tuning. Built-in defaults apply when the file is missing.         |
| `--output`                                 | `benchmark_results.json` | Where to write the results.                                                   |
| `--log-level`                              | `info`                   | Log verbosity.                                                                |

{% hint style="info" %}
Thorofare runs on your machine. Run it from a backend close to where your real production traffic originates; benchmarking from a different region distorts every result.
{% endhint %}

## Read the results

Thorofare writes a JSON report with slot timing comparisons, P50, P90, and P99 for every metric, win and loss counts for account and transaction updates, and ping latencies. Delay metrics count a win as 0 ms, so the percentiles cover every update: a P50 of 0 means that endpoint was faster more than half the time.

To chart a report, load the JSON file into the [Thorofare visualizer](https://thorofare.triton.one/). It shows a timeline of the slot stages, per-update account delays, and the percentile distributions.

## Common pitfalls

* **Comparing separate runs.** Results from different machines or times aren't comparable. Put both endpoints in one run.
* **A quiet program for account tracking.** `--with-accounts` only sees writes to accounts owned by `--account-owner`. A program with few writes gives few samples.
* **Untuned gRPC settings for heavy subscriptions.** `--config` takes a TOML file like `config-example.toml` in the repository. Keep `tcp_nodelay = true`, and raise `initial_connection_window_size` when you track accounts or transactions.

## What's next

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-gauge">:gauge:</i> <strong>Rate and connection limits</strong></td><td>Per-endpoint and method rate limits, plus streaming connection caps.</td><td><a href="https://docs.triton.one/using-your-endpoint/rate-and-connection-limits">Rate and connection limits</a></td></tr><tr><td><i class="fa-compass">:compass:</i> <strong>Streaming overview</strong></td><td>Compare every Triton streaming service and choose the right fit for your workload.</td><td><a href="https://docs.triton.one/solana/real-time-streaming">Real-time streaming</a></td></tr><tr><td><i class="fa-lock">:lock:</i> <strong>Auth and security</strong></td><td>Authenticate requests and lock your endpoint to trusted origins.</td><td><a href="https://docs.triton.one/security/authentication">Auth and security</a></td></tr><tr><td><i class="fa-book">:book:</i> <strong>Thorofare blog post</strong></td><td>Why most gRPC benchmarks are wrong, and how to do them right.</td><td><a href="https://blog.triton.one/how-to-benchmark-solana-rpc-endpoints/">https://blog.triton.one/how-to-benchmark-solana-rpc-endpoints/</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Transaction sending

End-to-end guides for sending Solana transactions.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-bolt">:bolt:</i> <strong>Yellowstone Jet TPU client</strong></td><td>Send transactions straight to validator TPUs over QUIC with the standalone Rust client: leader tracking, per-transaction callbacks, and stake-weighted QoS when your own sending identity is staked.</td><td><a href="https://docs.triton.one/solana/quickstart/sending-transactions/yellowstone-jet-tpu-client">Yellowstone Jet TPU client</a></td></tr><tr><td><i class="fa-shield">:shield:</i> <strong>Protect transactions from MEV with Shield</strong></td><td>Combine on-chain Shield allowlists and blocklists with the TPU client so transactions only reach validators you trust.</td><td><a href="https://docs.triton.one/solana/quickstart/sending-transactions/protect-transactions-with-shield">Protect transactions from MEV with Shield</a></td></tr></tbody></table>

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Yellowstone Jet TPU client

Send Solana transactions straight to validator TPUs over QUIC with the standalone Yellowstone Jet TPU client in Rust.

The Yellowstone Jet TPU client is a standalone Rust crate that sends transactions directly to validator TPUs over QUIC. It is the QUIC sending core of [Yellowstone Jet](https://github.com/rpcpool/yellowstone-jet), the open-source engine that delivers transactions sent through Triton endpoints, pulled out into a library you can drop into your own stack.

Writing a TPU client from scratch means handling every Agave release, managing QUIC connections, tracking the leader schedule, and caching connections without lock contention. This crate does all of that, and exposes the hooks a default client leaves out.

* Crate: [`yellowstone-jet-tpu-client`](https://crates.io/crates/yellowstone-jet-tpu-client)
* API docs: [docs.rs (0.8.1)](https://docs.rs/yellowstone-jet-tpu-client/0.8.1/yellowstone_jet_tpu_client/)
* Source: [github.com/rpcpool/yellowstone-jet](https://github.com/rpcpool/yellowstone-jet)

## When to use it

Anza's `tpu-client-next` shares much of its design and solves the performance problems of the legacy `ConnectionCache`. Reach for the Jet TPU client instead when you run arbitrage bots, liquidation engines, or custom routing, and need control the default client does not expose:

* **Transaction tracking.** Register a callback that fires when a transaction frame is written, fails, or is dropped by the internal event loop. Use it for custom retry logic, logging, and debugging.
* **Custom TPU contact info.** Bypass the gossip-provided contact info and supply your own TPU addresses.
* **Arbitrary remote peers.** Bypass the leader schedule entirely to implement your own offloading or routing logic.
* **Multi-step identity updates.** Rotate the sending identity through a controlled, multi-step process while keeping every sub-module in sync.
* **Allowlist and blocklist support.** Pass a custom blocklist when you call `send_txn_with_blocklist`. To gate sending on on-chain validator policies, see [Protect transactions from MEV with Shield](https://docs.triton.one/solana/quickstart/sending-transactions/protect-transactions-with-shield).

## Prerequisites

* Rust 1.97.1 or later. The crate itself needs Rust 1.91 (edition 2024); the 4.3 Solana client crates it builds on need 1.97.1.
* A Triton RPC endpoint and a Yellowstone gRPC endpoint with an x-token. [Get an endpoint](https://customers.triton.one/onboarding).
* An identity keypair for the sender. Validators prioritise QUIC connections by the stake of this identity, so an unstaked identity gets no stake-weighted QoS. The example below falls back to a random keypair if you do not supply one. It also uses this keypair as the fee payer and the source of the transfer, so it must hold SOL. With the random fallback the transaction is sent but cannot land.

## Set up the project

Create a new binary crate and add the dependencies. Version 0.8 of the client is built on the 4.x `solana-client`, `solana-message`, `solana-pubkey`, and `solana-transaction` crates and the 3.x `solana-keypair`, `solana-signature`, and `solana-signer` crates. Pin the same major versions so the types match. The examples target 0.8.x. Cargo treats each 0.x minor version as a breaking release, so keep the version pinned in `Cargo.toml` and don't run `cargo add` without a version.

```toml
[package]
name = "example-jet-tpu-client"
version = "0.1.0"
edition = "2024"

[dependencies]
bincode = "1.3.3"
clap = { version = "4.5.51", features = ["derive"] }
dotenvy = "0.15.0"
tokio = { version = "1.48.0", features = ["macros", "rt-multi-thread", "sync"] }
url = "2"

# Solana crates, at the major versions yellowstone-jet-tpu-client 0.8 is built against
# solana-client 4.4 pulls in solana-account 5, which yellowstone-shield-store 0.11 rejects;
# stay on 4.3 so the Shield guide builds on this project
solana-client = "~4.3"
solana-commitment-config = "3"
solana-hash = "4"
solana-keypair = "3"
solana-message = "4"
solana-pubkey = "4"
solana-signature = "3"
solana-signer = "3"
solana-system-interface = { version = "3", features = ["bincode"] }
solana-transaction = { version = "4", features = ["serde", "wincode"] }

yellowstone-jet-tpu-client = { version = "0.8.1", features = ["yellowstone-grpc"] }
```

## Imports and CLI arguments

The example is a small CLI that sends lamports to any Solana address, reading its endpoints from arguments or a `.env` file.

In `src/main.rs`, start with the imports:

{% tabs %}
{% tab title="Rust" %}

```rust
use {
    clap::Parser,
    solana_client::nonblocking::rpc_client::RpcClient,
    solana_commitment_config::CommitmentConfig,
    solana_hash::Hash,
    solana_keypair::Keypair,
    solana_message::{VersionedMessage, v0},
    solana_pubkey::Pubkey,
    solana_signature::Signature,
    solana_signer::Signer,
    solana_system_interface::instruction::transfer,
    solana_transaction::versioned::VersionedTransaction,
    std::{env, path::PathBuf},
    url::Url,
    yellowstone_jet_tpu_client::{
        config::{TpuPortKind, TpuSenderConfig},
        core::{TpuSenderResponse, TpuSenderTxnInfo},
        identity::TpuIdentity,
        yellowstone_grpc::sender::{
            Endpoints, NewYellowstoneTpuSender, YellowstoneTpuSender, YellowstoneTpuSenderConfig,
            create_yellowstone_tpu_sender_with_callback,
        },
    },
};
```

{% endtab %}
{% endtabs %}

Define the CLI arguments:

{% tabs %}
{% tab title="Rust" %}

```rust
#[derive(clap::Parser, Debug)]
struct Args {
    /// Path to .env file to load
    #[clap(long, short)]
    dotenv: Option<PathBuf>,

    /// Endpoint to the RPC service
    #[clap(long, short)]
    rpc: Option<String>,

    /// Endpoint to the Yellowstone gRPC service
    #[clap(long, short)]
    grpc: Option<String>,

    /// X-Token for the Yellowstone gRPC service
    #[clap(long)]
    x_token: Option<String>,

    /// Path to the identity keypair file
    #[clap(long)]
    identity: Option<PathBuf>,

    /// Recipient pubkey
    #[clap(long)]
    recipient: Option<String>,
}
```

{% endtab %}
{% endtabs %}

## Write the send function

Build the transfer, sign it, serialize it to wire format with bincode, and hand it to the sender. Attach the signature as `TpuSenderTxnInfo` metadata: the callback returns it with each outcome, so you can match outcomes to transactions. `send_txn` sends to the current leader, and also to the next leader once the current leader's 4-slot window is half over:

{% tabs %}
{% tab title="Rust" %}

```rust
async fn send_lamports(
    tpu_sender: &mut YellowstoneTpuSender,
    identity: &Keypair,
    recipient: &Pubkey,
    lamports: u64,
    latest_blockhash: Hash,
) -> Signature {
    let instructions = vec![transfer(&identity.pubkey(), &recipient, lamports)];

    let transaction = VersionedTransaction::try_new(
        VersionedMessage::V0(
            v0::Message::try_compile(
                &identity.pubkey(),
                &instructions,
                &[],
                latest_blockhash,
            )
            .expect("try_compile"),
        ),
        &[&identity],
    )
    .expect("try_new");

    let signature = transaction.signatures[0];

    // The TPU sender expects the transaction in its wire format (bincode).
    let wire_txn: Vec<u8> = bincode::serialize(&transaction).expect("bincode::serialize");

    // Attach the signature as metadata: the callback hands it back with each outcome.
    let txn_info = TpuSenderTxnInfo::new(signature);

    // Sends to the current leader, and also to the next leader once the
    // current leader's 4-slot window is half over.
    tpu_sender
        .send_txn(wire_txn, Some(txn_info))
        .await
        .expect("send_txn");

    signature
}
```

{% endtab %}
{% endtabs %}

## Wire up main

Parse the arguments, load the optional `.env` file, resolve the endpoints and identity, then build the sender. The endpoints go in the sender's config, the identity goes in as a `TpuIdentity` built from your keypair, and passing a callback channel to `create_yellowstone_tpu_sender_with_callback` lets you track each transaction's outcome:

{% tabs %}
{% tab title="Rust" %}

```rust
#[tokio::main]
async fn main() {
    use std::io::Write;

    let mut out = std::io::stdout();
    let args = Args::parse();

    // Supports a .env file with RPC_ENDPOINT, GRPC_ENDPOINT, GRPC_X_TOKEN, and IDENTITY.
    if let Ok(env_path) = args.dotenv.unwrap_or("./.env".into()).canonicalize() {
        if dotenvy::from_path(env_path).is_err() {
            eprintln!("Warning: failed to load .env file");
        }
    } else {
        eprintln!("Warning: failed to canonicalize .env file path");
    }

    let recipient_pubkey: Pubkey = match args.recipient {
        Some(recipient) => recipient.parse().expect("Failed to parse recipient pubkey"),
        None => Pubkey::new_unique(),
    };

    let rpc_endpoint = match args.rpc {
        Some(endpoint) => endpoint,
        None => env::var("RPC_ENDPOINT")
            .expect("RPC_ENDPOINT must be set in the .env file or environment"),
    };

    let grpc_endpoint = match args.grpc {
        Some(endpoint) => endpoint,
        None => env::var("GRPC_ENDPOINT")
            .expect("GRPC_ENDPOINT must be set in the .env file or environment"),
    };

    let grpc_x_token = match args.x_token {
        Some(x_token) => Some(x_token),
        None => match env::var("GRPC_X_TOKEN") {
            Ok(token) => Some(token),
            Err(_) => {
                eprintln!("Warning: GRPC_X_TOKEN not set in the .env file or environment");
                None
            }
        },
    };

    let identity = match args.identity {
        Some(path) => solana_keypair::read_keypair_file(path)
            .expect("Failed to read identity keypair file"),
        None => {
            if let Ok(identity_path) = env::var("IDENTITY") {
                solana_keypair::read_keypair_file(identity_path)
                    .expect("Failed to read identity keypair file from env")
            } else {
                eprintln!("IDENTITY not set, using a new random identity");
                Keypair::new()
            }
        }
    };

    let rpc_client =
        RpcClient::new_with_commitment(rpc_endpoint.clone(), CommitmentConfig::confirmed());

    writeln!(out, "Using identity: {}", identity.pubkey()).expect("writeln");

    // The sender connects to the RPC and gRPC endpoints set in its config.
    let config = YellowstoneTpuSenderConfig {
        endpoints: Endpoints {
            rpc: Url::parse(&rpc_endpoint).expect("Failed to parse RPC endpoint URL"),
            grpc: Url::parse(&grpc_endpoint).expect("Failed to parse gRPC endpoint URL"),
            grpc_x_token,
        },
        // Send to each leader's normal TPU port. Agave 4.3 can drop transactions sent
        // to the forwards port, the crate's default.
        tpu: TpuSenderConfig {
            tpu_port: TpuPortKind::Normal,
            ..Default::default()
        },
        ..Default::default()
    };

    // Pass a callback so you can track whether each transaction was sent, failed, or dropped.
    let (callback_tx, mut callback_rx) = tokio::sync::mpsc::unbounded_channel();

    // Keep `sender` alive: dropping the last sender shuts down the TPU driver and
    // discards transactions still waiting for a connection.
    let NewYellowstoneTpuSender {
        mut sender,
        related_objects_jh: _,
    } = create_yellowstone_tpu_sender_with_callback(
        config,
        TpuIdentity::from_keypair(&identity),
        callback_tx,
    )
    .await
    .expect("tpu-sender");

    const LAMPORTS: u64 = 1000;

    let latest_blockhash = rpc_client
        .get_latest_blockhash()
        .await
        .expect("get_latest_blockhash");

    let signature = send_lamports(
        &mut sender,
        &identity,
        &recipient_pubkey,
        LAMPORTS,
        latest_blockhash,
    )
    .await;

    // Read the signature back from the metadata attached to the response.
    let signature_of = |info: Option<TpuSenderTxnInfo>| {
        info.as_ref()
            .and_then(|info| info.downcast_ref::<Signature>())
            .copied()
    };

    match callback_rx
        .recv()
        .await
        .expect("receive tpu sender response")
    {
        TpuSenderResponse::TxSent(sent) => {
            assert_eq!(signature_of(sent.info), Some(signature), "unexpected tx signature");
            writeln!(
                out,
                "sent transaction with signature `{}` to validator `{}`",
                signature, sent.remote_peer_identity
            )
            .expect("writeln");
        }
        TpuSenderResponse::TxFailed(failed) => {
            eprintln!(
                "sending to validator `{}` failed: {}",
                failed.remote_peer_identity, failed.failure_reason
            );
        }
        TpuSenderResponse::TxDrop(dropped) => {
            eprintln!(
                "transaction dropped for validator `{}`: {}",
                dropped.remote_peer_identity, dropped.drop_reason
            );
        }
    }
}
```

{% endtab %}
{% endtabs %}

## Run it

Pass the endpoints as arguments, or put them in a `.env` file:

{% code title=".env" %}

```bash
RPC_ENDPOINT=https://<your-endpoint>.mainnet.rpcpool.com/<your-token>
GRPC_ENDPOINT=https://<your-endpoint>.mainnet.rpcpool.com:443
GRPC_X_TOKEN=<your-token>
IDENTITY=/path/to/identity.json
```

{% endcode %}

Then run:

```bash
cargo run -- --recipient <recipient-pubkey>
```

The callback reports one of three outcomes: `TxSent` when the transaction was written to a validator's QUIC stream (with that validator's identity and the metadata you attached), `TxFailed` when writing to the validator's connection still failed after the client's own send retries (3 attempts by default, set by `max_send_attempt`), or `TxDrop` when the transaction was dropped before it was sent (for example, the validator stayed unreachable after the client's connection retries, or its queue was full). `TxSent` means the transaction was written to the connection, not that it landed, so confirm it with `getSignatureStatuses`.

## What's next

This client gives you the primitives to build your own routing logic without reinventing QUIC handling or leader tracking. To send only to validators you trust and skip known bad actors, combine it with on-chain Shield policies: [Protect transactions from MEV with Shield](https://docs.triton.one/solana/quickstart/sending-transactions/protect-transactions-with-shield).

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Protect transactions from MEV with Shield

Combine on-chain Yellowstone Shield policies with the Jet TPU client so your transactions only reach validators you trust.

Solana's leader schedule is deterministic, so you often know exactly which validator will process your transaction. If that leader is a bad actor, your transaction still routes to it by default, which leaves you exposed to sandwiching, frontrunning, censorship, and slow block production.

[Yellowstone Shield](https://docs.triton.one/solana/sending-transactions/shield-mev-protection) addresses this with on-chain allowlists and blocklists for validators. Combined with the [Yellowstone Jet TPU client](https://docs.triton.one/solana/quickstart/sending-transactions/yellowstone-jet-tpu-client), your application connects directly to validator TPUs, checks each leader against your Shield policies, and only sends to validators you allow. The result is RPC-independent transaction routing where you decide which validators are allowed to see your transactions.

* Shield program: [github.com/rpcpool/yellowstone-shield](https://github.com/rpcpool/yellowstone-shield)
* Policy store crate: [`yellowstone-shield-store`](https://crates.io/crates/yellowstone-shield-store)
* Policy explorer: [validators.app/yellowstone-shield](https://www.validators.app/yellowstone-shield)

## How validator-level MEV happens

A transaction has to reach the current block leader to be processed. When that leader misbehaves, default transaction sending gives you no say in the matter. Common behaviours worth routing around:

* **Sandwich attacks:** inserting transactions before and after yours to extract value.
* **Frontrunning:** copying your transaction and executing it first.
* **Censorship:** selectively dropping transactions.
* **Slow block production:** delaying your transactions.

Shield lets you decide, ahead of time, which validators are allowed to handle your transactions.

## How Shield works

Yellowstone Shield is an on-chain access-control program (`b1ockYL7X6sGtJzueDbxRVBEEPN4YeqoLW276R3MX8W`). You define policies, and each policy lives on-chain as a Program Derived Address (PDA), derived from the seeds `"shield"`, `"policy"`, and the policy's mint, that anyone with the address can use:

* **Allowlists** send only to trusted validators.
* **Blocklists** never send to known bad actors.

The TPU client reads these policies through a `PolicyStore`, which loads every policy over RPC when it starts and then follows changes over a gRPC subscription.

## Community policies

The community already maintains several Shield policies. Browse them at [validators.app/yellowstone-shield](https://www.validators.app/yellowstone-shield):

| Policy                                | Type  | Validators | Purpose                         |
| ------------------------------------- | ----- | ---------- | ------------------------------- |
| Top 25 Validators by Stake (TV25)     | Allow | 25         | Only send to top validators     |
| Sandwiched.me Sandwicher List (DROPS) | Deny  | 3          | Block known MEV sandwichers     |
| Jito Drop List (DROPJ)                | Deny  | 17         | Block Jito blocklist validators |
| Marinade Drop List (DROPM)            | Deny  | 73         | Block Marinade's blocklist      |
| Slow Block Producers (SLOWAF)         | Deny  | 21         | Avoid slow validators           |

Validator counts are as of October 2026; the lists change as their maintainers update them. You can use these as they are, or create your own.

## RPC Shield or the TPU client?

If you send through Triton RPC, you can apply Shield without writing any Rust by adding a policy to your `sendTransaction` call:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sendTransaction",
  "params": [
    "<base64_transaction>",
    {
      "encoding": "base64",
      "forwardingPolicies": ["<your_policy_pda>"]
    }
  ]
}
```

That route is the quickest to integrate, but it depends on the RPC's forwarding logic and gives you no direct control over routing. With the TPU client, you connect to validators yourself, so you decide everything. Pick based on your workload:

| Feature                    | RPC Shield (Triton RPC)     | TPU client Shield                           |
| -------------------------- | --------------------------- | ------------------------------------------- |
| Setup                      | Easy: add one parameter     | Moderate: requires Rust                     |
| RPC dependency             | Needs a Shield-enabled RPC  | None                                        |
| Validator connection       | Through the RPC             | Direct QUIC connections                     |
| Control over routing       | Limited to the RPC's logic  | Full                                        |
| Transaction prioritisation | RPC-controlled              | Yours                                       |
| Best for                   | Quick integration, web apps | High-throughput apps, MEV-sensitive routing |

The rest of this guide covers the TPU client route.

## Prerequisites

* Rust 1.97.1 or later, as for the [Yellowstone Jet TPU client](https://docs.triton.one/solana/quickstart/sending-transactions/yellowstone-jet-tpu-client).
* A Triton RPC endpoint and a Yellowstone gRPC endpoint with an x-token. [Get an endpoint](https://customers.triton.one/onboarding).
* The [Yellowstone Jet TPU client](https://docs.triton.one/solana/quickstart/sending-transactions/yellowstone-jet-tpu-client) set up, or follow the project setup below.

## Choose or create a policy

### Option A: use an existing policy

The quickest start is a community policy. For example, to block known MEV sandwichers with the Sandwiched.me list (DROPS):

{% code title="Policy address" %}

```rust
use solana_pubkey::Pubkey;
use std::str::FromStr;

// Sandwiched.me Sandwicher List (DROPS), a deny list of known MEV sandwichers.
let shield_policy = Pubkey::from_str("xMTozeQTEX2MR9KUon8vjg17U5Q9459RSASE3wy5eNB")
    .expect("valid pubkey");
```

{% endcode %}

Browse more at [validators.app/yellowstone-shield](https://www.validators.app/yellowstone-shield).

### Option B: create your own policy

For custom control, create a policy with the Yellowstone Shield CLI.

{% stepper %}
{% step %}

#### Build the CLI

```bash
git clone https://github.com/rpcpool/yellowstone-shield
cd yellowstone-shield
cargo build --release --bin yellowstone-shield-cli
```

The CLI uses the RPC URL and keypair from your Solana CLI config. If you pass `--rpc` or `--keypair`, it also saves those values into that config file.
{% endstep %}

{% step %}

#### Prepare policy metadata

Create a JSON file describing the policy, upload it to IPFS or Arweave, and keep the URL:

```json
{
  "name": "My MEV blocklist",
  "symbol": "MEVBLOCK",
  "description": "Blocks validators known for sandwich attacks",
  "image": "https://the-image-url.com/shield.png",
  "external_url": "https://your-website.com"
}
```

{% endstep %}

{% step %}

#### Create the policy

Save both addresses the command prints, Policy (the PDA) and Mint:

```bash
# A blocklist denies the listed validators.
./target/release/yellowstone-shield-cli policy create \
  --strategy Deny \
  --name "My MEV blocklist" \
  --symbol "MEVBLOCK" \
  --uri "https://the-metadata-url.json"

# The output includes both addresses:
#   Policy: <YOUR_POLICY_PDA>
#   Mint: <YOUR_POLICY_MINT>
```

{% endstep %}

{% step %}

#### Add validators

Put one validator pubkey per line in `validators-to-block.txt`, then add them. Lines that aren't valid addresses are skipped:

```bash
./target/release/yellowstone-shield-cli identities add \
  --mint <YOUR_POLICY_MINT> \
  --identities-path validators-to-block.txt
```

The policy is now live on-chain and ready to use.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Use the Policy address (the PDA) wherever a policy is expected, such as `forwardingPolicies` or `shield_policy_addresses`, and the Mint only for the CLI's `--mint` flag. A Mint passed as a policy isn't found: Triton's RPC then skips every leader, so the transaction never lands even though you get a signature back, and the TPU client falls back to `default_return_value`.
{% endhint %}

## Set up the project

Create a binary crate with the TPU client's `shield` feature and the policy store. Both build on the upstream Solana crates from crates.io, so no `[patch.crates-io]` section is needed. `yellowstone-jet-tpu-client` 0.8 uses `yellowstone-grpc-client` 15.x, and `yellowstone-shield-store` 0.11 uses 13.x. Cargo builds both side by side, because the policy store does not expose its gRPC client. If you add `yellowstone-grpc-client` to your own crate, use 15.x to match the TPU client. The examples target 0.8.x. Cargo treats each 0.x minor version as a breaking release, so keep the version pinned in `Cargo.toml` and don't run `cargo add` without a version.

{% code title="Cargo.toml" %}

```toml
[package]
name = "shield-tpu-example"
version = "0.1.0"
edition = "2024"

[dependencies]
anyhow = "1"
bincode = "1.3.3"
tokio = { version = "1.48.0", features = ["macros", "rt-multi-thread", "sync", "time"] }
url = "2"

# Solana crates, at the major versions yellowstone-jet-tpu-client 0.8 is built against
# solana-client 4.4 pulls in solana-account 5, which yellowstone-shield-store 0.11 rejects
solana-client = "~4.3"
solana-commitment-config = "3"
solana-keypair = "3"
solana-message = "4"
solana-pubkey = "4"
solana-signer = "3"
solana-system-interface = { version = "3", features = ["bincode"] }
solana-transaction = { version = "4", features = ["serde", "wincode"] }

yellowstone-jet-tpu-client = { version = "0.8.1", features = ["yellowstone-grpc", "shield"] }
yellowstone-shield-store = "0.11.0"
```

{% endcode %}

Keep `solana-client` on 4.3.x until `yellowstone-shield-store` is built on `solana-account` 5. Version 0.11 uses `solana-account` 4, and `solana-client` 4.4 uses `solana-account` 5.

How the pieces fit together:

```
┌──────────────────────────────────────────────────────────┐
│                  Your application                        │
│  1. Create a Shield PolicyStore                          │
│  2. Create a TPU sender                                  │
│  3. Build and sign a transaction                         │
│  4. Call send_txn_with_shield_policies()                 │
└─────────────────┬────────────────────────────────────────┘
                  │
                  ▼
┌──────────────────────────────────────────────────────────┐
│           Yellowstone TPU client (Jet)                   │
│  • Tracks the current slot and the leader schedule       │
│  • Picks the leaders in range: the current leader,       │
│    plus the next one late in its 4-slot window           │
│  • Checks each leader against your policies              │
│    ├─ allowed → send the transaction over QUIC           │
│    └─ blocked → skip that leader                         │
│  • Every leader blocked → RemotePeerBlocked error        │
└──────────────────────────────────────────────────────────┘
```

## Send with Shield

This complete example sends a SOL transfer only to leaders that pass your Shield policy. Fill in your own endpoints and x-token.

{% code title="src/main.rs" lineNumbers="true" %}

```rust
use {
    solana_client::nonblocking::rpc_client::RpcClient,
    solana_commitment_config::CommitmentConfig,
    solana_keypair::Keypair,
    solana_message::{VersionedMessage, v0},
    solana_pubkey::Pubkey,
    solana_signer::Signer,
    solana_system_interface::instruction::transfer,
    solana_transaction::versioned::VersionedTransaction,
    std::{str::FromStr, time::Duration},
    url::Url,
    yellowstone_jet_tpu_client::{
        config::{TpuPortKind, TpuSenderConfig},
        core::{TpuSenderResponse, TpuSenderTxnInfo},
        identity::TpuIdentity,
        yellowstone_grpc::sender::{
            Endpoints, NewYellowstoneTpuSender, SendErrorKind, ShieldBlockList,
            YellowstoneTpuSenderConfig, create_yellowstone_tpu_sender_with_callback,
        },
    },
    yellowstone_shield_store::{
        PolicyStore, PolicyStoreConfig, PolicyStoreGrpcConfig, PolicyStoreRpcConfig,
    },
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let rpc_endpoint = "<your-rpc-endpoint>".to_string();
    let grpc_endpoint = "<your-grpc-endpoint>".to_string();
    let grpc_x_token = Some("<your-token>".to_string());

    // In production, read this from a file.
    let identity = Keypair::new();
    println!("Using identity: {}", identity.pubkey());

    let recipient = Pubkey::new_unique();

    // Step 1: set up the Shield policy store.
    let config = PolicyStoreConfig {
        rpc: PolicyStoreRpcConfig {
            endpoint: rpc_endpoint.clone(),
        },
        grpc: PolicyStoreGrpcConfig {
            endpoint: grpc_endpoint.clone(),
            x_token: grpc_x_token.clone(),
            commitment: None,
            timeout: Duration::from_secs(60),
            connect_timeout: Duration::from_secs(10),
            tcp_nodelay: true,
            http2_adaptive_window: true,
            http2_keep_alive: false,
            http2_keep_alive_interval: None,
            http2_keep_alive_timeout: None,
            http2_keep_alive_while_idle: None,
            max_decoding_message_size: Some(16 * 1024 * 1024), // 16 MiB
            initial_connection_window_size: None,
            initial_stream_window_size: None,
        },
    };

    let policy_store = PolicyStore::build().config(config).run().await?;

    // Use the Sandwiched.me MEV blocklist (DROPS). This is the policy PDA, not its mint.
    let shield_policy_pubkey = Pubkey::from_str("xMTozeQTEX2MR9KUon8vjg17U5Q9459RSASE3wy5eNB")?;

    // Step 2: create the TPU sender.
    let sender_config = YellowstoneTpuSenderConfig {
        endpoints: Endpoints {
            rpc: Url::parse(&rpc_endpoint)?,
            grpc: Url::parse(&grpc_endpoint)?,
            grpc_x_token,
        },
        // Send to each leader's normal TPU port. Agave 4.3 can drop transactions sent
        // to the forwards port, the crate's default.
        tpu: TpuSenderConfig {
            tpu_port: TpuPortKind::Normal,
            ..Default::default()
        },
        ..Default::default()
    };

    // The callback reports what happened to each transaction after it is queued.
    let (callback_tx, mut callback_rx) = tokio::sync::mpsc::unbounded_channel();

    let NewYellowstoneTpuSender {
        mut sender,
        related_objects_jh: _,
    } = create_yellowstone_tpu_sender_with_callback(
        sender_config,
        TpuIdentity::from_keypair(&identity),
        callback_tx,
    )
    .await?;

    // Step 3: create the RPC client.
    let rpc_client = RpcClient::new_with_commitment(rpc_endpoint, CommitmentConfig::confirmed());

    // Step 4: build the transaction.
    const LAMPORTS: u64 = 1000;
    let instructions = vec![transfer(&identity.pubkey(), &recipient, LAMPORTS)];

    let latest_blockhash = rpc_client.get_latest_blockhash().await?;

    let transaction = VersionedTransaction::try_new(
        VersionedMessage::V0(v0::Message::try_compile(
            &identity.pubkey(),
            &instructions,
            &[],
            latest_blockhash,
        )?),
        &[&identity],
    )?;

    let signature = transaction.signatures[0];
    let wire_txn = bincode::serialize(&transaction)?;

    // Step 5: send with Shield protection.
    let shield_blocklist = ShieldBlockList {
        policy_store: &policy_store,
        shield_policy_addresses: &[shield_policy_pubkey],
        default_return_value: true, // fail-open: send anyway if a policy address isn't found
    };

    match sender
        .send_txn_with_shield_policies(
            wire_txn,
            shield_blocklist,
            Some(TpuSenderTxnInfo::new(signature)),
        )
        .await
    {
        Ok(()) => {
            // Ok means the transaction was queued to the sender, not that it reached a leader.
            println!("Transaction queued. Signature: {}", signature);
            println!("At least one leader in range passed the Shield policy.");

            // Wait for the outcome before main returns: dropping `sender` shuts the driver down
            // and can discard a transaction that hasn't gone out yet.
            match callback_rx.recv().await {
                Some(TpuSenderResponse::TxSent(sent)) => {
                    println!("Sent to validator {}", sent.remote_peer_identity);
                }
                Some(TpuSenderResponse::TxFailed(failed)) => {
                    println!("Send to validator {} failed: {}", failed.remote_peer_identity, failed.failure_reason);
                }
                Some(TpuSenderResponse::TxDrop(dropped)) => {
                    println!("Dropped for validator {}: {}", dropped.remote_peer_identity, dropped.drop_reason);
                }
                None => println!("Sender shut down before reporting an outcome."),
            }
        }
        Err(e) if matches!(e.kind, SendErrorKind::RemotePeerBlocked) => {
            println!("Transaction not sent: every leader in range is blocked by the Shield policy.");
        }
        Err(e) => println!("Transaction not sent: {e}"),
    }

    Ok(())
}
```

{% endcode %}

What the key pieces do:

* **`PolicyStoreConfig`** points the store at your RPC and gRPC endpoints.
* **`PolicyStore`** caches Shield policies from on-chain data and keeps them current over gRPC. If that stream ends, the store logs a warning and stops receiving updates (it doesn't reconnect), so rebuild it to pick up later policy changes.
* **`ShieldBlockList`** links the policy store to the policy PDAs you want to enforce.
* **`send_txn_with_shield_policies()`** sends only to the leaders in range that your policies allow, and returns a `SendErrorKind::RemotePeerBlocked` error when none of them is allowed.
* **`default_return_value: true`** is fail-open: if a policy address isn't found in the policy store (a typo, the mint passed instead of the policy PDA, or a policy not yet synced), the transaction is sent anyway. Combined with a typo, fail-open gives no protection at all. Set it to `false` to fail closed.

## How it works under the hood

When you call `send_txn_with_shield_policies`, the client reads the current slot, picks the leaders in range from the schedule, and checks each one against your policies before deciding where to send:

```
1. send_txn_with_shield_policies(txn, shield, txn_info)
                  │
                  ▼
2. TPU client reads the current slot
                  │
                  ▼
3. Picks the leaders in range: the current leader, plus the
   next one once the current 4-slot window is half over
                  │
                  ▼
4. Shield check for each leader: is it allowed?
   ├─ PolicyStore → snapshot()
   └─ is_allowed([policies], &leader_pubkey)
                  │
        ┌─────────┴─────────┐
        ▼                   ▼
   YES (any leader)     NO (every leader)
   5a. Send over QUIC   5b. Return SendError { kind: SendErrorKind::RemotePeerBlocked, .. }
       to the allowed       (transaction not sent)
       leaders
```

The blocklist check, from the `yellowstone-jet-tpu-client` source:

{% code title="ShieldBlockList" %}

```rust
impl Blocklist for ShieldBlockList<'_> {
    fn is_blocked(&self, peer_address: &Pubkey) -> bool {
        use yellowstone_shield_store::PolicyStoreTrait;

        !self
            .policy_store
            .snapshot()
            .is_allowed(self.shield_policy_addresses, peer_address)
            .unwrap_or(self.default_return_value)
    }
}
```

{% endcode %}

This means:

* **Blocklists (Deny):** if the validator is on the list, `is_blocked()` is true and the transaction is not sent to it.
* **Allowlists (Allow):** if the validator is not on the list, `is_blocked()` is true and the transaction is not sent to it.

The `PolicyStore` syncs policies continuously, so `snapshot()` is a fast, lock-free read. It comes from the `PolicyStoreTrait` trait:

{% code title="PolicyStoreTrait" %}

```rust
use yellowstone_shield_store::PolicyStoreTrait; // provides snapshot()

let policy_store = PolicyStore::build().config(config).run().await?;

// Later: read the current snapshot and check a validator.
let snapshot = policy_store.snapshot();
match snapshot.is_allowed(&[policy_pda], &validator_pubkey) {
    Ok(true) => println!("Validator allowed"),
    Ok(false) => println!("Validator blocked"),
    Err(e) => println!("Policy check failed: {:?}", e),
}
```

{% endcode %}

## Handling blocked leaders

When every leader in range is blocked, the transaction is not sent, and nothing queues it for later. You have a few options:

**Retry when the next leader comes into range.** The error hands back the transaction bytes, so you can resend them unchanged:

{% code title="Retry" %}

```rust
use yellowstone_jet_tpu_client::yellowstone_grpc::sender::SendErrorKind;

let policies = [shield_policy_pubkey];
let shield = || ShieldBlockList {
    policy_store: &policy_store,
    shield_policy_addresses: &policies,
    default_return_value: true,
};
let txn_info = TpuSenderTxnInfo::new(signature);

if let Err(err) = sender
    .send_txn_with_shield_policies(wire_txn, shield(), Some(txn_info))
    .await
{
    if !matches!(err.kind, SendErrorKind::RemotePeerBlocked) {
        return Err(err.into());
    }
    // Every leader in range is blocked. A leader you haven't checked yet is only certain to be
    // in range after one full 4-slot leader window, so wait at least that long (four slots is
    // about 0.8 s at Solana's current 200 ms slot time; 1.6 s leaves margin), then resend.
    tokio::time::sleep(std::time::Duration::from_millis(1600)).await;
    sender
        .send_txn_with_shield_policies(err.txn, shield(), Some(txn_info))
        .await?;
}
```

{% endcode %}

**Fail open** by setting `default_return_value: true`, so the transaction is still sent if a policy address isn't found. With a mistyped address, that means no protection.

## Advanced usage

**Apply multiple policies.** Policies are checked in order, and the first one that lists the leader decides: a Deny policy blocks it and an Allow policy allows it. If none lists the leader, it's allowed unless one of the policies is an Allow policy:

{% code title="Multiple policies" %}

```rust
let policies = vec![
    Pubkey::from_str("xMTozeQTEX2MR9KUon8vjg17U5Q9459RSASE3wy5eNB")?, // DROPS
    Pubkey::from_str("7xTAiL3tTzgbDwsxMKi2rMXW7QKzcGrABsZc2tW6L6bj")?, // SLOWAF
];

let shield_blocklist = ShieldBlockList {
    policy_store: &policy_store,
    shield_policy_addresses: &policies,
    default_return_value: true,
};

sender
    .send_txn_with_shield_policies(
        wire_txn,
        shield_blocklist,
        Some(TpuSenderTxnInfo::new(signature)),
    )
    .await?;
```

{% endcode %}

**Broadcast to specific validators,** bypassing the leader schedule. No Shield check applies to these sends:

{% code title="Specific validators" %}

```rust
let target_validators = vec![
    Pubkey::from_str("ValidatorA...")?,
    Pubkey::from_str("ValidatorB...")?,
];

sender
    .send_txn_many_dest(
        wire_txn,
        &target_validators,
        Some(TpuSenderTxnInfo::new(signature)),
    )
    .await?;
```

{% endcode %}

## Resources

* Shield program: [github.com/rpcpool/yellowstone-shield](https://github.com/rpcpool/yellowstone-shield)
* Jet engine: [github.com/rpcpool/yellowstone-jet](https://github.com/rpcpool/yellowstone-jet)
* Policy store crate: [`yellowstone-shield-store`](https://crates.io/crates/yellowstone-shield-store)
* Policy explorer: [validators.app/yellowstone-shield](https://www.validators.app/yellowstone-shield)
* Shield announcement: [Introducing Yellowstone Shield](https://blog.triton.one/introducing-yellowstone-shield)

## What's next

Pair Shield with a sender you control: the [Yellowstone Jet TPU client](https://docs.triton.one/solana/quickstart/sending-transactions/yellowstone-jet-tpu-client) combines on-chain Shield policies with your own routing and retry logic.

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Account methods

Solana RPC methods for account data, balances, program accounts, SPL token accounts, token supply, vote accounts, and rent-exempt minimums.

## Account data

| Method                                                                                         | What it returns                                                                                                                                                                                                                                        |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`getAccountInfo`](https://docs.triton.one/solana/rpc-methods/readme/getaccountinfo)           | The state and metadata of one account, or null if it doesn't exist.                                                                                                                                                                                    |
| [`getMultipleAccounts`](https://docs.triton.one/solana/rpc-methods/readme/getmultipleaccounts) | The same, for many addresses in one call, in request order.                                                                                                                                                                                            |
| [`getBalance`](https://docs.triton.one/solana/rpc-methods/readme/getbalance)                   | The lamport (SOL) balance of an address.                                                                                                                                                                                                               |
| [`getProgramAccounts`](https://docs.triton.one/solana/rpc-methods/readme/getprogramaccounts)   | Every account a program owns, optionally filtered by data or size (on shared endpoints, SPL Token and Token-2022 queries need a `memcmp` filter on the owner at offset 32 or the mint at offset 0, and System Program queries need a `memcmp` filter). |

## SPL token accounts

| Method                                                                                                       | What it returns                                 |
| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
| [`getTokenAccountBalance`](https://docs.triton.one/solana/rpc-methods/readme/gettokenaccountbalance)         | The balance of a single SPL token account.      |
| [`getTokenAccountsByOwner`](https://docs.triton.one/solana/rpc-methods/readme/gettokenaccountsbyowner)       | The token accounts a wallet owns.               |
| [`getTokenAccountsByDelegate`](https://docs.triton.one/solana/rpc-methods/readme/gettokenaccountsbydelegate) | The token accounts a given delegate can act on. |
| [`getTokenSupply`](https://docs.triton.one/solana/rpc-methods/readme/gettokensupply)                         | A mint's total supply.                          |
| [`getTokenLargestAccounts`](https://docs.triton.one/solana/rpc-methods/readme/gettokenlargestaccounts)       | The 20 largest token accounts of a mint.        |

## Shared endpoint indexes

On Triton shared endpoints, `getProgramAccounts`, `getTokenAccountsByOwner`, and `getTokenAccountsByDelegate` are served from Cloudbreak's indexes, and `getTokenLargestAccounts` from the DAS index.

## Cluster and validator state

| Method                                                                                                                     | What it returns                                                                            |
| -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| [`getLargestAccounts`](https://docs.triton.one/solana/rpc-methods/readme/getlargestaccounts)                               | The 20 largest accounts by SOL balance. Disabled on Triton mainnet endpoints (HTTP `410`). |
| [`getMinimumBalanceForRentExemption`](https://docs.triton.one/solana/rpc-methods/readme/getminimumbalanceforrentexemption) | The lamports an account of a given size needs to be rent-exempt.                           |
| [`getStakeMinimumDelegation`](https://docs.triton.one/solana/rpc-methods/readme/getstakeminimumdelegation)                 | The cluster's minimum stake delegation.                                                    |
| [`getVoteAccounts`](https://docs.triton.one/solana/rpc-methods/readme/getvoteaccounts)                                     | Current and delinquent vote accounts.                                                      |

## NFTs and compressed assets

For NFTs, compressed assets, and token metadata, use the [Metaplex DAS API](https://docs.triton.one/solana/rpc-methods/readme/das-api).

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# getAccountInfo

Returns lamports, owner, data, executable flag, and space for one account address; value is null if the account does not exist at the requested commitment.

## Request

{% tabs %}
{% tab title="cURL" %}

```bash
curl "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>" -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getAccountInfo",
  "params": [
    "vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36NKPTg",
    {
      "commitment": "finalized",
      "encoding": "base64"
    }
  ]
}'
```

{% endtab %}

{% tab title="Kit" %}

```typescript
import { address, createSolanaRpc } from "@solana/kit";

const rpc_url = "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>";
const rpc = createSolanaRpc(rpc_url);

const publicKey = address("vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36NKPTg");
const accountInfo = await rpc.getAccountInfo(publicKey).send();

console.log("Account Info:", accountInfo);
```

{% endtab %}

{% tab title="web3.js" %}

```typescript
import { Connection, PublicKey } from "@solana/web3.js";

const connection = new Connection("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>", "confirmed");
const publicKey = new PublicKey("vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36NKPTg");
const accountInfo = await connection.getAccountInfo(publicKey);

console.log("Account Info:", accountInfo);
```

{% endtab %}

{% tab title="Rust" %}

```rust
// Cargo.toml: anyhow = "1", solana-client = "~4.4", solana-commitment-config = "3",
// solana-sdk = "5", tokio = { version = "1", features = ["full"] }. solana-client 4.4 takes
// solana-sdk 5.x types. Requires Rust 1.98.1 or newer (solana-client 4.4).
use anyhow::Result;
use solana_client::nonblocking::rpc_client::RpcClient;
use solana_commitment_config::CommitmentConfig;
use solana_sdk::pubkey::Pubkey;
use std::str::FromStr;

#[tokio::main]
async fn main() -> Result<()> {
    let client = RpcClient::new_with_commitment(
        String::from("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>"),
        CommitmentConfig::confirmed(),
    );
    let pubkey = Pubkey::from_str("vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36NKPTg")?;
    let account = client.get_account(&pubkey).await?;

    println!("{:#?}", account);

    Ok(())
}
```

{% endtab %}
{% endtabs %}

## Parameters

**`pubkey`** · string · required

Pubkey of account to query, as base-58 encoded string.

**`config`** · object

Configuration object.

**`commitment`** · string · default `finalized`

Values: `processed`, `confirmed`, `finalized`

Solana RPC uses the following commitment levels:

| Value       | Description                                                                                                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `processed` | Return data from the highest slot this node has processed on the fork it currently considers best. This is the newest view, but it can still change if the cluster switches forks. |
| `confirmed` | Return data from the highest slot the cluster has finalized. On Alpenglow, `confirmed` and `finalized` are the same level.                                                         |
| `finalized` | Return data from the highest slot that the cluster has finalized. On Alpenglow there are no vote towers or lockouts: a slot is finalized by certificates of aggregated votes.      |

**`encoding`** · string · default `binary`

Values: `base58`, `base64`, `base64+zstd`, `binary`, `jsonParsed`

Encoding format for account data.

| Encoding      | Data format                | Notes                                                                                                                                                                                                                       |
| ------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `base64`      | `[data, "base64"]`         | Recommended                                                                                                                                                                                                                 |
| `base58`      | `[data, "base58"]`         | Slow. The account's data field must be 128 bytes or fewer                                                                                                                                                                   |
| `base64+zstd` | `[data, "base64+zstd"]`    | [Zstandard](https://facebook.github.io/zstd/) compressed                                                                                                                                                                    |
| `jsonParsed`  | `{program, parsed, space}` | Falls back to `[data, "base64"]` if no parser found                                                                                                                                                                         |
| `binary`      | `string`                   | ⚠️ Deprecated. Legacy encoding retained for backwards compatibility. Same base58 encoding as `base58` with the same 128-byte data field limit, but returns data as a plain string instead of an array. Use `base64` instead |

If you use `jsonParsed`, the returned data object uses the stable wrapper `{program, parsed, space}`. The `program` field identifies the parser that produced `parsed`. If no parser is available, the RPC node falls back to `[data, "base64"]`.

| `program` value          | Parsed account type                            |
| ------------------------ | ---------------------------------------------- |
| `address-lookup-table`   | Address lookup table accounts                  |
| `bpf-upgradeable-loader` | Upgradeable loader program and buffer accounts |
| `config`                 | Config accounts                                |
| `nonce`                  | Durable nonce accounts                         |
| `spl-token`              | SPL Token accounts                             |
| `spl-token-2022`         | SPL Token 2022 accounts                        |
| `stake`                  | Stake accounts                                 |
| `sysvar`                 | Sysvar accounts                                |
| `vote`                   | Vote accounts                                  |

The nested `parsed` payload remains program-specific.

For the shared account wrapper returned by this method, see [Account Data](https://solana.com/docs/rpc/json-structures#account-data).

**`dataSlice`** · object

Request a slice of the account's data.

| Field    | Type    | Description                                           |
| -------- | ------- | ----------------------------------------------------- |
| `offset` | `usize` | Byte offset from which to start reading account data. |
| `length` | `usize` | Number of bytes to return.                            |

{% hint style="info" %}
Data slicing is only available for `base58`, `base64`, `base64+zstd`, and `binary` encodings.
{% endhint %}

**`minContextSlot`** · number

The minimum slot that the request can be evaluated at.

## Response

```json
{
  "jsonrpc": "2.0",
  "result": {
    "context": { "apiVersion": "4.3.2", "slot": 341197053 },
    "value": {
      "data": ["", "base64"],
      "executable": false,
      "lamports": 88849814690250,
      "owner": "11111111111111111111111111111111",
      "rentEpoch": 18446744073709551615,
      "space": 0
    }
  },
  "id": 1
}
```

## Result

RpcResponse object containing:

**`context`** · object

Slot and API version the node used to answer this request.

| Field        | Type     | Description                                                                     |
| ------------ | -------- | ------------------------------------------------------------------------------- |
| `slot`       | `u64`    | Slot at which the node evaluated this request.                                  |
| `apiVersion` | `string` | RPC API version reported by the node. This field may be omitted by older nodes. |

**`value`** · object | null

If the requested account does not exist, `value` is `null`. Otherwise, it is an account object with the following fields:

This uses the shared [Account Data](https://solana.com/docs/rpc/json-structures#account-data) structure.

| Field        | Type                                     | Description                                                                                                                                                                                                                                                                                              |
| ------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`       | `string \| [string, encoding] \| object` | Account data. If `encoding` is `binary`, this is a plain base-58 string. If `encoding` is `base58`, `base64`, or `base64+zstd`, this is `[data, encoding]`. If `encoding` is `jsonParsed`, this is `{program, parsed, space}`; if no parser is available, the RPC node falls back to `[data, "base64"]`. |
| `executable` | `bool`                                   | Whether the account contains a program and is therefore read-only.                                                                                                                                                                                                                                       |
| `lamports`   | `u64`                                    | Lamports assigned to this account.                                                                                                                                                                                                                                                                       |
| `owner`      | `string`                                 | Program owner pubkey, as a base-58 encoded string.                                                                                                                                                                                                                                                       |
| `rentEpoch`  | `u64`                                    | Legacy field. Solana no longer collects rent, and rent-exempt accounts report `18446744073709551615` (u64::MAX).                                                                                                                                                                                         |
| `space`      | `u64 \| null`                            | Account data size in bytes. Current Solana RPC responses populate this field for encoded account responses.                                                                                                                                                                                              |

When `data` is returned as an object, it contains:

| Field     | Type     | Description                                                                                 |
| --------- | -------- | ------------------------------------------------------------------------------------------- |
| `program` | `string` | Name of the parser that produced the decoded account data.                                  |
| `parsed`  | `object` | Parser-specific JSON payload. Its structure depends on the owning program and account type. |
| `space`   | `u64`    | Account data size in bytes.                                                                 |

***

*Adapted from the* [*Solana `getAccountInfo` reference*](https://solana.com/docs/rpc/http/getaccountinfo)*, maintained by the Solana Foundation.*

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# getBalance

Returns the lamport balance for a single account address at the requested commitment.

## Request

{% tabs %}
{% tab title="cURL" %}

```bash
curl "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>" -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getBalance",
  "params": [
    "83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri",
    {
      "commitment": "finalized"
    }
  ]
}'
```

{% endtab %}

{% tab title="Kit" %}

```typescript
import { address, createSolanaRpc } from "@solana/kit";

const rpc_url = "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>";
const rpc = createSolanaRpc(rpc_url);

const publicKey = address("83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri");
const balance = await rpc.getBalance(publicKey).send();

console.log("Account Balance:", balance);
```

{% endtab %}

{% tab title="web3.js" %}

```typescript
import { Connection, PublicKey } from "@solana/web3.js";

const connection = new Connection("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>", "confirmed");
const publicKey = new PublicKey("83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri");
const balance = await connection.getBalance(publicKey);

console.log("Account Balance:", balance);
```

{% endtab %}

{% tab title="Rust" %}

```rust
// Cargo.toml: anyhow = "1", solana-client = "~4.4", solana-commitment-config = "3",
// solana-sdk = "5", tokio = { version = "1", features = ["full"] }. solana-client 4.4 takes
// solana-sdk 5.x types. Requires Rust 1.98.1 or newer (solana-client 4.4).
use anyhow::Result;
use solana_client::nonblocking::rpc_client::RpcClient;
use solana_commitment_config::CommitmentConfig;
use solana_sdk::{native_token::LAMPORTS_PER_SOL, pubkey::Pubkey};
use std::str::FromStr;

#[tokio::main]
async fn main() -> Result<()> {
    let client = RpcClient::new_with_commitment(
        String::from("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>"),
        CommitmentConfig::confirmed(),
    );

    let pubkey = Pubkey::from_str("83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri")?;
    let balance = client.get_balance(&pubkey).await?;

    println!("{} SOL", balance as f64 / LAMPORTS_PER_SOL as f64);

    Ok(())
}
```

{% endtab %}
{% endtabs %}

## Parameters

**`pubkey`** · string · required

Pubkey of account to query, as base-58 encoded string.

**`config`** · object

Configuration object.

**`commitment`** · string · default `finalized`

Values: `processed`, `confirmed`, `finalized`

Solana RPC uses the following commitment levels:

| Value       | Description                                                                                                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `processed` | Return data from the highest slot this node has processed on the fork it currently considers best. This is the newest view, but it can still change if the cluster switches forks. |
| `confirmed` | Return data from the highest slot the cluster has finalized. On Alpenglow, `confirmed` and `finalized` are the same level.                                                         |
| `finalized` | Return data from the highest slot that the cluster has finalized. On Alpenglow there are no vote towers or lockouts: a slot is finalized by certificates of aggregated votes.      |

**`minContextSlot`** · number

The minimum slot that the request can be evaluated at.

## Response

```json
{
  "jsonrpc": "2.0",
  "result": {
    "context": { "apiVersion": "4.3.2", "slot": 1 },
    "value": 0
  },
  "id": 1
}
```

## Result

RpcResponse object containing:

**`context`** · object

Slot and API version the node used to answer this request.

| Field        | Type     | Description                                                                     |
| ------------ | -------- | ------------------------------------------------------------------------------- |
| `slot`       | `u64`    | Slot at which the node evaluated this request.                                  |
| `apiVersion` | `string` | RPC API version reported by the node. This field may be omitted by older nodes. |

**`value`** · u64

Account balance, in lamports.

***

*Adapted from the* [*Solana `getBalance` reference*](https://solana.com/docs/rpc/http/getbalance)*, maintained by the Solana Foundation.*

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# getMultipleAccounts

Returns account state and metadata for multiple addresses, in request order.

## Request

{% tabs %}
{% tab title="cURL" %}

```bash
curl "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>" -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getMultipleAccounts",
  "params": [
    [
      "vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36NKPTg",
      "4fYNw3dojWmQ4dXtSGE9epjRGy9pFSx62YypT7avPYvA"
    ],
    {
      "encoding": "base64",
      "commitment": "finalized"
    }
  ]
}'
```

{% endtab %}

{% tab title="Kit" %}

```typescript
import { address, createSolanaRpc } from "@solana/kit";

const rpc_url = "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>";
const rpc = createSolanaRpc(rpc_url);

let addresses = [
  address("vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36NKPTg"),
  address("4fYNw3dojWmQ4dXtSGE9epjRGy9pFSx62YypT7avPYvA")
];

let config = {
  encoding: "base64",
  commitment: "finalized"
} as const;

let accounts = await rpc.getMultipleAccounts(addresses, config).send();

console.log(accounts);
```

{% endtab %}

{% tab title="web3.js" %}

```typescript
import {
  Connection,
  PublicKey,
  type GetMultipleAccountsConfig
} from "@solana/web3.js";

const connection = new Connection("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>", "confirmed");

let addresses = [
  new PublicKey("vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36NKPTg"),
  new PublicKey("4fYNw3dojWmQ4dXtSGE9epjRGy9pFSx62YypT7avPYvA")
];

let config: GetMultipleAccountsConfig = {
  commitment: "finalized"
};

let accounts = await connection.getMultipleAccountsInfo(addresses, config);

console.log(accounts);
```

{% endtab %}

{% tab title="Rust" %}

```rust
// Cargo.toml: anyhow = "1", solana-account-decoder = "4", solana-client = "~4.4",
// solana-commitment-config = "3", solana-sdk = "5", tokio = { version = "1", features = ["full"] }.
// solana-client 4.4 takes solana-sdk 5.x types. Requires Rust 1.98.1 or newer (solana-client 4.4).
use anyhow::Result;
use solana_account_decoder::UiAccountEncoding;
use solana_client::{nonblocking::rpc_client::RpcClient, rpc_config::RpcAccountInfoConfig};
use solana_commitment_config::CommitmentConfig;
use solana_sdk::pubkey;

#[tokio::main]
async fn main() -> Result<()> {
    let client = RpcClient::new_with_commitment(
        String::from("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>"),
        CommitmentConfig::confirmed(),
    );

    let addresses = [
        pubkey!("vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36NKPTg"),
        pubkey!("4fYNw3dojWmQ4dXtSGE9epjRGy9pFSx62YypT7avPYvA"),
    ];

    let config = RpcAccountInfoConfig {
        encoding: UiAccountEncoding::Base64.into(),
        data_slice: None,
        commitment: CommitmentConfig::finalized().into(),
        min_context_slot: None,
    };

    let accounts = client
        .get_multiple_ui_accounts_with_config(&addresses, config)
        .await?;

    println!("{:#?}", accounts);

    Ok(())
}
```

{% endtab %}
{% endtabs %}

## Parameters

**`pubkeys`** · array · required

An array of Pubkeys to query, as base-58 encoded strings (up to a maximum of 100)

**`config`** · object

Configuration object containing the following fields:

**`commitment`** · string · default `finalized`

Values: `processed`, `confirmed`, `finalized`

Solana RPC uses the following commitment levels:

| Value       | Description                                                                                                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `processed` | Return data from the highest slot this node has processed on the fork it currently considers best. This is the newest view, but it can still change if the cluster switches forks. |
| `confirmed` | Return data from the highest slot the cluster has finalized. On Alpenglow, `confirmed` and `finalized` are the same level.                                                         |
| `finalized` | Return data from the highest slot that the cluster has finalized. On Alpenglow there are no vote towers or lockouts: a slot is finalized by certificates of aggregated votes.      |

**`minContextSlot`** · number

The minimum slot that the request can be evaluated at

**`dataSlice`** · object

Request a slice of the account's data.

| Field    | Type    | Description                                           |
| -------- | ------- | ----------------------------------------------------- |
| `offset` | `usize` | Byte offset from which to start reading account data. |
| `length` | `usize` | Number of bytes to return.                            |

{% hint style="info" %}
Data slicing is only available for `base58`, `base64`, `base64+zstd`, and `binary` encodings.
{% endhint %}

**`encoding`** · string · default `base64`

Values: `base58`, `base64`, `base64+zstd`, `binary`, `jsonParsed`

Encoding format for account data.

| Encoding      | Data format                | Notes                                                                                                                                                                                                                    |
| ------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `base64`      | `[data, "base64"]`         | Recommended                                                                                                                                                                                                              |
| `base58`      | `[data, "base58"]`         | Slow. The account's data field must be 128 bytes or fewer                                                                                                                                                                |
| `base64+zstd` | `[data, "base64+zstd"]`    | [Zstandard](https://facebook.github.io/zstd/) compressed                                                                                                                                                                 |
| `jsonParsed`  | `{program, parsed, space}` | Falls back to `[data, "base64"]` if no parser found                                                                                                                                                                      |
| `binary`      | `string`                   | Deprecated. Legacy encoding retained for backwards compatibility. Same base58 encoding as `base58` with the same 128-byte data field limit, but returns data as a plain string instead of an array. Use `base64` instead |

If you use `jsonParsed`, each returned account uses the stable wrapper `{program, parsed, space}`. The `program` field identifies the parser that produced `parsed`. If no parser is available, the RPC node falls back to `[data, "base64"]`.

| `program` value          | Parsed account type                            |
| ------------------------ | ---------------------------------------------- |
| `address-lookup-table`   | Address lookup table accounts                  |
| `bpf-upgradeable-loader` | Upgradeable loader program and buffer accounts |
| `config`                 | Config accounts                                |
| `nonce`                  | Durable nonce accounts                         |
| `spl-token`              | SPL Token accounts                             |
| `spl-token-2022`         | SPL Token 2022 accounts                        |
| `stake`                  | Stake accounts                                 |
| `sysvar`                 | Sysvar accounts                                |
| `vote`                   | Vote accounts                                  |

The nested `parsed` payload remains program-specific.

For the shared account wrapper returned by this method, see [Account Data](https://solana.com/docs/rpc/json-structures#account-data).

## Response

```json
{
  "jsonrpc": "2.0",
  "result": {
    "context": { "apiVersion": "4.3.2", "slot": 341197247 },
    "value": [
      {
        "data": ["", "base64"],
        "executable": false,
        "lamports": 88849814690250,
        "owner": "11111111111111111111111111111111",
        "rentEpoch": 18446744073709551615,
        "space": 0
      },
      {
        "data": ["", "base64"],
        "executable": false,
        "lamports": 998763433,
        "owner": "2WRuhE4GJFoE23DYzp2ij6ZnuQ8p9mJeU6gDgfsjR4or",
        "rentEpoch": 18446744073709551615,
        "space": 0
      }
    ]
  },
  "id": 1
}
```

## Result

RpcResponse object containing:

**`context`** · object

Slot and API version the node used to answer this request.

| Field        | Type     | Description                                                                     |
| ------------ | -------- | ------------------------------------------------------------------------------- |
| `slot`       | `u64`    | Slot at which the node evaluated this request.                                  |
| `apiVersion` | `string` | RPC API version reported by the node. This field may be omitted by older nodes. |

**`value`** · array

Array containing either:

* `null` if the account at that Pubkey doesn't exist
* An account object with the following fields:

Each non-null element uses the shared [Account Data](https://solana.com/docs/rpc/json-structures#account-data) structure.

| Field        | Type                                     | Description                                                                                                                                                                                                                                                                                              |
| ------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`       | `string \| [string, encoding] \| object` | Account data. If `encoding` is `binary`, this is a plain base-58 string. If `encoding` is `base58`, `base64`, or `base64+zstd`, this is `[data, encoding]`. If `encoding` is `jsonParsed`, this is `{program, parsed, space}`; if no parser is available, the RPC node falls back to `[data, "base64"]`. |
| `executable` | `bool`                                   | Whether the account contains a program and is therefore read-only.                                                                                                                                                                                                                                       |
| `lamports`   | `u64`                                    | Lamports assigned to this account.                                                                                                                                                                                                                                                                       |
| `owner`      | `string`                                 | Program owner pubkey, as a base-58 encoded string.                                                                                                                                                                                                                                                       |
| `rentEpoch`  | `u64`                                    | Legacy field. Solana no longer collects rent, and rent-exempt accounts report `18446744073709551615` (u64::MAX).                                                                                                                                                                                         |
| `space`      | `u64 \| null`                            | Account data size in bytes. Current Solana RPC responses populate this field for encoded account responses.                                                                                                                                                                                              |

When `data` is returned as an object, it contains:

| Field     | Type     | Description                                                                                 |
| --------- | -------- | ------------------------------------------------------------------------------------------- |
| `program` | `string` | Name of the parser that produced the decoded account data.                                  |
| `parsed`  | `object` | Parser-specific JSON payload. Its structure depends on the owning program and account type. |
| `space`   | `u64`    | Account data size in bytes.                                                                 |

***

*Adapted from the* [*Solana `getMultipleAccounts` reference*](https://solana.com/docs/rpc/http/getmultipleaccounts)*, maintained by the Solana Foundation.*

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# getProgramAccounts

Returns accounts owned by a program, optionally filtered by memcmp or dataSize; on shared endpoints SPL Token, Token-2022, and System Program need memcmp.

{% hint style="warning" %}
On Triton shared endpoints, `getProgramAccounts` needs filters only for these programs:

* **SPL Token and Token-2022:** a `memcmp` filter on the owner (offset `32`) or the mint (offset `0`), with the full 32-byte public key. A shorter `bytes` value returns error `-32602`.
* **System Program:** at least one `memcmp` filter.

Calls to these programs with no `memcmp` at the required offset are rejected with HTTP `403` ("Your IP or provider is blocked from this endpoint"). Every other program is served from Cloudbreak's index, with or without filters, except a few excluded programs, which return error `-32010`:

* Serum DEX v3 (`9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin`)
* Candy Machine v1 and v2 (`cndyAnrLdpjq1Ssp1z8xxDsB8dxe7u4HL5Nxi2K5WXZ`, `cndy3Z4yapfJBmL3ShUp5exZKqR3z33thTzeNMm2gRZ`)
* Legacy Metaplex auction programs (`auctxRXPeJoc4817jDhf4HbjnhEcr1cCXenosMhK5R8`, `p1exdMJcjVao65QdewkaZRUnU6VPSXhus9n2GzWfh98`)
* Kin token mint (`kinXdEcpDQeHPEuQnqmUgtYykqKGVFq6CeVX5iAHJq6`)

Light Protocol account compression (`compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq`) is served by standard RPC nodes on shared endpoints, without Cloudbreak's index. Filtering with `memcmp` or `dataSize` keeps large queries fast.
{% endhint %}

{% hint style="info" %}
Cloudbreak also differs from Agave here: `processed` is answered at `confirmed`, results are always sorted by pubkey (`sortResults: false` has no effect), and there's no limit on the number of filters. Like Agave, Cloudbreak checks `minContextSlot` on every call and returns error `-32016` if the index hasn't reached that slot.

Queries have a 45-second limit, or 20 seconds for SPL Token and Token-2022 queries, which Cloudbreak's token index serves. A query that exceeds it returns error `-32603`, or ends the connection early if the response has already started. Responses have a 90-second limit; a response still streaming at the limit ends early, and your JSON parser reports an incomplete document. Treat both as a failed request and retry. Narrow large queries with filters or `dataSlice`.
{% endhint %}

## Request

{% tabs %}
{% tab title="cURL" %}

```bash
curl "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>" -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getProgramAccounts",
  "params": [
    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
    {
      "commitment": "finalized",
      "encoding": "base64",
      "filters": [
        { "dataSize": 165 },
        {
          "memcmp": {
            "offset": 0,
            "bytes": "LSTxxxnJzKDFSLr4dUkPcmCf5VyryEqzPLz5j4bpxFp"
          }
        },
        {
          "memcmp": {
            "offset": 32,
            "bytes": "5wx11hXBHQALycTQNkeQ5w1N9vgup4ardN2yLiDK4JyK"
          }
        }
      ],
      "sortResults": true
    }
  ]
}'
```

{% endtab %}

{% tab title="Kit" %}

```typescript
import { address, createSolanaRpc, type Base58EncodedBytes } from "@solana/kit";

const rpc_url = "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>";
const rpc = createSolanaRpc(rpc_url);

let program = address("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");

let accounts = await rpc
  .getProgramAccounts(
    program,
    {
      commitment: "finalized",
      encoding: "base64",
      filters: [
        {
          dataSize: BigInt(165)
        },
        {
          memcmp: {
            bytes: "LSTxxxnJzKDFSLr4dUkPcmCf5VyryEqzPLz5j4bpxFp" as Base58EncodedBytes,
            encoding: "base58",
            offset: BigInt(0)
          }
        },
        {
          memcmp: {
            bytes: "5wx11hXBHQALycTQNkeQ5w1N9vgup4ardN2yLiDK4JyK" as Base58EncodedBytes,
            encoding: "base58",
            offset: BigInt(32)
          }
        }
      ]
    }
  )
  .send();

console.log(accounts);
```

{% endtab %}

{% tab title="web3.js" %}

```typescript
import {
  Connection,
  PublicKey,
  type GetProgramAccountsConfig
} from "@solana/web3.js";

const connection = new Connection("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>", "confirmed");

let programId = new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");

let config: GetProgramAccountsConfig = {
  commitment: "finalized",
  encoding: "base64",
  filters: [
    {
      dataSize: 165
    },
    {
      memcmp: {
        bytes: "LSTxxxnJzKDFSLr4dUkPcmCf5VyryEqzPLz5j4bpxFp",
        offset: 0
      }
    },
    {
      memcmp: {
        bytes: "5wx11hXBHQALycTQNkeQ5w1N9vgup4ardN2yLiDK4JyK",
        offset: 32
      }
    }
  ]
};

let accounts = await connection.getProgramAccounts(programId, config);

console.log(accounts);
```

{% endtab %}

{% tab title="Rust" %}

```rust
// Cargo.toml: anyhow = "1", solana-account-decoder = "4", solana-client = "~4.4",
// solana-commitment-config = "3", solana-sdk = "5", tokio = { version = "1", features = ["full"] }.
// solana-client 4.4 takes solana-sdk 5.x types. Requires Rust 1.98.1 or newer (solana-client 4.4).
use anyhow::Result;
use solana_account_decoder::UiAccountEncoding;
use solana_client::{
    nonblocking::rpc_client::RpcClient,
    rpc_config::{RpcAccountInfoConfig, RpcProgramAccountsConfig},
    rpc_filter::{Memcmp, MemcmpEncodedBytes, RpcFilterType},
};
use solana_commitment_config::CommitmentConfig;
use solana_sdk::pubkey;

#[tokio::main]
async fn main() -> Result<()> {
    let client = RpcClient::new_with_commitment(
        String::from("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>"),
        CommitmentConfig::confirmed(),
    );

    let program = pubkey!("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");

    let config = RpcProgramAccountsConfig {
        filters: vec![
            RpcFilterType::DataSize(165),
            RpcFilterType::Memcmp(Memcmp::new(
                0,
                MemcmpEncodedBytes::Base58("LSTxxxnJzKDFSLr4dUkPcmCf5VyryEqzPLz5j4bpxFp".to_string()),
            )),
            RpcFilterType::Memcmp(Memcmp::new(
                32,
                MemcmpEncodedBytes::Base58("5wx11hXBHQALycTQNkeQ5w1N9vgup4ardN2yLiDK4JyK".to_string()),
            )),
        ]
        .into(),
        account_config: RpcAccountInfoConfig {
            encoding: UiAccountEncoding::Base64.into(),
            data_slice: None,
            commitment: CommitmentConfig::finalized().into(),
            min_context_slot: None,
        },
        with_context: None,
        sort_results: true.into(),
    };

    let accounts = client
        .get_program_ui_accounts_with_config(&program, config)
        .await?;

    println!("{:#?}", accounts);

    Ok(())
}
```

{% endtab %}
{% endtabs %}

## Parameters

**`pubkey`** · string · required

Pubkey of program, as base-58 encoded string

**`config`** · object

Configuration object containing the following fields:

**`commitment`** · string · default `finalized`

Values: `processed`, `confirmed`, `finalized`

Solana RPC uses the following commitment levels:

| Value       | Description                                                                                                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `processed` | Return data from the highest slot this node has processed on the fork it currently considers best. This is the newest view, but it can still change if the cluster switches forks. |
| `confirmed` | Return data from the highest slot the cluster has finalized. On Alpenglow, `confirmed` and `finalized` are the same level.                                                         |
| `finalized` | Return data from the highest slot that the cluster has finalized. On Alpenglow there are no vote towers or lockouts: a slot is finalized by certificates of aggregated votes.      |

**`minContextSlot`** · number

The minimum slot that the request can be evaluated at

**`withContext`** · bool · default `false`

Values: `true`, `false`

Wrap the result in an RpcResponse JSON object

**`encoding`** · string · default `binary`

Values: `base58`, `base64`, `base64+zstd`, `binary`, `jsonParsed`

Encoding format for account data.

| Encoding      | Data format                | Notes                                                                                                                                                                                                                            |
| ------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `base64`      | `[data, "base64"]`         | Recommended                                                                                                                                                                                                                      |
| `base58`      | `[data, "base58"]`         | Slow. The account's data field must be 128 bytes or fewer                                                                                                                                                                        |
| `base64+zstd` | `[data, "base64+zstd"]`    | [Zstandard](https://facebook.github.io/zstd/) compressed                                                                                                                                                                         |
| `jsonParsed`  | `{program, parsed, space}` | Falls back to `[data, "base64"]` if no parser found                                                                                                                                                                              |
| `binary`      | `string`                   | Deprecated default. Legacy encoding retained for backwards compatibility. Same base58 encoding as `base58` with the same 128-byte data field limit, but returns data as a plain string instead of an array. Use `base64` instead |

{% hint style="warning" %}
Always set `encoding` to `base64` or `jsonParsed`. The default `binary` returns error `-32600` for any account with more than 128 bytes of data, and every token account is 165 bytes or more.
{% endhint %}

If you use `jsonParsed`, each returned account uses the stable wrapper `{program, parsed, space}`. The `program` field identifies the parser that produced `parsed`. If no parser is available, the RPC node falls back to `[data, "base64"]`.

| `program` value          | Parsed account type                            |
| ------------------------ | ---------------------------------------------- |
| `address-lookup-table`   | Address lookup table accounts                  |
| `bpf-upgradeable-loader` | Upgradeable loader program and buffer accounts |
| `config`                 | Config accounts                                |
| `nonce`                  | Durable nonce accounts                         |
| `spl-token`              | SPL Token accounts                             |
| `spl-token-2022`         | SPL Token 2022 accounts                        |
| `stake`                  | Stake accounts                                 |
| `sysvar`                 | Sysvar accounts                                |
| `vote`                   | Vote accounts                                  |

The nested `parsed` payload remains program-specific.

For the shared account wrapper returned in each `account` field, see [Account Data](https://solana.com/docs/rpc/json-structures#account-data).

**`dataSlice`** · object

Request a slice of the account's data.

| Field    | Type    | Description                                           |
| -------- | ------- | ----------------------------------------------------- |
| `offset` | `usize` | Byte offset from which to start reading account data. |
| `length` | `usize` | Number of bytes to return.                            |

{% hint style="info" %}
Data slicing applies to `base58`, `base64`, `base64+zstd`, and `binary` encodings. With `jsonParsed`, the slice applies only to accounts that fall back to `[data, "base64"]`; parsed accounts are returned in full.
{% endhint %}

**`filters`** · array

Filter results using filter objects. Agave allows up to 4. Cloudbreak, which serves this method on Triton, has no limit. The resultant account(s) must meet **all** filter criteria to be included in the returned results.

The following filter types are supported:

| Filter              | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `memcmp`            | `object` | Compares a provided series of bytes with account data at a particular offset. Fields: `offset` (`usize`), byte offset into account data; `bytes` (`string \| array`), data to match, provided as a base-58 string by default, a base-64 string when `encoding` is `"base64"`, or a raw byte array; `encoding` (`string`, optional), encoding for string `bytes`, either `"base58"` (default), `"base64"`, or `"bytes"`. Decoded data is limited to 128 bytes. |
| `dataSize`          | `u64`    | Compares the account data length with the provided size.                                                                                                                                                                                                                                                                                                                                                                                                      |
| `tokenAccountState` | N/A      | Matches accounts with the token-account layout: data of exactly 165 bytes, or longer with account type `2` at byte 165. On Triton the match is on layout only, so an uninitialized account with that layout also matches. No value is needed.                                                                                                                                                                                                                 |

**`sortResults`** · bool · default `true`

Values: `true`, `false`

Whether to sort returned accounts before returning them. If disabled, do not assume any particular response order. On Triton, results are always sorted by pubkey.

## Response

```json
{
  "jsonrpc": "2.0",
  "result": [
    {
      "pubkey": "CxELquR1gPP8wHe33gZ4QxqGB3sZ9RSwsJ2KshVewkFY",
      "account": {
        "data": [
          "KgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
          "base64"
        ],
        "executable": false,
        "lamports": 15298080,
        "owner": "4Nd1mBQtrMJVYVfKf2PJy9NZUZdTAsp7D4xWLs4gDB4T",
        "rentEpoch": 28,
        "space": 42
      }
    }
  ],
  "id": 1
}
```

## Result

By default, returns an array of JSON objects. If `withContext` flag is set, the array will be wrapped in an RpcResponse JSON object.

Each object contains:

**`pubkey`** · string

The account Pubkey as base-58 encoded string

**`account`** · object

Account data object.

This field uses the shared [Account Data](https://solana.com/docs/rpc/json-structures#account-data) structure.

| Field        | Type                                     | Description                                                                                                                                                                                                         |
| ------------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`       | `string \| [string, encoding] \| object` | Account data. Binary forms depend on the `encoding` parameter. When `encoding` is `jsonParsed`, this field is `{program, parsed, space}`; if no parser is available, the RPC node falls back to `[data, "base64"]`. |
| `executable` | `bool`                                   | Whether the account contains a program and is therefore read-only.                                                                                                                                                  |
| `lamports`   | `u64`                                    | Lamports assigned to the account.                                                                                                                                                                                   |
| `owner`      | `string`                                 | Program owner pubkey, as a base-58 encoded string.                                                                                                                                                                  |
| `rentEpoch`  | `u64`                                    | Legacy field. Solana no longer collects rent, and rent-exempt accounts report `18446744073709551615` (u64::MAX).                                                                                                    |
| `space`      | `u64 \| null`                            | Account data size in bytes. Current Solana RPC responses populate this field for encoded account responses.                                                                                                         |

When `account.data` is returned as an object, it contains:

| Field     | Type     | Description                                                                                 |
| --------- | -------- | ------------------------------------------------------------------------------------------- |
| `program` | `string` | Name of the parser that produced the decoded account data.                                  |
| `parsed`  | `object` | Parser-specific JSON payload. Its structure depends on the owning program and account type. |
| `space`   | `u64`    | Account data size in bytes.                                                                 |

***

*Adapted from the* [*Solana `getProgramAccounts` reference*](https://solana.com/docs/rpc/http/getprogramaccounts)*, maintained by the Solana Foundation.*

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# getTokenAccountBalance

Returns the token balance for an SPL Token account.

## Request

{% tabs %}
{% tab title="cURL" %}

```bash
curl "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>" -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getTokenAccountBalance",
  "params": [
    "7dQmths1cyCQ4xaC5KcVfXz4BvVWtnHc3hcgnfnE1PBx",
    {
      "commitment": "finalized"
    }
  ]
}'
```

{% endtab %}

{% tab title="Kit" %}

```typescript
import { address, createSolanaRpc } from "@solana/kit";

const rpc_url = "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>";
const rpc = createSolanaRpc(rpc_url);

let tokenAddress = address("7dQmths1cyCQ4xaC5KcVfXz4BvVWtnHc3hcgnfnE1PBx");

let tokenBalance = await rpc.getTokenAccountBalance(tokenAddress).send();

console.log(tokenBalance);
```

{% endtab %}

{% tab title="web3.js" %}

```typescript
import { Connection, PublicKey } from "@solana/web3.js";

const connection = new Connection("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>", "confirmed");

let tokenAddress = new PublicKey(
  "7dQmths1cyCQ4xaC5KcVfXz4BvVWtnHc3hcgnfnE1PBx"
);

let tokenBalance = await connection.getTokenAccountBalance(tokenAddress);

console.log(tokenBalance);
```

{% endtab %}

{% tab title="Rust" %}

```rust
// Cargo.toml: anyhow = "1", solana-client = "~4.4", solana-commitment-config = "3",
// solana-sdk = "5", tokio = { version = "1", features = ["full"] }. solana-client 4.4 takes
// solana-sdk 5.x types. Requires Rust 1.98.1 or newer (solana-client 4.4).
use anyhow::Result;
use solana_client::nonblocking::rpc_client::RpcClient;
use solana_commitment_config::CommitmentConfig;
use solana_sdk::pubkey;

#[tokio::main]
async fn main() -> Result<()> {
    let client = RpcClient::new_with_commitment(
        String::from("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>"),
        CommitmentConfig::confirmed(),
    );

    let token_address = pubkey!("7dQmths1cyCQ4xaC5KcVfXz4BvVWtnHc3hcgnfnE1PBx");
    let token_acc_bal = client.get_token_account_balance(&token_address).await?;

    println!("{:#?}", token_acc_bal);

    Ok(())
}
```

{% endtab %}
{% endtabs %}

## Parameters

**`pubkey`** · string · required

Pubkey of Token account to query, as base-58 encoded string

**`config`** · object

Configuration object containing the following fields:

**`commitment`** · string · default `finalized`

Values: `processed`, `confirmed`, `finalized`

Solana RPC uses the following commitment levels:

| Value       | Description                                                                                                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `processed` | Return data from the highest slot this node has processed on the fork it currently considers best. This is the newest view, but it can still change if the cluster switches forks. |
| `confirmed` | Return data from the highest slot the cluster has finalized. On Alpenglow, `confirmed` and `finalized` are the same level.                                                         |
| `finalized` | Return data from the highest slot that the cluster has finalized. On Alpenglow there are no vote towers or lockouts: a slot is finalized by certificates of aggregated votes.      |

## Response

```json
{
  "jsonrpc": "2.0",
  "result": {
    "context": { "apiVersion": "4.3.2", "slot": 464671878 },
    "value": {
      "amount": "1981312319692",
      "decimals": 6,
      "uiAmount": 1981312.319692,
      "uiAmountString": "1981312.319692"
    }
  },
  "id": 1
}
```

## Result

RpcResponse object containing:

**`context`** · object

Slot and API version the node used to answer this request.

| Field        | Type     | Description                                                                     |
| ------------ | -------- | ------------------------------------------------------------------------------- |
| `slot`       | `u64`    | Slot at which the node evaluated this request.                                  |
| `apiVersion` | `string` | RPC API version reported by the node. This field may be omitted by older nodes. |

**`value`** · object

Token amount object with the following fields:

This uses the same amount fields documented for `uiTokenAmount` in [Token Balances](https://solana.com/docs/rpc/json-structures#token-balances).

| Field            | Type             | Description                                                                                       |
| ---------------- | ---------------- | ------------------------------------------------------------------------------------------------- |
| `amount`         | `string`         | Raw token balance, as a base-10 integer string with no decimal point.                             |
| `decimals`       | `u8`             | Number of decimal places configured on the mint.                                                  |
| `uiAmount`       | `number \| null` | Decimal-scaled token balance as a floating-point number. Deprecated in favor of `uiAmountString`. |
| `uiAmountString` | `string`         | Decimal-scaled token balance as a string.                                                         |

***

*Adapted from the* [*Solana `getTokenAccountBalance` reference*](https://solana.com/docs/rpc/http/gettokenaccountbalance)*, maintained by the Solana Foundation.*

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# getTokenAccountsByDelegate

Returns SPL Token accounts whose approved delegate matches the supplied address.

{% hint style="info" %}
On Triton shared endpoints, this method is served from Cloudbreak's token index. `processed` is answered at `confirmed`. Queries have a 20-second limit; a query that exceeds it returns error `-32603`. Add a `mint` filter for delegates with many token accounts.
{% endhint %}

## Request

{% tabs %}
{% tab title="cURL" %}

```bash
curl "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>" -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getTokenAccountsByDelegate",
  "params": [
    "4kg8oh3jdNtn7j2wcS7TrUua31AgbLzDVkBZgTAe44aF",
    {
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
    },
    {
      "commitment": "finalized",
      "encoding": "jsonParsed"
    }
  ]
}'
```

{% endtab %}

{% tab title="Kit" %}

```typescript
import { address, createSolanaRpc } from "@solana/kit";

const rpc_url = "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>";
const rpc = createSolanaRpc(rpc_url);

let delegate = address("4kg8oh3jdNtn7j2wcS7TrUua31AgbLzDVkBZgTAe44aF");

let tokenProgram = address("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");

let tokenAccByDelegate = await rpc
  .getTokenAccountsByDelegate(
    delegate,
    { programId: tokenProgram },
    {
      commitment: "finalized",
      encoding: "jsonParsed"
    }
  )
  .send();

console.log(tokenAccByDelegate);
```

{% endtab %}

{% tab title="Rust" %}

```rust
// Cargo.toml: anyhow = "1", solana-client = "~4.4", solana-commitment-config = "3",
// solana-sdk = "5", tokio = { version = "1", features = ["full"] }. solana-client 4.4 takes
// solana-sdk 5.x types. Requires Rust 1.98.1 or newer (solana-client 4.4).
use anyhow::Result;
use solana_client::{nonblocking::rpc_client::RpcClient, rpc_request::TokenAccountsFilter};
use solana_commitment_config::CommitmentConfig;
use solana_sdk::pubkey;

#[tokio::main]
async fn main() -> Result<()> {
    let client = RpcClient::new_with_commitment(
        String::from("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>"),
        CommitmentConfig::confirmed(),
    );

    let delegate = pubkey!("4kg8oh3jdNtn7j2wcS7TrUua31AgbLzDVkBZgTAe44aF");

    let token_program = pubkey!("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");

    let token_acc_by_del = client
        .get_token_accounts_by_delegate_with_commitment(
            &delegate,
            TokenAccountsFilter::ProgramId(token_program),
            CommitmentConfig::finalized(),
        )
        .await?;

    println!("{:#?}", token_acc_by_del);

    Ok(())
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Example values are illustrative. Replace the delegate and the mint or program ID with your own.
{% endhint %}

## Parameters

**`pubkey`** · string · required

Pubkey of account delegate to query, as base-58 encoded string

**`token account filter`** · object · required

A JSON object with one of the following fields:

**`mint`** · string

Pubkey of the specific token Mint to limit accounts to, as base-58 encoded string

**`programId`** · string

Pubkey of the Token program that owns the accounts, as base-58 encoded string

**`config`** · object

Configuration object containing the following fields:

**`commitment`** · string · default `finalized`

Values: `processed`, `confirmed`, `finalized`

Solana RPC uses the following commitment levels:

| Value       | Description                                                                                                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `processed` | Return data from the highest slot this node has processed on the fork it currently considers best. This is the newest view, but it can still change if the cluster switches forks. |
| `confirmed` | Return data from the highest slot the cluster has finalized. On Alpenglow, `confirmed` and `finalized` are the same level.                                                         |
| `finalized` | Return data from the highest slot that the cluster has finalized. On Alpenglow there are no vote towers or lockouts: a slot is finalized by certificates of aggregated votes.      |

**`minContextSlot`** · number

The minimum slot that the request can be evaluated at

**`dataSlice`** · object

Request a slice of the account's data.

| Field    | Type    | Description                                           |
| -------- | ------- | ----------------------------------------------------- |
| `offset` | `usize` | Byte offset from which to start reading account data. |
| `length` | `usize` | Number of bytes to return.                            |

{% hint style="info" %}
Data slicing is only available for `base58`, `base64`, `base64+zstd`, and `binary` encodings.
{% endhint %}

{% hint style="info" %}
Use `encoding: "jsonParsed"` if you want the parsed token account structure shown in the response example below.
{% endhint %}

**`encoding`** · string · default `binary`

Values: `base58`, `base64`, `base64+zstd`, `binary`, `jsonParsed`

Encoding format for account data.

| Encoding      | Data format                | Notes                                                                                                                                                                                                                    |
| ------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `base64`      | `[data, "base64"]`         | Recommended                                                                                                                                                                                                              |
| `base58`      | `[data, "base58"]`         | Slow. The account's data field must be 128 bytes or fewer                                                                                                                                                                |
| `base64+zstd` | `[data, "base64+zstd"]`    | [Zstandard](https://facebook.github.io/zstd/) compressed                                                                                                                                                                 |
| `jsonParsed`  | `{program, parsed, space}` | Accounts that can't be parsed are left out of the result                                                                                                                                                                 |
| `binary`      | `string`                   | Deprecated. Legacy encoding retained for backwards compatibility. Same base58 encoding as `base58` with the same 128-byte data field limit, but returns data as a plain string instead of an array. Use `base64` instead |

{% hint style="warning" %}
Always set `encoding` to `base64` or `jsonParsed`. Token accounts are 165 bytes or more, so the default `binary` returns error `-32600`.
{% endhint %}

If you use `jsonParsed`, this method returns the token-account wrapper `{program, parsed, space}`. The `program` field identifies the token parser that produced `parsed`.

| `program` value  | Parsed account type     |
| ---------------- | ----------------------- |
| `spl-token`      | SPL Token accounts      |
| `spl-token-2022` | SPL Token 2022 accounts |

The nested `parsed` payload on this page uses the SPL Token account form documented below.

The nested `account` field uses the shared [Account Data](https://solana.com/docs/rpc/json-structures#account-data) wrapper, and `tokenAmount` uses the same amount fields documented in [Token Balances](https://solana.com/docs/rpc/json-structures#token-balances).

## Response

```json
{
  "jsonrpc": "2.0",
  "result": {
    "context": { "apiVersion": "4.3.2", "slot": 1114 },
    "value": [
      {
        "pubkey": "28YTZEwqtMHWrhWcvv34se7pjS7wctgqzCPB3gReCFKp",
        "account": {
          "data": {
            "program": "spl-token",
            "parsed": {
              "info": {
                "tokenAmount": {
                  "amount": "1",
                  "decimals": 1,
                  "uiAmount": 0.1,
                  "uiAmountString": "0.1"
                },
                "delegate": "4Nd1mBQtrMJVYVfKf2PJy9NZUZdTAsp7D4xWLs4gDB4T",
                "delegatedAmount": {
                  "amount": "1",
                  "decimals": 1,
                  "uiAmount": 0.1,
                  "uiAmountString": "0.1"
                },
                "state": "initialized",
                "isNative": false,
                "mint": "3wyAj7Rt1TWVPZVteFJPLa26JmLvdb1CAKEFZm3NY75E",
                "owner": "CnPoSPKXu7wJqxe59Fs72tkBeALovhsCxYeFwPCQH9TD"
              },
              "type": "account"
            },
            "space": 165
          },
          "executable": false,
          "lamports": 1726080,
          "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
          "rentEpoch": 4,
          "space": 165
        }
      }
    ]
  },
  "id": 1
}
```

## Result

RpcResponse object containing:

**`context`** · object

Slot and API version the node used to answer this request.

| Field        | Type     | Description                                                                     |
| ------------ | -------- | ------------------------------------------------------------------------------- |
| `slot`       | `u64`    | Slot at which the node evaluated this request.                                  |
| `apiVersion` | `string` | RPC API version reported by the node. This field may be omitted by older nodes. |

**`value`** · array

Array of keyed-account objects with the following fields:

| Field     | Type     | Description                                                                                                              |
| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `pubkey`  | `string` | Account pubkey, as a base-58 encoded string.                                                                             |
| `account` | `object` | Account data object. Uses the shared [Account Data](https://solana.com/docs/rpc/json-structures#account-data) structure. |

| Field        | Type                                     | Description                                                                                                                                                                                                   |
| ------------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`       | `string \| [string, encoding] \| object` | Token account data. Binary forms depend on the `encoding` parameter. When `encoding` is `jsonParsed`, this field is `{program, parsed, space}`, and accounts that can't be parsed are left out of the result. |
| `executable` | `bool`                                   | Whether the account contains a program and is therefore read-only.                                                                                                                                            |
| `lamports`   | `u64`                                    | Lamports assigned to the account.                                                                                                                                                                             |
| `owner`      | `string`                                 | Program owner pubkey, as a base-58 encoded string.                                                                                                                                                            |
| `rentEpoch`  | `u64`                                    | Legacy field. Solana no longer collects rent, and rent-exempt accounts report `18446744073709551615` (u64::MAX).                                                                                              |
| `space`      | `u64 \| null`                            | Account data size in bytes. Current Solana RPC responses populate this field for encoded account responses.                                                                                                   |

When `account.data` is returned as an object, it contains:

| Field     | Type     | Description                                                                                                 |
| --------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `program` | `string` | Name of the parser that produced the decoded token-account data.                                            |
| `parsed`  | `object` | Parsed SPL Token account payload. For this method, this field uses the token-account form documented below. |
| `space`   | `u64`    | Account data size in bytes.                                                                                 |

**`parsed` fields**

| Field  | Type     | Description                       |
| ------ | -------- | --------------------------------- |
| `type` | `string` | Always `account` for this method. |
| `info` | `object` | Parsed SPL Token account fields.  |

**`parsed.info` fields**

| Field               | Type             | Description                                                                                                                       |
| ------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `mint`              | `string`         | Token mint pubkey, as a base-58 encoded string.                                                                                   |
| `owner`             | `string`         | Token-account owner pubkey, as a base-58 encoded string.                                                                          |
| `tokenAmount`       | `object`         | Token amount object with raw and decimal-scaled representations.                                                                  |
| `delegate`          | `string \| null` | Delegate pubkey, when a delegate is set.                                                                                          |
| `state`             | `string`         | Token-account state. The value is `uninitialized`, `initialized`, or `frozen`.                                                    |
| `isNative`          | `bool`           | Whether this account wraps the native SOL mint.                                                                                   |
| `rentExemptReserve` | `object \| null` | Rent-exempt reserve amount for wrapped SOL accounts, when present. Uses the same token-amount schema as `tokenAmount`.            |
| `delegatedAmount`   | `object \| null` | Amount delegated to `delegate`, when present. Uses the same token-amount schema as `tokenAmount`.                                 |
| `closeAuthority`    | `string \| null` | Close-authority pubkey, when present.                                                                                             |
| `extensions`        | `array`          | Parsed SPL Token 2022 extension entries. Each element has an `extension` discriminator and an extension-specific `state` payload. |

**`tokenAmount` fields**

This nested amount object uses the same numeric fields documented in [Token Balances](https://solana.com/docs/rpc/json-structures#token-balances).

| Field            | Type             | Description                                                                                |
| ---------------- | ---------------- | ------------------------------------------------------------------------------------------ |
| `uiAmount`       | `number \| null` | Decimal-scaled amount as a floating-point number. Deprecated in favor of `uiAmountString`. |
| `decimals`       | `u8`             | Number of decimal places configured on the mint.                                           |
| `amount`         | `string`         | Raw token amount, as a base-10 integer string.                                             |
| `uiAmountString` | `string`         | Decimal-scaled amount as a string.                                                         |

***

*Adapted from the* [*Solana `getTokenAccountsByDelegate` reference*](https://solana.com/docs/rpc/http/gettokenaccountsbydelegate)*, maintained by the Solana Foundation.*

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# getTokenAccountsByOwner

Returns the SPL Token accounts of an owner address, filtered by token mint or token program ID.

{% hint style="info" %}
On Triton shared endpoints, this method is served from Cloudbreak's token index. `processed` is answered at `confirmed`. Queries have a 20-second limit; a query that exceeds it returns error `-32603`. Add a `mint` filter for owners with many token accounts.
{% endhint %}

## Request

{% tabs %}
{% tab title="cURL" %}

```bash
curl "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>" -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getTokenAccountsByOwner",
  "params": [
    "5wx11hXBHQALycTQNkeQ5w1N9vgup4ardN2yLiDK4JyK",
    {
      "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
    },
    {
      "commitment": "finalized",
      "encoding": "jsonParsed"
    }
  ]
}'
```

{% endtab %}

{% tab title="Kit" %}

```typescript
import { address, createSolanaRpc } from "@solana/kit";

const rpc_url = "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>";
const rpc = createSolanaRpc(rpc_url);

let owner = address("5wx11hXBHQALycTQNkeQ5w1N9vgup4ardN2yLiDK4JyK");

let tokenProgram = address("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");

let tokenAccounts = await rpc
  .getTokenAccountsByOwner(
    owner,
    { programId: tokenProgram },
    {
      commitment: "finalized",
      encoding: "jsonParsed"
    }
  )
  .send();

console.log(tokenAccounts);
```

{% endtab %}

{% tab title="web3.js" %}

```typescript
import { Connection, PublicKey } from "@solana/web3.js";

const connection = new Connection("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>", "confirmed");

let owner = new PublicKey("5wx11hXBHQALycTQNkeQ5w1N9vgup4ardN2yLiDK4JyK");

let tokenProgram = new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");

let tokenAccounts = await connection.getParsedTokenAccountsByOwner(
  owner,
  { programId: tokenProgram },
  "finalized"
);

console.log(tokenAccounts);
```

{% endtab %}

{% tab title="Rust" %}

```rust
// Cargo.toml: anyhow = "1", solana-client = "~4.4", solana-commitment-config = "3",
// solana-sdk = "5", tokio = { version = "1", features = ["full"] }. solana-client 4.4 takes
// solana-sdk 5.x types. Requires Rust 1.98.1 or newer (solana-client 4.4).
use anyhow::Result;
use solana_client::{nonblocking::rpc_client::RpcClient, rpc_request::TokenAccountsFilter};
use solana_commitment_config::CommitmentConfig;
use solana_sdk::pubkey;

#[tokio::main]
async fn main() -> Result<()> {
    let client = RpcClient::new_with_commitment(
        String::from("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>"),
        CommitmentConfig::confirmed(),
    );

    let owner = pubkey!("5wx11hXBHQALycTQNkeQ5w1N9vgup4ardN2yLiDK4JyK");

    let token_program = pubkey!("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");

    let token_accounts = client
        .get_token_accounts_by_owner(&owner, TokenAccountsFilter::ProgramId(token_program))
        .await?;

    println!("{:#?}", token_accounts);

    Ok(())
}
```

{% endtab %}
{% endtabs %}

## Parameters

**`pubkey`** · string · required

Pubkey of account owner to query, as base-58 encoded string

**`token account filter`** · object · required

A JSON object with one of the following fields:

**`mint`** · string

Pubkey of the specific token Mint to limit accounts to, as base-58 encoded string

**`programId`** · string

Pubkey of the Token program that owns the accounts, as base-58 encoded string

**`config`** · object

Configuration object containing the following fields:

**`commitment`** · string · default `finalized`

Values: `processed`, `confirmed`, `finalized`

Solana RPC uses the following commitment levels:

| Value       | Description                                                                                                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `processed` | Return data from the highest slot this node has processed on the fork it currently considers best. This is the newest view, but it can still change if the cluster switches forks. |
| `confirmed` | Return data from the highest slot the cluster has finalized. On Alpenglow, `confirmed` and `finalized` are the same level.                                                         |
| `finalized` | Return data from the highest slot that the cluster has finalized. On Alpenglow there are no vote towers or lockouts: a slot is finalized by certificates of aggregated votes.      |

**`minContextSlot`** · number

The minimum slot that the request can be evaluated at

**`dataSlice`** · object

Request a slice of the account's data.

| Field    | Type    | Description                                           |
| -------- | ------- | ----------------------------------------------------- |
| `offset` | `usize` | Byte offset from which to start reading account data. |
| `length` | `usize` | Number of bytes to return.                            |

{% hint style="info" %}
Data slicing is only available for `base58`, `base64`, `base64+zstd`, and `binary` encodings.
{% endhint %}

{% hint style="info" %}
Use `encoding: "jsonParsed"` if you want the parsed token account structure shown in the response example below.
{% endhint %}

**`encoding`** · string · default `binary`

Values: `base58`, `base64`, `base64+zstd`, `binary`, `jsonParsed`

Encoding format for account data.

| Encoding      | Data format                | Notes                                                                                                                                                                                                                    |
| ------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `base64`      | `[data, "base64"]`         | Recommended                                                                                                                                                                                                              |
| `base58`      | `[data, "base58"]`         | Slow. The account's data field must be 128 bytes or fewer                                                                                                                                                                |
| `base64+zstd` | `[data, "base64+zstd"]`    | [Zstandard](https://facebook.github.io/zstd/) compressed                                                                                                                                                                 |
| `jsonParsed`  | `{program, parsed, space}` | Accounts that can't be parsed are left out of the result                                                                                                                                                                 |
| `binary`      | `string`                   | Deprecated. Legacy encoding retained for backwards compatibility. Same base58 encoding as `base58` with the same 128-byte data field limit, but returns data as a plain string instead of an array. Use `base64` instead |

{% hint style="warning" %}
Always set `encoding` to `base64` or `jsonParsed`. Token accounts are 165 bytes or more, so the default `binary` returns error `-32600`.
{% endhint %}

If you use `jsonParsed`, this method returns the token-account wrapper `{program, parsed, space}`. The `program` field identifies the token parser that produced `parsed`.

| `program` value  | Parsed account type     |
| ---------------- | ----------------------- |
| `spl-token`      | SPL Token accounts      |
| `spl-token-2022` | SPL Token 2022 accounts |

The nested `parsed` payload on this page uses the SPL Token account form documented below.

The nested `account` field uses the shared [Account Data](https://solana.com/docs/rpc/json-structures#account-data) wrapper, and `tokenAmount` uses the same amount fields documented in [Token Balances](https://solana.com/docs/rpc/json-structures#token-balances).

## Response

```json
{
  "jsonrpc": "2.0",
  "result": {
    "context": { "apiVersion": "4.3.2", "slot": 464671878 },
    "value": [
      {
        "pubkey": "2iFDNrkzUELS4PtWvEKrF3nR54g6LF7T3GU6YEC4VWeN",
        "account": {
          "data": {
            "program": "spl-token",
            "parsed": {
              "info": {
                "isNative": false,
                "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
                "owner": "5wx11hXBHQALycTQNkeQ5w1N9vgup4ardN2yLiDK4JyK",
                "state": "initialized",
                "tokenAmount": {
                  "amount": "0",
                  "decimals": 6,
                  "uiAmount": 0.0,
                  "uiAmountString": "0"
                }
              },
              "type": "account"
            },
            "space": 165
          },
          "executable": false,
          "lamports": 2039280,
          "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
          "rentEpoch": 18446744073709551615,
          "space": 165
        }
      }
    ]
  },
  "id": 1
}
```

## Result

RpcResponse object containing:

**`context`** · object

Slot and API version the node used to answer this request.

| Field        | Type     | Description                                                                     |
| ------------ | -------- | ------------------------------------------------------------------------------- |
| `slot`       | `u64`    | Slot at which the node evaluated this request.                                  |
| `apiVersion` | `string` | RPC API version reported by the node. This field may be omitted by older nodes. |

**`value`** · array

Array of keyed-account objects with the following fields:

| Field     | Type     | Description                                                                                                              |
| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `pubkey`  | `string` | Account pubkey, as a base-58 encoded string.                                                                             |
| `account` | `object` | Account data object. Uses the shared [Account Data](https://solana.com/docs/rpc/json-structures#account-data) structure. |

| Field        | Type                                     | Description                                                                                                                                                                                                   |
| ------------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`       | `string \| [string, encoding] \| object` | Token account data. Binary forms depend on the `encoding` parameter. When `encoding` is `jsonParsed`, this field is `{program, parsed, space}`, and accounts that can't be parsed are left out of the result. |
| `executable` | `bool`                                   | Whether the account contains a program and is therefore read-only.                                                                                                                                            |
| `lamports`   | `u64`                                    | Lamports assigned to the account.                                                                                                                                                                             |
| `owner`      | `string`                                 | Program owner pubkey, as a base-58 encoded string.                                                                                                                                                            |
| `rentEpoch`  | `u64`                                    | Legacy field. Solana no longer collects rent, and rent-exempt accounts report `18446744073709551615` (u64::MAX).                                                                                              |
| `space`      | `u64 \| null`                            | Account data size in bytes. Current Solana RPC responses populate this field for encoded account responses.                                                                                                   |

When `account.data` is returned as an object, it contains:

| Field     | Type     | Description                                                                                                 |
| --------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `program` | `string` | Name of the parser that produced the decoded token-account data.                                            |
| `parsed`  | `object` | Parsed SPL Token account payload. For this method, this field uses the token-account form documented below. |
| `space`   | `u64`    | Account data size in bytes.                                                                                 |

**`parsed` fields**

| Field  | Type     | Description                       |
| ------ | -------- | --------------------------------- |
| `type` | `string` | Always `account` for this method. |
| `info` | `object` | Parsed SPL Token account fields.  |

**`parsed.info` fields**

| Field               | Type             | Description                                                                                                                       |
| ------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `mint`              | `string`         | Token mint pubkey, as a base-58 encoded string.                                                                                   |
| `owner`             | `string`         | Token-account owner pubkey, as a base-58 encoded string.                                                                          |
| `tokenAmount`       | `object`         | Token amount object with raw and decimal-scaled representations.                                                                  |
| `delegate`          | `string \| null` | Delegate pubkey, when a delegate is set.                                                                                          |
| `state`             | `string`         | Token-account state. The value is `uninitialized`, `initialized`, or `frozen`.                                                    |
| `isNative`          | `bool`           | Whether this account wraps the native SOL mint.                                                                                   |
| `rentExemptReserve` | `object \| null` | Rent-exempt reserve amount for wrapped SOL accounts, when present. Uses the same token-amount schema as `tokenAmount`.            |
| `delegatedAmount`   | `object \| null` | Amount delegated to `delegate`, when present. Uses the same token-amount schema as `tokenAmount`.                                 |
| `closeAuthority`    | `string \| null` | Close-authority pubkey, when present.                                                                                             |
| `extensions`        | `array`          | Parsed SPL Token 2022 extension entries. Each element has an `extension` discriminator and an extension-specific `state` payload. |

**`tokenAmount` fields**

This nested amount object uses the same numeric fields documented in [Token Balances](https://solana.com/docs/rpc/json-structures#token-balances).

| Field            | Type             | Description                                                                                |
| ---------------- | ---------------- | ------------------------------------------------------------------------------------------ |
| `uiAmount`       | `number \| null` | Decimal-scaled amount as a floating-point number. Deprecated in favor of `uiAmountString`. |
| `decimals`       | `u8`             | Number of decimal places configured on the mint.                                           |
| `amount`         | `string`         | Raw token amount, as a base-10 integer string.                                             |
| `uiAmountString` | `string`         | Decimal-scaled amount as a string.                                                         |

***

*Adapted from the* [*Solana `getTokenAccountsByOwner` reference*](https://solana.com/docs/rpc/http/gettokenaccountsbyowner)*, maintained by the Solana Foundation.*

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# getTokenLargestAccounts

Returns the 20 largest token accounts for an SPL Token mint, with address, amount, decimals and uiAmountString for each.

{% hint style="info" %}
On most Triton endpoints, this method is served by the DAS index. It accepts only `confirmed` or `finalized` commitment, and both return the index's latest state. If you pass a config, it must set `commitment`. The response `context` carries `slot` only. An unknown mint returns an empty list. `uiAmount` and `uiAmountString` come from a floating-point value and don't apply Token-2022 UI-amount extensions, so use `amount` for exact values.
{% endhint %}

## Request

{% tabs %}
{% tab title="cURL" %}

```bash
curl "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>" -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getTokenLargestAccounts",
  "params": [
    "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    {
      "commitment": "finalized"
    }
  ]
}'
```

{% endtab %}

{% tab title="Kit" %}

```typescript
import { address, createSolanaRpc } from "@solana/kit";

const rpc_url = "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>";
const rpc = createSolanaRpc(rpc_url);

let mint = address("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");

let largestHolders = await rpc.getTokenLargestAccounts(mint).send();

console.log(largestHolders);
```

{% endtab %}

{% tab title="web3.js" %}

```typescript
import { Connection, PublicKey } from "@solana/web3.js";

const connection = new Connection("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>", "confirmed");

let mint = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");

let largestHolders = await connection.getTokenLargestAccounts(mint);

console.log(largestHolders);
```

{% endtab %}

{% tab title="Rust" %}

```rust
// Cargo.toml: anyhow = "1", solana-client = "~4.4", solana-commitment-config = "3",
// solana-sdk = "5", tokio = { version = "1", features = ["full"] }. solana-client 4.4 takes
// solana-sdk 5.x types. Requires Rust 1.98.1 or newer (solana-client 4.4).
use anyhow::Result;
use solana_client::nonblocking::rpc_client::RpcClient;
use solana_commitment_config::CommitmentConfig;
use solana_sdk::pubkey;

#[tokio::main]
async fn main() -> Result<()> {
    let client = RpcClient::new_with_commitment(
        String::from("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>"),
        CommitmentConfig::confirmed(),
    );

    let mint = pubkey!("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");

    let largest_holders = client.get_token_largest_accounts(&mint).await?;

    println!("{:#?}", largest_holders);

    Ok(())
}
```

{% endtab %}
{% endtabs %}

## Parameters

**`pubkey`** · string · required

Pubkey of the token Mint to query, as base-58 encoded string

**`config`** · object

Configuration object containing the following fields:

**`commitment`** · string · default `finalized`

Values: `processed`, `confirmed`, `finalized`. Triton accepts only `confirmed` or `finalized` for this method.

Solana RPC uses the following commitment levels:

| Value       | Description                                                                                                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `processed` | Return data from the highest slot this node has processed on the fork it currently considers best. This is the newest view, but it can still change if the cluster switches forks. |
| `confirmed` | Return data from the highest slot the cluster has finalized. On Alpenglow, `confirmed` and `finalized` are the same level.                                                         |
| `finalized` | Return data from the highest slot that the cluster has finalized. On Alpenglow there are no vote towers or lockouts: a slot is finalized by certificates of aggregated votes.      |

## Response

```json
{
  "jsonrpc": "2.0",
  "result": {
    "context": { "slot": 464671878 },
    "value": [
      {
        "address": "HLmqeL62xR1QoZ1HKKbXRrdN1p3phKpxRMb2VVopvBBz",
        "amount": "9036593316313",
        "decimals": 6,
        "uiAmount": 9036593.316313,
        "uiAmountString": "9036593.316313"
      },
      {
        "address": "7dQmths1cyCQ4xaC5KcVfXz4BvVWtnHc3hcgnfnE1PBx",
        "amount": "1981312319692",
        "decimals": 6,
        "uiAmount": 1981312.319692,
        "uiAmountString": "1981312.319692"
      }
    ]
  },
  "id": 1
}
```

## Result

RpcResponse object containing:

**`context`** · object

Slot the node used to answer this request. On Triton, the context carries `slot` only.

| Field  | Type  | Description                                    |
| ------ | ----- | ---------------------------------------------- |
| `slot` | `u64` | Slot at which the node evaluated this request. |

**`value`** · array

Array of up to 20 token-balance objects with the following fields:

Each element combines a token-account address with the same amount fields documented for `uiTokenAmount` in [Token Balances](https://solana.com/docs/rpc/json-structures#token-balances).

| Field            | Type             | Description                                                                                       |
| ---------------- | ---------------- | ------------------------------------------------------------------------------------------------- |
| `address`        | `string`         | Token-account address, as a base-58 encoded string.                                               |
| `amount`         | `string`         | Raw token balance, as a base-10 integer string with no decimal point.                             |
| `decimals`       | `u8`             | Number of decimal places configured on the mint.                                                  |
| `uiAmount`       | `number \| null` | Decimal-scaled token balance as a floating-point number. Deprecated in favor of `uiAmountString`. |
| `uiAmountString` | `string`         | Decimal-scaled token balance as a string.                                                         |

***

*Adapted from the* [*Solana `getTokenLargestAccounts` reference*](https://solana.com/docs/rpc/http/gettokenlargestaccounts)*, maintained by the Solana Foundation.*

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# getTokenSupply

Returns the total supply of an SPL Token mint as raw amount, decimals and uiAmountString.

## Request

{% tabs %}
{% tab title="cURL" %}

```bash
curl "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>" -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getTokenSupply",
  "params": [
    "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    {
      "commitment": "finalized"
    }
  ]
}'
```

{% endtab %}

{% tab title="Kit" %}

```typescript
import { address, createSolanaRpc } from "@solana/kit";

const rpc_url = "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>";
const rpc = createSolanaRpc(rpc_url);

let mint = address("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");

let tokenSupply = await rpc.getTokenSupply(mint).send();

console.log(tokenSupply);
```

{% endtab %}

{% tab title="web3.js" %}

```typescript
import { Connection, PublicKey } from "@solana/web3.js";

const connection = new Connection("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>", "confirmed");

let mint = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");

let tokenSupply = await connection.getTokenSupply(mint);

console.log(tokenSupply);
```

{% endtab %}

{% tab title="Rust" %}

```rust
// Cargo.toml: anyhow = "1", solana-client = "~4.4", solana-commitment-config = "3",
// solana-sdk = "5", tokio = { version = "1", features = ["full"] }. solana-client 4.4 takes
// solana-sdk 5.x types. Requires Rust 1.98.1 or newer (solana-client 4.4).
use anyhow::Result;
use solana_client::nonblocking::rpc_client::RpcClient;
use solana_commitment_config::CommitmentConfig;
use solana_sdk::pubkey;

#[tokio::main]
async fn main() -> Result<()> {
    let client = RpcClient::new_with_commitment(
        String::from("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>"),
        CommitmentConfig::confirmed(),
    );

    let mint = pubkey!("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");

    let token_supply = client.get_token_supply(&mint).await?;

    println!("{:#?}", token_supply);

    Ok(())
}
```

{% endtab %}
{% endtabs %}

## Parameters

**`pubkey`** · string · required

Pubkey of the token Mint to query, as base-58 encoded string

**`config`** · object

Configuration object containing the following fields:

**`commitment`** · string · default `finalized`

Values: `processed`, `confirmed`, `finalized`

Solana RPC uses the following commitment levels:

| Value       | Description                                                                                                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `processed` | Return data from the highest slot this node has processed on the fork it currently considers best. This is the newest view, but it can still change if the cluster switches forks. |
| `confirmed` | Return data from the highest slot the cluster has finalized. On Alpenglow, `confirmed` and `finalized` are the same level.                                                         |
| `finalized` | Return data from the highest slot that the cluster has finalized. On Alpenglow there are no vote towers or lockouts: a slot is finalized by certificates of aggregated votes.      |

## Response

```json
{
  "jsonrpc": "2.0",
  "result": {
    "context": { "apiVersion": "4.3.2", "slot": 464671944 },
    "value": {
      "amount": "8891608622856058",
      "decimals": 6,
      "uiAmount": 8891608622.856058,
      "uiAmountString": "8891608622.856058"
    }
  },
  "id": 1
}
```

## Result

RpcResponse object containing:

**`context`** · object

Slot and API version the node used to answer this request.

| Field        | Type     | Description                                                                     |
| ------------ | -------- | ------------------------------------------------------------------------------- |
| `slot`       | `u64`    | Slot at which the node evaluated this request.                                  |
| `apiVersion` | `string` | RPC API version reported by the node. This field may be omitted by older nodes. |

**`value`** · object

Token amount object with the following fields:

This uses the same amount fields documented for `uiTokenAmount` in [Token Balances](https://solana.com/docs/rpc/json-structures#token-balances).

| Field            | Type             | Description                                                                                      |
| ---------------- | ---------------- | ------------------------------------------------------------------------------------------------ |
| `amount`         | `string`         | Raw total token supply, as a base-10 integer string with no decimal point.                       |
| `decimals`       | `u8`             | Number of decimal places configured on the mint.                                                 |
| `uiAmount`       | `number \| null` | Decimal-scaled total supply as a floating-point number. Deprecated in favor of `uiAmountString`. |
| `uiAmountString` | `string`         | Decimal-scaled total supply as a string.                                                         |

***

*Adapted from the* [*Solana `getTokenSupply` reference*](https://solana.com/docs/rpc/http/gettokensupply)*, maintained by the Solana Foundation.*

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# getLargestAccounts

Returns the 20 largest accounts by lamport balance, optionally filtered to circulating or nonCirculating; disabled on Triton mainnet endpoints (HTTP 410).

{% hint style="warning" %}
`getLargestAccounts` is disabled on Triton's mainnet endpoints. Calls return HTTP `410` with the message "The RPC call or parameters have been disabled".
{% endhint %}

## Request

{% tabs %}
{% tab title="cURL" %}

```bash
curl "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>" -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getLargestAccounts",
  "params": [
    {
      "commitment": "finalized",
      "sortResults": true
    }
  ]
}'
```

{% endtab %}

{% tab title="Kit" %}

```typescript
import { createSolanaRpc } from "@solana/kit";

const rpc_url = "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>";
const rpc = createSolanaRpc(rpc_url);

let largestAccounts = await rpc.getLargestAccounts().send();

console.log(largestAccounts);
```

{% endtab %}

{% tab title="web3.js" %}

```typescript
import {
  Connection,
  type GetLargestAccountsConfig
} from "@solana/web3.js";

const connection = new Connection("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>", "confirmed");

let config: GetLargestAccountsConfig = {
  commitment: "finalized",
  filter: "circulating"
};

let largestAccounts = await connection.getLargestAccounts(config);

console.log(largestAccounts);
```

{% endtab %}

{% tab title="Rust" %}

```rust
// Cargo.toml: anyhow = "1", solana-client = "~4.4", solana-commitment-config = "3",
// tokio = { version = "1", features = ["full"] }.
// Requires Rust 1.98.1 or newer (solana-client 4.4).
use anyhow::Result;
use solana_client::{
    nonblocking::rpc_client::RpcClient,
    rpc_config::{RpcLargestAccountsConfig, RpcLargestAccountsFilter},
};
use solana_commitment_config::CommitmentConfig;

#[tokio::main]
async fn main() -> Result<()> {
    let client = RpcClient::new_with_commitment(
        String::from("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>"),
        CommitmentConfig::confirmed(),
    );

    let config = RpcLargestAccountsConfig {
        commitment: CommitmentConfig::finalized().into(),
        filter: RpcLargestAccountsFilter::Circulating.into(),
        sort_results: true.into(),
    };
    let largest_accounts = client.get_largest_accounts_with_config(config).await?;

    println!("{:#?}", largest_accounts);

    Ok(())
}
```

{% endtab %}
{% endtabs %}

## Parameters

**`config`** · object

Configuration object containing the following fields:

**`commitment`** · string · default `finalized`

Values: `processed`, `confirmed`, `finalized`

Solana RPC uses the following commitment levels:

| Value       | Description                                                                                                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `processed` | Return data from the highest slot this node has processed on the fork it currently considers best. This is the newest view, but it can still change if the cluster switches forks. |
| `confirmed` | Return data from the highest slot the cluster has finalized. On Alpenglow, `confirmed` and `finalized` are the same level.                                                         |
| `finalized` | Return data from the highest slot that the cluster has finalized. On Alpenglow there are no vote towers or lockouts: a slot is finalized by certificates of aggregated votes.      |

**`filter`** · string

Values: `circulating`, `nonCirculating`

Filter results by account type. If omitted, the RPC node includes both circulating and non-circulating accounts.

**`sortResults`** · bool

Accepted in the config, but the Agave RPC handler does not read it, so it does not change the result.

## Response

```json
{
  "jsonrpc": "2.0",
  "result": {
    "context": { "apiVersion": "4.3.2", "slot": 54 },
    "value": [
      {
        "address": "99P8ZgtJYe1buSK8JXkvpLh8xPsCFuLYhz9hQFNw93WJ",
        "lamports": 999974
      },
      {
        "address": "uPwWLo16MVehpyWqsLkK3Ka8nLowWvAHbBChqv2FZeL",
        "lamports": 42
      }
    ]
  },
  "id": 1
}
```

## Result

RpcResponse object containing:

**`context`** · object

Slot and API version the node used to answer this request.

| Field        | Type     | Description                                                                     |
| ------------ | -------- | ------------------------------------------------------------------------------- |
| `slot`       | `u64`    | Slot at which the node evaluated this request.                                  |
| `apiVersion` | `string` | RPC API version reported by the node. This field may be omitted by older nodes. |

**`value`** · array

Array of up to 20 account-balance objects with the following fields:

| Field      | Type     | Description                                   |
| ---------- | -------- | --------------------------------------------- |
| `address`  | `string` | Account address, as a base-58 encoded string. |
| `lamports` | `u64`    | Number of lamports in the account.            |

***

*Adapted from the* [*Solana `getLargestAccounts` reference*](https://solana.com/docs/rpc/http/getlargestaccounts)*, maintained by the Solana Foundation.*

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# getMinimumBalanceForRentExemption

Returns the minimum lamports an account with a given data length needs to be rent exempt.

## Request

{% tabs %}
{% tab title="cURL" %}

```bash
curl "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>" -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getMinimumBalanceForRentExemption",
  "params": [
    50,
    {
      "commitment": "processed"
    }
  ]
}'
```

{% endtab %}

{% tab title="Kit" %}

```typescript
import { createSolanaRpc } from "@solana/kit";

const rpc_url = "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>";
const rpc = createSolanaRpc(rpc_url);

let dataLength = BigInt(50);
let minBalForRentExemption = await rpc
  .getMinimumBalanceForRentExemption(dataLength)
  .send();

console.log(minBalForRentExemption);
```

{% endtab %}

{% tab title="web3.js" %}

```typescript
import { Connection } from "@solana/web3.js";

const connection = new Connection("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>", "confirmed");

let dataLength = 50;
let minBalForRentExemption =
  await connection.getMinimumBalanceForRentExemption(dataLength);

console.log(minBalForRentExemption);
```

{% endtab %}

{% tab title="Rust" %}

```rust
// Cargo.toml: anyhow = "1", solana-client = "~4.4", solana-commitment-config = "3",
// tokio = { version = "1", features = ["full"] }.
// Requires Rust 1.98.1 or newer (solana-client 4.4).
use anyhow::Result;
use solana_client::nonblocking::rpc_client::RpcClient;
use solana_commitment_config::CommitmentConfig;

#[tokio::main]
async fn main() -> Result<()> {
    let client = RpcClient::new_with_commitment(
        String::from("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>"),
        CommitmentConfig::confirmed(),
    );

    let data_len = 50;

    let min_bal_for_rent_exemption = client
        .get_minimum_balance_for_rent_exemption(data_len)
        .await?;

    println!("{:#?}", min_bal_for_rent_exemption);

    Ok(())
}
```

{% endtab %}
{% endtabs %}

## Parameters

**`length`** · usize · required

The Account's data length

**`config`** · object

Configuration object containing the following fields:

**`commitment`** · string · default `finalized`

Values: `processed`, `confirmed`, `finalized`

Solana RPC uses the following commitment levels:

| Value       | Description                                                                                                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `processed` | Return data from the highest slot this node has processed on the fork it currently considers best. This is the newest view, but it can still change if the cluster switches forks. |
| `confirmed` | Return data from the highest slot the cluster has finalized. On Alpenglow, `confirmed` and `finalized` are the same level.                                                         |
| `finalized` | Return data from the highest slot that the cluster has finalized. On Alpenglow there are no vote towers or lockouts: a slot is finalized by certificates of aggregated votes.      |

## Response

```json
{
  "jsonrpc": "2.0",
  "result": 904240,
  "id": 1
}
```

## Result

Minimum lamports required in the Account to remain rent free

***

*Adapted from the* [*Solana `getMinimumBalanceForRentExemption` reference*](https://solana.com/docs/rpc/http/getminimumbalanceforrentexemption)*, maintained by the Solana Foundation.*

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# getStakeMinimumDelegation

Returns the cluster's current minimum stake delegation, in lamports.

## Request

{% tabs %}
{% tab title="cURL" %}

```bash
curl "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>" -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getStakeMinimumDelegation",
  "params": [
    {
      "commitment": "finalized"
    }
  ]
}'
```

{% endtab %}

{% tab title="Kit" %}

```typescript
import { createSolanaRpc } from "@solana/kit";

const rpc_url = "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>";
const rpc = createSolanaRpc(rpc_url);

let stakeMinDelegation = await rpc.getStakeMinimumDelegation().send();

console.log(stakeMinDelegation);
```

{% endtab %}

{% tab title="web3.js" %}

```typescript
import { Connection } from "@solana/web3.js";

const connection = new Connection("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>", "confirmed");

let stakeMinDelegation = await connection.getStakeMinimumDelegation();

console.log(stakeMinDelegation);
```

{% endtab %}

{% tab title="Rust" %}

```rust
// Cargo.toml: anyhow = "1", solana-client = "~4.4", solana-commitment-config = "3",
// tokio = { version = "1", features = ["full"] }.
// Requires Rust 1.98.1 or newer (solana-client 4.4).
use anyhow::Result;
use solana_client::nonblocking::rpc_client::RpcClient;
use solana_commitment_config::CommitmentConfig;

#[tokio::main]
async fn main() -> Result<()> {
    let client = RpcClient::new_with_commitment(
        String::from("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>"),
        CommitmentConfig::confirmed(),
    );

    let min_stake_delegation = client.get_stake_minimum_delegation().await?;

    println!("{}", min_stake_delegation);

    Ok(())
}
```

{% endtab %}
{% endtabs %}

## Parameters

**`config`** · object · optional

Configuration object containing the following fields:

**`commitment`** · string · default `finalized`

Values: `processed`, `confirmed`, `finalized`

Solana RPC uses the following commitment levels:

| Value       | Description                                                                                                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `processed` | Return data from the highest slot this node has processed on the fork it currently considers best. This is the newest view, but it can still change if the cluster switches forks. |
| `confirmed` | Return data from the highest slot the cluster has finalized. On Alpenglow, `confirmed` and `finalized` are the same level.                                                         |
| `finalized` | Return data from the highest slot that the cluster has finalized. On Alpenglow there are no vote towers or lockouts: a slot is finalized by certificates of aggregated votes.      |

**`minContextSlot`** · number

The minimum slot that the request can be evaluated at

## Response

```json
{
  "jsonrpc": "2.0",
  "result": {
    "context": { "apiVersion": "4.3.2", "slot": 501 },
    "value": 1000000000
  },
  "id": 1
}
```

## Result

RpcResponse object containing:

**`context`** · object

Slot and API version the node used to answer this request.

| Field        | Type     | Description                                                                     |
| ------------ | -------- | ------------------------------------------------------------------------------- |
| `slot`       | `u64`    | Slot at which the node evaluated this request.                                  |
| `apiVersion` | `string` | RPC API version reported by the node. This field may be omitted by older nodes. |

**`value`** · u64

Current minimum stake delegation, in lamports.

***

*Adapted from the* [*Solana `getStakeMinimumDelegation` reference*](https://solana.com/docs/rpc/http/getstakeminimumdelegation)*, maintained by the Solana Foundation.*

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# getVoteAccounts

Returns current and delinquent vote accounts with activatedStake, commission, lastVote, rootSlot and epochCredits, optionally filtered by votePubkey.

## Request

{% tabs %}
{% tab title="cURL" %}

```bash
curl "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>" -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getVoteAccounts",
  "params": [
    {
      "commitment": "finalized",
      "votePubkey": "<vote-account-pubkey>"
    }
  ]
}'
```

{% endtab %}

{% tab title="Kit" %}

```typescript
import { address, createSolanaRpc } from "@solana/kit";

const rpc_url = "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>";
const rpc = createSolanaRpc(rpc_url);

let votePubkey = address("<vote-account-pubkey>");

let voteAccounts = await rpc
  .getVoteAccounts({
    votePubkey
  })
  .send();

console.log(voteAccounts);
```

{% endtab %}

{% tab title="web3.js" %}

```typescript
import { Connection, PublicKey } from "@solana/web3.js";

const connection = new Connection("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>", "confirmed");

// web3.js getVoteAccounts takes only a commitment, so it returns all vote accounts; filter the result by votePubkey.
let voteAccounts = await connection.getVoteAccounts();
let mine = voteAccounts.current.find((v) => v.votePubkey === "<vote-account-pubkey>");

console.log(mine);
```

{% endtab %}

{% tab title="Rust" %}

```rust
// Cargo.toml: anyhow = "1", solana-client = "~4.4", solana-commitment-config = "3",
// tokio = { version = "1", features = ["full"] }.
// Requires Rust 1.98.1 or newer (solana-client 4.4).
use anyhow::Result;
use solana_client::{nonblocking::rpc_client::RpcClient, rpc_config::RpcGetVoteAccountsConfig};
use solana_commitment_config::CommitmentConfig;

#[tokio::main]
async fn main() -> Result<()> {
    let client = RpcClient::new_with_commitment(
        String::from("https://<your-endpoint>.mainnet.rpcpool.com/<your-token>"),
        CommitmentConfig::confirmed(),
    );

    let vote_pubkey = String::from("<vote-account-pubkey>");

    let config = RpcGetVoteAccountsConfig {
        vote_pubkey: Some(vote_pubkey),
        commitment: CommitmentConfig::finalized().into(),
        keep_unstaked_delinquents: None,
        delinquent_slot_distance: None,
    };

    let vote_accounts = client.get_vote_accounts_with_config(config).await?;

    println!("{:#?}", vote_accounts);

    Ok(())
}
```

{% endtab %}
{% endtabs %}

## Parameters

**`config`** · object · optional

Configuration object containing the following fields:

**`commitment`** · string · default `finalized`

Values: `processed`, `confirmed`, `finalized`

Solana RPC uses the following commitment levels:

| Value       | Description                                                                                                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `processed` | Return data from the highest slot this node has processed on the fork it currently considers best. This is the newest view, but it can still change if the cluster switches forks. |
| `confirmed` | Return data from the highest slot the cluster has finalized. On Alpenglow, `confirmed` and `finalized` are the same level.                                                         |
| `finalized` | Return data from the highest slot that the cluster has finalized. On Alpenglow there are no vote towers or lockouts: a slot is finalized by certificates of aggregated votes.      |

**`votePubkey`** · string

Return only entries for this vote account address, as a base-58 encoded string.

**`keepUnstakedDelinquents`** · bool · default `false`

Values: `true`, `false`

Keep delinquent vote accounts even if their activated stake is zero.

**`delinquentSlotDistance`** · u64 · default `128`

Number of slots a validator may trail the selected slot before the RPC node classifies it as delinquent. **Note:** ecosystem tools usually leave this unset to preserve consistent behaviour.

## Response

```json
{
  "jsonrpc": "2.0",
  "result": {
    "current": [
      {
        "activatedStake": 17034353881158988,
        "commission": 7,
        "epochCredits": [
          [1071, 19495919626183, 17032766306108],
          [1072, 21945030397590, 19495919626183],
          [1073, 24369876940155, 21945030397590],
          [1074, 26854232539350, 24369876940155],
          [1075, 28399585778820, 26854232539350]
        ],
        "epochVoteAccount": true,
        "inflationRewardsCommissionBps": 700,
        "lastVote": 464671960,
        "nodePubkey": "<validator-identity>",
        "rootSlot": 464671960,
        "votePubkey": "<vote-account-pubkey>"
      }
    ],
    "delinquent": []
  },
  "id": 1
}
```

## Result

Vote-account status object containing `current` and `delinquent` arrays of vote account records.

**`current`** · array

Vote accounts the RPC node classifies as current at the requested commitment.

**`delinquent`** · array

Vote accounts the RPC node classifies as delinquent at the requested commitment.

Each element of `current` and `delinquent` is a vote-account object containing:

| Field                           | Type     | Description                                                                                                  |
| ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `activatedStake`                | `u64`    | Stake, in lamports, delegated to this vote account and active in the current epoch.                          |
| `commission`                    | `u8`     | Commission percentage (0-100) used for rewards payout.                                                       |
| `epochCredits`                  | `array`  | Recent history of earned credits for up to five epochs. Each element is `[epoch, credits, previousCredits]`. |
| `epochVoteAccount`              | `bool`   | Whether this vote account is staked for the current epoch.                                                   |
| `inflationRewardsCommissionBps` | `u16`    | Commission in basis points (0-10000) used for rewards payout. Older nodes omit this field.                   |
| `lastVote`                      | `u64`    | Most recent slot this vote account voted on. Returns `0` if no votes exist.                                  |
| `nodePubkey`                    | `string` | Validator identity pubkey, as a base-58 encoded string.                                                      |
| `rootSlot`                      | `u64`    | Current root slot for this vote account. Returns `0` if no root slot exists.                                 |
| `votePubkey`                    | `string` | Vote account pubkey, as a base-58 encoded string.                                                            |

***

*Adapted from the* [*Solana `getVoteAccounts` reference*](https://solana.com/docs/rpc/http/getvoteaccounts)*, maintained by the Solana Foundation.*

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# Metaplex DAS API methods

Metaplex DAS API methods on Triton for assets, Merkle proofs, token accounts, and editions: getAsset, getAssetsByOwner, searchAssets, getAssetProof, and more.

Triton's DAS endpoints implement the Metaplex [Digital Asset Standard (DAS) API](https://www.metaplex.com/docs/dev-tools/das-api). The pages below describe each method as served on Triton.

## Assets

| Method                                                                                                   | What it returns                                              |
| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| [`getAsset`](https://docs.triton.one/solana/rpc-methods/readme/das-api/getasset)                         | Detailed information about one digital asset.                |
| [`getAssets`](https://docs.triton.one/solana/rpc-methods/readme/das-api/getassets)                       | The same, for many assets by ID (getAssetBatch is an alias). |
| [`getAssetsByOwner`](https://docs.triton.one/solana/rpc-methods/readme/das-api/getassetsbyowner)         | The assets owned by an address.                              |
| [`getAssetsByAuthority`](https://docs.triton.one/solana/rpc-methods/readme/das-api/getassetsbyauthority) | The assets under a given authority.                          |
| [`getAssetsByCreator`](https://docs.triton.one/solana/rpc-methods/readme/das-api/getassetsbycreator)     | The assets created by a given creator.                       |
| [`getAssetsByGroup`](https://docs.triton.one/solana/rpc-methods/readme/das-api/getassetsbygroup)         | The assets in a group, such as a collection.                 |
| [`searchAssets`](https://docs.triton.one/solana/rpc-methods/readme/das-api/searchassets)                 | The assets matching a set of filters.                        |

## Compressed assets

| Method                                                                                                     | What it returns                                |
| ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| [`getAssetProof`](https://docs.triton.one/solana/rpc-methods/readme/das-api/getassetproof)                 | The Merkle proof for a compressed asset.       |
| [`getAssetProofBatch`](https://docs.triton.one/solana/rpc-methods/readme/das-api/getassetproofbatch)       | The Merkle proofs for many compressed assets.  |
| [`getSignaturesForAsset`](https://docs.triton.one/solana/rpc-methods/readme/das-api/getsignaturesforasset) | The transaction history of a compressed asset. |

## Token accounts and editions

| Method                                                                                                         | What it returns                               |
| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| [`getTokenAccounts`](https://docs.triton.one/solana/rpc-methods/readme/das-api/gettokenaccounts)               | The token accounts for a mint or owner.       |
| [`getTokenLargestAccounts`](https://docs.triton.one/solana/rpc-methods/readme/das-api/gettokenlargestaccounts) | The 20 largest token accounts for a mint.     |
| [`getNftEditions`](https://docs.triton.one/solana/rpc-methods/readme/das-api/getnfteditions)                   | The printed editions of a master edition NFT. |

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)


# getAsset

Metaplex DAS getAsset: returns metadata, ownership, authorities, collection, creators, and compression details for one digital asset by ID.

## Request

{% tabs %}
{% tab title="cURL" %}

```bash
curl "https://<your-endpoint>.mainnet.rpcpool.com/<your-token>" -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "123",
    "method": "getAsset",
    "params": {
      "id": "7k7YqWc85BtyTx5UyvNnogv2jPHVe4BZ9HQsFLM8VnoJ"
    }
}'
```

{% endtab %}
{% endtabs %}

## Parameters

| Name    | Description                                                                                                                                                                                                     | Required |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| id      | The unique identifier of the asset to retrieve.                                                                                                                                                                 | Yes      |
| options | Display options, as an object of flags that default to `false`: `showFungible`, `showCollectionMetadata`, `showUnverifiedCollections`, `showZeroBalance`, `showInscription`. Also accepted as `displayOptions`. | No       |

***

*Adapted from the* [*Metaplex `getAsset` reference*](https://www.metaplex.com/docs/dev-tools/das-api/methods/get-asset)*, maintained by the Metaplex Foundation.*

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)




---

[Next Page](https://docs.triton.one/llms-full.txt/1)

