Documentation

sendBundle

Submit one to four signed transactions as one bundle for delivery through block engines.

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

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

Request body (application/json)

One JSON object using the shared request conventions. Submit one to four fully signed transactions in execution order, each with a distinct first signature. Each member must meet the size limits; the bundle must satisfy the tip and rate rules. Bundles have no preflight simulation.

Control accounts

SWQoS recognizes these base58 address prefixes among a transaction's static keys:

ControlRecognized when
jitodontfrontAny static account address starts with it, or the first account of the first Compute Budget instruction starts with it
dontfrontThe first account of the first Compute Budget instruction starts with it
dontbund1eThe first account of the first Compute Budget instruction starts with it

A transaction carrying any recognized control must be first, and at most one member may carry controls. With dontbund1e, later members may call only the System, Compute Budget and Memo programs.

A violation returns bundle_control with a zero based index and a rule of first_only, one_only or default_programs_only. Controls can narrow which engines can accept the bundle and raise the minimum tip. SWQoS checks them at admission only; they do not govern transactions submitted outside your bundle.

FieldTypeRequiredDescription
jsonrpc"2.0"yes
idstring or number or nullnoOptional request id, echoed exactly in the response. Null when absent or refused before the id could be read.
method"sendBundle"yes
paramsarrayyesThe array of transactions followed by optional options. minItems: 1. maxItems: 2.
params[0]array of stringyesOne to four fully signed wire transactions in execution order, with a distinct first signature per member. minItems: 1. maxItems: 4.
params[1]objectnoOptional. Other fields, including skipPreflight, are ignored. Bundles are never simulated.
params[1].encoding"base58" or "base64"noEncoding used for every transaction of the bundle. Default "base58".
params[1].tipintegernoOne declared tip in lamports for the whole bundle. Used when the bundle's own tips are below your minimum and your key may declare tips. Partner keys reject this option even when the bundle already pays a tip. minimum: 0.
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sendBundle",
  "params": [
    [
      "SIGNED_TRANSACTION_1",
      "SIGNED_TRANSACTION_2"
    ],
    {
      "encoding": "base64"
    }
  ]
}

Responses

200

Returns a 64 character lowercase hex bundle ID after accepting the bundle for delivery. Confirm each signature through your Solana RPC provider. SWQoS has no bundle status method, and its bundle ID cannot query a block engine's status.

Refusals with HTTP 200, by error.data.reason:

  • invalid_request: invalid call.
  • bundle_size: outside 1 to 4 transactions; count and limit.
  • malformed: invalid member, repeated signature (duplicate_signature), tip sum overflow (tip_overflow) or paid tip above 2 SOL (tip_too_large); index identifies a repeated or invalid member.
  • too_large: member exceeds a size limit; index identifies it.
  • unsigned: member is unsigned; index identifies it.
  • signature_count: member signature mismatch; index identifies it.
  • bundle_control: control account rule broken; index and rule.
  • missing_tip: below your or the engine minimum; minimum applies.
  • credit_exhausted: declared tip credit unavailable.

Content type: application/json

FieldTypeRequiredDescription
jsonrpc"2.0"yes
resultstringyesSHA-256 of the members' first signatures, concatenated in order as raw 64-byte values. Not a block engine's status id. minLength: 64. maxLength: 64. pattern: "^[0-9a-f]{64}$".
idstring or number or nullyesOptional request id, echoed exactly in the response. Null when absent or refused before the id could be read.
jsonrpc"2.0"yes
errorobjectyes
error.code-32700 or -32600 or -32601 or -32602 or -32603 or -32000 or -32001 or -32002 or -32003yesStatus codes maps reasons and problems to codes. Match on data.reason.
error.messagestringyesThe same sentence as data.message.
error.dataobjectyesReason-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.
error.data.reasonstringyesStable snake_case reason. Match on this; message wording can change, and the numeric codes are shared with Solana's RPC.
error.data.messagestringyesWhat happened and what to change. Wording can change.
error.data.retryablebooleanyesWhether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired.
error.data.docsstring (uri)noOptional error documentation URL followed by the reason anchor. Supanode endpoints omit this field.
idstring or number or nullyesOptional request id, echoed exactly in the response. Null when absent or refused before the id could be read.
{
  "jsonrpc": "2.0",
  "result": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "id": 1
}
{
  "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
}
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Submit between one and four transactions.",
    "data": {
      "reason": "bundle_size",
      "count": 0,
      "limit": 4,
      "message": "Submit between one and four transactions.",
      "retryable": false
    }
  },
  "id": 1
}

401

unauthorized: missing, unknown or revoked API key.

Content type: application/json

