Falcon submission methods

Every route takes one signed Solana transaction per request. Which one you want depends on what your client is already holding, and on whether you need an answer back.

The decoded transaction is capped at 1,232 bytes everywhere; the larger JSON-RPC and /plaintext limits cover the envelope and the base64 expansion on top of it.

Authenticate

http://fra.falcon.wtf/binary?api-key=00000000-0000-0000-0000-000000000000

Anything that stores a full URL stores your key with it; Telemetry covers what not to record.

JSON-RPC

POST to the region root. There are two methods.

Anything else comes back as -32601 method not found. There are no batch arrays; send a single request object.

sendTransaction parameters

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sendTransaction",
  "params": [
    "SIGNED_TRANSACTION_BASE64",
    { "encoding": "base64", "skipPreflight": true }
  ]
}

Send a base64 string without "encoding":"base64" and you get -32602 transaction string is not valid base58.

Preflight

Set skipPreflight: false and Falcon simulates the transaction, signature verification included, against an upstream RPC before forwarding. A short server-side timeout bounds the wait.

None of those forward the transaction.

Reading responses

{"jsonrpc":"2.0","result":"5Yv...signature...","id":1}

JSON-RPC errors come back with HTTP 200 and an error object. Two of them do carry a matching status: 401 with -32000 unauthorized, and 429 with -32001 rate limit exceeded. The full table is on Falcon errors & retries.

HTTP /binary

For when you're already holding serialized transaction bytes. No envelope, no length prefix, no key in the body.

curl -sS -X POST "http://fra.falcon.wtf/binary?api-key=${FALCON_API_KEY}" \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @transaction.bin

HTTP /plaintext

Base64 transaction text, no JSON envelope. Whitespace around it is trimmed for you.

curl -sS -X POST "http://fra.falcon.wtf/plaintext?api-key=${FALCON_API_KEY}" \
  -H 'Content-Type: text/plain' \
  --data "${TX_BASE64}"

Both raw routes check size, signatures and tip; neither runs preflight.

QUIC with falcon-client

The published Rust SDK handles the persistent connection, serialization, authentication and one reconnect-and-retry for you.

[dependencies]
falcon-client = "0.1"
uuid          = "1"

use {falcon_client::FalconClient, uuid::Uuid};

let api_key = Uuid::parse_str("YOUR_API_KEY_UUID")?;
let mut client = FalconClient::connect("fra.falcon.wtf:5000", api_key).await?;

client.send_transaction(&transaction).await?;

Other entry points, if you need them:

Transport modes

use falcon_client::TransportMode;

client.set_transport_mode(TransportMode::Datagram);
client.send_transaction(&transaction).await?;

Delivery semantics

HTTP and QUIC stream mode acknowledge acceptance. QUIC datagram mode and native UDP acknowledge nothing.

Falcon keeps a signature-keyed cache of recent submissions and suppresses a duplicate, but only once that signature has already been delivered. That's why resending the same signed bytes while the blockhash is still valid is still the right way to chase a landing.

Don't re-sign to retry, though. A new signature is a different transaction, and it can land independently of the first.

Related

• Falcon native UDP
• Falcon tips & transaction requirements
• Falcon errors & retries