JSON-RPC reference
Shared SWQoS JSON-RPC endpoint, authentication, request and response conventions, status codes and client examples
// updated 2026-11-17
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:
| 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.
{"jsonrpc":"2.0","id":1,"method":"getHealth"}
Methods
| Method | Params | Result |
|---|---|---|
sendTransaction | [transaction, options?] | Base58 signature string |
sendBundle | [[transaction, ...], options?] | 64 character hex bundle ID |
getTipFloor | none | Array of zero or one tip floor objects |
getHealth | none | "ok" |
getSlot | 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:
{"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
}
| 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 |
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 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, key_paused | 401 | -32000 |
rate_limited | 429 | -32001 |
simulation_failed | 200 | -32002 |
payment_required | 402 | -32003 |
not_ready, overloaded, forward_failed, preflight_unavailable, internal | 503 | -32603 |
malformed, too_large, unsigned, signature_count, missing_tip, credit_exhausted, bundle_size, bundle_control | 200 | -32602 |
invalid_request | 200 | by problem, below |
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.
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_ERRORcarrying onlystatusCodeand headers. Kit does not read the body, soreason,retry_after_msandunpaid_lamportsare lost. - A
simulation_failedrefusal 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.reasonor 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