FieldTypeRequiredDescription
jsonrpc"2.0"yes
errorobjectyes
error.code-32700 or -32600 or -32601 or -32602 or -32603 or -32000 or -32001 or -32002 or -32003yesStatus codes maps reasons and problems to codes. Match on data.reason.
error.messagestringyesThe same sentence as data.message.
error.dataobjectyesReason-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.
error.data.reasonstringyesStable snake_case reason. Match on this; message wording can change, and the numeric codes are shared with Solana's RPC.
error.data.messagestringyesWhat happened and what to change. Wording can change.
error.data.retryablebooleanyesWhether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired.
error.data.docsstring (uri)noOptional error documentation URL followed by the reason anchor. Supanode endpoints omit this field.
idstring or number or nullyesOptional request id, echoed exactly in the response. Null when absent or refused before the id could be read.
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "API key missing or not recognized; pass it as the api-key query parameter, an x-api-key header or Authorization: Bearer",
    "data": {
      "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
    }
  },
  "id": null
}

402

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

Content type: application/json

FieldTypeRequiredDescription
jsonrpc"2.0"yes
errorobjectyes
error.code-32700 or -32600 or -32601 or -32602 or -32603 or -32000 or -32001 or -32002 or -32003yesStatus codes maps reasons and problems to codes. Match on data.reason.
error.messagestringyesThe same sentence as data.message.
error.dataobjectyesReason-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.
error.data.reasonstringyesStable snake_case reason. Match on this; message wording can change, and the numeric codes are shared with Solana's RPC.
error.data.messagestringyesWhat happened and what to change. Wording can change.
error.data.retryablebooleanyesWhether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired.
error.data.docsstring (uri)noOptional error documentation URL followed by the reason anchor. Supanode endpoints omit this field.
idstring or number or nullyesOptional request id, echoed exactly in the response. Null when absent or refused before the id could be read.
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32003,
    "message": "The key is suspended until its overdue invoice is paid.",
    "data": {
      "reason": "payment_required",
      "unpaid_lamports": 1000000,
      "message": "The key is suspended until its overdue invoice is paid.",
      "retryable": false
    }
  },
  "id": 1
}

403

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

Content type: application/json

FieldTypeRequiredDescription
jsonrpc"2.0"yes
errorobjectyes
error.code-32700 or -32600 or -32601 or -32602 or -32603 or -32000 or -32001 or -32002 or -32003yesStatus codes maps reasons and problems to codes. Match on data.reason.
error.messagestringyesThe same sentence as data.message.
error.dataobjectyesReason-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.
error.data.reasonstringyesStable snake_case reason. Match on this; message wording can change, and the numeric codes are shared with Solana's RPC.
error.data.messagestringyesWhat happened and what to change. Wording can change.
error.data.retryablebooleanyesWhether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired.
error.data.docsstring (uri)noOptional error documentation URL followed by the reason anchor. Supanode endpoints omit this field.
idstring or number or nullyesOptional request id, echoed exactly in the response. Null when absent or refused before the id could be read.
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "bundles are not enabled for this key; ask Supanode to enable them",
    "data": {
      "reason": "unsupported",
      "feature": "bundles",
      "message": "bundles are not enabled for this key; ask Supanode to enable them",
      "retryable": false
    }
  },
  "id": 1
}
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "declared tips are not available for this key; send an on-chain tip to a Supanode tip account",
    "data": {
      "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
    }
  },
  "id": 1
}

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: limit: bundles; over your key's bundle rate. Wait for retry_after_ms when supplied. If the edge cannot take another bundle, it returns this reason without per_second or retry_after_ms.

Content type: application/json

FieldTypeRequiredDescription
jsonrpc"2.0"yes
errorobjectyes
error.code-32700 or -32600 or -32601 or -32602 or -32603 or -32000 or -32001 or -32002 or -32003yesStatus codes maps reasons and problems to codes. Match on data.reason.
error.messagestringyesThe same sentence as data.message.
error.dataobjectyesReason-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.
error.data.reasonstringyesStable snake_case reason. Match on this; message wording can change, and the numeric codes are shared with Solana's RPC.
error.data.messagestringyesWhat happened and what to change. Wording can change.
error.data.retryablebooleanyesWhether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired.
error.data.docsstring (uri)noOptional error documentation URL followed by the reason anchor. Supanode endpoints omit this field.
idstring or number or nullyesOptional request id, echoed exactly in the response. Null when absent or refused before the id could be read.
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "rate limited: too many bundles from this key; retry shortly",
    "data": {
      "reason": "rate_limited",
      "limit": "bundles",
      "message": "rate limited: too many bundles from this key; retry shortly",
      "retryable": true
    }
  },
  "id": 1
}

503

Wait and retry while the signed transactions remain valid. Do not submit members separately if they must execute together.

  • not_ready: waiting for block_engine, blockhash, tip_vaults or declared_tips.
  • overloaded: edge temporarily busy.

Content type: application/json

