Documentation

Send raw bytes

Send a signed transaction or bundle as raw payload bytes over HTTP, with an optional declared tip.

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

POST https://fra.tpu.supanode.xyz/binary

Authentication: API key, one of: x-api-key header, api-key query, Authorization: Bearer header.

Request body (application/octet-stream)

One signed transaction or a payload envelope with a declared tip or bundle. Maximum body 16,403 bytes, received within 2 seconds. There is no encoding option or preflight simulation. The same tip, send rate and transaction rules apply as for JSON-RPC. Uses the same hosts, ports and authentication as JSON-RPC.

SIGNED_TRANSACTION_BYTES

Responses

200

Returns the transaction's first signature in base58 or the bundle ID as 64 hex characters, in plain text. Acceptance does not mean landing; confirm signatures through your Solana RPC provider.

Content type: text/plain

Base58 transaction signature or 64-character hex bundle id.

BASE58_SIGNATURE
0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

400

JSON rejection body, with the reason, its fields, message, retryable and optional docs, as in JSON-RPC error.data

Content type: application/json

Reason-specific fields are included alongside these members, such as minimum, found, declared, available, unpaid_lamports, index, per_second and retry_after_ms. Failed preflight also includes Solana simulation fields such as err, logs and unitsConsumed.

FieldTypeRequiredDescription
reasonstringyesStable snake_case reason. Match on this; message wording can change, and the numeric codes are shared with Solana's RPC.
messagestringyesWhat happened and what to change. Wording can change.
retryablebooleanyesWhether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired.
docsstring (uri)noOptional error documentation URL followed by the reason anchor. Supanode endpoints omit this field.
{
  "reason": "missing_tip",
  "minimum": 1000000,
  "found": 123,
  "message": "tip too small: the tip transfers add up to 123 lamports, the minimum is 1,000,000; raise the transfer to one of the tip accounts to at least 1,000,000 lamports",
  "retryable": false
}

401

unauthorized: missing, unknown or revoked API key.

Content type: application/json

Reason-specific fields are included alongside these members, such as minimum, found, declared, available, unpaid_lamports, index, per_second and retry_after_ms. Failed preflight also includes Solana simulation fields such as err, logs and unitsConsumed.

FieldTypeRequiredDescription
reasonstringyesStable snake_case reason. Match on this; message wording can change, and the numeric codes are shared with Solana's RPC.
messagestringyesWhat happened and what to change. Wording can change.
retryablebooleanyesWhether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired.
docsstring (uri)noOptional error documentation URL followed by the reason anchor. Supanode endpoints omit this field.
{
  "reason": "unauthorized",
  "message": "API key missing or not recognized; pass it as the api-key query parameter, an x-api-key header or Authorization: Bearer",
  "retryable": false
}

402

payment_required: sending is suspended until the overdue invoice is paid; unpaid_lamports is outstanding.

Content type: application/json

Reason-specific fields are included alongside these members, such as minimum, found, declared, available, unpaid_lamports, index, per_second and retry_after_ms. Failed preflight also includes Solana simulation fields such as err, logs and unitsConsumed.

FieldTypeRequiredDescription
reasonstringyesStable snake_case reason. Match on this; message wording can change, and the numeric codes are shared with Solana's RPC.
messagestringyesWhat happened and what to change. Wording can change.
retryablebooleanyesWhether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired.
docsstring (uri)noOptional error documentation URL followed by the reason anchor. Supanode endpoints omit this field.
{
  "reason": "payment_required",
  "unpaid_lamports": 1000000,
  "message": "The key is suspended until its overdue invoice is paid.",
  "retryable": false
}

403

unsupported: feature: bundles when bundles are disabled, or feature: partner_declared_tips when a partner key declares a tip.

Content type: application/json

Reason-specific fields are included alongside these members, such as minimum, found, declared, available, unpaid_lamports, index, per_second and retry_after_ms. Failed preflight also includes Solana simulation fields such as err, logs and unitsConsumed.

