BSV blockchainBSV blockchain

Submit a single transaction

POST/v1/tx

Submits a single raw transaction to the ARC network. The body must be a JSON object with a rawTx field containing the hex-encoded transaction.

The SDK tries Extended Format (EF) first (tx.toHexEF()). If EF is not available (source transactions missing), it falls back to raw hex (tx.toHex()).

ARC may return HTTP 200 with txStatus values that indicate failure (e.g. DOUBLE_SPEND_ATTEMPTED, REJECTED, INVALID, MALFORMED, MINED_IN_STALE_BLOCK, or any status containing ORPHAN). These are treated as broadcast failures by the SDK.

Header Parameters

Authorizationstring

Bearer token: Bearer <apiKey>

XDeployment-IDstring

Deployment identifier for correlating requests. Auto-generated if not set.

X-CallbackUrlstring

HTTPS URL to which ARC will POST a Merkle proof callback once the transaction has been mined.

X-CallbackTokenstring

Bearer token that ARC will include in the Authorization header when calling the callback URL. Used to verify the callback origin.

Body application/json

rawTxstringrequired

Hex-encoded raw transaction. The ts-sdk attempts Extended Format (EF) first; falls back to standard raw hex when source transactions are missing.

Response

Transaction accepted (or accepted with a warning status). Note: ARC may return HTTP 200 with a txStatus that indicates rejection. Callers must inspect txStatus to determine success vs. failure.

txidstring

Transaction ID.

txStatus"STORED" | "ANNOUNCED_TO_NETWORK" | "REQUESTED_BY_NETWORK" | "SENT_TO_NETWORK" | "ACCEPTED_BY_NETWORK" | "SEEN_ON_NETWORK" | "MINED" | "SEEN_IN_ORPHAN_MEMPOOL" | "DOUBLE_SPEND_ATTEMPTED" | "REJECTED" | "INVALID" | "MALFORMED" | "MINED_IN_STALE_BLOCK" | "UNKNOWN"

Network status of the transaction as reported by ARC. Success statuses (HTTP 200, not treated as failure):

  • STORED — received but not yet broadcast
  • ANNOUNCED_TO_NETWORK — gossiped to peers
  • REQUESTED_BY_NETWORK — requested by a peer
  • SENT_TO_NETWORK — submitted to the network
  • ACCEPTED_BY_NETWORK — accepted by at least one miner
  • SEEN_ON_NETWORK — seen propagating on the network
  • MINED — included in a block (Merkle proof available)
  • SEEN_IN_ORPHAN_MEMPOOL — in an orphan block mempool (not a stable success) Failure statuses (HTTP 200 body, treated as BroadcastFailure by ts-sdk):
  • DOUBLE_SPEND_ATTEMPTED
  • REJECTED
  • INVALID
  • MALFORMED
  • MINED_IN_STALE_BLOCK
  • (any value containing “ORPHAN” in extraInfo or txStatus) Unknown:
  • UNKNOWN
extraInfostring

Additional human-readable context about the status.

competingTxsstring[]

Present when txStatus is DOUBLE_SPEND_ATTEMPTED. Lists competing transaction IDs.

Bad request — malformed payload.

txidstring

Transaction ID if known at the time of error.

detailstring

Human-readable error detail. Mapped to description in BroadcastFailure.

statusinteger

HTTP status code echoed in the body (ARC convention).

titlestring

Short error title.

typestring<uri>

URI identifying the error type.

instancestring

URI identifying the specific occurrence.

extraInfostring

Missing or invalid Authorization header.

txidstring

Transaction ID if known at the time of error.

detailstring

Human-readable error detail. Mapped to description in BroadcastFailure.

statusinteger

HTTP status code echoed in the body (ARC convention).

titlestring

Short error title.

typestring<uri>

URI identifying the error type.

instancestring

URI identifying the specific occurrence.

extraInfostring

Conflict — e.g. transaction already known.

txidstring

Transaction ID if known at the time of error.

detailstring

Human-readable error detail. Mapped to description in BroadcastFailure.

statusinteger

HTTP status code echoed in the body (ARC convention).

titlestring

Short error title.

typestring<uri>

URI identifying the error type.

instancestring

URI identifying the specific occurrence.

extraInfostring

Unprocessable entity — invalid transaction.

txidstring

Transaction ID if known at the time of error.

detailstring

Human-readable error detail. Mapped to description in BroadcastFailure.

statusinteger

HTTP status code echoed in the body (ARC convention).

titlestring

Short error title.

typestring<uri>

URI identifying the error type.

instancestring

URI identifying the specific occurrence.

extraInfostring

Rate limit exceeded.

txidstring

Transaction ID if known at the time of error.

detailstring

Human-readable error detail. Mapped to description in BroadcastFailure.

statusinteger

HTTP status code echoed in the body (ARC convention).

titlestring

Short error title.

typestring<uri>

URI identifying the error type.

instancestring

URI identifying the specific occurrence.

extraInfostring

ARC internal error.

txidstring

Transaction ID if known at the time of error.

detailstring

Human-readable error detail. Mapped to description in BroadcastFailure.

statusinteger

HTTP status code echoed in the body (ARC convention).

titlestring

Short error title.

typestring<uri>

URI identifying the error type.

instancestring

URI identifying the specific occurrence.

extraInfostring
Request
curl -X POST "https://arc.taal.com/v1/tx" \
  -H "Content-Type: application/json" \
  -H "Authorization: <Authorization>" \
  -H "XDeployment-ID: <XDeployment-ID>" \
  -H "X-CallbackUrl: <X-CallbackUrl>" \
  -H "X-CallbackToken: <X-CallbackToken>" \
  -d '{
  "rawTx": "0100000001..."
}'
Response
{
  "txid": "string",
  "txStatus": "STORED",
  "extraInfo": "string",
  "competingTxs": [
    "string"
  ]
}