Documentation

JSON-RPC reference

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

// updated 2026-11-17

NOTE

Supanode issues keys through Telegram. 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.

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 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 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; see 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, except GET /health, which needs no key.

For compatibility, the service accepts these forms in order:

PrecedenceFormExample
1Query parameterhttps://fra.tpu.supanode.xyz/?api-key=YOUR_KEY
2Headerx-api-key: YOUR_KEY
3HeaderAuthorization: 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.

MemberRule
jsonrpcExactly "2.0".
methodOne of the methods below.
paramsMethod parameters, documented on each method page
idOptional. 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.

{"jsonrpc":"2.0","id":1,"method":"getHealth"}

Methods

MethodParamsResult
sendTransaction[transaction, options?]Base58 signature string
sendBundle[[transaction, ...], options?]64 character hex bundle ID
getTipFloornoneArray of zero or one tip floor objects
getHealthnone"ok"
getSlotnoneInteger 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:

{"jsonrpc":"2.0","result":RESULT,"id":ID}

A refusal carries the rejection in error.data:

{
  "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
}
FieldMeaning
data.reasonStable snake_case reason. Match on this.
Other data fieldsThe numbers behind the refusal, specific to each reason. See Errors
data.message, error.messageThe same sentence: what happened and what to change. Wording can change.
data.retryableWhether sending the same request again, unchanged, can succeed.
data.docsOptional 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 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.

ReasonHTTPJSON-RPC code
unauthorized, key_paused401-32000
rate_limited429-32001
simulation_failed200-32002
payment_required402-32003
not_ready, overloaded, forward_failed, preflight_unavailable, internal503-32603
malformed, too_large, unsigned, signature_count, missing_tip, credit_exhausted, bundle_size, bundle_control200-32602
invalid_request200by problem, below
unsupported403 for disabled bundles or a partner key's declared tip-32601
invalid_request problemJSON-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.

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.

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.

[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"

Other interfaces

  • HTTP: raw transaction and bundle routes, health and tip floor
  • QUIC: connection settings, stream framing and reply codes
  • Payload envelope: the payload shared by raw interfaces