FieldTypeRequiredDescription
reasonstringyesStable snake_case reason. Match on this; message wording can change, and the numeric codes are shared with Solana's RPC.
messagestringyesWhat happened and what to change. Wording can change.
retryablebooleanyesWhether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired.
docsstring (uri)noOptional error documentation URL followed by the reason anchor. Supanode endpoints omit this field.
{
  "reason": "unsupported",
  "feature": "bundles",
  "message": "bundles are not enabled for this key; ask Supanode to enable them",
  "retryable": false
}
{
  "reason": "unsupported",
  "feature": "partner_declared_tips",
  "message": "declared tips are not available for this key; send an on-chain tip to a Supanode tip account",
  "retryable": false
}

404

GET is supported only at /health and /tip_floor; methods other than GET and POST are refused. POST to another path is JSON-RPC.

Content type: application/json

Reason-specific fields are included alongside these members, such as minimum, found, declared, available, unpaid_lamports, index, per_second and retry_after_ms. Failed preflight also includes Solana simulation fields such as err, logs and unitsConsumed.

FieldTypeRequiredDescription
reasonstringyesStable snake_case reason. Match on this; message wording can change, and the numeric codes are shared with Solana's RPC.
messagestringyesWhat happened and what to change. Wording can change.
retryablebooleanyesWhether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired.
docsstring (uri)noOptional error documentation URL followed by the reason anchor. Supanode endpoints omit this field.
{
  "reason": "invalid_request",
  "problem": "not_found",
  "message": "unknown path or method: POST raw transactions to /binary, base64 to /plaintext, or JSON-RPC to any other path",
  "retryable": false
}

408

invalid_request: problem: body_timeout; the body did not arrive within 2 seconds.

Content type: application/json

Reason-specific fields are included alongside these members, such as minimum, found, declared, available, unpaid_lamports, index, per_second and retry_after_ms. Failed preflight also includes Solana simulation fields such as err, logs and unitsConsumed.

FieldTypeRequiredDescription
reasonstringyesStable snake_case reason. Match on this; message wording can change, and the numeric codes are shared with Solana's RPC.
messagestringyesWhat happened and what to change. Wording can change.
retryablebooleanyesWhether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired.
docsstring (uri)noOptional error documentation URL followed by the reason anchor. Supanode endpoints omit this field.
{
  "reason": "invalid_request",
  "problem": "body_timeout",
  "message": "the request body did not arrive within 2 seconds; retry",
  "retryable": true
}

413

too_large: request body, decoded payload or transaction exceeds a size limit.

Content type: application/json

Reason-specific fields are included alongside these members, such as minimum, found, declared, available, unpaid_lamports, index, per_second and retry_after_ms. Failed preflight also includes Solana simulation fields such as err, logs and unitsConsumed.

FieldTypeRequiredDescription
reasonstringyesStable snake_case reason. Match on this; message wording can change, and the numeric codes are shared with Solana's RPC.
messagestringyesWhat happened and what to change. Wording can change.
retryablebooleanyesWhether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired.
docsstring (uri)noOptional error documentation URL followed by the reason anchor. Supanode endpoints omit this field.
{
  "reason": "too_large",
  "limit": 16403,
  "size": 16404,
  "message": "The payload exceeds the byte limit.",
  "retryable": false
}

421

Unknown or removed TLS SNI or HTTP Host/:authority. Returns plain text without a JSON-RPC envelope or rejection object. The current hostname policy also applies to existing connections and resumed TLS sessions.

Content type: text/plain

This hostname is not served here. Check the endpoint address

429

rate_limited: over the send rate, with per_second and retry_after_ms, or, without numbers, while a request with the same signature is still being processed.

Content type: application/json

Reason-specific fields are included alongside these members, such as minimum, found, declared, available, unpaid_lamports, index, per_second and retry_after_ms. Failed preflight also includes Solana simulation fields such as err, logs and unitsConsumed.

FieldTypeRequiredDescription
reasonstringyesStable snake_case reason. Match on this; message wording can change, and the numeric codes are shared with Solana's RPC.
messagestringyesWhat happened and what to change. Wording can change.
retryablebooleanyesWhether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired.
docsstring (uri)noOptional error documentation URL followed by the reason anchor. Supanode endpoints omit this field.
{
  "reason": "rate_limited",
  "limit": "transactions",
  "message": "rate limited: too many transactions from this key; retry shortly",
  "retryable": true
}

