# sendBundle

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

<Note>
Supanode issues keys through [Telegram](https://telegram.me/supanode_tgs). 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.
</Note>

`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](https://supanode.xyz/docs/solana/sender/reference/json-rpc#request). 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](https://supanode.xyz/docs/solana/sender/tips) and [rate](https://supanode.xyz/docs/solana/sender/limits#send-rate) rules. Bundles have no preflight simulation.

### Control accounts

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

| Control | Recognized when |
| --- | --- |
| `jitodontfront` | Any static account address starts with it, or the first account of the first Compute Budget instruction starts with it |
| `dontfront` | The first account of the first Compute Budget instruction starts with it |
| `dontbund1e` | The 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`](https://supanode.xyz/docs/solana/sender/reference/errors#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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `jsonrpc` | `"2.0"` | yes |  |
| `id` | string or number or null | no | Optional request id, echoed exactly in the response. Null when absent or refused before the id could be read. |
| `method` | `"sendBundle"` | yes |  |
| `params` | array | yes | The array of transactions followed by optional options. minItems: `1`. maxItems: `2`. |
| `params[0]` | array of string | yes | One to four fully signed wire transactions in execution order, with a distinct first signature per member. minItems: `1`. maxItems: `4`. |
| `params[1]` | object | no | Optional. Other fields, including `skipPreflight`, are ignored. Bundles are never simulated. |
| `params[1].encoding` | `"base58"` or `"base64"` | no | Encoding used for every transaction of the bundle. Default `"base58"`. |
| `params[1].tip` | integer | no | One [declared tip](https://supanode.xyz/docs/solana/sender/api-keys) 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`. |

```json title="Request"
{
  "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`](https://supanode.xyz/docs/solana/sender/reference/errors#invalid_request): invalid call.
- [`bundle_size`](https://supanode.xyz/docs/solana/sender/reference/errors#bundle_size): outside 1 to 4 transactions; `count` and `limit`.
- [`malformed`](https://supanode.xyz/docs/solana/sender/reference/errors#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`](https://supanode.xyz/docs/solana/sender/reference/errors#too_large): member exceeds a size limit; `index` identifies it.
- [`unsigned`](https://supanode.xyz/docs/solana/sender/reference/errors#unsigned): member is unsigned; `index` identifies it.
- [`signature_count`](https://supanode.xyz/docs/solana/sender/reference/errors#signature_count): member signature mismatch; `index` identifies it.
- [`bundle_control`](https://supanode.xyz/docs/solana/sender/reference/errors#bundle_control): control account rule broken; `index` and `rule`.
- [`missing_tip`](https://supanode.xyz/docs/solana/sender/reference/errors#missing_tip): below your or the engine minimum; `minimum` applies.
- [`credit_exhausted`](https://supanode.xyz/docs/solana/sender/reference/errors#credit_exhausted): declared tip credit unavailable.

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `jsonrpc` | `"2.0"` | yes |  |
| `result` | string | yes | SHA-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}$"`. |
| `id` | string or number or null | yes | Optional request id, echoed exactly in the response. Null when absent or refused before the id could be read. |
| `jsonrpc` | `"2.0"` | yes |  |
| `error` | object | yes |  |
| `error.code` | `-32700` or `-32600` or `-32601` or `-32602` or `-32603` or `-32000` or `-32001` or `-32002` or `-32003` | yes | [Status codes](https://supanode.xyz/docs/solana/sender/reference/json-rpc#status-codes) maps reasons and problems to codes. Match on `data.reason`. |
| `error.message` | string | yes | The same sentence as data.message. |
| `error.data` | object | yes | 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. |
| `error.data.reason` | string | yes | Stable snake_case reason. Match on this; `message` wording can change, and the numeric codes are shared with Solana's RPC. |
| `error.data.message` | string | yes | What happened and what to change. Wording can change. |
| `error.data.retryable` | boolean | yes | Whether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired. |
| `error.data.docs` | string (uri) | no | Optional error documentation URL followed by the reason anchor. Supanode endpoints omit this field. |
| `id` | string or number or null | yes | Optional request id, echoed exactly in the response. Null when absent or refused before the id could be read. |

```json title="Success"
{
  "jsonrpc": "2.0",
  "result": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "id": 1
}
```

```json title="Missing tip"
{
  "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
}
```

```json title="Bundle size"
{
  "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`](https://supanode.xyz/docs/solana/sender/reference/errors#unauthorized): missing, unknown or revoked API key.

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `jsonrpc` | `"2.0"` | yes |  |
| `error` | object | yes |  |
| `error.code` | `-32700` or `-32600` or `-32601` or `-32602` or `-32603` or `-32000` or `-32001` or `-32002` or `-32003` | yes | [Status codes](https://supanode.xyz/docs/solana/sender/reference/json-rpc#status-codes) maps reasons and problems to codes. Match on `data.reason`. |
| `error.message` | string | yes | The same sentence as data.message. |
| `error.data` | object | yes | 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. |
| `error.data.reason` | string | yes | Stable snake_case reason. Match on this; `message` wording can change, and the numeric codes are shared with Solana's RPC. |
| `error.data.message` | string | yes | What happened and what to change. Wording can change. |
| `error.data.retryable` | boolean | yes | Whether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired. |
| `error.data.docs` | string (uri) | no | Optional error documentation URL followed by the reason anchor. Supanode endpoints omit this field. |
| `id` | string or number or null | yes | Optional request id, echoed exactly in the response. Null when absent or refused before the id could be read. |

```json title="unauthorized"
{
  "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`](https://supanode.xyz/docs/solana/sender/reference/errors#payment_required): sending is suspended until the overdue invoice is paid; `unpaid_lamports` is outstanding.

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `jsonrpc` | `"2.0"` | yes |  |
| `error` | object | yes |  |
| `error.code` | `-32700` or `-32600` or `-32601` or `-32602` or `-32603` or `-32000` or `-32001` or `-32002` or `-32003` | yes | [Status codes](https://supanode.xyz/docs/solana/sender/reference/json-rpc#status-codes) maps reasons and problems to codes. Match on `data.reason`. |
| `error.message` | string | yes | The same sentence as data.message. |
| `error.data` | object | yes | 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. |
| `error.data.reason` | string | yes | Stable snake_case reason. Match on this; `message` wording can change, and the numeric codes are shared with Solana's RPC. |
| `error.data.message` | string | yes | What happened and what to change. Wording can change. |
| `error.data.retryable` | boolean | yes | Whether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired. |
| `error.data.docs` | string (uri) | no | Optional error documentation URL followed by the reason anchor. Supanode endpoints omit this field. |
| `id` | string or number or null | yes | Optional request id, echoed exactly in the response. Null when absent or refused before the id could be read. |

```json title="payment_required"
{
  "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`](https://supanode.xyz/docs/solana/sender/reference/errors#unsupported): `feature: bundles` when bundles are disabled, or `feature: partner_declared_tips` when a partner key declares a tip.

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `jsonrpc` | `"2.0"` | yes |  |
| `error` | object | yes |  |
| `error.code` | `-32700` or `-32600` or `-32601` or `-32602` or `-32603` or `-32000` or `-32001` or `-32002` or `-32003` | yes | [Status codes](https://supanode.xyz/docs/solana/sender/reference/json-rpc#status-codes) maps reasons and problems to codes. Match on `data.reason`. |
| `error.message` | string | yes | The same sentence as data.message. |
| `error.data` | object | yes | 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. |
| `error.data.reason` | string | yes | Stable snake_case reason. Match on this; `message` wording can change, and the numeric codes are shared with Solana's RPC. |
| `error.data.message` | string | yes | What happened and what to change. Wording can change. |
| `error.data.retryable` | boolean | yes | Whether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired. |
| `error.data.docs` | string (uri) | no | Optional error documentation URL followed by the reason anchor. Supanode endpoints omit this field. |
| `id` | string or number or null | yes | Optional request id, echoed exactly in the response. Null when absent or refused before the id could be read. |

```json title="unsupported"
{
  "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
}
```

```json title="partner_declared_tips"
{
  "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`

```text title="UnknownHost"
This hostname is not served here. Check the endpoint address
```

### 429

[`rate_limited`](https://supanode.xyz/docs/solana/sender/reference/errors#rate_limited): `limit: bundles`; over your key's [bundle rate](https://supanode.xyz/docs/solana/sender/bundles#rates). 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`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `jsonrpc` | `"2.0"` | yes |  |
| `error` | object | yes |  |
| `error.code` | `-32700` or `-32600` or `-32601` or `-32602` or `-32603` or `-32000` or `-32001` or `-32002` or `-32003` | yes | [Status codes](https://supanode.xyz/docs/solana/sender/reference/json-rpc#status-codes) maps reasons and problems to codes. Match on `data.reason`. |
| `error.message` | string | yes | The same sentence as data.message. |
| `error.data` | object | yes | 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. |
| `error.data.reason` | string | yes | Stable snake_case reason. Match on this; `message` wording can change, and the numeric codes are shared with Solana's RPC. |
| `error.data.message` | string | yes | What happened and what to change. Wording can change. |
| `error.data.retryable` | boolean | yes | Whether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired. |
| `error.data.docs` | string (uri) | no | Optional error documentation URL followed by the reason anchor. Supanode endpoints omit this field. |
| `id` | string or number or null | yes | Optional request id, echoed exactly in the response. Null when absent or refused before the id could be read. |

```json title="rate_limited"
{
  "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`](https://supanode.xyz/docs/solana/sender/reference/errors#not_ready): waiting for `block_engine`, `blockhash`, `tip_vaults` or `declared_tips`.
- [`overloaded`](https://supanode.xyz/docs/solana/sender/reference/errors#overloaded): edge temporarily busy.

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `jsonrpc` | `"2.0"` | yes |  |
| `error` | object | yes |  |
| `error.code` | `-32700` or `-32600` or `-32601` or `-32602` or `-32603` or `-32000` or `-32001` or `-32002` or `-32003` | yes | [Status codes](https://supanode.xyz/docs/solana/sender/reference/json-rpc#status-codes) maps reasons and problems to codes. Match on `data.reason`. |
| `error.message` | string | yes | The same sentence as data.message. |
| `error.data` | object | yes | 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. |
| `error.data.reason` | string | yes | Stable snake_case reason. Match on this; `message` wording can change, and the numeric codes are shared with Solana's RPC. |
| `error.data.message` | string | yes | What happened and what to change. Wording can change. |
| `error.data.retryable` | boolean | yes | Whether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired. |
| `error.data.docs` | string (uri) | no | Optional error documentation URL followed by the reason anchor. Supanode endpoints omit this field. |
| `id` | string or number or null | yes | Optional request id, echoed exactly in the response. Null when absent or refused before the id could be read. |

```json title="not_ready"
{
  "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

```rust title="Rust"
// 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(())
}
```

```rust title="Rust (bundle ID)"
// 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)
}
```

```go title="Go"
// 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
}
```

```go title="Go (bundle ID)"
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
}
```

```ts title="TypeScript (bundle ID)"
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')
}
```

```ts title="TypeScript"
// 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)
}
```
