# JSON-RPC reference

> Shared SWQoS JSON-RPC endpoint, authentication, request and response conventions, status codes and client examples

<Note>
Supanode issues keys through [Telegram](https://telegram.me/supanode_tgs). Default minimum tip: 0.001 SOL; default rate: 15 sends/s per key per metro. Your key settings can differ. Declared tips are off by default and require enablement and a payment arrangement with Supanode. If your key returns `partner_declared_tips`, use an on-chain transfer instead.
</Note>

Use JSON-RPC to submit transactions and bundles or query an SWQoS host. Use your Solana RPC provider for blockhashes, balances and confirmation. The [HTTP reference](https://supanode.xyz/docs/solana/sender/reference/http) covers raw payload routes.

## Endpoint

Send JSON-RPC requests with `POST` to any path of an SWQoS host other than `/binary` and `/plaintext`. `https://fra.tpu.supanode.xyz/`, `https://fra.tpu.supanode.xyz/rpc` and `https://fra.tpu.supanode.xyz/` are equivalent. [Endpoints](https://supanode.xyz/docs/solana/sender/endpoints) lists the hosts and ports.

Every JSON-RPC method needs an API key. Send it in the `x-api-key` header.
Request a key from [Supanode on Telegram](https://telegram.me/supanode_tgs); see [API keys](https://supanode.xyz/docs/solana/sender/api-keys).

## Authentication

Use HTTPS and prefer the `x-api-key` header to keep the key out of URL logs.
The same authentication rules apply to the [HTTP routes](https://supanode.xyz/docs/solana/sender/reference/http), except
`GET /health`, which needs no key.

For compatibility, the service accepts these forms in order:

| Precedence | Form | Example |
| --- | --- | --- |
| 1 | Query parameter | `https://fra.tpu.supanode.xyz/?api-key=YOUR_KEY` |
| 2 | Header | `x-api-key: YOUR_KEY` |
| 3 | Header | `Authorization: Bearer YOUR_KEY` |

The first form present wins, even if its value is empty or invalid. `Bearer ` is
case sensitive. Query authentication puts the secret in the URL, where proxies,
servers and monitoring tools may log it. Use it only when a client cannot send headers.

## Request

A request body is one JSON object of at most 65,536 bytes, received within 2 seconds.

| Member | Rule |
| --- | --- |
| `jsonrpc` | Exactly `"2.0"`. |
| `method` | One of the methods below. |
| `params` | Method parameters, documented on each method page |
| `id` | Optional. Echoed in the response exactly as sent; `null` when absent. |

Batches (a JSON array of requests) are refused with problem `batch`; send one request per call. HTTP/2 connections can carry many requests at once.

```json title="Request"
{"jsonrpc":"2.0","id":1,"method":"getHealth"}
```

## Methods

| Method | Params | Result |
| --- | --- | --- |
| [`sendTransaction`](https://supanode.xyz/docs/solana/sender/reference/json-rpc/send-transaction) | `[transaction, options?]` | Base58 signature string |
| [`sendBundle`](https://supanode.xyz/docs/solana/sender/reference/json-rpc/send-bundle) | `[[transaction, ...], options?]` | 64 character hex bundle ID |
| [`getTipFloor`](https://supanode.xyz/docs/solana/sender/reference/json-rpc/tip-floor) | none | Array of zero or one tip floor objects |
| [`getHealth`](https://supanode.xyz/docs/solana/sender/reference/json-rpc/health) | none | `"ok"` |
| [`getSlot`](https://supanode.xyz/docs/solana/sender/reference/json-rpc/slot) | none | Integer slot |

An unrecognized method name is refused with problem `unknown_method` and code `-32601`. There is no `getLatestBlockhash`, `getSignatureStatuses`, `simulateTransaction`, bundle status method or WebSocket subscription.

## Responses

A result comes back with HTTP `200`:

```text title="Result shape"
{"jsonrpc":"2.0","result":RESULT,"id":ID}
```

A refusal carries the rejection in `error.data`:

```json title="Rejection (example from sendTransaction)"
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "tip missing: add a System transfer of at least 1,000,000 lamports to a Supanode tip account, or declare a tip",
    "data": {
      "reason": "missing_tip",
      "minimum": 1000000,
      "found": 0,
      "message": "tip missing: add a System transfer of at least 1,000,000 lamports to a Supanode tip account, or declare a tip",
      "retryable": false
    }
  },
  "id": 1
}
```

| Field | Meaning |
| --- | --- |
| `data.reason` | Stable snake_case reason. Match on this. |
| Other `data` fields | The numbers behind the refusal, specific to each reason. See [Errors](https://supanode.xyz/docs/solana/sender/reference/errors) |
| `data.message`, `error.message` | The same sentence: what happened and what to change. Wording can change. |
| `data.retryable` | Whether sending the same request again, unchanged, can succeed. |
| `data.docs` | Optional public error documentation URL followed by the reason anchor. |

A failed preflight simulation also puts Solana's simulation result fields, such as `err`, `logs` and `unitsConsumed`, at the top level of `data`. See [`getHealth`](https://supanode.xyz/docs/solana/sender/reference/json-rpc/health) for its separate unhealthy response.

`id` is `null` when the request was refused before its `id` could be read: a missing or unknown key, a body that is too large, unreadable or late, invalid JSON, a batch, or a body that is not a JSON object.

Hosted responses on Supanode domains omit the optional `data.docs` field. Match `data.reason`, not the documentation URL.

An unknown or removed hostname receives HTTP 421 with a plain-text body and no
JSON-RPC envelope. The server checks TLS SNI and each request's `Host` or
`:authority`, including requests on existing connections. Resumed TLS sessions
cannot bypass a domain removal after the server refreshes its hostname policy.

## Status codes

JSON-RPC answers most refusals with HTTP `200`, as Solana RPC does. It uses another status where a client acts on it.

| Reason | HTTP | JSON-RPC code |
| --- | --- | --- |
| [`unauthorized`](https://supanode.xyz/docs/solana/sender/reference/errors#unauthorized), [`key_paused`](https://supanode.xyz/docs/solana/sender/reference/errors#key_paused) | 401 | -32000 |
| [`rate_limited`](https://supanode.xyz/docs/solana/sender/reference/errors#rate_limited) | 429 | -32001 |
| [`simulation_failed`](https://supanode.xyz/docs/solana/sender/reference/errors#simulation_failed) | 200 | -32002 |
| [`payment_required`](https://supanode.xyz/docs/solana/sender/reference/errors#payment_required) | 402 | -32003 |
| [`not_ready`](https://supanode.xyz/docs/solana/sender/reference/errors#not_ready), [`overloaded`](https://supanode.xyz/docs/solana/sender/reference/errors#overloaded), [`forward_failed`](https://supanode.xyz/docs/solana/sender/reference/errors#forward_failed), [`preflight_unavailable`](https://supanode.xyz/docs/solana/sender/reference/errors#preflight_unavailable), [`internal`](https://supanode.xyz/docs/solana/sender/reference/errors#internal) | 503 | -32603 |
| [`malformed`](https://supanode.xyz/docs/solana/sender/reference/errors#malformed), [`too_large`](https://supanode.xyz/docs/solana/sender/reference/errors#too_large), [`unsigned`](https://supanode.xyz/docs/solana/sender/reference/errors#unsigned), [`signature_count`](https://supanode.xyz/docs/solana/sender/reference/errors#signature_count), [`missing_tip`](https://supanode.xyz/docs/solana/sender/reference/errors#missing_tip), [`credit_exhausted`](https://supanode.xyz/docs/solana/sender/reference/errors#credit_exhausted), [`bundle_size`](https://supanode.xyz/docs/solana/sender/reference/errors#bundle_size), [`bundle_control`](https://supanode.xyz/docs/solana/sender/reference/errors#bundle_control) | 200 | -32602 |
| [`invalid_request`](https://supanode.xyz/docs/solana/sender/reference/errors#invalid_request) | 200 | by problem, below |
| [`unsupported`](https://supanode.xyz/docs/solana/sender/reference/errors#unsupported) | 403 for disabled bundles or a partner key's declared tip | -32601 |

| `invalid_request` problem | JSON-RPC code |
| --- | --- |
| `parse_error` | -32700 |
| `not_found`, `body_timeout`, `body_unreadable`, `batch`, `not_json_rpc` | -32600 |
| `unknown_method` | -32601 |
| `missing_params`, `invalid_params`, `transaction_not_string`, `invalid_options`, `invalid_commitment` | -32602 |

Codes -32001 and -32003 have other meanings in Solana's RPC (a cleaned-up block and a failed signature verification). Identify an SWQoS refusal by `error.data.reason`.

<span id="openapi" />

## OpenAPI documents

Each JSON-RPC method and HTTP route is described in OpenAPI 3.1, with its shared parts included in the document. Import a document into an HTTP client or a code generator.

| Document | Operations |
| --- | --- |
| [`send-transaction.json`](https://supanode.xyz/sender/openapi/send-transaction.json) | [`sendTransaction`](https://supanode.xyz/docs/solana/sender/reference/json-rpc/send-transaction) |
| [`send-bundle.json`](https://supanode.xyz/sender/openapi/send-bundle.json) | [`sendBundle`](https://supanode.xyz/docs/solana/sender/reference/json-rpc/send-bundle) |
| [`tip-floor.json`](https://supanode.xyz/sender/openapi/tip-floor.json) | [`getTipFloor`](https://supanode.xyz/docs/solana/sender/reference/json-rpc/tip-floor), [`GET /tip_floor`](https://supanode.xyz/docs/solana/sender/reference/http/tip-floor) |
| [`health.json`](https://supanode.xyz/sender/openapi/health.json) | [`getHealth`](https://supanode.xyz/docs/solana/sender/reference/json-rpc/health), [`GET /health`](https://supanode.xyz/docs/solana/sender/reference/http/health) |
| [`slot.json`](https://supanode.xyz/sender/openapi/slot.json) | [`getSlot`](https://supanode.xyz/docs/solana/sender/reference/json-rpc/slot) |
| [`http.json`](https://supanode.xyz/sender/openapi/http.json) | [`POST /binary`](https://supanode.xyz/docs/solana/sender/reference/http/binary), [`POST /plaintext`](https://supanode.xyz/docs/solana/sender/reference/http/plaintext) |

<span id="client-libraries" />

## Solana client libraries

`sendTransaction` has Solana's request shape, so Solana clients can call it. They do not surface SWQoS rejections in full. With `@solana/kit` 8.5:

- A response with HTTP status 401, 402, 429 or 503 throws `SOLANA_ERROR__RPC__TRANSPORT_HTTP_ERROR` carrying only `statusCode` and headers. Kit does not read the body, so `reason`, `retry_after_ms` and `unpaid_lamports` are lost.
- A `simulation_failed` refusal throws Kit's preflight failure error, which keeps the simulation fields.
- A refusal with code -32602, -32600, -32601 or -32700 throws an error that keeps only the message text, not `data.reason` or its fields.

Use Kit, or another Solana client, to build and sign transactions. Use a plain HTTP request, like `call` below, when your code needs to act on a rejection reason.

## Example project

Rust examples use the Cargo project below. Go examples use the Go module. Each version reads the key from `SWQOS_API_KEY` and the endpoint from `SWQOS_URL`. The TypeScript helper `swqos.ts` needs only `fetch` and runs in Bun and Node.js 18 or later.

<Tabs>

<Tab title="Rust">

```toml title="Cargo.toml" tab="Rust" tab-group="language"
[package]
name = "swqos-examples"
version = "0.1.0"
edition = "2024"

[dependencies]
base64 = "0.23.1"
libc = "0.2"
rand = "0.10.3"
reqwest = { version = "0.13.5", default-features = false, features = ["rustls", "json", "http2"] }
serde = { version = "1.0.229", features = ["derive"] }
serde_json = "1.0.154"
sha2 = "0.11.1"
solana-address = { version = "2.9.0", features = ["std"] }
solana-hash = { version = "4.7.0", features = ["decode"] }
solana-keypair = "4.0.0"
solana-message = { version = "6.0.0", features = ["wincode"] }
solana-signature = "3.6.0"
solana-signer = "4.0.0"
solana-system-interface = { version = "3.3.0", features = ["wincode"] }
solana-transaction = { version = "6.0.0", features = ["wincode"] }
tokio = { version = "1.54.1", features = ["macros", "rt-multi-thread", "time", "fs"] }
wincode = "0.6.3"
```

</Tab>

<Tab title="Rust">

```rust title="src/lib.rs" tab="Rust" tab-group="language"
pub mod bundle_id;
pub mod confirm;
pub mod payload;
pub mod send_transaction;
pub mod swqos;
```

</Tab>

<Tab title="Rust">

```rust title="src/swqos.rs" tab="Rust" tab-group="language"
use std::{collections::BTreeMap, error::Error, fmt, sync::LazyLock};

use reqwest::Client;
use serde::{Deserialize, de::DeserializeOwned};
use serde_json::{Value, json};

pub type Result<T, E = Box<dyn Error>> = std::result::Result<T, E>;

static CLIENT: LazyLock<Client> = LazyLock::new(Client::new);

#[derive(Debug, Deserialize)]
pub struct Rejection {
    pub reason: String,
    pub message: String,
    pub retryable: bool,
    pub docs: Option<String>,
    #[serde(flatten)]
    pub fields: BTreeMap<String, Value>,
}

#[derive(Deserialize)]
struct Reply<T> {
    result: Option<T>,
    error: Option<RpcError>,
}

#[derive(Deserialize)]
struct RpcError {
    code: i64,
    message: String,
    data: Option<Rejection>,
}

#[derive(Debug)]
pub struct SwqosError {
    pub status: u16,
    pub code: i64,
    pub message: String,
    pub rejection: Option<Rejection>,
}

impl fmt::Display for SwqosError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        let message = self
            .rejection
            .as_ref()
            .map_or(self.message.as_str(), |rejection| {
                rejection.message.as_str()
            });
        formatter.write_str(message)
    }
}

impl Error for SwqosError {}

pub fn required(name: &str) -> Result<String> {
    match std::env::var(name) {
        Ok(value) if !value.is_empty() => Ok(value),
        _ => Err(format!("set {name}").into()),
    }
}

pub fn url() -> String {
    match std::env::var("SWQOS_URL") {
        Ok(value) => value,
        Err(_) => "https://fra.tpu.supanode.xyz".into(),
    }
}

pub async fn call<T: DeserializeOwned>(
    method: &str,
    params: Option<Value>,
) -> Result<T> {
    request(&url(), Some(&required("SWQOS_API_KEY")?), method, params).await
}

pub async fn request<T: DeserializeOwned>(
    endpoint: &str,
    api_key: Option<&str>,
    method: &str,
    params: Option<Value>,
) -> Result<T> {
    let mut body = json!({ "jsonrpc": "2.0", "id": 1, "method": method });
    if let Some(params) = params {
        body["params"] = params;
    }
    let mut request = CLIENT.post(endpoint).json(&body);
    if let Some(api_key) = api_key {
        request = request.header("x-api-key", api_key);
    }
    let response = request.send().await?;
    let status = response.status();
    let http_error = response.error_for_status_ref().err();
    let reply: Reply<T> = response.json().await?;
    if let Some(error) = reply.error {
        return Err(Box::new(SwqosError {
            status: status.as_u16(),
            code: error.code,
            message: error.message,
            rejection: error.data,
        }));
    }
    if let Some(error) = http_error {
        return Err(error.into());
    }
    reply
        .result
        .ok_or_else(|| "JSON-RPC reply has no result".into())
}
```

</Tab>

<Tab title="Go">

```text title="go.mod" tab="Go" tab-group="language"
module swqos-examples

go 1.26.0

require (
	github.com/gagliardetto/solana-go v1.25.0
	github.com/quic-go/quic-go v0.64.1
)

require (
	github.com/blendle/zapdriver v1.3.1 // indirect
	github.com/davecgh/go-spew v1.1.1 // indirect
	github.com/fatih/color v1.18.0 // indirect
	github.com/gagliardetto/binary v0.8.0 // indirect
	github.com/gagliardetto/treeout v0.1.4 // indirect
	github.com/goccy/go-json v0.10.6 // indirect
	github.com/klauspost/compress v1.18.7 // indirect
	github.com/logrusorgru/aurora v2.0.3+incompatible // indirect
	github.com/mattn/go-colorable v0.1.14 // indirect
	github.com/mattn/go-isatty v0.0.20 // indirect
	github.com/mitchellh/go-testing-interface v1.14.1 // indirect
	github.com/mostynb/zstdpool-freelist v0.0.0-20201229113212-927304c0c3b1 // indirect
	github.com/oasisprotocol/curve25519-voi v0.0.0-20251114093237-2ab5a27a1729 // indirect
	github.com/streamingfast/logging v0.0.0-20250404134358-92b15d2fbd2e // indirect
	go.mongodb.org/mongo-driver/v2 v2.5.0 // indirect
	go.uber.org/multierr v1.11.0 // indirect
	go.uber.org/zap v1.27.0 // indirect
	golang.org/x/crypto v0.55.0 // indirect
	golang.org/x/net v0.58.0 // indirect
	golang.org/x/sys v0.47.0 // indirect
	golang.org/x/term v0.45.0 // indirect
)
```

</Tab>

<Tab title="Go">

```go title="swqos.go" tab="Go" tab-group="language"
package swqos

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

type Rejection struct {
	Reason    string                     `json:"reason"`
	Message   string                     `json:"message"`
	Retryable bool                       `json:"retryable"`
	Docs      *string                    `json:"docs,omitempty"`
	Fields    map[string]json.RawMessage `json:"-"`
}

func (r *Rejection) UnmarshalJSON(data []byte) error {
	type rejection Rejection
	var decoded rejection
	if err := json.Unmarshal(data, &decoded); err != nil {
		return err
	}
	if err := json.Unmarshal(data, &decoded.Fields); err != nil {
		return err
	}
	*r = Rejection(decoded)
	return nil
}

type SwqosError struct {
	Status    int
	Code      int
	Message   string
	Rejection *Rejection
}

func (e *SwqosError) Error() string {
	if e.Rejection != nil {
		return e.Rejection.Message
	}
	return e.Message
}

func Required(name string) (string, error) {
	value := os.Getenv(name)
	if value == "" {
		return "", fmt.Errorf("set %s", name)
	}
	return value, nil
}

func URL() string {
	if value, ok := os.LookupEnv("SWQOS_URL"); ok {
		return value
	}
	return "https://fra.tpu.supanode.xyz"
}

func Call[T any](ctx context.Context, method string, params ...any) (T, error) {
	apiKey, err := Required("SWQOS_API_KEY")
	if err != nil {
		var zero T
		return zero, err
	}
	return callAt[T](ctx, URL(), apiKey, method, params...)
}

func callAt[T any](ctx context.Context, endpoint, apiKey, method string, params ...any) (T, error) {
	var zero T
	body, err := json.Marshal(struct {
		JSONRPC string `json:"jsonrpc"`
		ID      int    `json:"id"`
		Method  string `json:"method"`
		Params  []any  `json:"params,omitempty"`
	}{"2.0", 1, method, params})
	if err != nil {
		return zero, err
	}
	request, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, bytes.NewReader(body))
	if err != nil {
		return zero, err
	}
	request.Header.Set("content-type", "application/json")
	if apiKey != "" {
		request.Header.Set("x-api-key", apiKey)
	}
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		return zero, err
	}
	defer response.Body.Close()
	var reply struct {
		Result T `json:"result"`
		Error  *struct {
			Code    int        `json:"code"`
			Message string     `json:"message"`
			Data    *Rejection `json:"data"`
		} `json:"error"`
	}
	if err := json.NewDecoder(response.Body).Decode(&reply); err != nil {
		return zero, fmt.Errorf("HTTP %d: %w", response.StatusCode, err)
	}
	if reply.Error != nil {
		return zero, &SwqosError{
			Status: response.StatusCode, Code: reply.Error.Code,
			Message: reply.Error.Message, Rejection: reply.Error.Data,
		}
	}
	if response.StatusCode < 200 || response.StatusCode >= 300 {
		return zero, fmt.Errorf("HTTP %d", response.StatusCode)
	}
	return reply.Result, nil
}
```

</Tab>

<Tab title="TypeScript">

```ts title="swqos.ts" tab="TypeScript" tab-group="language"
export type Rejection = {
  reason: string
  message: string
  retryable: boolean
  docs?: string
  [field: string]: unknown
}

type Reply<T> =
  | { result: T }
  | { error: { code: number; message: string; data?: Rejection } }

export class SwqosError extends Error {
  readonly status: number
  readonly code: number
  readonly rejection: Rejection | undefined

  constructor(status: number, code: number, message: string, rejection?: Rejection) {
    super(rejection?.message ?? message)
    this.status = status
    this.code = code
    this.rejection = rejection
  }
}

export function required(name: string): string {
  const value = process.env[name]
  if (!value) throw new Error(`set ${name}`)
  return value
}

export const url = process.env.SWQOS_URL ?? 'https://fra.tpu.supanode.xyz'
const apiKey = required('SWQOS_API_KEY')

export async function call<T>(method: string, params?: unknown[]): Promise<T> {
  const response = await fetch(url, {
    method: 'POST',
    headers: { 'content-type': 'application/json', 'x-api-key': apiKey },
    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
  })
  const reply = (await response.json()) as Reply<T>
  if ('error' in reply) {
    const { code, message, data } = reply.error
    throw new SwqosError(response.status, code, message, data)
  }
  return reply.result
}
```

</Tab>

</Tabs>

## Other interfaces

- [HTTP](https://supanode.xyz/docs/solana/sender/reference/http): raw transaction and bundle routes, health and tip floor
- [QUIC](https://supanode.xyz/docs/solana/sender/reference/quic): connection settings, stream framing and reply codes
- [Payload envelope](https://supanode.xyz/docs/solana/sender/reference/payload-envelope): the payload shared by raw interfaces