503

JSON rejection body; submission is temporarily unavailable.

Content type: application/json

Reason-specific fields are included alongside these members, such as minimum, found, declared, available, unpaid_lamports, index, per_second and retry_after_ms. Failed preflight also includes Solana simulation fields such as err, logs and unitsConsumed.

FieldTypeRequiredDescription
reasonstringyesStable snake_case reason. Match on this; message wording can change, and the numeric codes are shared with Solana's RPC.
messagestringyesWhat happened and what to change. Wording can change.
retryablebooleanyesWhether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired.
docsstring (uri)noOptional error documentation URL followed by the reason anchor. Supanode endpoints omit this field.
{
  "reason": "not_ready",
  "waiting_for": "leader_route",
  "message": "the region is not ready to send yet; retry in a moment",
  "retryable": true
}

Code samples

// Builds on the example project (/reference/json-rpc#example-project).
// src/payload.rs
use crate::swqos::Result;

pub fn transaction_payload(transaction: &[u8], declared_tip: Option<u64>) -> Vec<u8> {
    let mut payload = Vec::with_capacity(
        transaction.len() + usize::from(declared_tip.is_some()) * 10,
    );
    if let Some(tip) = declared_tip {
        payload.extend_from_slice(&[0x00, 0x01]);
        payload.extend_from_slice(&tip.to_le_bytes());
    }
    payload.extend_from_slice(transaction);
    payload
}

pub fn bundle_payload(
    transactions: &[Vec<u8>],
    declared_tip: Option<u64>,
) -> Result<Vec<u8>> {
    if !(1..=4).contains(&transactions.len()) {
        return Err("a bundle holds 1 to 4 transactions".into());
    }
    let size = 3
        + usize::from(declared_tip.is_some()) * 8
        + transactions
            .iter()
            .map(|transaction| 2 + transaction.len())
            .sum::<usize>();
    let mut payload = Vec::with_capacity(size);
    payload
        .extend_from_slice(&[0x00, if declared_tip.is_some() { 0x03 } else { 0x02 }]);
    if let Some(tip) = declared_tip {
        payload.extend_from_slice(&tip.to_le_bytes());
    }
    payload.push(transactions.len() as u8);
    for transaction in transactions {
        payload.extend_from_slice(&(transaction.len() as u16).to_le_bytes());
        payload.extend_from_slice(transaction);
    }
    Ok(payload)
}
// Builds on the example project (/reference/json-rpc#example-project).
use swqos_examples::{
    payload::bundle_payload,
    swqos::{Result, required, url},
};

#[tokio::main]
async fn main() -> Result<()> {
    // Signed transaction files, in bundle order.
    let mut transactions = Vec::new();
    for file in std::env::args().skip(1) {
        transactions.push(tokio::fs::read(file).await?);
    }
    let response = reqwest::Client::new()
        .post(format!("{}/binary", url()))
        .header("x-api-key", required("SWQOS_API_KEY")?)
        .body(bundle_payload(&transactions, None)?)
        .send()
        .await?;
    let status = response.status();
    let body = response.text().await?;
    if status.is_success() {
        println!("bundle {body}");
    } else {
        println!("refused {}: {body}", status.as_u16());
    }
    Ok(())
}
// payload.go
package swqos

import (
	"encoding/binary"
	"errors"
)

func TransactionPayload(transaction []byte, declaredTip *uint64) []byte {
	if declaredTip == nil {
		return append([]byte(nil), transaction...)
	}
	payload := make([]byte, 10+len(transaction))
	payload[1] = 0x01
	binary.LittleEndian.PutUint64(payload[2:10], *declaredTip)
	copy(payload[10:], transaction)
	return payload
}

