sendTransaction
Submit one signed transaction with sendTransaction, choose encoding and preflight options, and handle refusals.
// 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.
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. The transaction must meet the size limits and your key's tip requirement; each submission counts against the send rate. Read the blockhash from your Solana RPC provider.
| 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 | "sendTransaction" | yes | |
params | array | yes | The signed transaction followed by optional options. minItems: 1. maxItems: 2. |
params[0] | string | yes | One fully signed wire transaction: base58 allows 1,683 characters and 1,232 bytes for any version; base64 allows 1,644 characters and 1,232 bytes for legacy or v0, or 5,464 characters and 4,096 bytes for v1. A v1 transaction over 1,232 bytes needs base64 here, or raw bytes through /binary or QUIC; see Transactions. maxLength: 5464. |
params[1] | object | no | Optional. Fields not listed are ignored. A listed field of the wrong type is refused as invalid_request, problem invalid_options. |
params[1].encoding | "base58" or "base64" | no | Transaction encoding. Any other value is refused as malformed, problem unknown_encoding. Default "base58". |
params[1].skipPreflight | boolean | no | false simulates on Supanode's RPC infrastructure provider before sending. Solana RPC defaults to false; SWQoS does not. Default true. |
params[1].preflightCommitment | "processed" or "confirmed" or "finalized" | no | Read only when skipPreflight is false. Default "finalized". |
params[1].minContextSlot | integer | no | Passed to simulation. Read only when skipPreflight is false. minimum: 0. |
params[1].maxRetries | integer | no | Accepted and ignored. SWQoS does not periodically resubmit. minimum: 0. |
params[1].tip | integer | no | A declared tip in lamports. Used when the transaction's own tip is below your minimum and your key may declare tips. Partner keys reject this option even when the transaction already pays a tip. minimum: 0. |
{
"jsonrpc": "2.0",
"id": 1,
"method": "sendTransaction",
"params": [
"SIGNED_TRANSACTION",
{
"encoding": "base64"
}
]
}
{
"jsonrpc": "2.0",
"id": 1,
"method": "sendTransaction",
"params": [
"SIGNED_TRANSACTION",
{
"encoding": "base64",
"skipPreflight": false,
"preflightCommitment": "confirmed"
}
]
}
{
"jsonrpc": "2.0",
"id": 1,
"method": "sendTransaction",
"params": [
"SIGNED_TRANSACTION",
{
"encoding": "base64",
"tip": 1000000
}
]
}
Responses
200
Returns the transaction's first signature in base58. Confirm landing through your Solana RPC provider. A duplicate can return the same signature without being sent again.
Refusals with HTTP 200, by error.data.reason:
invalid_request: invalid call;problemnames the cause.malformed: invalid transaction, tip sum overflow (tip_overflow) or paid tip above 2 SOL (tip_too_large);problemnames the cause.too_large: size limit exceeded;limitandsizeare bytes.unsigned: first signature is all zeros.signature_count: signatures do not match required signers.missing_tip: tip below the minimum without a usable declaration.credit_exhausted: declared tip credit unavailable.simulation_failed: preflight returned an error; Solana's fields are indata.
Content type: application/json
| Field | Type | Required | Description |
|---|---|---|---|
jsonrpc | "2.0" | yes | |
result | string | yes | The base58 encoding of the transaction's first signature. |
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 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. |
{
"jsonrpc": "2.0",
"result": "BASE58_SIGNATURE",
"id": 1
}
{
"jsonrpc": "2.0",
"error": {
"code": -32700,
"message": "the body is not valid JSON",
"data": {
"reason": "invalid_request",
"problem": "parse_error",
"message": "the body is not valid JSON",
"retryable": false
}
},
"id": null
}
{
"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
}
401
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 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. |
{
"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
| 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 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. |
{
"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: partner_declared_tips; remove the declaration and send an on-chain tip to a Supanode tip account.
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 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. |
{
"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: 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
| 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 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. |
{
"jsonrpc": "2.0",
"error": {
"code": -32001,
"message": "rate limited: too many transactions from this key; retry shortly",
"data": {
"reason": "rate_limited",
"limit": "transactions",
"message": "rate limited: too many transactions from this key; retry shortly",
"retryable": true
}
},
"id": 1
}
503
Submission is temporarily unavailable.
not_ready: waiting fortip_vaults,declared_tipsorleader_route.preflight_unavailable: simulation unavailable.overloaded: edge temporarily busy.forward_failed: transaction could not be dispatched.internal: internal error.
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 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. |
{
"jsonrpc": "2.0",
"error": {
"code": -32603,
"message": "the region is not ready to send yet; retry in a moment",
"data": {
"reason": "not_ready",
"waiting_for": "leader_route",
"message": "the region is not ready to send yet; retry in a moment",
"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 solana_transaction::versioned::VersionedTransaction;
use swqos_examples::swqos::{Result, call, required};
#[tokio::main]
async fn main() -> Result<()> {
// A fully signed transaction in wire format, from your signing flow.
let bytes = tokio::fs::read(required("SIGNED_TX_FILE")?).await?;
let transaction: VersionedTransaction = wincode::deserialize(&bytes)?;
let signature: String = call(
"sendTransaction",
Some(json!([
BASE64_STANDARD.encode(wincode::serialize(&transaction)?),
{ "encoding": "base64" }
])),
)
.await?;
println!("{signature}");
Ok(())
}
// 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, required};
#[tokio::main]
async fn main() -> Result<()> {
let transaction =
BASE64_STANDARD.encode(tokio::fs::read(required("SIGNED_TX_FILE")?).await?);
match call::<String>(
"sendTransaction",
Some(json!([
transaction,
{ "encoding": "base64", "skipPreflight": false, "preflightCommitment": "confirmed" }
])),
)
.await
{
Ok(signature) => println!("accepted {signature}"),
Err(error) => {
let Some(swqos) = error.downcast_ref::<SwqosError>() else {
return Err(error);
};
let Some(rejection) = swqos.rejection.as_ref() else {
return Err(error);
};
eprintln!(
"{} {} {} {}",
swqos.status, rejection.reason, rejection.retryable, rejection.message
);
if rejection.reason == "simulation_failed"
&& let Some(logs) = rejection.fields.get("logs")
{
eprintln!("{logs}");
}
}
}
Ok(())
}
// 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, call, required};
#[tokio::main]
async fn main() -> Result<()> {
let transaction =
BASE64_STANDARD.encode(tokio::fs::read(required("SIGNED_TX_FILE")?).await?);
let tip = required("DECLARED_TIP_LAMPORTS")?
.parse::<u64>()
.map_err(|_| "tip must be a positive safe integer")?;
if tip == 0 || tip > 9_007_199_254_740_991 {
return Err("tip must be a positive safe integer".into());
}
let signature: String = call(
"sendTransaction",
Some(json!([transaction, { "encoding": "base64", "tip": tip }])),
)
.await?;
println!("{signature}");
Ok(())
}
// Builds on the example project (/reference/json-rpc#example-project).
package swqos
import (
"context"
"encoding/base64"
"fmt"
"os"
"github.com/gagliardetto/solana-go"
)
func SendWithSolanaGo(ctx context.Context) error {
// A fully signed transaction in wire format, from your signing flow.
path, err := Required("SIGNED_TX_FILE")
if err != nil {
return err
}
wire, err := os.ReadFile(path)
if err != nil {
return err
}
transaction, err := solana.TransactionFromBytes(wire)
if err != nil {
return err
}
encoded, err := transaction.MarshalBinary()
if err != nil {
return err
}
signature, err := Call[string](ctx, "sendTransaction", base64.StdEncoding.EncodeToString(encoded),
map[string]any{"encoding": "base64"})
if err != nil {
return err
}
fmt.Println(signature)
return nil
}
// Builds on the example project (/reference/json-rpc#example-project).
package swqos
import (
"context"
"encoding/base64"
"errors"
"fmt"
"os"
)
func SendWithPreflight(ctx context.Context) error {
path, err := Required("SIGNED_TX_FILE")
if err != nil {
return err
}
wire, err := os.ReadFile(path)
if err != nil {
return err
}
signature, err := Call[string](ctx, "sendTransaction", base64.StdEncoding.EncodeToString(wire),
map[string]any{"encoding": "base64", "skipPreflight": false, "preflightCommitment": "confirmed"})
if err != nil {
var refusal *SwqosError
if !errors.As(err, &refusal) || refusal.Rejection == nil {
return err
}
rejection := refusal.Rejection
fmt.Fprintln(os.Stderr, refusal.Status, rejection.Reason, rejection.Retryable, rejection.Message)
if rejection.Reason == "simulation_failed" {
fmt.Fprintln(os.Stderr, string(rejection.Fields["logs"]))
}
return nil
}
fmt.Println("accepted", signature)
return nil
}
// Builds on the example project (/reference/json-rpc#example-project).
package swqos
import (
"context"
"encoding/base64"
"errors"
"fmt"
"os"
"strconv"
)
func SendDeclared(ctx context.Context) error {
path, err := Required("SIGNED_TX_FILE")
if err != nil {
return err
}
wire, err := os.ReadFile(path)
if err != nil {
return err
}
value, err := Required("DECLARED_TIP_LAMPORTS")
if err != nil {
return err
}
tip, err := strconv.ParseUint(value, 10, 64)
if err != nil || tip == 0 || tip > 9_007_199_254_740_991 {
return errors.New("tip must be a positive safe integer")
}
signature, err := Call[string](ctx, "sendTransaction", base64.StdEncoding.EncodeToString(wire),
map[string]any{"encoding": "base64", "tip": tip})
if err != nil {
return err
}
fmt.Println(signature)
return nil
}
// Builds on the example project (/reference/json-rpc#example-project).
import { readFile } from 'node:fs/promises'
import { call, required } from './swqos.ts'
const transaction = (await readFile(required('SIGNED_TX_FILE'))).toString('base64')
const tip = Number(required('DECLARED_TIP_LAMPORTS'))
if (!Number.isSafeInteger(tip) || tip <= 0) throw new Error('tip must be a positive safe integer')
const signature = await call<string>('sendTransaction', [
transaction,
{ encoding: 'base64', tip },
])
console.log(signature)
// Builds on the example project (/reference/json-rpc#example-project).
import { readFile } from 'node:fs/promises'
import {
createSolanaRpc,
getBase64EncodedWireTransaction,
getTransactionDecoder,
} from '@solana/kit'
import { required, url } from './swqos.ts'
// A fully signed transaction in wire format, from your signing flow.
const transaction = getTransactionDecoder().decode(await readFile(required('SIGNED_TX_FILE')))
const swqos = createSolanaRpc(url, { headers: { 'x-api-key': required('SWQOS_API_KEY') } })
const signature = await swqos
.sendTransaction(getBase64EncodedWireTransaction(transaction), { encoding: 'base64' })
.send()
console.log(signature)
// Builds on the example project (/reference/json-rpc#example-project).
import { readFile } from 'node:fs/promises'
import { call, required, SwqosError } from './swqos.ts'
const transaction = (await readFile(required('SIGNED_TX_FILE'))).toString('base64')
try {
const signature = await call<string>('sendTransaction', [
transaction,
{ encoding: 'base64', skipPreflight: false, preflightCommitment: 'confirmed' },
])
console.log('accepted', signature)
} catch (error) {
if (!(error instanceof SwqosError) || !error.rejection) throw error
const { reason, retryable, message } = error.rejection
console.error(error.status, reason, retryable, message)
if (reason === 'simulation_failed') console.error(error.rejection.logs)
}