Arcade · BSV Transaction Broadcaster

The world's most scalable transaction broadcast manager

A high-throughput, callback-driven gateway for submitting BSV transactions, tracking their lifecycle, and streaming status updates to subscribers in real time.

API Reference

Click any endpoint to expand its full request / response contract, headers, and examples. The defaults below cover the everyday submit-and-track flow.

Base URL
—
Content Encoding
UTF-8
Status Codes
2xx · 4xx · 5xx

Reports liveness of the API server process and the upstream Datahub endpoints it depends on. Suitable as a Kubernetes liveness probe.

Response

200 OK
{
  "status": "ok",
  "datahub_urls": [
    { "url": "https://...", "healthy": true }
  ]
}

Indicates that the process has finished start-up and is ready to accept traffic. Suitable as a Kubernetes readiness probe.

Response

200 OK
{
  "status": "ready"
}

Returns the current lifecycle state of a previously submitted transaction, including its merkle path once mined.

Headers

HeaderRequirementDescription
Accept Optional application/json (default).

Response

200 OK
{
  "txid": "<hex>",
  "txStatus": "SEEN_ON_NETWORK",
  "status": "SEEN_ON_NETWORK",
  "timestamp": "2026-05-20T12:00:00Z",
  "blockHash": "<hex|null>",
  "blockHeight": 870123,
  "merklePath": "<BUMP hex|null>",
  "extraInfo": "",
  "competingTxs": []
}

Long-lived Server-Sent Events stream that pushes lifecycle updates for every transaction submitted under the supplied callback token. Hosted by Arcade's standalone SSE service — a separate listener from the main API (default port 8082, fronted by its own Kubernetes Service in production). CORS is permissive on this endpoint so browsers can connect directly with the EventSource API.

Headers

HeaderRequirementDescription
Accept Recommended text/event-stream
Last-Event-ID Optional Nanosecond timestamp returned by Arcade as the id of the last event the client received. Triggers a catchup replay of every status update that occurred strictly after this timestamp. Omit on first connect to receive the current persisted status of every txid registered under the token.

Request Body

?callbackToken=<token> the same opaque token sent as X-CallbackToken when submitting transactions. Scopes the stream to that token's transactions.

GET /events?callbackToken=my-token

Open a stream from JavaScript. Last-Event-ID is handled automatically by the browser on reconnect.

const es = new EventSource(
  "https://arcade.example.com/events?callbackToken=my-token"
);
es.addEventListener("status", (e) => {
  const status = JSON.parse(e.data);
  console.log(status.txid, status.txStatus);
});

Tail the stream from a shell.

curl -N "https://arcade.example.com/events?callbackToken=my-token"

Response

200 OK · text/event-stream
id: 1716205200123456789
event: status
data: {"txid":"<hex>","txStatus":"SEEN_ON_NETWORK","timestamp":"2026-05-20T12:00:00Z"}

id: 1716205260987654321
event: status
data: {"txid":"<hex>","txStatus":"MINED","timestamp":"2026-05-20T12:01:00Z"}

: keepalive

Submits one Bitcoin SV transaction for validation, propagation, and lifecycle tracking. Synchronous policy validation runs before the 202 is returned; fee and script checks are delegated to the network. Pick the body encoding that matches your client — raw bytes are the most efficient.

Headers

HeaderRequirementDescription
Content-Type Required One of application/octet-stream, text/plain (hex), or application/json — see the request body tabs below.
X-CallbackUrl Optional Webhook URL Arcade should POST status events to as this transaction progresses through the network. Must be a public HTTPS endpoint; private/loopback hosts are rejected unless the deployment is configured to allow them.
X-CallbackToken Recommended Opaque bearer token. Sent on every outbound webhook as Authorization: Bearer <token>, and used to scope Server-Sent Events streams when the client subscribes via SSE.
X-FullStatusUpdates Optional Set to "true" to receive every status transition (RECEIVED, SEEN_ON_NETWORK, SEEN_ON_MULTIPLE_NODES, MINED, IMMUTABLE). Default behavior delivers only terminal/notable transitions.

Request Body

Raw serialized transaction bytes. Most efficient — no encoding overhead. Supports Extended Format; the canonical txid is derived from the parsed transaction structure, not from a hash of the wire bytes.

<binary raw transaction bytes>

