{
  "openapi": "3.2.0",
  "info": {
    "title": "Raw HTTP",
    "version": "1",
    "description": "Send raw transaction and bundle payloads over HTTP with /binary and /plaintext, using raw bytes or base64 text."
  },
  "servers": [
    {
      "url": "https://ams.tpu.supanode.xyz"
    },
    {
      "url": "https://fra.tpu.supanode.xyz"
    },
    {
      "url": "https://la.tpu.supanode.xyz"
    },
    {
      "url": "https://lon.tpu.supanode.xyz"
    },
    {
      "url": "https://ny.tpu.supanode.xyz"
    },
    {
      "url": "https://toy.tpu.supanode.xyz"
    }
  ],
  "security": [
    {
      "apiKeyHeader": []
    },
    {
      "apiKeyQuery": []
    },
    {
      "bearer": []
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKeyHeader": {
        "$ref": "#/x-ext/b08d7c8/components/securitySchemes/apiKeyHeader"
      },
      "apiKeyQuery": {
        "$ref": "#/x-ext/b08d7c8/components/securitySchemes/apiKeyQuery"
      },
      "bearer": {
        "$ref": "#/x-ext/b08d7c8/components/securitySchemes/bearer"
      }
    }
  },
  "paths": {
    "/binary": {
      "post": {
        "operationId": "sendBinary",
        "summary": "Send raw bytes",
        "description": "Send a signed transaction or bundle as raw payload bytes over HTTP, with an optional declared tip.",
        "requestBody": {
          "required": true,
          "description": "One signed transaction or a [payload envelope](https://supanode.xyz/docs/solana/sender/reference/payload-envelope) with a declared tip or bundle. Maximum body 16,403 bytes, received within 2 seconds. There is no encoding option or preflight simulation. The same [tip](https://supanode.xyz/docs/solana/sender/tips), [send rate](https://supanode.xyz/docs/solana/sender/limits#send-rate) and transaction rules apply as for JSON-RPC. Uses the same hosts, ports and [authentication](https://supanode.xyz/docs/solana/sender/api-keys) as JSON-RPC.",
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary",
                "description": "Raw payload bytes. A signed transaction or an envelope with a declared tip or bundle; the [payload envelope](https://supanode.xyz/docs/solana/sender/reference/payload-envelope) defines the binary layout shared with QUIC streams."
              },
              "examples": {
                "SignedTransaction": {
                  "summary": "Signed transaction wire bytes",
                  "value": "SIGNED_TRANSACTION_BYTES"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returns the transaction's first signature in base58 or the [bundle ID](https://supanode.xyz/docs/solana/sender/reference/json-rpc/send-bundle) as 64 hex characters, in plain text. Acceptance does not mean landing; confirm signatures through your Solana RPC provider.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "description": "Base58 transaction signature or 64-character hex bundle id."
                },
                "examples": {
                  "Signature": {
                    "summary": "Signature",
                    "value": "BASE58_SIGNATURE"
                  },
                  "Bundle id": {
                    "summary": "Bundle id",
                    "value": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
                  }
                }
              }
            }
          },
          "400": {
            "description": "JSON rejection body, with the reason, its fields, `message`, `retryable` and optional `docs`, as in JSON-RPC [`error.data`](https://supanode.xyz/docs/solana/sender/reference/json-rpc#responses)\n- [`malformed`](https://supanode.xyz/docs/solana/sender/reference/errors#malformed): invalid payload or transaction, repeated bundle signature (`duplicate_signature`), tip sum overflow (`tip_overflow`) or paid tip above 2 SOL (`tip_too_large`).\n- [`unsigned`](https://supanode.xyz/docs/solana/sender/reference/errors#unsigned): unsigned transaction.\n- [`signature_count`](https://supanode.xyz/docs/solana/sender/reference/errors#signature_count): signature mismatch.\n- [`missing_tip`](https://supanode.xyz/docs/solana/sender/reference/errors#missing_tip): tip below the minimum.\n- [`credit_exhausted`](https://supanode.xyz/docs/solana/sender/reference/errors#credit_exhausted): declared tip credit unavailable.\n- [`bundle_size`](https://supanode.xyz/docs/solana/sender/reference/errors#bundle_size): invalid transaction count.\n- [`bundle_control`](https://supanode.xyz/docs/solana/sender/reference/errors#bundle_control): control account rule broken.\n- [`invalid_request`](https://supanode.xyz/docs/solana/sender/reference/errors#invalid_request): other than `not_found` or `body_timeout`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/x-ext/b08d7c8/components/schemas/Rejection"
                },
                "examples": {
                  "missing_tip": {
                    "value": {
                      "reason": "missing_tip",
                      "minimum": 1000000,
                      "found": 123,
                      "message": "tip too small: the tip transfers add up to 123 lamports, the minimum is 1,000,000; raise the transfer to one of the tip accounts to at least 1,000,000 lamports",
                      "retryable": false,
                      "docs": "https://supanode.xyz/docs/solana/sender/reference/errors#missing_tip"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/x-ext/b08d7c8/components/responses/RawUnauthorized"
          },
          "402": {
            "$ref": "#/x-ext/b08d7c8/components/responses/RawPaymentRequired"
          },
          "403": {
            "$ref": "#/x-ext/b08d7c8/components/responses/RawBundlesForbidden"
          },
          "404": {
            "description": "GET is supported only at [/health](https://supanode.xyz/docs/solana/sender/reference/http/health) and [/tip_floor](https://supanode.xyz/docs/solana/sender/reference/http/tip-floor); methods other than GET and POST are refused. POST to another path is [JSON-RPC](https://supanode.xyz/docs/solana/sender/reference/json-rpc).\n- [`invalid_request`](https://supanode.xyz/docs/solana/sender/reference/errors#invalid_request): `problem: not_found`.\n- [`unsupported`](https://supanode.xyz/docs/solana/sender/reference/errors#unsupported): `feature: tip_floor` from the agent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/x-ext/b08d7c8/components/schemas/Rejection"
                },
                "examples": {
                  "invalid_request": {
                    "value": {
                      "reason": "invalid_request",
                      "problem": "not_found",
                      "message": "unknown path or method: POST raw transactions to /binary, base64 to /plaintext, or JSON-RPC to any other path",
                      "retryable": false,
                      "docs": "https://supanode.xyz/docs/solana/sender/reference/errors#invalid_request"
                    }
                  }
                }
              }
            }
          },
          "408": {
            "description": "[`invalid_request`](https://supanode.xyz/docs/solana/sender/reference/errors#invalid_request): `problem: body_timeout`; the body did not arrive within 2 seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/x-ext/b08d7c8/components/schemas/Rejection"
                },
                "examples": {
                  "invalid_request": {
                    "value": {
                      "reason": "invalid_request",
                      "problem": "body_timeout",
                      "message": "the request body did not arrive within 2 seconds; retry",
                      "retryable": true,
                      "docs": "https://supanode.xyz/docs/solana/sender/reference/errors#invalid_request"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "[`too_large`](https://supanode.xyz/docs/solana/sender/reference/errors#too_large): request body, decoded payload or transaction exceeds a size limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/x-ext/b08d7c8/components/schemas/Rejection"
                },
                "examples": {
                  "too_large": {
                    "value": {
                      "reason": "too_large",
                      "limit": 16403,
                      "size": 16404,
                      "message": "The payload exceeds the byte limit.",
                      "retryable": false,
                      "docs": "https://supanode.xyz/docs/solana/sender/reference/errors#too_large"
                    }
                  }
                }
              }
            }
          },
          "421": {
            "$ref": "#/x-ext/b08d7c8/components/responses/MisdirectedRequest"
          },
          "429": {
            "$ref": "#/x-ext/b08d7c8/components/responses/RawRateLimited"
          },
          "503": {
            "$ref": "#/x-ext/b08d7c8/components/responses/RawUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "rust",
            "id": "rust-payload-encoder",
            "label": "Rust (payload encoder)",
            "source": "// Builds on the example project (https://supanode.xyz/docs/solana/sender/reference/json-rpc#example-project).\n// src/payload.rs\nuse crate::swqos::Result;\n\npub fn transaction_payload(transaction: &[u8], declared_tip: Option<u64>) -> Vec<u8> {\n    let mut payload = Vec::with_capacity(\n        transaction.len() + usize::from(declared_tip.is_some()) * 10,\n    );\n    if let Some(tip) = declared_tip {\n        payload.extend_from_slice(&[0x00, 0x01]);\n        payload.extend_from_slice(&tip.to_le_bytes());\n    }\n    payload.extend_from_slice(transaction);\n    payload\n}\n\npub fn bundle_payload(\n    transactions: &[Vec<u8>],\n    declared_tip: Option<u64>,\n) -> Result<Vec<u8>> {\n    if !(1..=4).contains(&transactions.len()) {\n        return Err(\"a bundle holds 1 to 4 transactions\".into());\n    }\n    let size = 3\n        + usize::from(declared_tip.is_some()) * 8\n        + transactions\n            .iter()\n            .map(|transaction| 2 + transaction.len())\n            .sum::<usize>();\n    let mut payload = Vec::with_capacity(size);\n    payload\n        .extend_from_slice(&[0x00, if declared_tip.is_some() { 0x03 } else { 0x02 }]);\n    if let Some(tip) = declared_tip {\n        payload.extend_from_slice(&tip.to_le_bytes());\n    }\n    payload.push(transactions.len() as u8);\n    for transaction in transactions {\n        payload.extend_from_slice(&(transaction.len() as u16).to_le_bytes());\n        payload.extend_from_slice(transaction);\n    }\n    Ok(payload)\n}"
          },
          {
            "lang": "rust",
            "id": "rust",
            "label": "Rust",
            "source": "// Builds on the example project (https://supanode.xyz/docs/solana/sender/reference/json-rpc#example-project).\nuse swqos_examples::{\n    payload::bundle_payload,\n    swqos::{Result, required, url},\n};\n\n#[tokio::main]\nasync fn main() -> Result<()> {\n    // Signed transaction files, in bundle order.\n    let mut transactions = Vec::new();\n    for file in std::env::args().skip(1) {\n        transactions.push(tokio::fs::read(file).await?);\n    }\n    let response = reqwest::Client::new()\n        .post(format!(\"{}/binary\", url()))\n        .header(\"x-api-key\", required(\"SWQOS_API_KEY\")?)\n        .body(bundle_payload(&transactions, None)?)\n        .send()\n        .await?;\n    let status = response.status();\n    let body = response.text().await?;\n    if status.is_success() {\n        println!(\"bundle {body}\");\n    } else {\n        println!(\"refused {}: {body}\", status.as_u16());\n    }\n    Ok(())\n}"
          },
          {
            "lang": "go",
            "id": "go-payload-encoder",
            "label": "Go (payload encoder)",
            "source": "// payload.go\npackage swqos\n\nimport (\n\t\"encoding/binary\"\n\t\"errors\"\n)\n\nfunc TransactionPayload(transaction []byte, declaredTip *uint64) []byte {\n\tif declaredTip == nil {\n\t\treturn append([]byte(nil), transaction...)\n\t}\n\tpayload := make([]byte, 10+len(transaction))\n\tpayload[1] = 0x01\n\tbinary.LittleEndian.PutUint64(payload[2:10], *declaredTip)\n\tcopy(payload[10:], transaction)\n\treturn payload\n}\n\nfunc BundlePayload(transactions [][]byte, declaredTip *uint64) ([]byte, error) {\n\tif len(transactions) < 1 || len(transactions) > 4 {\n\t\treturn nil, errors.New(\"a bundle holds 1 to 4 transactions\")\n\t}\n\tsize := 3\n\tif declaredTip != nil {\n\t\tsize += 8\n\t}\n\tfor _, transaction := range transactions {\n\t\tsize += 2 + len(transaction)\n\t}\n\tpayload := make([]byte, size)\n\tpayload[1] = 0x02\n\toffset := 2\n\tif declaredTip != nil {\n\t\tpayload[1] = 0x03\n\t\tbinary.LittleEndian.PutUint64(payload[offset:offset+8], *declaredTip)\n\t\toffset += 8\n\t}\n\tpayload[offset] = byte(len(transactions))\n\toffset++\n\tfor _, transaction := range transactions {\n\t\tbinary.LittleEndian.PutUint16(payload[offset:offset+2], uint16(len(transaction)))\n\t\toffset += 2\n\t\tcopy(payload[offset:], transaction)\n\t\toffset += len(transaction)\n\t}\n\treturn payload, nil\n}"
          },
          {
            "lang": "go",
            "id": "go",
            "label": "Go",
            "source": "// Builds on the example project (https://supanode.xyz/docs/solana/sender/reference/json-rpc#example-project).\npackage swqos\n\nimport (\n\t\"bytes\"\n\t\"context\"\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc SendBinary(ctx context.Context) error {\n\t// Signed transaction files, in bundle order.\n\tvar transactions [][]byte\n\tfor _, file := range os.Args[1:] {\n\t\ttransaction, err := os.ReadFile(file)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\ttransactions = append(transactions, transaction)\n\t}\n\tpayload, err := BundlePayload(transactions, nil)\n\tif err != nil {\n\t\treturn err\n\t}\n\tapiKey, err := Required(\"SWQOS_API_KEY\")\n\tif err != nil {\n\t\treturn err\n\t}\n\trequest, err := http.NewRequestWithContext(ctx, http.MethodPost, URL()+\"/binary\", bytes.NewReader(payload))\n\tif err != nil {\n\t\treturn err\n\t}\n\trequest.Header.Set(\"x-api-key\", apiKey)\n\tresponse, err := http.DefaultClient.Do(request)\n\tif err != nil {\n\t\treturn err\n\t}\n\tdefer response.Body.Close()\n\tbody, err := io.ReadAll(response.Body)\n\tif err != nil {\n\t\treturn err\n\t}\n\tif response.StatusCode >= 200 && response.StatusCode < 300 {\n\t\tfmt.Printf(\"bundle %s\\n\", body)\n\t} else {\n\t\tfmt.Printf(\"refused %d: %s\\n\", response.StatusCode, body)\n\t}\n\treturn nil\n}"
          },
          {
            "lang": "ts",
            "id": "ts-payload-encoder",
            "label": "TypeScript (payload encoder)",
            "source": "// payload.ts\nexport function transactionPayload(\n  transaction: Uint8Array,\n  declaredTip?: bigint,\n): Uint8Array<ArrayBuffer> {\n  if (declaredTip === undefined) return concat([transaction])\n  return concat([Uint8Array.of(0x00, 0x01), u64(declaredTip), transaction])\n}\n\nexport function bundlePayload(\n  transactions: Uint8Array[],\n  declaredTip?: bigint,\n): Uint8Array<ArrayBuffer> {\n  if (transactions.length < 1 || transactions.length > 4) {\n    throw new RangeError('a bundle holds 1 to 4 transactions')\n  }\n  const parts: Uint8Array[] = [Uint8Array.of(0x00, declaredTip === undefined ? 0x02 : 0x03)]\n  if (declaredTip !== undefined) parts.push(u64(declaredTip))\n  parts.push(Uint8Array.of(transactions.length))\n  for (const transaction of transactions) parts.push(u16(transaction.length), transaction)\n  return concat(parts)\n}\n\nfunction u64(value: bigint): Uint8Array<ArrayBuffer> {\n  const bytes = new Uint8Array(8)\n  new DataView(bytes.buffer).setBigUint64(0, value, true)\n  return bytes\n}\n\nfunction u16(value: number): Uint8Array<ArrayBuffer> {\n  const bytes = new Uint8Array(2)\n  new DataView(bytes.buffer).setUint16(0, value, true)\n  return bytes\n}\n\nfunction concat(parts: Uint8Array[]): Uint8Array<ArrayBuffer> {\n  const out = new Uint8Array(parts.reduce((size, part) => size + part.length, 0))\n  let offset = 0\n  for (const part of parts) {\n    out.set(part, offset)\n    offset += part.length\n  }\n  return out\n}"
          },
          {
            "lang": "ts",
            "id": "ts",
            "label": "TypeScript",
            "source": "// Builds on the example project (https://supanode.xyz/docs/solana/sender/reference/json-rpc#example-project).\nimport { readFile } from 'node:fs/promises'\nimport { bundlePayload } from './payload.ts'\nimport { required, url } from './swqos.ts'\n\n// Signed transaction files, in bundle order.\nconst transactions = await Promise.all(\n  process.argv.slice(2).map(async (file) => new Uint8Array(await readFile(file))),\n)\nconst response = await fetch(`${url}/binary`, {\n  method: 'POST',\n  headers: { 'x-api-key': required('SWQOS_API_KEY') },\n  body: bundlePayload(transactions),\n})\nconst body = await response.text()\nconsole.log(response.ok ? `bundle ${body}` : `refused ${response.status}: ${body}`)"
          }
        ]
      }
    },
    "/plaintext": {
      "post": {
        "operationId": "sendPlaintext",
        "summary": "Send base64 text",
        "description": "Send a signed transaction or bundle as base64 text over HTTP, using the same payload envelope as the raw-byte route.",
        "requestBody": {
          "required": true,
          "description": "The same [payload](https://supanode.xyz/docs/solana/sender/reference/payload-envelope) as [/binary](https://supanode.xyz/docs/solana/sender/reference/http/binary), encoded as base64 text. Maximum body 21,888 bytes; decoded payload at most 16,403 bytes, received within 2 seconds. There is no encoding option or preflight simulation. The same [tip](https://supanode.xyz/docs/solana/sender/tips), [send rate](https://supanode.xyz/docs/solana/sender/limits#send-rate) and transaction rules apply as for JSON-RPC. Uses the same hosts, ports and [authentication](https://supanode.xyz/docs/solana/sender/api-keys) as JSON-RPC.",
          "content": {
            "text/plain": {
              "schema": {
                "type": "string",
                "maxLength": 21888,
                "description": "Standard base64 with padding, on one line. Whitespace before and after it is ignored."
              },
              "examples": {
                "SignedTransaction": {
                  "summary": "Base64-encoded signed transaction payload",
                  "value": "BASE64_PAYLOAD"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returns the transaction's first signature in base58 or the [bundle ID](https://supanode.xyz/docs/solana/sender/reference/json-rpc/send-bundle) as 64 hex characters, in plain text. Acceptance does not mean landing; confirm signatures through your Solana RPC provider.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "description": "Base58 transaction signature or 64-character hex bundle id."
                },
                "examples": {
                  "Signature": {
                    "summary": "Signature",
                    "value": "BASE58_SIGNATURE"
                  },
                  "Bundle id": {
                    "summary": "Bundle id",
                    "value": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
                  }
                }
              }
            }
          },
          "400": {
            "description": "JSON rejection body, with the reason, its fields, `message`, `retryable` and optional `docs`, as in JSON-RPC [`error.data`](https://supanode.xyz/docs/solana/sender/reference/json-rpc#responses)\n- [`malformed`](https://supanode.xyz/docs/solana/sender/reference/errors#malformed): invalid payload or transaction, repeated bundle signature (`duplicate_signature`), tip sum overflow (`tip_overflow`) or paid tip above 2 SOL (`tip_too_large`).\n- [`unsigned`](https://supanode.xyz/docs/solana/sender/reference/errors#unsigned): unsigned transaction.\n- [`signature_count`](https://supanode.xyz/docs/solana/sender/reference/errors#signature_count): signature mismatch.\n- [`missing_tip`](https://supanode.xyz/docs/solana/sender/reference/errors#missing_tip): tip below the minimum.\n- [`credit_exhausted`](https://supanode.xyz/docs/solana/sender/reference/errors#credit_exhausted): declared tip credit unavailable.\n- [`bundle_size`](https://supanode.xyz/docs/solana/sender/reference/errors#bundle_size): invalid transaction count.\n- [`bundle_control`](https://supanode.xyz/docs/solana/sender/reference/errors#bundle_control): control account rule broken.\n- [`invalid_request`](https://supanode.xyz/docs/solana/sender/reference/errors#invalid_request): other than `not_found` or `body_timeout`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/x-ext/b08d7c8/components/schemas/Rejection"
                },
                "examples": {
                  "missing_tip": {
                    "value": {
                      "reason": "missing_tip",
                      "minimum": 1000000,
                      "found": 123,
                      "message": "tip too small: the tip transfers add up to 123 lamports, the minimum is 1,000,000; raise the transfer to one of the tip accounts to at least 1,000,000 lamports",
                      "retryable": false,
                      "docs": "https://supanode.xyz/docs/solana/sender/reference/errors#missing_tip"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/x-ext/b08d7c8/components/responses/RawUnauthorized"
          },
          "402": {
            "$ref": "#/x-ext/b08d7c8/components/responses/RawPaymentRequired"
          },
          "403": {
            "$ref": "#/x-ext/b08d7c8/components/responses/RawBundlesForbidden"
          },
          "404": {
            "description": "GET is supported only at [/health](https://supanode.xyz/docs/solana/sender/reference/http/health) and [/tip_floor](https://supanode.xyz/docs/solana/sender/reference/http/tip-floor); methods other than GET and POST are refused. POST to another path is [JSON-RPC](https://supanode.xyz/docs/solana/sender/reference/json-rpc).\n- [`invalid_request`](https://supanode.xyz/docs/solana/sender/reference/errors#invalid_request): `problem: not_found`.\n- [`unsupported`](https://supanode.xyz/docs/solana/sender/reference/errors#unsupported): `feature: tip_floor` from the agent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/x-ext/b08d7c8/components/schemas/Rejection"
                },
                "examples": {
                  "invalid_request": {
                    "value": {
                      "reason": "invalid_request",
                      "problem": "not_found",
                      "message": "unknown path or method: POST raw transactions to /binary, base64 to /plaintext, or JSON-RPC to any other path",
                      "retryable": false,
                      "docs": "https://supanode.xyz/docs/solana/sender/reference/errors#invalid_request"
                    }
                  }
                }
              }
            }
          },
          "408": {
            "description": "[`invalid_request`](https://supanode.xyz/docs/solana/sender/reference/errors#invalid_request): `problem: body_timeout`; the body did not arrive within 2 seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/x-ext/b08d7c8/components/schemas/Rejection"
                },
                "examples": {
                  "invalid_request": {
                    "value": {
                      "reason": "invalid_request",
                      "problem": "body_timeout",
                      "message": "the request body did not arrive within 2 seconds; retry",
                      "retryable": true,
                      "docs": "https://supanode.xyz/docs/solana/sender/reference/errors#invalid_request"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "[`too_large`](https://supanode.xyz/docs/solana/sender/reference/errors#too_large): request body, decoded payload or transaction exceeds a size limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/x-ext/b08d7c8/components/schemas/Rejection"
                },
                "examples": {
                  "too_large": {
                    "value": {
                      "reason": "too_large",
                      "limit": 16403,
                      "size": 16404,
                      "message": "The payload exceeds the byte limit.",
                      "retryable": false,
                      "docs": "https://supanode.xyz/docs/solana/sender/reference/errors#too_large"
                    }
                  }
                }
              }
            }
          },
          "421": {
            "$ref": "#/x-ext/b08d7c8/components/responses/MisdirectedRequest"
          },
          "429": {
            "$ref": "#/x-ext/b08d7c8/components/responses/RawRateLimited"
          },
          "503": {
            "$ref": "#/x-ext/b08d7c8/components/responses/RawUnavailable"
          }
        },
        "x-codeSamples": [
          {
            "lang": "rust",
            "id": "rust-payload-encoder",
            "label": "Rust (payload encoder)",
            "source": "// Builds on the example project (https://supanode.xyz/docs/solana/sender/reference/json-rpc#example-project).\n// src/payload.rs\nuse crate::swqos::Result;\n\npub fn transaction_payload(transaction: &[u8], declared_tip: Option<u64>) -> Vec<u8> {\n    let mut payload = Vec::with_capacity(\n        transaction.len() + usize::from(declared_tip.is_some()) * 10,\n    );\n    if let Some(tip) = declared_tip {\n        payload.extend_from_slice(&[0x00, 0x01]);\n        payload.extend_from_slice(&tip.to_le_bytes());\n    }\n    payload.extend_from_slice(transaction);\n    payload\n}\n\npub fn bundle_payload(\n    transactions: &[Vec<u8>],\n    declared_tip: Option<u64>,\n) -> Result<Vec<u8>> {\n    if !(1..=4).contains(&transactions.len()) {\n        return Err(\"a bundle holds 1 to 4 transactions\".into());\n    }\n    let size = 3\n        + usize::from(declared_tip.is_some()) * 8\n        + transactions\n            .iter()\n            .map(|transaction| 2 + transaction.len())\n            .sum::<usize>();\n    let mut payload = Vec::with_capacity(size);\n    payload\n        .extend_from_slice(&[0x00, if declared_tip.is_some() { 0x03 } else { 0x02 }]);\n    if let Some(tip) = declared_tip {\n        payload.extend_from_slice(&tip.to_le_bytes());\n    }\n    payload.push(transactions.len() as u8);\n    for transaction in transactions {\n        payload.extend_from_slice(&(transaction.len() as u16).to_le_bytes());\n        payload.extend_from_slice(transaction);\n    }\n    Ok(payload)\n}"
          },
          {
            "lang": "rust",
            "id": "rust",
            "label": "Rust",
            "source": "// src/bin/http_plaintext_send.rs\n// Builds on the example project (https://supanode.xyz/docs/solana/sender/reference/json-rpc#example-project).\nuse base64::{Engine, prelude::BASE64_STANDARD};\nuse swqos_examples::{payload::bundle_payload, swqos::{Result, required, url}};\n\n#[tokio::main]\nasync fn main() -> Result<()> {\n    // Signed transaction files, in bundle order (1 to 4 files).\n    let mut transactions = Vec::new();\n    for file in std::env::args().skip(1) {\n        transactions.push(tokio::fs::read(file).await?);\n    }\n    let payload = bundle_payload(&transactions, None)?;\n    let mut endpoint = reqwest::Url::parse(&url())?;\n    endpoint.set_path(\"/plaintext\");\n    endpoint.set_query(None);\n    let response = reqwest::Client::new().post(endpoint)\n        .header(\"x-api-key\", required(\"SWQOS_API_KEY\")?)\n        .header(\"Content-Type\", \"text/plain\")\n        .body(BASE64_STANDARD.encode(payload))\n        .send().await?;\n    let status = response.status();\n    let body = response.text().await?;\n    if !status.is_success() {\n        return Err(format!(\"HTTP {status}: {body}\").into());\n    }\n    println!(\"bundle {body}\");\n    Ok(())\n}"
          },
          {
            "lang": "go",
            "id": "go-payload-encoder",
            "label": "Go (payload encoder)",
            "source": "// payload.go\npackage swqos\n\nimport (\n\t\"encoding/binary\"\n\t\"errors\"\n)\n\nfunc TransactionPayload(transaction []byte, declaredTip *uint64) []byte {\n\tif declaredTip == nil {\n\t\treturn append([]byte(nil), transaction...)\n\t}\n\tpayload := make([]byte, 10+len(transaction))\n\tpayload[1] = 0x01\n\tbinary.LittleEndian.PutUint64(payload[2:10], *declaredTip)\n\tcopy(payload[10:], transaction)\n\treturn payload\n}\n\nfunc BundlePayload(transactions [][]byte, declaredTip *uint64) ([]byte, error) {\n\tif len(transactions) < 1 || len(transactions) > 4 {\n\t\treturn nil, errors.New(\"a bundle holds 1 to 4 transactions\")\n\t}\n\tsize := 3\n\tif declaredTip != nil {\n\t\tsize += 8\n\t}\n\tfor _, transaction := range transactions {\n\t\tsize += 2 + len(transaction)\n\t}\n\tpayload := make([]byte, size)\n\tpayload[1] = 0x02\n\toffset := 2\n\tif declaredTip != nil {\n\t\tpayload[1] = 0x03\n\t\tbinary.LittleEndian.PutUint64(payload[offset:offset+8], *declaredTip)\n\t\toffset += 8\n\t}\n\tpayload[offset] = byte(len(transactions))\n\toffset++\n\tfor _, transaction := range transactions {\n\t\tbinary.LittleEndian.PutUint16(payload[offset:offset+2], uint16(len(transaction)))\n\t\toffset += 2\n\t\tcopy(payload[offset:], transaction)\n\t\toffset += len(transaction)\n\t}\n\treturn payload, nil\n}"
          },
          {
            "lang": "go",
            "id": "go",
            "label": "Go",
            "source": "// http_plaintext_send/main.go\npackage main\n\nimport (\n    \"encoding/base64\"\n    \"fmt\"\n    \"io\"\n    \"net/http\"\n    \"net/url\"\n    \"os\"\n    \"strings\"\n\n    swqos \"swqos-examples\"\n)\n\nfunc run() error {\n    // Signed transaction files, in bundle order (1 to 4 files).\n    var transactions [][]byte\n    for _, file := range os.Args[1:] {\n        transaction, err := os.ReadFile(file)\n        if err != nil {\n            return err\n        }\n        transactions = append(transactions, transaction)\n    }\n    payload, err := swqos.BundlePayload(transactions, nil)\n    if err != nil {\n        return err\n    }\n    apiKey, err := swqos.Required(\"SWQOS_API_KEY\")\n    if err != nil {\n        return err\n    }\n    endpoint, err := url.Parse(swqos.URL())\n    if err != nil {\n        return err\n    }\n    endpoint.Path = \"/plaintext\"\n    endpoint.RawQuery = \"\"\n    request, err := http.NewRequest(http.MethodPost, endpoint.String(), strings.NewReader(base64.StdEncoding.EncodeToString(payload)))\n    if err != nil {\n        return err\n    }\n    request.Header.Set(\"x-api-key\", apiKey)\n    request.Header.Set(\"Content-Type\", \"text/plain\")\n    response, err := http.DefaultClient.Do(request)\n    if err != nil {\n        return err\n    }\n    defer response.Body.Close()\n    body, err := io.ReadAll(response.Body)\n    if err != nil {\n        return err\n    }\n    if response.StatusCode < 200 || response.StatusCode >= 300 {\n        return fmt.Errorf(\"HTTP %d: %s\", response.StatusCode, body)\n    }\n    fmt.Printf(\"bundle %s\\n\", body)\n    return nil\n}\n\nfunc main() {\n    if err := run(); err != nil {\n        fmt.Fprintln(os.Stderr, err)\n        os.Exit(1)\n    }\n}"
          },
          {
            "lang": "ts",
            "id": "ts-payload-encoder",
            "label": "TypeScript (payload encoder)",
            "source": "// payload.ts\nexport function transactionPayload(\n  transaction: Uint8Array,\n  declaredTip?: bigint,\n): Uint8Array<ArrayBuffer> {\n  if (declaredTip === undefined) return concat([transaction])\n  return concat([Uint8Array.of(0x00, 0x01), u64(declaredTip), transaction])\n}\n\nexport function bundlePayload(\n  transactions: Uint8Array[],\n  declaredTip?: bigint,\n): Uint8Array<ArrayBuffer> {\n  if (transactions.length < 1 || transactions.length > 4) {\n    throw new RangeError('a bundle holds 1 to 4 transactions')\n  }\n  const parts: Uint8Array[] = [Uint8Array.of(0x00, declaredTip === undefined ? 0x02 : 0x03)]\n  if (declaredTip !== undefined) parts.push(u64(declaredTip))\n  parts.push(Uint8Array.of(transactions.length))\n  for (const transaction of transactions) parts.push(u16(transaction.length), transaction)\n  return concat(parts)\n}\n\nfunction u64(value: bigint): Uint8Array<ArrayBuffer> {\n  const bytes = new Uint8Array(8)\n  new DataView(bytes.buffer).setBigUint64(0, value, true)\n  return bytes\n}\n\nfunction u16(value: number): Uint8Array<ArrayBuffer> {\n  const bytes = new Uint8Array(2)\n  new DataView(bytes.buffer).setUint16(0, value, true)\n  return bytes\n}\n\nfunction concat(parts: Uint8Array[]): Uint8Array<ArrayBuffer> {\n  const out = new Uint8Array(parts.reduce((size, part) => size + part.length, 0))\n  let offset = 0\n  for (const part of parts) {\n    out.set(part, offset)\n    offset += part.length\n  }\n  return out\n}"
          },
          {
            "lang": "ts",
            "id": "ts",
            "label": "TypeScript",
            "source": "// http-plaintext-send.ts\nimport { readFile } from 'node:fs/promises'\nimport { bundlePayload } from './payload.ts'\nimport { required, url } from './swqos.ts'\n\n// Signed transaction files, in bundle order (1 to 4 files).\nconst transactions = await Promise.all(\n  process.argv.slice(2).map(async (file) => new Uint8Array(await readFile(file))),\n)\nconst endpoint = new URL('/plaintext', url)\nconst response = await fetch(endpoint, {\n  method: 'POST',\n  headers: { 'x-api-key': required('SWQOS_API_KEY'), 'Content-Type': 'text/plain' },\n  body: Buffer.from(bundlePayload(transactions)).toString('base64'),\n})\nconst body = await response.text()\nif (!response.ok) throw new Error(`HTTP ${response.status}: ${body}`)\nconsole.log(`bundle ${body}`)"
          }
        ]
      }
    }
  },
  "x-ext": {
    "b08d7c8": {
      "components": {
        "schemas": {
          "Rejection": {
            "type": "object",
            "required": [
              "reason",
              "message",
              "retryable"
            ],
            "properties": {
              "reason": {
                "type": "string",
                "description": "Stable snake_case reason. Match on this; `message` wording can change, and the numeric codes are shared with Solana's RPC.",
                "examples": [
                  "missing_tip"
                ]
              },
              "message": {
                "type": "string",
                "description": "What happened and what to change. Wording can change.",
                "examples": [
                  "tip too small: the tip transfers add up to 123 lamports, the minimum is 1,000,000; raise the transfer to one of the tip accounts to at least 1,000,000 lamports"
                ]
              },
              "retryable": {
                "type": "boolean",
                "description": "Whether the unchanged request can succeed later. Wait before retrying, and check that the transaction has not expired.",
                "examples": [
                  false
                ]
              },
              "docs": {
                "type": "string",
                "format": "uri",
                "description": "Optional error documentation URL followed by the reason anchor. Supanode endpoints omit this field.",
                "examples": [
                  "https://supanode.xyz/docs/solana/sender/reference/errors#missing_tip"
                ]
              }
            },
            "additionalProperties": true,
            "description": "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.",
            "examples": [
              {
                "reason": "missing_tip",
                "minimum": 1000000,
                "found": 123,
                "message": "tip too small: the tip transfers add up to 123 lamports, the minimum is 1,000,000; raise the transfer to one of the tip accounts to at least 1,000,000 lamports",
                "retryable": false,
                "docs": "https://supanode.xyz/docs/solana/sender/reference/errors#missing_tip"
              }
            ]
          },
          "JsonRpcVersion": {
            "type": "string",
            "enum": [
              "2.0"
            ],
            "examples": [
              "2.0"
            ]
          },
          "JsonRpcError": {
            "type": "object",
            "required": [
              "code",
              "message",
              "data"
            ],
            "properties": {
              "code": {
                "type": "integer",
                "enum": [
                  -32700,
                  -32600,
                  -32601,
                  -32602,
                  -32603,
                  -32000,
                  -32001,
                  -32002,
                  -32003
                ],
                "description": "[Status codes](https://supanode.xyz/docs/solana/sender/reference/json-rpc#status-codes) maps reasons and problems to codes. Match on `data.reason`.",
                "examples": [
                  -32602
                ]
              },
              "message": {
                "type": "string",
                "description": "The same sentence as data.message."
              },
              "data": {
                "$ref": "#/x-ext/b08d7c8/components/schemas/Rejection"
              }
            },
            "additionalProperties": false
          },
          "JsonRpcId": {
            "type": [
              "string",
              "number",
              "null"
            ],
            "description": "Optional request id, echoed exactly in the response. Null when absent or refused before the id could be read.",
            "examples": [
              1,
              "request-1",
              null
            ]
          },
          "JsonRpcErrorEnvelope": {
            "type": "object",
            "required": [
              "jsonrpc",
              "error",
              "id"
            ],
            "properties": {
              "jsonrpc": {
                "$ref": "#/x-ext/b08d7c8/components/schemas/JsonRpcVersion"
              },
              "error": {
                "$ref": "#/x-ext/b08d7c8/components/schemas/JsonRpcError"
              },
              "id": {
                "$ref": "#/x-ext/b08d7c8/components/schemas/JsonRpcId"
              }
            },
            "additionalProperties": false
          }
        },
        "securitySchemes": {
          "apiKeyHeader": {
            "type": "apiKey",
            "in": "header",
            "name": "x-api-key",
            "description": "Send the SWQoS API key in this header. See the [authentication reference](https://supanode.xyz/docs/solana/sender/reference/json-rpc#authentication) for compatibility forms and precedence."
          },
          "apiKeyQuery": {
            "type": "apiKey",
            "in": "query",
            "name": "api-key",
            "description": "Compatibility authentication. See the [authentication reference](https://supanode.xyz/docs/solana/sender/reference/json-rpc#authentication) for precedence and the URL logging warning. Prefer x-api-key."
          },
          "bearer": {
            "type": "http",
            "scheme": "bearer",
            "description": "SWQoS API key sent as Authorization: Bearer YOUR_KEY. The prefix `Bearer ` is case-sensitive. Prefer x-api-key. See the [authentication reference](https://supanode.xyz/docs/solana/sender/reference/json-rpc#authentication) for precedence."
          }
        },
        "responses": {
          "RawUnauthorized": {
            "description": "[`unauthorized`](https://supanode.xyz/docs/solana/sender/reference/errors#unauthorized): missing, unknown or revoked API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/x-ext/b08d7c8/components/schemas/Rejection"
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "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,
                      "docs": "https://supanode.xyz/docs/solana/sender/reference/errors#unauthorized"
                    }
                  }
                }
              }
            }
          },
          "RawPaymentRequired": {
            "description": "[`payment_required`](https://supanode.xyz/docs/solana/sender/reference/errors#payment_required): sending is suspended until the overdue invoice is paid; `unpaid_lamports` is outstanding.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/x-ext/b08d7c8/components/schemas/Rejection"
                },
                "examples": {
                  "payment_required": {
                    "value": {
                      "reason": "payment_required",
                      "unpaid_lamports": 1000000,
                      "message": "The key is suspended until its overdue invoice is paid.",
                      "retryable": false,
                      "docs": "https://supanode.xyz/docs/solana/sender/reference/errors#payment_required"
                    }
                  }
                }
              }
            }
          },
          "RawBundlesForbidden": {
            "description": "[`unsupported`](https://supanode.xyz/docs/solana/sender/reference/errors#unsupported): `feature: bundles` when bundles are disabled, or `feature: partner_declared_tips` when a partner key declares a tip.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/x-ext/b08d7c8/components/schemas/Rejection"
                },
                "examples": {
                  "unsupported": {
                    "value": {
                      "reason": "unsupported",
                      "feature": "bundles",
                      "message": "bundles are not enabled for this key; ask Supanode to enable them",
                      "retryable": false,
                      "docs": "https://supanode.xyz/docs/solana/sender/reference/errors#unsupported"
                    }
                  },
                  "partner_declared_tips": {
                    "value": {
                      "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,
                      "docs": "https://supanode.xyz/docs/solana/sender/reference/errors#unsupported"
                    }
                  }
                }
              }
            }
          },
          "MisdirectedRequest": {
            "description": "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": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "examples": {
                  "UnknownHost": {
                    "value": "This hostname is not served here. Check the endpoint address"
                  }
                }
              }
            }
          },
          "RawRateLimited": {
            "description": "[`rate_limited`](https://supanode.xyz/docs/solana/sender/reference/errors#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": {
              "application/json": {
                "schema": {
                  "$ref": "#/x-ext/b08d7c8/components/schemas/Rejection"
                },
                "examples": {
                  "rate_limited": {
                    "value": {
                      "reason": "rate_limited",
                      "limit": "transactions",
                      "message": "rate limited: too many transactions from this key; retry shortly",
                      "retryable": true,
                      "docs": "https://supanode.xyz/docs/solana/sender/reference/errors#rate_limited"
                    }
                  }
                }
              }
            }
          },
          "RawUnavailable": {
            "description": "JSON rejection body; submission is temporarily unavailable.\n- [`not_ready`](https://supanode.xyz/docs/solana/sender/reference/errors#not_ready): edge not ready.\n- [`overloaded`](https://supanode.xyz/docs/solana/sender/reference/errors#overloaded): edge temporarily busy.\n- [`forward_failed`](https://supanode.xyz/docs/solana/sender/reference/errors#forward_failed): transaction could not be dispatched.\n- [`preflight_unavailable`](https://supanode.xyz/docs/solana/sender/reference/errors#preflight_unavailable): simulation unavailable.\n- [`internal`](https://supanode.xyz/docs/solana/sender/reference/errors#internal): internal error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/x-ext/b08d7c8/components/schemas/Rejection"
                },
                "examples": {
                  "not_ready": {
                    "value": {
                      "reason": "not_ready",
                      "waiting_for": "leader_route",
                      "message": "the region is not ready to send yet; retry in a moment",
                      "retryable": true,
                      "docs": "https://supanode.xyz/docs/solana/sender/reference/errors#not_ready"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
