QUIC
The SWQoS QUIC protocol, with connection setup, client-certificate keys, channels, reply frames and codes.
// 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.
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
| Setting | Value |
|---|---|
| Address | UDP port 443 of a metro host or fra.tpu.supanode.xyz |
| ALPN | zerocopy-swqos/1 |
| TLS | 1.3 only |
| Server certificate | Publicly trusted, valid for the Supanode hostname you connect to. Verify it against the hostname you connect to. |
| Client certificate | Required. Any certificate whose first subject common name is your API key. A self-signed certificate works; the chain is not validated. |
| Idle timeout | 30 seconds. The server sends no keep-alives, so configure your client to send them. |
| Streams | At most 64 bidirectional and 64 unidirectional streams open at once per connection. |
| Handshake | Must 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 code | Reason text | Meaning |
|---|---|---|
| 0 | shutdown | The server is shutting down. Reconnect. |
| 1 | connection limit | A connection limit was reached. Keep at most 32 open connections per key at one edge. |
| 4 | unknown host | The hostname is unknown or has been removed. Use a current endpoint. |
| 8 | unauthorized | No client certificate, or the key in it is missing, unknown or revoked. |
| 8 | key_paused | The 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.
| Channel | Request | Reply | Preflight |
|---|---|---|---|
| Unidirectional stream | One payload, up to 16,403 bytes, then the end of the stream. | None | No |
Bidirectional stream, kind 0x01 | [0x01][flags][payload], a transaction. | Transaction frame | Flag 0x01 |
Bidirectional stream, kind 0x03 | [0x03][payload], a bundle envelope with flag 0x02. | Bundle frame | No |
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.
| Frame | Layout |
|---|---|
| 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.
| Code | Name | Reasons |
|---|---|---|
| 0 | Accepted | none |
| 1 | RateLimited | rate_limited |
| 2 | Unsigned | unsigned |
| 3 | MissingTip | missing_tip, credit_exhausted |
| 4 | Malformed | malformed, invalid_request, unsupported for tip_floor or partner_declared_tips |
| 5 | TooLarge | too_large |
| 6 | ForwardFailed | forward_failed |
| 7 | SignatureCount | signature_count |
| 8 | Unauthorized | unauthorized, key_paused |
| 9 | Simulation | simulation_failed |
| 10 | BundleInvalid | bundle_size, bundle_control, unsupported for bundles or declared_tips |
| 11 | NotReady | not_ready, overloaded |
| 12 | Internal | preflight_unavailable, internal |
| 13 | PaymentRequired | payment_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