func BundlePayload(transactions [][]byte, declaredTip *uint64) ([]byte, error) {
	if len(transactions) < 1 || len(transactions) > 4 {
		return nil, errors.New("a bundle holds 1 to 4 transactions")
	}
	size := 3
	if declaredTip != nil {
		size += 8
	}
	for _, transaction := range transactions {
		size += 2 + len(transaction)
	}
	payload := make([]byte, size)
	payload[1] = 0x02
	offset := 2
	if declaredTip != nil {
		payload[1] = 0x03
		binary.LittleEndian.PutUint64(payload[offset:offset+8], *declaredTip)
		offset += 8
	}
	payload[offset] = byte(len(transactions))
	offset++
	for _, transaction := range transactions {
		binary.LittleEndian.PutUint16(payload[offset:offset+2], uint16(len(transaction)))
		offset += 2
		copy(payload[offset:], transaction)
		offset += len(transaction)
	}
	return payload, nil
}
// Builds on the example project (/reference/json-rpc#example-project).
package swqos

import (
	"bytes"
	"context"
	"fmt"
	"io"
	"net/http"
	"os"
)

func SendBinary(ctx context.Context) error {
	// Signed transaction files, in bundle order.
	var transactions [][]byte
	for _, file := range os.Args[1:] {
		transaction, err := os.ReadFile(file)
		if err != nil {
			return err
		}
		transactions = append(transactions, transaction)
	}
	payload, err := BundlePayload(transactions, nil)
	if err != nil {
		return err
	}
	apiKey, err := Required("SWQOS_API_KEY")
	if err != nil {
		return err
	}
	request, err := http.NewRequestWithContext(ctx, http.MethodPost, URL()+"/binary", bytes.NewReader(payload))
	if err != nil {
		return err
	}
	request.Header.Set("x-api-key", apiKey)
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		return err
	}
	defer response.Body.Close()
	body, err := io.ReadAll(response.Body)
	if err != nil {
		return err
	}
	if response.StatusCode >= 200 && response.StatusCode < 300 {
		fmt.Printf("bundle %s\n", body)
	} else {
		fmt.Printf("refused %d: %s\n", response.StatusCode, body)
	}
	return nil
}
// payload.ts
export function transactionPayload(
  transaction: Uint8Array,
  declaredTip?: bigint,
): Uint8Array<ArrayBuffer> {
  if (declaredTip === undefined) return concat([transaction])
  return concat([Uint8Array.of(0x00, 0x01), u64(declaredTip), transaction])
}

export function bundlePayload(
  transactions: Uint8Array[],
  declaredTip?: bigint,
): Uint8Array<ArrayBuffer> {
  if (transactions.length < 1 || transactions.length > 4) {
    throw new RangeError('a bundle holds 1 to 4 transactions')
  }
  const parts: Uint8Array[] = [Uint8Array.of(0x00, declaredTip === undefined ? 0x02 : 0x03)]
  if (declaredTip !== undefined) parts.push(u64(declaredTip))
  parts.push(Uint8Array.of(transactions.length))
  for (const transaction of transactions) parts.push(u16(transaction.length), transaction)
  return concat(parts)
}

function u64(value: bigint): Uint8Array<ArrayBuffer> {
  const bytes = new Uint8Array(8)
  new DataView(bytes.buffer).setBigUint64(0, value, true)
  return bytes
}

function u16(value: number): Uint8Array<ArrayBuffer> {
  const bytes = new Uint8Array(2)
  new DataView(bytes.buffer).setUint16(0, value, true)
  return bytes
}

function concat(parts: Uint8Array[]): Uint8Array<ArrayBuffer> {
  const out = new Uint8Array(parts.reduce((size, part) => size + part.length, 0))
  let offset = 0
  for (const part of parts) {
    out.set(part, offset)
    offset += part.length
  }
  return out
}
// Builds on the example project (/reference/json-rpc#example-project).
import { readFile } from 'node:fs/promises'
import { bundlePayload } from './payload.ts'
import { required, url } from './swqos.ts'

// Signed transaction files, in bundle order.
const transactions = await Promise.all(
  process.argv.slice(2).map(async (file) => new Uint8Array(await readFile(file))),
)
const response = await fetch(`${url}/binary`, {
  method: 'POST',
  headers: { 'x-api-key': required('SWQOS_API_KEY') },
  body: bundlePayload(transactions),
})
const body = await response.text()
console.log(response.ok ? `bundle ${body}` : `refused ${response.status}: ${body}`)