UltraSend Implementation Guide

export ULTRASEND_API_KEY='usq_live_REDACTED' curl -fsS https://ultrasend.nolimitnodes.com/v1/account \  -H "Authorization: Bearer $ULTRASEND_API_KEY"

{  "account_id": "nln_account_uuid",  "name": "NoLimitNodes account",  "public_key": "CUSTOMER_PUBLIC_KEY",  "balance_lamports": 100000000,  "enabled": true,  "submission_price_lamports": 200000}

remaining = balance_lamports // submission_price_lamports

curl -fsS https://ultrasend.nolimitnodes.com/v1/transactions \  -H "Authorization: Bearer $ULTRASEND_API_KEY" \  -H 'Content-Type: application/json' \  -d '{"transaction":"BASE64_SIGNED_TRANSACTION"}'

{  "signature": "SOLANA_SIGNATURE",  "accepted": true,  "charged_lamports": 200000,  "balance_remaining_lamports": 99800000,  "upstream_acknowledged": true}

npm install @solana/web3.js

import {  Connection,  Transaction,  VersionedTransaction,} from "@solana/web3.js"; const ULTRASEND_URL =  "https://ultrasend.nolimitnodes.com/v1/transactions";const RPC_URL = process.env.NLN_RPC_URL!;const RPC_API_KEY = process.env.NLN_RPC_API_KEY!;const API_KEY = process.env.ULTRASEND_API_KEY!; type SignedTransaction = Transaction | VersionedTransaction; type UltraSendReceipt = {  signature: string;  accepted: boolean;  charged_lamports: number;  balance_remaining_lamports: number;  upstream_acknowledged: boolean;}; class UltraSendError extends Error {  constructor(    readonly status: number,    readonly code: string,    message: string,  ) {    super(message);  }} async function submitExactPayload(  transactionBase64: string,  timeoutMs = 2_000,): Promise<UltraSendReceipt> {  const controller = new AbortController();  const timer = setTimeout(() => controller.abort(), timeoutMs);  try {    const response = await fetch(ULTRASEND_URL, {      method: "POST",      headers: {        Authorization: `Bearer ${API_KEY}`,        "Content-Type": "application/json",      },      body: JSON.stringify({ transaction: transactionBase64 }),      signal: controller.signal,    });    const body = await response.json();    if (!response.ok) {      throw new UltraSendError(        response.status,        body.code ?? "UNKNOWN_ERROR",        body.message ?? "UltraSend rejected the transaction",      );    }    return body as UltraSendReceipt;  } finally {    clearTimeout(timer);  }} export async function sendWithUltraSend(  signed: SignedTransaction,): Promise<UltraSendReceipt> {  // Serialize once. Every retry must use this exact Base64 payload.  const transactionBase64 = Buffer.from(signed.serialize()).toString("base64");  try {    return await submitExactPayload(transactionBase64);  } catch (error) {    // Retry only ambiguous transport failures. Do not rebuild or resign here.    if (error instanceof DOMException && error.name === "AbortError") {      return submitExactPayload(transactionBase64, 4_000);    }    throw error;  }} export async function waitForFinalized(signature: string) {  const connection = new Connection(RPC_URL, {    commitment: "confirmed",    httpHeaders: { "x-api-key": RPC_API_KEY },  });  for (let attempt = 0; attempt < 40; attempt += 1) {    const response = await connection.getSignatureStatuses(      [signature],      { searchTransactionHistory: true },    );    const status = response.value[0];    if (status?.confirmationStatus === "finalized") {      if (status.err) throw new Error(`Transaction failed: ${JSON.stringify(status.err)}`);      return status;    }    await new Promise((resolve) => setTimeout(resolve, 500));  }  throw new Error("Transaction was not finalized before the client deadline");}

python -m pip install 'solders>=0.26' 'httpx>=0.27'

from __future__ import annotations import base64import osimport timefrom typing import Any import httpxfrom solders.transaction import Transaction, VersionedTransaction ULTRASEND_URL = "https://ultrasend.nolimitnodes.com/v1/transactions"RPC_URL = os.environ["NLN_RPC_URL"]RPC_API_KEY = os.environ["NLN_RPC_API_KEY"]API_KEY = os.environ["ULTRASEND_API_KEY"]  class UltraSendError(RuntimeError):    def __init__(self, status: int, code: str, message: str):        super().__init__(f"{code}: {message}")        self.status = status        self.code = code  def submit_exact_payload(    client: httpx.Client,    transaction_base64: str,    timeout_seconds: float,) -> dict[str, Any]:    response = client.post(        ULTRASEND_URL,        headers={"Authorization": f"Bearer {API_KEY}"},        json={"transaction": transaction_base64},        timeout=timeout_seconds,    )    body = response.json()    if response.is_error:        raise UltraSendError(            response.status_code,            body.get("code", "UNKNOWN_ERROR"),            body.get("message", "UltraSend rejected the transaction"),        )    return body  def send_with_ultrasend(    signed: Transaction | VersionedTransaction,) -> dict[str, Any]:    # bytes(signed) is the complete wire transaction. Encode it once.    payload = base64.b64encode(bytes(signed)).decode("ascii")    with httpx.Client() as client:        try:            return submit_exact_payload(client, payload, 2.0)        except (httpx.TimeoutException, httpx.NetworkError):            # Ambiguous transport result: retry the same payload, not a new tx.            return submit_exact_payload(client, payload, 4.0)  def wait_for_finalized(signature: str) -> dict[str, Any]:    headers = {"Content-Type": "application/json", "x-api-key": RPC_API_KEY}    with httpx.Client(headers=headers, timeout=5.0) as client:        for request_id in range(40):            response = client.post(                RPC_URL,                json={                    "jsonrpc": "2.0",                    "id": request_id,                    "method": "getSignatureStatuses",                    "params": [[signature], {"searchTransactionHistory": True}],                },            )            response.raise_for_status()            status = response.json()["result"]["value"][0]            if status and status.get("confirmationStatus") == "finalized":                if status.get("err") is not None:                    raise RuntimeError(f"Transaction failed: {status['err']}")                return status            time.sleep(0.5)    raise TimeoutError("Transaction was not finalized before the client deadline")

[dependencies]anyhow = "1"base64 = "0.22"reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }serde = { version = "1", features = ["derive"] }serde_json = "1"tokio = { version = "1", features = ["macros", "rt-multi-thread", "time"] }