Hex-encoded serialized transaction as a UTF-8 string. Whitespace is trimmed before decoding.

0100000001abc...def00000000

JSON envelope carrying the hex-encoded transaction. Useful for clients that cannot easily send a raw or text/plain body.

{
  "rawTx": "0100000001abc...def00000000"
}

Response

202 Accepted
{
  "status": "submitted"
}

// Idempotent re-submit of a txid Arcade has already seen:
{
  "status": "already submitted",
  "txid": "<hex>",
  "state": "SEEN_ON_NETWORK"
}

Submits a batch of concatenated raw transactions in a single HTTP request. Each transaction is parsed, validated, dedup-CAS'd, and published as part of one fan-out. Bodies are capped at 256 MiB.

Headers

HeaderRequirementDescription
Content-Type Required application/octet-stream — the only encoding accepted for batches.
X-CallbackUrl Optional Webhook URL Arcade should POST status events to as this transaction progresses through the network. Must be a public HTTPS endpoint; private/loopback hosts are rejected unless the deployment is configured to allow them.
X-CallbackToken Recommended Opaque bearer token. Sent on every outbound webhook as Authorization: Bearer <token>, and used to scope Server-Sent Events streams when the client subscribes via SSE.
X-FullStatusUpdates Optional Set to "true" to receive every status transition (RECEIVED, SEEN_ON_NETWORK, SEEN_ON_MULTIPLE_NODES, MINED, IMMUTABLE). Default behavior delivers only terminal/notable transitions.

Request Body

Concatenated raw transaction bytes. No length prefixes or separators — each transaction is parsed sequentially using the stream parser.

<binary raw tx 1><binary raw tx 2>...<binary raw tx N>

Response

202 Accepted
{
  "submitted": 42,
  "duplicates": 3,
  "total": 45
}

Internal endpoint used by the Merkle Service to deliver SEEN_ON_NETWORK, SEEN_ON_MULTIPLE_NODES, STUMP and BLOCK_PROCESSED events. Bearer authentication is mandatory; the deployment refuses to start without a configured callback token.

Headers

HeaderRequirementDescription
Authorization Required Bearer <callback_token>. Compared in constant time against the configured token.
Content-Type Required application/json

Request Body

CallbackMessage envelope; the type field discriminates the variant.

{
  "type": "SEEN_ON_NETWORK",
  "txid": "<hex>",
  "txids": ["<hex>", "..."],
  "blockHash": "<hex>",
  "subtreeIndex": 0,
  "stump": "<base64>"
}

Response

200 OK
(empty body)

Lists block processing milestones (header seen, BLOCK_PROCESSED received, compound BUMP built) in descending-height order. Paginates via a height-cursor; pass the lowest height returned from the previous page as before-height to fetch the next page.

Headers

HeaderRequirementDescription
Accept Optional application/json (default).

Request Body

?limit=<int> default 50, max 200. ?before-height=<int> cursor — pass the lowest height from the previous page.

GET /api/v1/blocks/processing-status?limit=50&before-height=870000

Response

200 OK
{
  "blocks": [
    {
      "blockHash": "<hex>",
      "blockHeight": 870123,
      "headerSeenAt": "2026-05-20T12:00:00Z",
      "processedAt": "2026-05-20T12:00:30Z",
      "bumpBuiltAt": "2026-05-20T12:00:45Z",
      "status": "compound-bump-built",
      "orphanedAt": null,
      "hasBlockProcessed": true,
      "hasCompoundBUMP": true
    }
  ],
  "nextCursor": 870000
}

Returns the block processing milestones for one block, looked up by block hash.

Response

200 OK
{
  "blockHash": "<hex>",
  "blockHeight": 870123,
  "headerSeenAt": "2026-05-20T12:00:00Z",
  "processedAt": "2026-05-20T12:00:30Z",
  "bumpBuiltAt": "2026-05-20T12:00:45Z",
  "status": "compound-bump-built",
  "orphanedAt": null,
  "hasBlockProcessed": true,
  "hasCompoundBUMP": true
}

Requests that the upstream Merkle Service re-emit STUMP and BLOCK_PROCESSED callbacks for the given block hash. Useful for healing a deployment whose callback stream missed a block.

Response

202 Accepted
{
  "status": "accepted",
  "blockHash": "<hex>"
}