BSV blockchainBSV blockchain

Broadcast transactions with BSV Broadcaster

BSV Broadcaster is BSV Association’s transaction broadcaster, and it replaces ARCThe broadcaster that came before BSV Broadcaster. BSV Broadcaster keeps most of its request and response shapes, but the ARC class of @bsv/sdk does not work with it and mAPIMerchant API: the broadcast API that came before ARC. It takes a signed transaction over HTTP, delivers it to the network, follows it until a miner includes it in a block, and returns the merkle path that proves it.

Use it when your app or server builds and signs transactions itself and has to send them. An app that uses WalletClient does not need BSV Broadcaster to broadcast, because the wallet broadcasts the transactions it creates. When the app acts on a payment, for example to deliver an order or collect a tip, it also submits the same transaction to BSV Broadcaster and reads its status there. Submitting a transaction BSV Broadcaster already has is safe. In this guide you pick an endpoint, check its limits, submit a transaction and read its status.

BSV Broadcaster was called Arcade until version 0.19.0. The public hostnames still contain arcade, and so does the Python SDK class. If you run your own instance, follow the migration guide before you upgrade, because the storage path, the configuration directory and the environment variable prefix changed.

Before you begin

You need curl, and for the SDK example Node.js 22 or newer. To submit a transaction you also need a fully signed one, as hex. This guide does not build it: create it with @bsv/sdk, as described on the SDK page.

BSV Broadcaster has public endpoints for testnet and for Mainnet. This guide uses testnet, where the coins have no value. A valid transaction you submit to a Mainnet endpoint spends real BitcoinSV (BSV), and a blockchain transaction cannot be reversed.

How it works

Your app submits the transaction and then follows it. BSV Broadcaster reports each step as it happens:

  1. Submit

    POST /tx
    Your app

    Sends the signed transaction as hex or bytes.

    BSV Broadcaster

    Checks the fee and the scripts, then answers 202 and delivers it to Teranode.

  2. Follow

    GET /tx/TXID
    Your app

    Asks for the status, or listens for events or a webhook.

    BSV Broadcaster

    Reports each step, from RECEIVED to MINED.

  3. Prove

    merklePath
    Your app

    Keeps the merkle path from the MINED answer.

    BSV Broadcaster

    Returns the proof once the transaction is in a block, so you can verify it with block headers.

A 202 answer means BSV Broadcaster checked the transaction and accepted it for delivery. It does not mean a miner has it. Follow the status until it reaches SEEN_ON_NETWORK or MINED.

Check an endpoint

The public endpoints are open and need no API key:

NetworkOperatorURL
testnetBSV Associationhttps://arcade-v2-testnet-us-1.bsvblockchain.tech
MainnetBSV Association, United Stateshttps://arcade-us-1.bsvblockchain.tech
MainnetBSV Association, Europehttps://arcade-eu-1.bsvblockchain.tech
MainnetBSV Association, Asia-Pacifichttps://arcade-ap-1.bsvblockchain.tech
MainnetGorillaPoolhttps://arcade.gorillapool.io

To go live, change the address to a Mainnet endpoint and read Move your app to mainnet. Check the limits of the endpoint before you build a transaction:

Read the policy

Each endpoint publishes the fee and the sizes it accepts:

curl -s https://arcade-v2-testnet-us-1.bsvblockchain.tech/policy
{"policy":{"miningFee":{"satoshis":1,"bytes":1000},"maxtxsizepolicy":100000000,...},"timestamp":"..."}

The miningFee is the lowest fee rate the endpoint accepts, here 1 satoshiThe smallest unit of BSV. 100,000,000 satoshis make 1 BSV for each 1,000 bytes. A transaction that pays less is refused. At the time of writing the Mainnet endpoints ask for 100 satoshis for each 1,000 bytes, so read the policy of the endpoint you use.

Check that it is healthy

Ask the endpoint for its status:

curl -s https://arcade-v2-testnet-us-1.bsvblockchain.tech/health
{"healthy":true,"version":"v0.16.0","status":"ok","blockHeight":1764512,"datahub_urls":[...]}

healthy is true when the endpoint is connected to the network, and blockHeight is the block it has reached.

Try an invalid transaction

Send input that is not a transaction, to see how BSV Broadcaster refuses it. Nothing is broadcast:

curl -s -X POST https://arcade-v2-testnet-us-1.bsvblockchain.tech/tx \
  -H "Content-Type: text/plain" \
  --data "00"
{"error":"failed to parse transaction"}

The answer is a 400, which BSV Broadcaster gives whenever the transaction itself is wrong.

Choose the format

BSV Broadcaster takes the transaction in two formats:

  • Raw: the transaction as it appears on the chain
  • EFExtended Format (BRC-30): the raw transaction plus the satoshis and locking script of every output it spends: preferred, because BSV Broadcaster can check the fee and the scripts without looking up the outputs the transaction spends

BSV Broadcaster does not accept BEEFBackground Evaluation Extended Format (BRC-62): a transaction with the evidence a host needs to verify it.. Convert it to EF before you submit. A body can be up to 32 MiB, and it can be hex with Content-Type: text/plain, raw bytes with application/octet-stream, or JSON as { "rawTx": "HEX" } with application/json.

Submit a transaction

With a signed transaction in hand, send it to the endpoint you picked.

Submit with curl

Replace YOUR_SIGNED_TX_HEX with the hex of your transaction:

curl -s -X POST https://arcade-v2-testnet-us-1.bsvblockchain.tech/tx \
  -H "Content-Type: text/plain" \
  --data "YOUR_SIGNED_TX_HEX"
{"txid":"9f2b…","status":202,"txStatus":"RECEIVED"}