use std::time::Duration; use anyhow::{Context, Result, bail};use base64::{Engine as _, engine::general_purpose::STANDARD};use reqwest::{Client, StatusCode};use serde::Deserialize;use serde_json::json; const ULTRASEND_URL: &str =    "https://ultrasend.nolimitnodes.com/v1/transactions"; #[derive(Debug, Deserialize)]struct Receipt {    signature: String,    accepted: bool,    charged_lamports: u64,    balance_remaining_lamports: u64,    upstream_acknowledged: bool,} async fn submit_exact_payload(    client: &Client,    api_key: &str,    transaction_base64: &str,) -> Result<Receipt> {    let response = client        .post(ULTRASEND_URL)        .bearer_auth(api_key)        .json(&json!({ "transaction": transaction_base64 }))        .send()        .await        .context("UltraSend request failed")?;    let status = response.status();    if !status.is_success() {        let body = response.text().await.unwrap_or_default();        bail!("UltraSend returned {status}: {body}");    }    response.json().await.context("invalid UltraSend receipt")} async fn send_with_ultrasend(signed_transaction: &[u8]) -> Result<Receipt> {    let api_key = std::env::var("ULTRASEND_API_KEY")?;    let client = Client::builder()        .connect_timeout(Duration::from_secs(2))        .timeout(Duration::from_secs(4))        .build()?;    // Encode once so an ambiguous retry keeps the same signature.    let payload = STANDARD.encode(signed_transaction);    match submit_exact_payload(&client, &api_key, &payload).await {        Ok(receipt) => Ok(receipt),        Err(first_error) => {            // Apply this retry only to transport/timeout errors in production.            eprintln!("ambiguous first attempt: {first_error:#}");            submit_exact_payload(&client, &api_key, &payload).await        }    }}

use anyhow::Result;use ultrasend::client::UltraSendClient; async fn run_sender(signed_transactions: Vec<Vec<u8>>) -> Result<()> {    let api_key = std::env::var("ULTRASEND_API_KEY")?;    let client = UltraSendClient::connect(        &api_key,        "ultrasend.nolimitnodes.com:11000",    ).await?;     for transaction in signed_transactions {        let receipt = client.send(&transaction).await?;        println!(            "signature={} charged={} remaining={}",            receipt.signature,            receipt.charged_lamports,            receipt.balance_remaining_lamports,        );    }    Ok(())}

curl -fsS https://rpc.nln.clr3.org \  -H "x-api-key: $NLN_RPC_API_KEY" \  -H 'Content-Type: application/json' \  -d '{    "jsonrpc":"2.0",    "id":1,    "method":"getSignatureStatuses",    "params":[["SOLANA_SIGNATURE"],{"searchTransactionHistory":true}]  }'