# UltraSend Implementation Guide

> Activate, fund, and integrate the UltraSend Solana transaction relay in JavaScript, Python, and Rust.

Canonical: https://nolimitnodes.com/docs/api-reference/ultrasend/overview

UltraSend accepts an **already-signed** Solana transaction and forwards the exact serialized bytes. It does not simulate, rebuild, resign, replace the blockhash, or add instructions.

Use HTTPS for the simplest integration. Use a persistent QUIC connection when handshake overhead matters to your sender.

| Endpoint | Value |
|---|---|
| HTTPS base | `https://ultrasend.nolimitnodes.com` |
| Submit transaction | `POST /v1/transactions` |
| Account and balance | `GET /v1/account` |
| Pricing | `GET /v1/pricing` |
| Health | `GET /v1/health` |
| QUIC | `ultrasend.nolimitnodes.com:11000/UDP` |
| QUIC ALPN | `ultrasend/1` |
| Network | Solana mainnet-beta |

  An UltraSend credential contains Ed25519 private-key material. Never put it in browser code, a mobile binary, a public repository, a URL, logs, or analytics. Reveal it once in the dashboard and store it in a secrets manager.

## Activate and fund the account

  ### Activate UltraSend

Open **Dashboard → UltraSend**. An active Pro, Ultra, or Enterprise plan is required. Activation does not create or modify a Stripe subscription.

  ### Store the credential

Select **Reveal once**, copy the `usq_live_...` value, and put it in a server-side `ULTRASEND_API_KEY` environment variable. It cannot be displayed again.

  ### Create a deposit request

Enter the Solana wallet that will fund the account and an exact native-SOL amount. Send that amount to the displayed deposit wallet, then paste the finalized signature. NoLimitNodes independently verifies sender, recipient, amount, chain success, and finality before crediting it.

  ### Check the effective price

Read `GET /v1/account`. The current launch price is 200,000 lamports, or 0.0002 SOL, per accepted submission.

```bash

curl -fsS https://ultrasend.nolimitnodes.com/v1/account \
  -H "Authorization: Bearer $ULTRASEND_API_KEY"
```

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

Estimate remaining submissions with integer division:

```text
remaining = balance_lamports // submission_price_lamports
```

## HTTPS request and receipt

Send JSON containing one standard Base64 string. Do not use Base58 for the transaction bytes.

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

An accepted receipt has this shape:

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

`accepted: true` means billing committed and the forwarding transport acknowledged the submission. It does **not** mean the transaction landed or succeeded on-chain.

## JavaScript and TypeScript

Install an HTTP client only if your Node version does not include `fetch`. This example accepts a transaction your application has already signed with `@solana/web3.js`.

```bash
npm install @solana/web3.js
```

```typescript TypeScript

  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 {
  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);
  }
}

  signed: SignedTransaction,
): Promise {
  // 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;
  }
}

  const connection = new Connection(RPC_URL, {
    commitment: "confirmed",
    httpHeaders: { "x-api-key": RPC_API_KEY },
  });
  for (let attempt = 0; attempt  setTimeout(resolve, 500));
  }
  throw new Error("Transaction was not finalized before the client deadline");
}
```

Do not retry HTTP `400`, `401`, `402`, or `403` without correcting the request or account. HTTP `409` means the same signature is already being processed; wait briefly and retry the exact same payload.

## Python

The example uses `solders` for Solana transaction types and `httpx` for bounded HTTP timeouts.

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

```python Python
from __future__ import annotations

from typing import Any

from 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")
```

## Rust over HTTPS

This example is independent of the QUIC client and works with any Solana transaction type once your signer produces the serialized wire bytes.

```toml Cargo.toml
[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"] }
```

```rust Rust
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 {
    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 {
    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
        }
    }
}
```

In production, distinguish a timeout from a definite HTTP rejection before retrying. The compact example retries any `anyhow` error only to keep the exact-payload rule visible.

## Rust over persistent QUIC

The canonical client authenticates QUIC with the Ed25519 key embedded in the UltraSend credential. Connect once, keep the client alive, and open one bidirectional stream per transaction.

```rust Rust
use anyhow::Result;
use ultrasend::client::UltraSendClient;

async fn run_sender(signed_transactions: Vec>) -> 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(())
}
```

Use ALPN `ultrasend/1`, UDP port `11000`, and SNI `ultrasend.nolimitnodes.com`. Keepalive is 25 seconds. Do not open a new QUIC connection for every transaction.

## Confirm independently

Always confirm the signature through Solana RPC. Do not scrape an explorer for automation.

```bash
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}]
  }'
```

- `value[0] == null`: not observed, expired, dropped, or not indexed yet.
- `finalized` with `err == null`: finalized successfully.
- `finalized` with `err != null`: finalized with a chain error.

## Production checklist

- Simulate before signing when your workflow permits it.
- Use a recent blockhash or intentional durable nonce.
- Serialize once and keep the exact payload for ambiguous retries.
- Never log the API key or signed transaction bytes.
- Treat `accepted` as a relay receipt, not a landing guarantee.
- Confirm signatures independently.
- Alert on HTTP `402`, repeated `409`, and `503` responses.
- Monitor prepaid balance before a send loop reaches zero.
- Revoke and replace a credential immediately if it is exposed.

Continue with [errors and retries](/docs/api-reference/ultrasend/errors-retries) for status-specific handling.