FieldTypeRequiredDescription
jsonrpc"2.0"yes
errorobjectyes
error.code-32700 or -32600 or -32601 or -32602 or -32603 or -32000 or -32001 or -32002 or -32003yesStatus codes maps reasons and problems to codes. Match on data.reason.
error.messagestringyesThe same sentence as data.message.
error.dataobjectyesReason-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.
error.data.reasonstringyesStable snake_case reason. Match on this; message wording can change, and the numeric codes are shared with Solana's RPC.
error.data.messagestringyesWhat happened and what to change. Wording can change.
error.data.retryablebooleanyesWhether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired.
error.data.docsstring (uri)noOptional error documentation URL followed by the reason anchor. Supanode endpoints omit this field.
idstring or number or nullyesOptional request id, echoed exactly in the response. Null when absent or refused before the id could be read.
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32603,
    "message": "No block engine can take bundles right now; retry while the signed transactions remain valid.",
    "data": {
      "reason": "not_ready",
      "waiting_for": "block_engine",
      "message": "No block engine can take bundles right now; retry while the signed transactions remain valid.",
      "retryable": true
    }
  },
  "id": 1
}

Code samples

// Builds on the example project (/reference/json-rpc#example-project).
use base64::{Engine, prelude::BASE64_STANDARD};
use serde_json::json;
use swqos_examples::swqos::{Result, SwqosError, call};

#[tokio::main]
async fn main() -> Result<()> {
    let mut transactions = Vec::new();
    for file in std::env::args().skip(1) {
        transactions.push(BASE64_STANDARD.encode(tokio::fs::read(file).await?));
    }
    match call::<String>(
        "sendBundle",
        Some(json!([transactions, { "encoding": "base64" }])),
    )
    .await
    {
        Ok(bundle_id) => println!("accepted {bundle_id}"),
        Err(error) => {
            let rejection = error
                .downcast_ref::<SwqosError>()
                .and_then(|error| error.rejection.as_ref());
            if let Some(rejection) = rejection {
                eprintln!("{} {}", rejection.reason, rejection.message);
            } else {
                return Err(error);
            }
        }
    }
    Ok(())
}
// Builds on the example project (/reference/json-rpc#example-project).
use std::fmt::Write;

use sha2::{Digest, Sha256};
use solana_transaction::versioned::VersionedTransaction;

use crate::swqos::Result;

pub fn bundle_id(wire_transactions: &[Vec<u8>]) -> Result<String> {
    let mut hash = Sha256::new();
    for wire in wire_transactions {
        let transaction: VersionedTransaction = wincode::deserialize(wire)?;
        let signature = transaction
            .signatures
            .first()
            .ok_or("transaction has no signature")?;
        hash.update(signature.as_ref());
    }
    let mut id = String::with_capacity(64);
    for byte in hash.finalize() {
        write!(&mut id, "{byte:02x}")?;
    }
    Ok(id)
}
// Builds on the example project (/reference/json-rpc#example-project).
package swqos

import (
	"context"
	"encoding/base64"
	"errors"
	"fmt"
	"os"
)

func SendBundle(ctx context.Context) error {
	transactions := make([]string, 0, len(os.Args)-1)
	for _, file := range os.Args[1:] {
		wire, err := os.ReadFile(file)
		if err != nil {
			return err
		}
		transactions = append(transactions, base64.StdEncoding.EncodeToString(wire))
	}
	bundleID, err := Call[string](ctx, "sendBundle", transactions, map[string]any{"encoding": "base64"})
	if err != nil {
		var refusal *SwqosError
		if !errors.As(err, &refusal) || refusal.Rejection == nil {
			return err
		}
		fmt.Fprintln(os.Stderr, refusal.Rejection.Reason, refusal.Rejection.Message)
		return nil
	}
	fmt.Println("accepted", bundleID)
	return nil
}
package swqos

import (
	"crypto/sha256"
	"encoding/hex"
	"errors"

	"github.com/gagliardetto/solana-go"
)

func BundleID(wireTransactions [][]byte) (string, error) {
	hash := sha256.New()
	for _, wire := range wireTransactions {
		transaction, err := solana.TransactionFromBytes(wire)
		if err != nil {
			return "", err
		}
		if len(transaction.Signatures) == 0 {
			return "", errors.New("transaction has no first signature")
		}
		_, _ = hash.Write(transaction.Signatures[0][:])
	}
	return hex.EncodeToString(hash.Sum(nil)), nil
}
import { createHash } from 'node:crypto'
import {
  getBase58Encoder,
  getSignatureFromTransaction,
  getTransactionDecoder,
} from '@solana/kit'

export function bundleId(wireTransactions: Uint8Array[]): string {
  const hash = createHash('sha256')
  for (const wire of wireTransactions) {
    const signature = getSignatureFromTransaction(getTransactionDecoder().decode(wire))
    hash.update(Uint8Array.from(getBase58Encoder().encode(signature)))
  }
  return hash.digest('hex')
}
// Builds on the example project (/reference/json-rpc#example-project).
import { readFile } from 'node:fs/promises'
import { call, SwqosError } from './swqos.ts'

const files = process.argv.slice(2)
const transactions = await Promise.all(
  files.map(async (file) => (await readFile(file)).toString('base64')),
)

try {
  const bundleId = await call<string>('sendBundle', [transactions, { encoding: 'base64' }])
  console.log('accepted', bundleId)
} catch (error) {
  if (!(error instanceof SwqosError) || !error.rejection) throw error
  console.error(error.rejection.reason, error.rejection.message)
}