The txid is the identifier you follow in the next section. Submitting the same transaction again is safe: BSV Broadcaster answers 202 again, with the status the transaction has reached.

Submit with TypeScript

To submit from your app, use the Teranode broadcaster of @bsv/sdk with the /tx address of the endpoint. Here tx is your signed Transaction, and every input of it needs its sourceTransaction, so that the SDK can produce EF. This example was tested with @bsv/sdk 3.2.1:

import { Transaction, Teranode } from '@bsv/sdk'

const broadcaster = new Teranode('https://arcade-v2-testnet-us-1.bsvblockchain.tech/tx')

const result = await tx.broadcast(broadcaster)
console.log(result)
{ status: 'success', txid: '9f2b…', message: 'broadcast successful' }

Do not point the ARC class of the SDK at BSV Broadcaster, it calls a path BSV Broadcaster does not serve. A call to tx.broadcast() with no argument uses GorillaPool’s ARC, so pass the Teranode broadcaster as above.

The other SDKs work too. In the Go SDK, give the Arc broadcaster the endpoint root as ApiUrl, without /tx. The Python SDK has its own Arcade class. See Using BSV Broadcaster from the SDKs.

Follow the transaction

Read the status

Ask BSV Broadcaster for the status of the txid:

curl -s https://arcade-v2-testnet-us-1.bsvblockchain.tech/tx/TXID

The txStatus field says where the transaction is. Once it is mined, the answer looks like this:

{"txid":"9f2b…","txStatus":"MINED","blockHash":"0000…","blockHeight":972090,"merklePath":"BUMP_HEX"}

Statuses

These are the statuses you will see most:

StatusWhat it means
RECEIVEDBSV Broadcaster checked it and queued it
SENT_TO_NETWORKDelivered to at least one TeranodeThe node software of the BSV blockchain node
ACCEPTED_BY_NETWORKA Teranode node accepted it into its mempoolThe set of valid transactions a node holds until a miner includes them in a block
SEEN_ON_NETWORKObserved in a miner’s subtree. Safe to treat as zero-confirmation, before it is mined
MINEDIn a block. The answer now carries blockHash, blockHeight and merklePath
IMMUTABLEEnough blocks are on top that a reorganizationA reorganization, or reorg: the network switches to a longer chain, and the blocks it leaves are orphaned is no longer a practical concern
PENDING_RETRYDelivery failed and BSV Broadcaster tries again. Read extraInfo for the reason
REJECTEDThe network rejected it. Final
DOUBLE_SPEND_ATTEMPTEDAnother transaction spends the same output, and competingTxs lists it. Final

The merklePath of a mined transaction is a BUMPBRC-74: a compact merkle path that proves a transaction is in a block. Keep it, because it is the proof that your app needs to verify the transaction with block headers. If the block is orphanedLeft out of the chain after a reorganization. Its transactions return to the mempool and go into another block, BSV Broadcaster moves the transaction to the replacement block and sends a new MINED status with a new merklePath. Replace the stored proof each time a new MINED status arrives, and keep following the transaction until it reaches IMMUTABLE.

Get notified instead of polling

Instead of asking again and again, you can have BSV Broadcaster tell you. Choose one of two ways when you submit:

  • Events: send an X-CallbackToken header with a token you choose, then read the events of that token with curl -N "ENDPOINT/events?callbackToken=YOUR_TOKEN"
  • Webhook: send an X-CallbackUrl header, and BSV Broadcaster posts each change to that address, which must be reachable from the internet

Add X-FullStatusUpdates: true to get every intermediate status, not only the final ones. A webhook request has a User-Agent that starts with bsv-broadcaster-webhook/, or with arcade-webhook/ from an endpoint that runs a version before 0.19.0. The public endpoints ran 0.16.0 on 28 October 2026, so if you filter callbacks by User-Agent, allow both.

The Teranode broadcaster of the SDK sends neither header. Use curl, or write your own Broadcaster that adds them.

Each event of the stream looks like this:

id: 1716205260987654321
event: status
data: {"txid":"9f2b…","txStatus":"MINED","timestamp":"..."}

The id is the time of the event in nanoseconds. If the stream drops, reconnect with a Last-Event-ID header set to the last id you saw, and the endpoint replays the events you missed. A browser EventSource sends this header on its own.

Handle failures

  • Keep the signed transaction until you have seen it on the network
  • After a timeout or a 503 (BSV Broadcaster is under backpressure and queued nothing), send the same bytes again. Do not build a new transaction from the same inputs, or you can double spend against your own first attempt
  • A 400 is final. Fix the transaction before you send it again. The one exception is code 476, a locktime that has not passed yet: send the same transaction again after it passes
  • Have a second route ready, for when the endpoint is unreachable. Another public endpoint works, and so does an explorer API or a node. Ways to broadcast compares them

Troubleshooting

400 failed to parse transaction #

The body is not a complete transaction. Check that the hex is complete, and that Content-Type matches the body: text/plain for hex.

404 transaction not found #

{"error":"transaction not found"} means this endpoint has never seen the txid. Ask the same endpoint you submitted to, because each one keeps its own records.

Status stays PENDING_RETRY with TX_MISSING_PARENT #

The network does not know an output the transaction spends. In extraInfo the status shows TX_MISSING_PARENT and the txid of the missing transaction. BSV Broadcaster accepted the transaction at intake, because EF carries the data of the spent outputs, and keeps retrying. Check that the transaction that created the output is on the network, and that you are on the right network.

Next steps

With a transaction broadcast, continue with: