{
  "openapi": "3.0.3",
  "info": {
    "title": "BSV Broadcaster API",
    "description": "REST API for **BSV Broadcaster** — a Bitcoin SV transaction broadcasting and\nlifecycle-tracking service. Clients submit transactions, look up their\nstatus, subscribe to status updates (via webhooks or Server-Sent Events),\nand inspect block-processing milestones.\n\n## Services and ports\n\nBSV Broadcaster is decomposed into independent services, each binding its own HTTP\nport. The endpoints in this document are split across three of them:\n\n| Service       | Default port | Endpoints                                                                 |\n|---------------|--------------|---------------------------------------------------------------------------|\n| `api-server`  | `8080`       | `/`, `/health`, `/ready`, `/metrics`, `/tx`, `/txs`, `/tx/{txid}`, `/api/v1/*` |\n| `sse`         | `8082`       | `/events`                                                                 |\n| `chaintracks` | `8083`       | `/chaintracks/v1/*`, `/chaintracks/v2/*`                                   |\n\nOperations that are not served by the default `api-server` declare their own\n`servers` override. Adjust the host/port to match your deployment — in\nproduction each service sits behind its own Kubernetes Service.\n\n## Callback subscriptions\n\n`POST /tx` and `POST /txs` accept optional `X-CallbackUrl` /\n`X-CallbackToken` / `X-FullStatusUpdates` headers. Supplying a callback URL\nregisters an outbound webhook; supplying a token scopes a Server-Sent Events\nstream on the `sse` service. See the individual operations for details.\n",
    "version": "1.0.0",
    "license": {
      "name": "Apache License 2.0",
      "url": "https://github.com/bsv-blockchain/broadcaster/blob/main/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:8080",
      "description": "api-server (local default)"
    },
    {
      "url": "https://broadcaster.example.com",
      "description": "Production api-server (behind ingress)"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "Transactions",
      "description": "Submit transactions and look up their lifecycle status."
    },
    {
      "name": "Blocks",
      "description": "Inspect block-processing milestones and trigger reprocessing."
    },
    {
      "name": "Callbacks",
      "description": "Internal endpoint used by the Merkle Service to deliver events."
    },
    {
      "name": "Events",
      "description": "Server-Sent Events stream of transaction status updates. Hosted by the\nstandalone `sse` service (default port **8082**), not the api-server.\n"
    },
    {
      "name": "Chaintracks",
      "description": "Embedded block-header tracker (go-chaintracks). Hosted by the standalone\n`chaintracks` service (default port **8083**). Exposes JSON and binary\nheader endpoints plus tip/reorg SSE streams under `/chaintracks/v1`\n(legacy RPC-style) and `/chaintracks/v2` (current).\n"
    },
    {
      "name": "Operations",
      "description": "Liveness, readiness, and metrics endpoints."
    }
  ],
  "paths": {
    "/": {
      "get": {
        "operationId": "getDocsPage",
        "tags": [
          "Operations"
        ],
        "summary": "API documentation page",
        "description": "Renders the human-readable HTML API documentation page.",
        "responses": {
          "200": {
            "description": "HTML documentation page.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "getHealth",
        "tags": [
          "Operations"
        ],
        "summary": "Liveness probe",
        "description": "Reports liveness of the API server process and the upstream Datahub\nendpoints it depends on. Suitable as a Kubernetes liveness probe.\n\n`blockHeight` is this instance's own processed chain-tip height — a\nfreshness signal, not a liveness gate. `datahub_urls[].healthy` is\nreachability-only, so an instance can report healthy while its chain\nview is stale; clients that compare `blockHeight` against the real\nnetwork tip can detect a lagging instance and route around it.\n",
        "responses": {
          "200": {
            "description": "Process is live.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                },
                "example": {
                  "healthy": true,
                  "version": "v0.8.0",
                  "status": "ok",
                  "blockHeight": 958779,
                  "datahub_urls": [
                    {
                      "url": "https://datahub.example.com",
                      "source": "discovered",
                      "healthy": true,
                      "policy": {
                        "miningFee": {
                          "satoshis": 100,
                          "bytes": 1000
                        },
                        "maxtxsizepolicy": 100000000,
                        "maxscriptsizepolicy": 500000,
                        "maxtxsigopscountspolicy": 4294967295
                      }
                    },
                    {
                      "url": "https://seeded.example.com",
                      "source": "configured",
                      "healthy": true
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/ready": {
      "get": {
        "operationId": "getReady",
        "tags": [
          "Operations"
        ],
        "summary": "Readiness probe",
        "description": "Indicates that the process has finished start-up and is ready to accept\ntraffic. Suitable as a Kubernetes readiness probe.\n",
        "responses": {
          "200": {
            "description": "Process is ready.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ready"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/policy": {
      "get": {
        "operationId": "getPolicy",
        "tags": [
          "Operations"
        ],
        "summary": "Discover the current fee and size policy (ARC-compatible)",
        "description": "Returns BSV Broadcaster's effective transaction policy in the ARC schema so\nclients can discover the fee rate and size limits before building\ntransactions. Every value reflects exactly what intake enforces.\n\nWhen the operator hasn't pinned a fee, `miningFee` tracks the lowest fee\nthe network will accept — the minimum advertised across peer\n`node_status` announcements — and BSV Broadcaster enforces that same floor at\nintake, falling back to the built-in default until a peer is heard.\n`maxtxsigopscountspolicy` of `4294967295` means unlimited (the BSV\npost-Genesis default), matching the ARC convention. Also served at\n`/v1/policy`. Always returns 200.\n",
        "responses": {
          "200": {
            "description": "Current transaction policy.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PolicyResponse"
                },
                "example": {
                  "policy": {
                    "miningFee": {
                      "satoshis": 100,
                      "bytes": 1000
                    },
                    "maxtxsizepolicy": 10485760,
                    "maxscriptsizepolicy": 500000,
                    "maxtxsigopscountspolicy": 4294967295,
                    "standardFormatSupported": false
                  },
                  "timestamp": "2026-08-07T12:00:00Z"
                }
              }
            }
          }
        }
      }
    },
    "/v1/policy": {
      "get": {
        "operationId": "getPolicyV1",
        "tags": [
          "Operations"
        ],
        "summary": "Discover the current fee and size policy (ARC alias)",
        "description": "Alias of `GET /policy` matching the ARC specification path. Returns the\nidentical response.\n",
        "responses": {
          "200": {
            "description": "Current transaction policy.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PolicyResponse"
                }
              }
            }
          }
        }
      }
    },
    "/metrics": {
      "get": {
        "operationId": "getMetrics",
        "tags": [
          "Operations"
        ],
        "summary": "Prometheus metrics",
        "description": "Prometheus scrape endpoint exposing process and application metrics in\nthe Prometheus text exposition format.\n",
        "responses": {
          "200": {
            "description": "Metrics in Prometheus text format.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/tx": {
      "post": {
        "operationId": "submitTransaction",
        "tags": [
          "Transactions"
        ],
        "summary": "Submit a single transaction",
        "description": "Submits one Bitcoin SV transaction for validation, propagation, and\nlifecycle tracking. Synchronous policy/script/fee validation runs before\nthe `202` is returned; fee and script checks are delegated to the\nnetwork. Pick the body encoding that matches your client — raw bytes are\nthe most efficient.\n\nThe canonical txid is derived from the parsed transaction structure (so\nExtended Format submissions key correctly), not from a hash of the wire\nbytes.\n\nBodies are capped at **32 MiB**.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ContentTypeSingleTx"
          },
          {
            "$ref": "#/components/parameters/XCallbackUrl"
          },
          {
            "$ref": "#/components/parameters/XCallbackToken"
          },
          {
            "$ref": "#/components/parameters/XFullStatusUpdates"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary",
                "description": "Raw serialized transaction bytes in Extended Format (EF). A plain (standard-format) transaction is rejected with ARC 460 because validation needs each input's source output. BEEF is not accepted and is rejected with 400."
              }
            },
            "text/plain": {
              "schema": {
                "type": "string",
                "description": "Hex-encoded serialized transaction in Extended Format (EF). Whitespace is trimmed before decoding.",
                "example": "0100000001abc...def00000000"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmitTxJSON"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Transaction accepted for processing, or an idempotent re-submit of a\ntxid BSV Broadcaster has already seen.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmitResponse"
                },
                "examples": {
                  "submitted": {
                    "summary": "New submission",
                    "value": {
                      "txid": "<hex>",
                      "status": 202,
                      "txStatus": "RECEIVED"
                    }
                  },
                  "alreadySubmitted": {
                    "summary": "Idempotent re-submit (txStatus echoes the existing state)",
                    "value": {
                      "txid": "<hex>",
                      "status": 202,
                      "txStatus": "SEEN_ON_NETWORK"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Malformed request, decode failure, empty transaction, validation\nfailure, or unsafe callback URL. On a **validator** failure — a\nverdict about the transaction bytes — a terminal `REJECTED` row is\npersisted so subscribers see the outcome, carrying the numeric ARC\ncode as `status`.\n\nThe nLockTime/BIP113 finality gate is different: a transaction\nwhose locktime is still ahead of the chain's median-time-past\n(with a non-final input sequence) gets a `400` with ARC code `476`\nand a reason stating when it becomes final, but **no verdict is\npersisted** — non-finality is a condition of this instance's chain\nview, not a property of the transaction. `GET /tx/{txid}` keeps\nreturning its prior state (`404` for a first submission), so\nresubmission policies keyed on \"no verdict\" work unchanged.\nResubmit the identical transaction once the locktime expires and\nit enters the broadcast pipeline normally.\n\nValidation-failure bodies carry the legacy `error`/`reason`/`txid`\nfields plus the additive ARC error taxonomy (`status`, `title`,\n`detail`, `type`) when the failure maps onto it.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                },
                "example": {
                  "error": "transaction failed validation",
                  "reason": "script evaluation failed",
                  "txid": "<hex>",
                  "status": 461,
                  "title": "Malformed transaction",
                  "detail": "Transaction unlocking scripts are invalid",
                  "type": "https://bitcoin-sv.github.io/arc/#/errors?id=_461"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "503": {
            "description": "Broker is under backpressure; the transaction was not queued and a\nretry is safe.\n",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "example": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/txs": {
      "post": {
        "operationId": "submitTransactions",
        "tags": [
          "Transactions"
        ],
        "summary": "Submit a batch of transactions",
        "description": "Submits a batch of concatenated raw transactions in a single HTTP\nrequest. Each transaction is parsed, validated, dedup-CAS'd, and\npublished as part of one fan-out. No length prefixes or separators —\neach transaction is parsed sequentially using the stream parser.\n\nBodies are capped at **256 MiB**. If any transaction in the batch fails\nvalidation the whole call returns `400` with the offending txid and\nreason; a validator failure records the transaction as `REJECTED`,\nwhile a non-final (locktime) failure persists nothing — see `POST /tx`\nfor the verdict-vs-condition distinction and the additive ARC fields.\n",
        "parameters": [
          {
            "name": "Content-Type",
            "in": "header",
            "required": true,
            "description": "Must be `application/octet-stream` — the only encoding accepted for batches.",
            "schema": {
              "type": "string",
              "enum": [
                "application/octet-stream"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/XCallbackUrl"
          },
          {
            "$ref": "#/components/parameters/XCallbackToken"
          },
          {
            "$ref": "#/components/parameters/XFullStatusUpdates"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary",
                "description": "Concatenated raw transaction bytes."
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Batch accepted; counts reconcile submitted vs duplicates vs total parsed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchSubmitResponse"
                },
                "example": {
                  "submitted": 42,
                  "duplicates": 3,
                  "total": 45
                }
              }
            }
          },
          "400": {
            "description": "Wrong content type, empty body, parse failure, no transactions\nparsed, validation failure, or unsafe callback URL.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "503": {
            "description": "Broker backpressure; retry is safe.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "example": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/tx/{txid}": {
      "get": {
        "operationId": "getTransaction",
        "tags": [
          "Transactions"
        ],
        "summary": "Look up transaction status by txid",
        "description": "Returns the current lifecycle state of a previously submitted\ntransaction, including its merkle path once mined.\n\n`404` means exactly \"this instance has no verdict for this txid\":\neither it was never submitted here, or its only submissions were\nanswered with a non-persisting `400` (e.g. the non-final gate).\nStatus rows and mined proofs are retained indefinitely — there is no\nretention window — so a previously returned verdict never expires\ninto a `404`. A mined transaction whose proof is temporarily\nunretrievable still returns `200` with `txStatus: MINED` and block\nfields, with `merklePath` omitted; retry the GET to recover the proof.\n\nTerminal `REJECTED` rows include the rejection reason in `extraInfo`\nand, when classifiable, the numeric ARC code in `status`. A reason\nprefixed `parent rejected` names the rejected ancestor and is\nretryable: resubmit after the ancestor is accepted (resubmitting a\n`REJECTED` transaction re-validates and re-broadcasts it).\n\nWith `?callbackToken=…` the response additionally carries a\n`callbacks` array: the webhook delivery state of the submissions\nregistered under that token (and only that token — a txid can carry\nsubscriptions from multiple clients). `attempts`/`lastAttemptAt`/\n`lastResult` are stamped on every POST BSV Broadcaster makes, so a receiver\nwhose edge is rejecting callbacks (e.g. a WAF answering 403) can\nself-diagnose: `lastResult: \"status 403\"` with a climbing `attempts`\nmeans BSV Broadcaster is delivering and the receiver's side is refusing. Note\nthe top-level `retryCount`/`nextRetryAt` fields are the transaction's\nBROADCAST retry state — webhook retry state lives inside `callbacks`.\n",
        "parameters": [
          {
            "name": "txid",
            "in": "path",
            "required": true,
            "description": "Transaction id (hex).",
            "schema": {
              "type": "string",
              "example": "<hex>"
            }
          },
          {
            "name": "callbackToken",
            "in": "query",
            "required": false,
            "description": "The X-CallbackToken supplied at submit time. Reveals the webhook delivery state (`callbacks` array) of this token's submissions for the txid. Same capability model as the SSE stream's callbackToken.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current transaction status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransactionStatus"
                }
              }
            }
          },
          "404": {
            "description": "The txid has never been submitted to this BSV Broadcaster instance.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "transaction not found"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/v1/blocks/processing-status": {
      "get": {
        "operationId": "listBlockProcessingStatus",
        "tags": [
          "Blocks"
        ],
        "summary": "List block processing milestones",
        "description": "Lists block processing milestones (header seen, `BLOCK_PROCESSED`\nreceived, compound BUMP built) in descending-height order. Paginates via\na height-cursor; pass the lowest height returned from the previous page\nas `before-height` to fetch the next page.\n",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Default 50, max 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "before-height",
            "in": "query",
            "required": false,
            "description": "Cursor — pass the lowest height from the previous page.",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of block processing milestones.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListBlockProcessingStatusResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid `limit` or `before-height` query parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/v1/blocks/processing-status/{blockHash}": {
      "get": {
        "operationId": "getBlockProcessingStatus",
        "tags": [
          "Blocks"
        ],
        "summary": "Get processing status for a single block",
        "description": "Returns the block processing milestones for one block, looked up by block hash.",
        "parameters": [
          {
            "$ref": "#/components/parameters/BlockHashPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Block processing milestones.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BlockProcessingStatus"
                }
              }
            }
          },
          "404": {
            "description": "BSV Broadcaster has no record of the block hash.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/v1/blocks/{blockHash}/reprocess": {
      "post": {
        "operationId": "reprocessBlock",
        "tags": [
          "Blocks"
        ],
        "summary": "Ask Merkle Service to re-emit STUMP + BLOCK_PROCESSED",
        "description": "Requests that the upstream Merkle Service re-emit `STUMP` and\n`BLOCK_PROCESSED` callbacks for the given block hash. Useful for healing\na deployment whose callback stream missed a block.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/BlockHashPath"
          }
        ],
        "responses": {
          "202": {
            "description": "Reprocess request accepted by Merkle Service.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "accepted"
                    },
                    "blockHash": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or malformed block hash (must be 64 hex characters).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Merkle Service responded 4xx — typically \"block isn't on the\nconsensus chain\"; retrying without changing input won't help.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpstreamErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Transport-level failure (network, marshaling).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "502": {
            "description": "Merkle Service responded 5xx — transient infrastructure failure; the caller can retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpstreamErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "No Merkle Service is configured for this deployment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/merkle-service/callback": {
      "post": {
        "operationId": "merkleServiceCallback",
        "tags": [
          "Callbacks"
        ],
        "summary": "Internal — receive callbacks from Merkle Service",
        "description": "Internal endpoint used by the Merkle Service to deliver\n`SEEN_ON_NETWORK`, `SEEN_MULTIPLE_NODES`, `STUMP` and `BLOCK_PROCESSED`\nevents. Bearer authentication is mandatory; the deployment refuses to\nstart without a configured callback token.\n\nRequest bodies are capped (default 16 MiB) to bound the memory cost of\nembedded STUMP blobs; oversize bodies return `413`.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CallbackMessage"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Callback accepted (empty body)."
          },
          "400": {
            "description": "Malformed JSON body, or required fields missing for the callback type.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "unauthorized"
                }
              }
            }
          },
          "413": {
            "description": "Request body exceeded the configured maximum.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/events": {
      "get": {
        "operationId": "streamEvents",
        "tags": [
          "Events"
        ],
        "summary": "Stream status updates over Server-Sent Events",
        "description": "Long-lived Server-Sent Events stream that pushes lifecycle updates for\nevery transaction submitted under the supplied callback token. Hosted by\nBSV Broadcaster's standalone SSE service — a separate listener from the main API\n(default port **8082**). CORS is permissive so browsers can connect\ndirectly with the `EventSource` API.\n\nLines prefixed with `:` are SSE comments — BSV Broadcaster sends a `: keepalive`\ncomment every 15 seconds. The `id` field is the event timestamp in\nnanoseconds; clients reconnecting after a network blip should send it\nback as `Last-Event-ID` to trigger a catchup replay of every status\nupdate that occurred strictly after that timestamp.\n",
        "servers": [
          {
            "url": "http://localhost:8082",
            "description": "sse service (local default)"
          },
          {
            "url": "https://broadcaster.example.com",
            "description": "Production sse service (behind ingress)"
          }
        ],
        "parameters": [
          {
            "name": "callbackToken",
            "in": "query",
            "required": true,
            "description": "The same opaque token sent as `X-CallbackToken` when submitting transactions. Scopes the stream to that token's transactions.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "example": "text/event-stream"
            }
          },
          {
            "name": "Last-Event-ID",
            "in": "header",
            "required": false,
            "description": "Nanosecond timestamp of the last event the client received. Triggers\na catchup replay of every status update after this timestamp. Omit on\nfirst connect to receive the current persisted status of every txid\nregistered under the token.\n",
            "schema": {
              "type": "string",
              "example": "1716205200123456789"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "An event stream of status updates. Every frame carries\ntxid/txStatus/timestamp; timestamp is RFC 3339 and carries\nfractional seconds when the event has sub-second precision, so it\ndenotes the same instant as the frame id. MINED (and IMMUTABLE)\nframes additionally\ncarry blockHash, blockHeight, and merklePath (the transaction's BUMP,\nhex-encoded) — the same proof GET /tx/{txid} and the webhook callback\nreturn, so push-only clients need not poll. Those three fields are\nomitted from earlier frames. On a Last-Event-ID reconnect, replayed\nMINED frames include merklePath best-effort (bounded per reconnect);\nwhen omitted, recover it via GET /tx/{txid}.\n",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                },
                "example": "id: 1716205200123456789\nevent: status\ndata: {\"txid\":\"<hex>\",\"txStatus\":\"SEEN_ON_NETWORK\",\"timestamp\":\"2026-05-20T12:00:00.123456789Z\"}\n\nid: 1716205260987654321\nevent: status\ndata: {\"txid\":\"<hex>\",\"txStatus\":\"MINED\",\"timestamp\":\"2026-05-20T12:01:00.987654321Z\",\"blockHash\":\"<hex>\",\"blockHeight\":870123,\"merklePath\":\"<BUMP hex>\"}\n\n: keepalive\n"
              }
            }
          }
        }
      }
    },
    "/chaintracks/v2/network": {
      "get": {
        "operationId": "chaintracksGetNetwork",
        "tags": [
          "Chaintracks"
        ],
        "summary": "Get the active network",
        "servers": [
          {
            "url": "http://localhost:8083",
            "description": "chaintracks service (local default)"
          }
        ],
        "responses": {
          "200": {
            "description": "The configured network.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "network": {
                      "type": "string",
                      "example": "main"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/chaintracks/v2/height": {
      "get": {
        "operationId": "chaintracksGetHeight",
        "tags": [
          "Chaintracks"
        ],
        "summary": "Get the current chain height",
        "servers": [
          {
            "url": "http://localhost:8083",
            "description": "chaintracks service (local default)"
          }
        ],
        "responses": {
          "200": {
            "description": "Current best-chain height.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "height": {
                      "type": "integer",
                      "format": "int64",
                      "example": 870123
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/chaintracks/v2/tip": {
      "get": {
        "operationId": "chaintracksGetTip",
        "tags": [
          "Chaintracks"
        ],
        "summary": "Get the current chain tip header (JSON)",
        "servers": [
          {
            "url": "http://localhost:8083",
            "description": "chaintracks service (local default)"
          }
        ],
        "responses": {
          "200": {
            "description": "The chain tip block header. The `X-Block-Height` response header carries the tip height.",
            "headers": {
              "X-Block-Height": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChaintracksHeader"
                }
              }
            }
          },
          "404": {
            "description": "Chain tip not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/chaintracks/v2/tip.bin": {
      "get": {
        "operationId": "chaintracksGetTipBinary",
        "tags": [
          "Chaintracks"
        ],
        "summary": "Get the current chain tip header (binary)",
        "servers": [
          {
            "url": "http://localhost:8083",
            "description": "chaintracks service (local default)"
          }
        ],
        "responses": {
          "200": {
            "description": "The serialized 80-byte block header.",
            "headers": {
              "X-Block-Height": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "Chain tip not found."
          }
        }
      }
    },
    "/chaintracks/v2/headers": {
      "get": {
        "operationId": "chaintracksGetHeadersBinary",
        "tags": [
          "Chaintracks"
        ],
        "summary": "Get a run of serialized headers (binary)",
        "description": "Returns `count` consecutive serialized headers starting at `height`, concatenated as raw bytes.",
        "servers": [
          {
            "url": "http://localhost:8083",
            "description": "chaintracks service (local default)"
          }
        ],
        "parameters": [
          {
            "name": "height",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "count",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Concatenated serialized headers.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid `height`/`count`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/chaintracks/v2/header/height/{height}": {
      "get": {
        "operationId": "chaintracksGetHeaderByHeight",
        "tags": [
          "Chaintracks"
        ],
        "summary": "Get a header by height",
        "description": "Returns the header at the given height. Append `.bin` to the height\n(e.g. `/header/height/870123.bin`) to receive the serialized binary\nheader instead of JSON.\n",
        "servers": [
          {
            "url": "http://localhost:8083",
            "description": "chaintracks service (local default)"
          }
        ],
        "parameters": [
          {
            "name": "height",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "870123"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The block header (JSON, or binary when the `.bin` suffix is used).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChaintracksHeader"
                }
              },
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Invalid height parameter."
          },
          "404": {
            "description": "Header not found."
          }
        }
      }
    },
    "/chaintracks/v2/header/hash/{hash}": {
      "get": {
        "operationId": "chaintracksGetHeaderByHash",
        "tags": [
          "Chaintracks"
        ],
        "summary": "Get a header by block hash",
        "description": "Returns the header for the given block hash. Append `.bin` to the hash\nto receive the serialized binary header instead of JSON.\n",
        "servers": [
          {
            "url": "http://localhost:8083",
            "description": "chaintracks service (local default)"
          }
        ],
        "parameters": [
          {
            "name": "hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The block header (JSON, or binary when the `.bin` suffix is used).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChaintracksHeader"
                }
              },
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Invalid hash parameter."
          },
          "404": {
            "description": "Header not found."
          }
        }
      }
    },
    "/chaintracks/v2/tip/stream": {
      "get": {
        "operationId": "chaintracksStreamTip",
        "tags": [
          "Chaintracks"
        ],
        "summary": "Stream chain-tip updates (SSE)",
        "description": "Server-Sent Events stream that emits the current tip immediately on\nconnect and then pushes each new tip as blocks arrive. A `: keepalive`\ncomment is sent every 15 seconds.\n",
        "servers": [
          {
            "url": "http://localhost:8083",
            "description": "chaintracks service (local default)"
          }
        ],
        "responses": {
          "200": {
            "description": "An event stream of tip headers.",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/chaintracks/v2/reorg/stream": {
      "get": {
        "operationId": "chaintracksStreamReorg",
        "tags": [
          "Chaintracks"
        ],
        "summary": "Stream chain-reorg events (SSE)",
        "servers": [
          {
            "url": "http://localhost:8083",
            "description": "chaintracks service (local default)"
          }
        ],
        "responses": {
          "200": {
            "description": "An event stream of reorg events.",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/chaintracks/v1/getChain": {
      "get": {
        "operationId": "chaintracksLegacyGetChain",
        "tags": [
          "Chaintracks"
        ],
        "summary": "Legacy: get the active network",
        "description": "Legacy RPC-style endpoint. Responses are wrapped in a\n`{ status, value }` envelope (or `{ status, code, description }` on\nerror). The `/chaintracks/v1` prefix also serves the full JSON/binary\nsurface available under `/chaintracks/v2`.\n",
        "servers": [
          {
            "url": "http://localhost:8083",
            "description": "chaintracks service (local default)"
          }
        ],
        "responses": {
          "200": {
            "description": "Wrapped network value.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegacyResponse"
                }
              }
            }
          }
        }
      }
    },
    "/chaintracks/v1/getPresentHeight": {
      "get": {
        "operationId": "chaintracksLegacyGetPresentHeight",
        "tags": [
          "Chaintracks"
        ],
        "summary": "Legacy: get the current height",
        "servers": [
          {
            "url": "http://localhost:8083",
            "description": "chaintracks service (local default)"
          }
        ],
        "responses": {
          "200": {
            "description": "Wrapped height value.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegacyResponse"
                }
              }
            }
          }
        }
      }
    },
    "/chaintracks/v1/findChainTipHashHex": {
      "get": {
        "operationId": "chaintracksLegacyFindChainTipHashHex",
        "tags": [
          "Chaintracks"
        ],
        "summary": "Legacy: get the chain tip hash (hex)",
        "servers": [
          {
            "url": "http://localhost:8083",
            "description": "chaintracks service (local default)"
          }
        ],
        "responses": {
          "200": {
            "description": "Wrapped tip-hash value.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegacyResponse"
                }
              }
            }
          },
          "404": {
            "description": "Chain tip not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegacyResponse"
                }
              }
            }
          }
        }
      }
    },
    "/chaintracks/v1/findChainTipHeaderHex": {
      "get": {
        "operationId": "chaintracksLegacyFindChainTipHeaderHex",
        "tags": [
          "Chaintracks"
        ],
        "summary": "Legacy: get the chain tip header",
        "servers": [
          {
            "url": "http://localhost:8083",
            "description": "chaintracks service (local default)"
          }
        ],
        "responses": {
          "200": {
            "description": "Wrapped tip-header value.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegacyResponse"
                }
              }
            }
          },
          "404": {
            "description": "Chain tip not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegacyResponse"
                }
              }
            }
          }
        }
      }
    },
    "/chaintracks/v1/findHeaderHexForHeight": {
      "get": {
        "operationId": "chaintracksLegacyFindHeaderHexForHeight",
        "tags": [
          "Chaintracks"
        ],
        "summary": "Legacy: get a header by height",
        "servers": [
          {
            "url": "http://localhost:8083",
            "description": "chaintracks service (local default)"
          }
        ],
        "parameters": [
          {
            "name": "height",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Wrapped header value.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegacyResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid height parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegacyResponse"
                }
              }
            }
          },
          "404": {
            "description": "Header not found at the requested height.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegacyResponse"
                }
              }
            }
          }
        }
      }
    },
    "/chaintracks/v1/findHeaderHexForBlockHash": {
      "get": {
        "operationId": "chaintracksLegacyFindHeaderHexForBlockHash",
        "tags": [
          "Chaintracks"
        ],
        "summary": "Legacy: get a header by block hash",
        "servers": [
          {
            "url": "http://localhost:8083",
            "description": "chaintracks service (local default)"
          }
        ],
        "parameters": [
          {
            "name": "hash",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Wrapped header value.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegacyResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid hash parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegacyResponse"
                }
              }
            }
          },
          "404": {
            "description": "Header not found for the requested hash.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegacyResponse"
                }
              }
            }
          }
        }
      }
    },
    "/chaintracks/v1/getHeaders": {
      "get": {
        "operationId": "chaintracksLegacyGetHeaders",
        "tags": [
          "Chaintracks"
        ],
        "summary": "Legacy: get a run of headers (hex)",
        "description": "Returns `count` consecutive headers starting at `height`, concatenated and hex-encoded inside the `value` field.",
        "servers": [
          {
            "url": "http://localhost:8083",
            "description": "chaintracks service (local default)"
          }
        ],
        "parameters": [
          {
            "name": "height",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "count",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Wrapped hex-encoded header run.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegacyResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid `height`/`count`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegacyResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Bearer token shared between the Merkle Service and BSV Broadcaster. Compared in\nconstant time against the configured callback token.\n"
      }
    },
    "parameters": {
      "BlockHashPath": {
        "name": "blockHash",
        "in": "path",
        "required": true,
        "description": "Block hash (64 hex characters).",
        "schema": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{64}$"
        }
      },
      "ContentTypeSingleTx": {
        "name": "Content-Type",
        "in": "header",
        "required": true,
        "description": "One of `application/octet-stream`, `text/plain` (hex), or `application/json`.",
        "schema": {
          "type": "string",
          "enum": [
            "application/octet-stream",
            "text/plain",
            "application/json"
          ]
        }
      },
      "XCallbackUrl": {
        "name": "X-CallbackUrl",
        "in": "header",
        "required": false,
        "description": "Webhook URL BSV Broadcaster should POST status events to as this transaction\nprogresses. Must be a public HTTPS endpoint; private/loopback hosts are\nrejected unless the deployment is configured to allow them. The POST body\nis a TransactionStatus; MINED/IMMUTABLE callbacks include blockHash,\nblockHeight, and merklePath (the tx's BUMP), so the proof arrives on the\ncallback without a follow-up GET.\n\nEvery callback POST carries `User-Agent: bsv-broadcaster-webhook/<version>` —\nallowlist the `bsv-broadcaster-webhook/` prefix at your edge so bot/WAF rules\nfor generic HTTP clients don't silently reject deliveries. Delivery\nhealth per submission (attempts, last result) is inspectable via\n`GET /tx/{txid}?callbackToken=…`.\n",
        "schema": {
          "type": "string",
          "format": "uri"
        }
      },
      "XCallbackToken": {
        "name": "X-CallbackToken",
        "in": "header",
        "required": false,
        "description": "Opaque bearer token. Sent on every outbound webhook as\n`Authorization: Bearer <token>`, and used to scope Server-Sent Events\nstreams when the client subscribes via SSE.\n",
        "schema": {
          "type": "string"
        }
      },
      "XFullStatusUpdates": {
        "name": "X-FullStatusUpdates",
        "in": "header",
        "required": false,
        "description": "Set to `true` to receive every status transition. Default behavior\ndelivers only terminal/notable transitions.\n",
        "schema": {
          "type": "string",
          "enum": [
            "true",
            "false"
          ]
        }
      }
    },
    "responses": {
      "InternalError": {
        "description": "Internal server error.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "Status": {
        "type": "string",
        "description": "A transaction's lifecycle state. Emitted in practice: RECEIVED → ACCEPTED_BY_NETWORK → SEEN_ON_NETWORK → SEEN_MULTIPLE_NODES → MINED, with PENDING_RETRY and REJECTED as side states. PENDING_RETRY means no network verdict yet; the reaper rebroadcasts until a peer gives one or the durable retry budget (propagation.pending_retry_max_attempts, default 288) runs out, at which point the tx becomes REJECTED with no peer verdict behind it and extraInfo starting \"no network verdict after N durable retry attempts\". Otherwise REJECTED is a validator or Teranode verdict on the bytes. A double spend is REJECTED with ARC code 466, the conflict signal; competingTxs names the spender only when Teranode's reason does (UTXO_SPENT), and is omitted for TX_CONFLICTING, TX_INVALID_DOUBLE_SPEND and TX_LOCKED. SENT_TO_NETWORK and DOUBLE_SPEND_ATTEMPTED are reserved for ARC compatibility and are not emitted. IMMUTABLE is reserved: nothing emits it yet, so MINED is the last status a client receives.",
        "enum": [
          "UNKNOWN",
          "RECEIVED",
          "SENT_TO_NETWORK",
          "ACCEPTED_BY_NETWORK",
          "SEEN_ON_NETWORK",
          "SEEN_MULTIPLE_NODES",
          "DOUBLE_SPEND_ATTEMPTED",
          "REJECTED",
          "PENDING_RETRY",
          "STUMP_PROCESSING",
          "MINED",
          "IMMUTABLE"
        ]
      },
      "CallbackDelivery": {
        "type": "object",
        "description": "Webhook delivery state of one submission, for delivery self-diagnosis. attempts/lastAttemptAt/lastResult are lifetime bookkeeping stamped on every POST BSV Broadcaster makes (never reset); nextRetryAt/lastDeliveredStatus reflect the current transition's retry scheduling.",
        "properties": {
          "callbackUrl": {
            "type": "string"
          },
          "lastDeliveredStatus": {
            "type": "string",
            "description": "Last status transition claimed for delivery to this URL."
          },
          "attempts": {
            "type": "integer",
            "description": "Total POSTs ever attempted for this submission."
          },
          "lastAttemptAt": {
            "type": "string",
            "format": "date-time"
          },
          "lastResult": {
            "type": "string",
            "description": "\"delivered\" on success, otherwise the last failure — an HTTP outcome like \"status 403\" (the receiver or its edge answered that code) or a transport error.",
            "example": "status 403"
          },
          "nextRetryAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the webhook reaper will retry a failed delivery; absent when not in retry state."
          }
        }
      },
      "TransactionStatus": {
        "type": "object",
        "properties": {
          "txid": {
            "type": "string",
            "description": "Transaction id (hex)."
          },
          "txStatus": {
            "$ref": "#/components/schemas/Status"
          },
          "status": {
            "type": "integer",
            "description": "Numeric ARC error code (460-476 taxonomy) recorded with a REJECTED verdict when the failure is classifiable — e.g. 466 conflicting tx, 476 not final. Omitted when zero/unclassified."
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "txids": {
            "type": "array",
            "description": "Present only on bulk-transition events on the publisher channel; never on rows read from the store.",
            "items": {
              "type": "string"
            }
          },
          "blockHash": {
            "type": "string"
          },
          "blockHeight": {
            "type": "integer",
            "format": "int64"
          },
          "merklePath": {
            "type": "string",
            "nullable": true,
            "description": "BUMP merkle path, hex-encoded. Null/absent until mined. On and after MINED it is returned by GET /tx/{txid}, pushed on the webhook callback body, and included in the SSE MINED frame (best-effort on catchup replay)."
          },
          "extraInfo": {
            "type": "string",
            "description": "Free-form detail (e.g. rejection reason)."
          },
          "callbacks": {
            "type": "array",
            "description": "Webhook delivery state of the requester's submissions. Present only when the request carried a matching ?callbackToken=… — scoped to that token's submissions.",
            "items": {
              "$ref": "#/components/schemas/CallbackDelivery"
            }
          },
          "competingTxs": {
            "type": "array",
            "description": "For a REJECTED double spend (ARC code 466), the transaction(s) that already spent the outpoints, when Teranode's reason names them (UTXO_SPENT). Omitted when the reason does not name a spender (TX_CONFLICTING, TX_INVALID_DOUBLE_SPEND, TX_LOCKED).",
            "items": {
              "type": "string"
            }
          },
          "rawTx": {
            "type": "string",
            "description": "Raw transaction bytes, hex-encoded. Set only while in PENDING_RETRY."
          },
          "retryCount": {
            "type": "integer",
            "description": "Number of durable (reaper) rebroadcast attempts so far. Kept as history after a recovery."
          },
          "nextRetryAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the propagation reaper will next rebroadcast a PENDING_RETRY transaction. Absent when no retry is scheduled."
          },
          "merkleRegisteredAt": {
            "type": "string",
            "format": "date-time",
            "description": "Time of the most recent successful merkle-service registration for this txid. Registration happens before the first broadcast (so a proof can always be delivered), which is why it is also present on a transaction the network later REJECTED. Absent when never registered."
          },
          "orphanedProofs": {
            "type": "array",
            "description": "Historical MINED anchors a chain reorganization superseded, newest last (capped at 5). Present only on transactions that were once anchored to a block that later lost its height to a competitor — e.g. after a same-height reorg the tx re-anchors to the winning block (blockHash/merklePath above) while the losing block's anchor is preserved here, with its proof still resolvable against the orphaned header.",
            "items": {
              "$ref": "#/components/schemas/OrphanedProof"
            }
          }
        },
        "required": [
          "txid",
          "txStatus",
          "timestamp"
        ]
      },
      "OrphanedProof": {
        "type": "object",
        "description": "One historical anchor a reorg superseded: the orphaned block the transaction was MINED against, when the anchor was replaced, and the transaction's BUMP against that block (best-effort — absent if the orphaned block's compound BUMP is no longer retained).",
        "properties": {
          "blockHash": {
            "type": "string",
            "description": "Hash of the orphaned block."
          },
          "blockHeight": {
            "type": "integer",
            "format": "int64"
          },
          "orphanedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the anchor was superseded (re-anchor or revert)."
          },
          "merklePath": {
            "type": "string",
            "description": "BUMP merkle path against the ORPHANED block, hex-encoded. Computes to the orphaned header's merkle root, not the active chain's."
          }
        },
        "required": [
          "blockHash",
          "blockHeight",
          "orphanedAt"
        ]
      },
      "SubmitTxJSON": {
        "type": "object",
        "description": "JSON envelope carrying the hex-encoded transaction.",
        "properties": {
          "rawTx": {
            "type": "string",
            "description": "Hex-encoded serialized transaction in Extended Format (EF); a plain raw transaction is rejected with ARC 460. BEEF is not accepted.",
            "example": "0100000001abc...def00000000"
          }
        },
        "required": [
          "rawTx"
        ]
      },
      "SubmitResponse": {
        "type": "object",
        "description": "ARC-compatible response for a successful single-transaction submission\n(both new submissions and idempotent re-submits). status is the integer\nHTTP code (202 Accepted); txStatus carries the lifecycle state.\n",
        "properties": {
          "txid": {
            "type": "string"
          },
          "status": {
            "type": "integer",
            "example": 202
          },
          "txStatus": {
            "$ref": "#/components/schemas/Status"
          }
        },
        "required": [
          "txid",
          "status",
          "txStatus"
        ]
      },
      "BatchSubmitResponse": {
        "type": "object",
        "properties": {
          "submitted": {
            "type": "integer",
            "description": "Number of transactions newly published."
          },
          "duplicates": {
            "type": "integer",
            "description": "Number of transactions already seen and skipped."
          },
          "total": {
            "type": "integer",
            "description": "Total number of transactions parsed from the body."
          }
        },
        "required": [
          "submitted",
          "duplicates",
          "total"
        ]
      },
      "BlockProcessingStatus": {
        "type": "object",
        "properties": {
          "blockHash": {
            "type": "string"
          },
          "blockHeight": {
            "type": "integer",
            "format": "int64"
          },
          "headerSeenAt": {
            "type": "string",
            "format": "date-time"
          },
          "processedAt": {
            "type": "string",
            "format": "date-time"
          },
          "bumpBuiltAt": {
            "type": "string",
            "format": "date-time"
          },
          "status": {
            "type": "string",
            "description": "Whether the block is on the active chain (active), was displaced by a reorg or a same-height competition (orphaned), or is an active-chain block whose reprocess attempts the watchdog gave up on (parked). A block that returns to the active chain in a later reorg goes back to active, with orphanedAt and reconciledAt cleared.",
            "enum": [
              "active",
              "orphaned",
              "parked"
            ]
          },
          "orphanedAt": {
            "type": "string",
            "format": "date-time"
          },
          "reconciledAt": {
            "type": "string",
            "format": "date-time",
            "description": "Set once the anchor reconciler has finished re-anchoring or reverting the transactions of an orphaned block. An orphaned row without it is still queued for reconciliation."
          },
          "hasBlockProcessed": {
            "type": "boolean"
          },
          "hasCompoundBUMP": {
            "type": "boolean"
          }
        },
        "required": [
          "blockHash",
          "blockHeight",
          "status",
          "hasBlockProcessed",
          "hasCompoundBUMP"
        ]
      },
      "ListBlockProcessingStatusResponse": {
        "type": "object",
        "properties": {
          "blocks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BlockProcessingStatus"
            }
          },
          "nextCursor": {
            "type": "integer",
            "format": "int64",
            "description": "Lowest height on this page; pass as `before-height` for the next page. Absent on the last page."
          }
        },
        "required": [
          "blocks"
        ]
      },
      "CallbackMessage": {
        "type": "object",
        "description": "Payload received from the Merkle Service. The `type` field discriminates the variant.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "SEEN_ON_NETWORK",
              "SEEN_MULTIPLE_NODES",
              "STUMP",
              "BLOCK_PROCESSED"
            ]
          },
          "txid": {
            "type": "string"
          },
          "txids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "blockHash": {
            "type": "string"
          },
          "subtreeIndex": {
            "type": "integer"
          },
          "stump": {
            "type": "string",
            "description": "STUMP blob, hex-encoded."
          }
        },
        "required": [
          "type"
        ]
      },
      "ChaintracksHeader": {
        "type": "object",
        "description": "Block header as serialized by the embedded go-chaintracks library. The\nexact field set is owned by that library; the properties below are\nindicative.\n",
        "additionalProperties": true,
        "properties": {
          "hash": {
            "type": "string"
          },
          "height": {
            "type": "integer",
            "format": "int64"
          },
          "version": {
            "type": "integer"
          },
          "previousblockhash": {
            "type": "string"
          },
          "merkleroot": {
            "type": "string"
          },
          "time": {
            "type": "integer"
          },
          "bits": {
            "type": "integer"
          },
          "nonce": {
            "type": "integer"
          }
        }
      },
      "LegacyResponse": {
        "type": "object",
        "description": "Legacy v1 RPC-style envelope.",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "success",
              "error"
            ]
          },
          "value": {
            "description": "Present on success; type varies by endpoint."
          },
          "code": {
            "type": "string",
            "description": "Error code (present on error)."
          },
          "description": {
            "type": "string",
            "description": "Human-readable error description (present on error)."
          }
        },
        "required": [
          "status"
        ]
      },
      "HealthResponse": {
        "type": "object",
        "properties": {
          "healthy": {
            "type": "boolean",
            "description": "ARC health contract — true whenever the process is live.",
            "example": true
          },
          "version": {
            "type": "string",
            "description": "Build version of the running BSV Broadcaster binary (git tag).",
            "example": "v0.8.0"
          },
          "status": {
            "type": "string",
            "example": "ok"
          },
          "blockHeight": {
            "type": "integer",
            "format": "int64",
            "description": "This instance's processed active chain-tip height. A freshness signal (compare against the network tip to detect a stale chain view); omitted when the height has never been readable.",
            "example": 958779
          },
          "datahub_urls": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EndpointStatus"
            }
          }
        },
        "required": [
          "healthy",
          "version",
          "status"
        ]
      },
      "EndpointStatus": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "configured",
              "discovered"
            ],
            "description": "How the endpoint entered the registry: seeded from static config, or discovered at runtime from a peer's node_status announcement.",
            "example": "discovered"
          },
          "healthy": {
            "type": "boolean"
          },
          "policy": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EndpointPolicy"
              }
            ],
            "description": "The transaction policy this node advertised when it registered the URL — what this specific endpoint will accept, as opposed to the single network-wide policy BSV Broadcaster enforces and GET /policy reports. Absent for an endpoint no node_status has announced (a statically configured URL, typically) or whose node predates fee_policy."
          }
        }
      },
      "EndpointPolicy": {
        "type": "object",
        "description": "Transaction policy advertised by a single Teranode endpoint. Field names match the GET /policy document so both surfaces read the same way; standardFormatSupported is absent because it is an ARC transport flag, not something a peer advertises.",
        "properties": {
          "miningFee": {
            "$ref": "#/components/schemas/FeeAmount"
          },
          "maxtxsizepolicy": {
            "type": "integer",
            "format": "int64",
            "description": "Maximum transaction size in bytes this endpoint accepts.",
            "example": 100000000
          },
          "maxscriptsizepolicy": {
            "type": "integer",
            "format": "int64",
            "description": "Maximum script size in bytes this endpoint accepts.",
            "example": 500000
          },
          "maxtxsigopscountspolicy": {
            "type": "integer",
            "format": "int64",
            "description": "Maximum sigops per transaction this endpoint accepts.",
            "example": 4294967295
          }
        }
      },
      "FeeAmount": {
        "type": "object",
        "description": "Mining-fee rate expressed as satoshis per a number of bytes.",
        "properties": {
          "satoshis": {
            "type": "integer",
            "format": "int64",
            "example": 100
          },
          "bytes": {
            "type": "integer",
            "format": "int64",
            "example": 1000
          }
        },
        "required": [
          "satoshis",
          "bytes"
        ]
      },
      "Policy": {
        "type": "object",
        "description": "ARC-compatible transaction policy.",
        "properties": {
          "miningFee": {
            "$ref": "#/components/schemas/FeeAmount"
          },
          "maxtxsizepolicy": {
            "type": "integer",
            "format": "int64",
            "description": "Maximum accepted transaction size in bytes. Unless the operator has pinned a value, this tracks the largest limit advertised by any Teranode peer, so a transaction is rejected at intake only when no node on the network would accept it.",
            "example": 10485760
          },
          "maxscriptsizepolicy": {
            "type": "integer",
            "format": "int64",
            "description": "Maximum accepted script size in bytes. Tracks the network the same way maxtxsizepolicy does unless the operator has pinned a value.",
            "example": 500000
          },
          "maxtxsigopscountspolicy": {
            "type": "integer",
            "format": "int64",
            "description": "Maximum sigops per transaction; 4294967295 means unlimited (BSV post-Genesis), the ARC convention.",
            "example": 4294967295
          },
          "standardFormatSupported": {
            "type": "boolean",
            "description": "Whether standard (non-EF) transaction format is accepted at intake. Always false in this release: validation needs each input's source output, which of the accepted encodings only Extended Format (EF) carries, so a plain raw transaction is rejected with ARC 460. BEEF is not accepted.",
            "example": false
          }
        },
        "required": [
          "miningFee",
          "maxtxsizepolicy",
          "maxscriptsizepolicy",
          "maxtxsigopscountspolicy",
          "standardFormatSupported"
        ]
      },
      "PolicyResponse": {
        "type": "object",
        "properties": {
          "policy": {
            "$ref": "#/components/schemas/Policy"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Policy timestamp (RFC 3339).",
            "example": "2026-08-07T12:00:00Z"
          }
        },
        "required": [
          "policy",
          "timestamp"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "ValidationErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "reason": {
            "type": "string",
            "description": "Validation failure detail (present when a transaction fails validation)."
          },
          "txid": {
            "type": "string",
            "description": "The offending txid (present when a specific transaction failed)."
          },
          "status": {
            "type": "integer",
            "description": "Numeric ARC error code (460-476 taxonomy) when the failure maps onto it — e.g. 461 malformed unlocking scripts, 465 fee too low, 476 not final (retryable; resubmit after the locktime expires). Absent for failures with no confident classification.",
            "example": 476
          },
          "title": {
            "type": "string",
            "description": "ARC error title for the status code."
          },
          "detail": {
            "type": "string",
            "description": "ARC error detail for the status code."
          },
          "type": {
            "type": "string",
            "description": "ARC error documentation URL for the status code."
          }
        },
        "required": [
          "error"
        ]
      },
      "UpstreamErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "upstreamStatus": {
            "type": "integer"
          },
          "upstreamMessage": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}
