Using the Blockdaemon Stellar Relayer (Channels)

High-throughput Stellar and Soroban applications quickly run into a classic bottleneck: a single source account can only have one transaction in flight at a time, because Stellar sequence numbers are strictly ordered. Running your own pool of "channel accounts" to work around this means managing extra keys, funding, and submission logic.

Blockdaemon's Stellar Relayer removes that work. It's a hosted deployment of OpenZeppelin's Relayer, configured with the Stellar Channels plugin, so you submit transactions through a simple HTTPS API and Blockdaemon handles channel account pooling, fee-bumping, and parallel submission behind the scenes.

1. Who This Guide Is For

This page is for teams that:

• Submit a high volume of Stellar or Soroban transactions and are hitting sequence-number contention from a single account.
• Want managed transaction submission without operating their own relayer infrastructure or channel-account pool.
• Are integrating against Soroban smart contracts and need reliable parallel invocation.

By the end, you should be able to:

• Obtain an API key for mainnet or testnet.
• Submit a transaction two different ways, depending on how much control you need.
• Handle the relayer's error responses and rate limits correctly.

2. How It Works

The Channels relayer sits in front of a pool of dedicated Stellar accounts ("channels"). When you submit a transaction, the relayer picks an available channel account, wraps your operation into a transaction from that account, signs it, and submits it to the network, all without you needing to manage sequence numbers or hold funds in the submitting account. A separate Blockdaemon-managed fee account covers network fees via fee-bump transactions.

📘

Info

You still choose what gets submitted (a Soroban invocation or a fully-built transaction). Blockdaemon's relayer only owns which account submits it and how fees are paid.

3. Service Endpoints

All requests below are relative to the base URL for the network you're targeting.

4. Getting Started

4.1 Generate an API Key

curl https://channels-testnet.blockdaemon.tech/gen

{
  "apiKey": "5f1e2d3c-4b5a-6789-0abc-def123456789"
}

Store this key securely, it's shown once and isn't recoverable. Key issuance is rate-limited per IP address (currently 2 keys per hour), so avoid generating keys in a loop.

4.2 Check Service Health

curl https://channels-testnet.blockdaemon.tech/api/v1/health

{
  "status": "ok"
}

This endpoint is unauthenticated and safe to use for uptime checks.

5. Submitting a Transaction

The relayer accepts two request shapes, depending on how much control you need over the transaction.

Method 1: Soroban Function + Auth (Recommended)

Send the function invocation and its authorization entries, and let the relayer build, sign, and submit the transaction using a pooled channel account. This is the simplest path for most Soroban calls.

curl -X POST https://channels-testnet.blockdaemon.tech/ \
  -H "Authorization: Bearer $CHANNELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "func": "AAAABAAAAAEAAAAGc3ltYm9s...",
    "auth": ["AAAACAAAAAEAAAA..."]
  }'

• func — base64-encoded XDR of the HostFunction to invoke (e.g. op.func.toXDR("base64") from js-stellar-sdk).
• auth — array of base64-encoded SorobanAuthorizationEntry XDR strings (e.g. (op.auth ?? []).map(a => a.toXDR("base64"))).

Method 2: Pre-Signed Transaction XDR

If you need full control over the transaction — a classic payment, a multi-operation transaction, or a Soroban call you've already built and signed yourself — submit the signed envelope directly:

curl -X POST https://channels-testnet.blockdaemon.tech/ \
  -H "Authorization: Bearer $CHANNELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "xdr": "AAAAAgAAAAA..."
  }'

• xdr — base64-encoded signed transaction envelope XDR.

🚧

Warning

Use one method or the other, not both. Sending xdr together with func/auth returns an INVALID_PARAMS error.

6. Response Format

A successful submission returns:

{
  "transactionId": "txn_01hq...",
  "hash": "a1b2c3d4...",
  "status": "confirmed"
}

7. Rate Limits

• Key issuance (/gen) is limited per source IP. If you exceed it, you'll get a 429 with a Retry-After header, so wait before retrying.

• Per-key submissions are limited to 60 requests per minute per API key. Exceeding it returns:

  Response - 429

  {
    "success": false,
    "code": 429,
    "error": "Too Many Requests",
    "message": "Rate limit exceeded"
  }

• Mainnet additionally enforces a shared daily cap on total transaction volume across all callers, to protect channel-account capacity. If the cap is reached, you'll get a 429 with a Retry-After header, back off and retry after that interval.

8. Error Handling

Errors are returned in the response body with a code field you can branch on:

❗️

Important

A 401 Unauthorized means your API key is missing, inactive, or was issued by a different environment (a testnet key won't work against the mainnet endpoint, and vice versa).

9. Responsibility Boundaries

• You own: Constructing the Soroban invocation or transaction, choosing when to submit, and handling the response in your application.
• Blockdaemon provides: The channel-account pool, transaction signing, fee-bump payment, parallel submission, and relayer uptime.

10. Where to Go Next

• Accepting agentic payments on Stellar? See the x402 payments guide — Blockdaemon's x402 facilitator settles payments through this same Channels relayer.
• Running Stellar infrastructure more broadly? See Dedicated Stellar Nodes and Institutional Payments on Stellar.
• Need a higher rate limit, a static key, or production support? Contact your Blockdaemon account team.