Batch Send

Nozomi sendBatch Client Integration Guide

1. What sendBatch does

POST /api/sendBatch lets you submit multiple raw Solana transactions in one request using a compact binary format (no base64).

Use this when you already have serialized tx bytes and want to reduce per-request overhead.

2. Endpoint and auth

• Method: POST

• Path: /api/sendBatch

• Required query param: c=<client_id>

• Recommended header: Content-Type: application/octet-stream

Example URL:

https://YOUR_HOST/api/sendBatch?c=YOUR_CLIENT_ID

3. Binary wire format

Body is a concatenation of entries:

[len_hi][len_lo][tx_bytes...] [len_hi][len_lo][tx_bytes...] ...

• len_hi,len_lo: unsigned big-endian u16 length

• len > 0

• tx_bytes: raw serialized transaction bytes for that entry

No separators and no JSON wrapper are used.

4. Limits and validation

• Max entries per request: 16

• Max tx size per entry: 1232 bytes

• Min tx size accepted: 66 bytes

• Max total request body: 19,744 bytes (16 * (1232 + 2))

Requests violating framing, count, or parsing rules are rejected.

5. Response behavior (important)

sendBatch is stream-processed.

That means entries are handled in order as bytes arrive. If entry N fails:

• entries 1..N-1 may already be accepted and forwarded

• there is no rollback

• response is an error for the overall request

Your client should treat this endpoint as partially successful on some failures.

6. HTTP status codes and response bodies

All responses are plain text (text/plain).

• 200 OK + empty body Full request accepted.

• 400 Bad Request + Bad Request\n Framing/format errors (invalid length prefixes, truncated payload, too many entries, empty batch, etc.).

• 400 Bad Request + Transaction too large\n At least one tx exceeded allowed size, or body exceeded max cap.

• 400 Bad Request + Failed to parse transaction\n Transaction bytes failed metadata/parse checks.

• 400 Bad Request + Malformed transaction string\n Transaction payload is malformed (for example, too small).

• 400 Bad Request + Insufficient tip\n Tx did not satisfy configured tip policy.

• 401 Unauthorized + Unauthorized\n Missing/invalid c client id.

• 429 Too Many Requests + Too Many Requests\n Rate limit exceeded.

• 405 Method Not Allowed + Used HTTP Method is not allowed. POST is required\n Non-POST usage.

• 500 Internal Server Error + Internal Server Error\n Internal forwarding/queue failure.

7. JavaScript reference implementation

function encodeBatch(rawTxs) {
  // rawTxs: Array<Uint8Array|Buffer> of serialized Solana tx bytes
  if (!Array.isArray(rawTxs) || rawTxs.length === 0) {
    throw new Error("batch must contain at least one transaction");
  }
  if (rawTxs.length > 16) {
    throw new Error("batch cannot exceed 16 transactions");
  }

  let total = 0;
  for (const tx of rawTxs) {
    if (tx.length < 66 || tx.length > 1232) {
      throw new Error(`invalid tx size: ${tx.length}`);
    }
    total += 2 + tx.length;
  }
  if (total > 19744) {
    throw new Error(`batch body too large: ${total}`);
  }

  const out = Buffer.allocUnsafe(total);
  let off = 0;
  for (const tx of rawTxs) {
    out.writeUInt16BE(tx.length, off);
    off += 2;
    Buffer.from(tx).copy(out, off);
    off += tx.length;
  }
  return out;
}

async function sendBatch(endpointBase, clientId, rawTxs) {
  const body = encodeBatch(rawTxs);
  const url = `${endpointBase}/api/sendBatch?c=${encodeURIComponent(clientId)}`;

  const res = await fetch(url, {
    method: "POST",
    headers: { "content-type": "application/octet-stream" },
    body,
  });

  if (!res.ok) {
    const text = await res.text();
    // Caller should handle possible partial success on some 4xx responses.
    throw new Error(`sendBatch failed: HTTP ${res.status}: ${text}`);
  }
}

8. curl example

curl -X POST \
  "https://YOUR_HOST/api/sendBatch?c=YOUR_CLIENT_ID" \
  -H "content-type: application/octet-stream" \
  --data-binary @batch.bin

9. Production recommendations

1. Keep batch sizes small enough for your retry strategy (for example 2-8 txs).

2. Track tx signatures client-side before send, so you can reconcile partial success.

3. On non-200 responses, do not assume the whole batch failed.

4. Make retries idempotent at the tx/signature level in your system.

5. Log both HTTP status and response text; response text is meaningful for error class.

10. CORS/preflight

• OPTIONS is supported.

• Response headers include:

  • Access-Control-Allow-Origin: *

  • Access-Control-Allow-Methods: POST, GET, OPTIONS

  • Access-Control-Allow-Headers: Content-Type