Documentation

sendTransaction

Submit one signed transaction with sendTransaction, choose encoding and preflight options, and handle refusals.

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

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"sendTransaction"yes
paramsarrayyesThe signed transaction followed by optional options. minItems: 1. maxItems: 2.
params[0]stringyesOne 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]objectnoOptional. 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"noTransaction encoding. Any other value is refused as malformed, problem unknown_encoding. Default "base58".
params[1].skipPreflightbooleannofalse 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"noRead only when skipPreflight is false. Default "finalized".
params[1].minContextSlotintegernoPassed to simulation. Read only when skipPreflight is false. minimum: 0.
params[1].maxRetriesintegernoAccepted and ignored. SWQoS does not periodically resubmit. minimum: 0.
params[1].tipintegernoA 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; problem names the cause.
  • malformed: invalid transaction, tip sum overflow (tip_overflow) or paid tip above 2 SOL (tip_too_large); problem names the cause.
  • too_large: size limit exceeded; limit and size are 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 in data.

Content type: application/json

FieldTypeRequiredDescription
jsonrpc"2.0"yes
resultstringyesThe base58 encoding of the transaction's first signature.
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": "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

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: partner_declared_tips; remove the declaration and send an on-chain tip to a Supanode tip account.

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": "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

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

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": "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)
}