Documentation

QUIC

The SWQoS QUIC protocol, with connection setup, client-certificate keys, channels, reply frames and codes.

// 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.

QUIC carries the same transactions, bundles and payment rules as HTTP over long-lived connections. Each request is a stream, so a client opens a connection once and keeps it.

Connect

SettingValue
AddressUDP port 443 of a metro host or fra.tpu.supanode.xyz
ALPNzerocopy-swqos/1
TLS1.3 only
Server certificatePublicly trusted, valid for the Supanode hostname you connect to. Verify it against the hostname you connect to.
Client certificateRequired. Any certificate whose first subject common name is your API key. A self-signed certificate works; the chain is not validated.
Idle timeout30 seconds. The server sends no keep-alives, so configure your client to send them.
StreamsAt most 64 bidirectional and 64 unidirectional streams open at once per connection.
HandshakeMust complete within 3 seconds.

A missing, unknown, revoked or paused key closes the connection with application code 8. If the key is revoked or paused after connection, a stream request receives unauthorized or key_paused before the connection closes.

Send the hostname you connect to as TLS SNI. An unknown or removed hostname closes the connection with application code 4 and reason text unknown host. After a server refresh removes a domain, existing connections and resumed TLS sessions cannot keep using it.

Close codeReason textMeaning
0shutdownThe server is shutting down. Reconnect.
1connection limitA connection limit was reached. Keep at most 32 open connections per key at one edge.
4unknown hostThe hostname is unknown or has been removed. Use a current endpoint.
8unauthorizedNo client certificate, or the key in it is missing, unknown or revoked.
8key_pausedThe key in the client certificate is paused. It works again once resumed.

Channels

A QUIC connection carries three kinds of request, each on its own stream. Every request body is a payload: a bare transaction or an envelope.

ChannelRequestReplyPreflight
Unidirectional streamOne payload, up to 16,403 bytes, then the end of the stream.NoneNo
Bidirectional stream, kind 0x01[0x01][flags][payload], a transaction.Transaction frameFlag 0x01
Bidirectional stream, kind 0x03[0x03][payload], a bundle envelope with flag 0x02.Bundle frameNo

The server reads each stream to its end, so finish your sending side after the request. The whole request must arrive within 2 seconds of the stream opening, or the server drops it without a reply.

A unidirectional stream gets no answer, and a refusal on it is dropped silently. A transaction sent that way counts against your send rate even when it is then refused. Use a bidirectional stream when you need the outcome.

On a kind 0x01 stream, the flags byte after the kind is 0x00, or 0x01 to run a preflight simulation at processed commitment. No other bits may be set. After the kind byte, the stream may carry up to 16,404 bytes: one flags byte and a payload of up to 16,403 bytes. A bundle payload on this stream is refused as malformed with problem expected_transaction, and a single transaction on a kind 0x03 stream with problem expected_bundle.

Other kind bytes are reserved; do not open streams with them. A stream that starts with an unrecognized byte is refused as malformed, problem invalid_stream_kind, and ends without a reply.

Reply frames

The server writes one frame and finishes the stream.

FrameLayout
Transaction[0x01][code: u8][detail length: u16 LE][detail]
Bundle[0x03][code: u8][bundle id: 32 bytes][detail length: u16 LE][detail]

An accepted request has code 0 and an empty detail. An accepted bundle's frame carries its bundle ID as 32 raw bytes; a refused bundle's ID is all zeros. The detail of a refusal is the UTF-8 JSON rejection, the same object /binary returns: reason, its fields, message, retryable and optional docs. Hosted responses on Supanode domains omit docs. A failed simulation whose detail would exceed 65,535 bytes is shortened to err and the first 1,024 bytes of error.

Accepted transaction   01 00 00 00
Refused transaction    01 03 LL LL {"reason":"missing_tip",...}
Accepted bundle        03 00 ID...(32 bytes) 00 00

Reply codes

A code groups reasons. Read reason in the detail for the exact cause.

CodeNameReasons
0Acceptednone
1RateLimitedrate_limited
2Unsignedunsigned
3MissingTipmissing_tip, credit_exhausted
4Malformedmalformed, invalid_request, unsupported for tip_floor or partner_declared_tips
5TooLargetoo_large
6ForwardFailedforward_failed
7SignatureCountsignature_count
8Unauthorizedunauthorized, key_paused
9Simulationsimulation_failed
10BundleInvalidbundle_size, bundle_control, unsupported for bundles or declared_tips
11NotReadynot_ready, overloaded
12Internalpreflight_unavailable, internal
13PaymentRequiredpayment_required

Example

These clients send one signed transaction on a kind 0x01 stream and print the reply. Each reads the key from SWQOS_API_KEY and the transaction's wire bytes from the file named on the command line. Rust uses quinn; Go uses quic-go in the example project's module. TypeScript uses native node:quic and requires Node.js 26.6 or later built with QUIC support, with --experimental-quic enabled. It does not run in Bun or browsers.

[package]
name = "swqos-quic-example"
version = "0.1.0"
edition = "2024"

[dependencies]
quinn = { version = "0.11", default-features = false, features = ["runtime-tokio", "rustls-ring"] }
rcgen = "0.14"
rustls = { version = "0.23", default-features = false, features = ["std", "ring"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread", "net"] }
webpki-roots = "1"

For TypeScript, create the client certificate once with OpenSSL. Keep both files private. Its first common name must match SWQOS_API_KEY; the program checks that before connecting. Node verifies the hosted certificate chain and hostname.

umask 077
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
  -keyout client-key.pem -out client-cert.pem -days 1 \
  -subj "/CN=${SWQOS_API_KEY:?set SWQOS_API_KEY}"
node --experimental-quic quic-send.ts signed-transaction.bin