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

# Example Solana RPC

> A comprehensive guide to setting up a Solana RPC proxy using the H402 protocol for micropayments, enabling on-demand, account-free access to the Solana blockchain.

<Card title="View example code" icon="github" href="https://github.com/bit-gpt/h402-solana-rpc" arrow="true">
  Explore the complete collection of h402 solana RPC integration examples in our repository.
</Card>

## H402 Solana RPC Proxy

**Your personal, on-demand, account-free gateway to the Solana blockchain.**

This project is a simple but powerful proxy server for Solana RPC calls that uses the [H402 protocol](https://h402.xyz/) for micropayments. Think of it as your own personal Helius or QuickNode, but without the need to create an account, manage API keys, or commit to a monthly subscription. You pay for exactly what you use, on the fly.

```mermaid theme={"system"}
sequenceDiagram
    participant Client
    participant H402 Proxy
    participant Facilitator
    participant RPC Provider

    Client->>H402 Proxy: 1. RPC request (e.g. getAccountInfo)
    H402 Proxy-->>Client: 2. 402 payment required<br/>(USDC amount + payment address)
    
    rect rgb(240, 240, 240)
        Note over Client,Facilitator: Payment flow
        Client->>H402 Proxy: 3. Send signed USDC payload
        H402 Proxy->>Facilitator: 3. Validate and Settle the payload
        Facilitator-->>H402 Proxy: 4. Payment receipt<br/>(~100ms)
    end

    rect rgb(240, 240, 240)
        Note over Client,RPC Provider: RPC Flow
        H402 Proxy->>RPC Provider: 5. Retry original request
        RPC Provider-->>H402 Proxy: 6. RPC response
        H402 Proxy-->>Client: 7. Forward response
    end
```

**The flow varies depending on blockchain, token, crypto and other aspects**

## Why is this cool?

In the current Web3 landscape, accessing blockchain data usually means signing up for a service, getting an API key, and dealing with monthly bills. This project demonstrates a more open, decentralized, and flexible approach.

* **No Accounts, No Subscriptions:** Ditch the tedious sign-up forms and monthly commitments. Your wallet is your account.
* **On-Demand, Per-Request Payments:** Pay only for the specific RPC calls you make, when you make them.
* **Enhanced Privacy:** No need to hand over personal information to a third-party service.
* **Perfect for High-Availability Systems:** Use it as a primary RPC endpoint or as a pay-on-demand backup. If your main provider fails, you can instantly fall back to this proxy without any prior setup or cost commitment. This is the model we use for our resilient infrastructure.

## The Power of H402 + Solana

This project leverages a powerful combination:

1. **The H402 Protocol:** A standard for handling payments over HTTP. It allows the server to issue a `402 Payment Required` challenge, which the client can programmatically pay and retry.
2. **The Solana Blockchain:** With transactions that confirm in the blink of an eye and cost a fraction of a cent, Solana is the perfect payment rail for this kind of real-time, high-frequency use case.

The result is a seamless, fast, and incredibly efficient system for monetizing API access.

## How It Works

Here's how it works step by step:

1. A client makes a standard RPC request to the proxy server (e.g., `getAccountInfo`).
2. The proxy checks its configuration and determines the cost for that specific method.
3. It responds with a standard `402 Payment Required` header, detailing the exact amount of USDC to send and the address to send it to.
4. An H402-aware client (like one using our `@bit-gpt/h402-fetch` library) automatically parses this challenge, crafts and signs the tiny payment transaction, and sends it on Solana.
5. Once the payment is confirmed (typically in under a second), the client automatically retries the original RPC request.
6. The proxy verifies the payment and forwards the RPC request to the upstream provider (e.g., Helius), returning the response to the client.

## Getting Started

### Prerequisites

* Node.js
* `pnpm` is recommended (`npm install -g pnpm`)

### 1. Clone the Repository

```bash theme={"system"}
git clone https://github.com/bit-gpt/h402-solana-rpc.git
cd h402-solana-rpc
```

### 2. Install Dependencies

```bash theme={"system"}
npm i
```

### 3. Configure Your Environment

Copy the example environment file and fill in the details.

```bash theme={"system"}
cp .env-example .env
```

You will need to edit the `.env` file:

**Server Config:**

* `RPC_URL`: The upstream Solana RPC endpoint you want to proxy.
* `PORT`: The port your proxy server will run on.
* `SOLANA_PAY_TO_ADDRESS`: The public key of the Solana wallet that will **receive** the payments.

**Client Config (for testing):**

* `SOLANA_PRIVATE_KEY`: The base58-encoded private key of the Solana wallet that will **send** the payments.
* `RESOURCE_SERVER_URL`: The full URL of your running proxy server (e.g., `http://localhost:19782`).
* `ENDPOINT_PATH`: The path for the RPC endpoint on your proxy (`/rpc`).

### 4. Run the Proxy Server

```bash theme={"system"}
pnpm dev
```

The server will start, listening on the `PORT` you configured.

### 5. Run the Client to Test

In a separate terminal, run the client to send a test `getLatestBlockhash` request:

```bash theme={"system"}
pnpm client
```

You'll see the JSON response from the server logged in your console, and if you check your server logs, you'll see the request being processed after payment.

## Future Roadmap

This is just the beginning! We're planning to evolve this concept by adding:

* **A Credit-Based System:** Allow users to pre-fund an account with a larger, one-time payment. The proxy will then deduct credits for each RPC call, offering even lower latency by removing the need for an on-chain transaction for every single request.

We believe this model can fundamentally change how we build and pay for decentralized infrastructure.

## Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.