swagger.json

Overview

The [swagger.json](/projects/291/68851) file is an OpenAPI 3.0 specification document that defines the REST API contract for the [@shapeshiftoss/bitcoincash-api](/projects/291/69281) service. This API provides endpoints for interacting with a Bitcoin Cash coinstack, supporting operations such as retrieving account information, transaction history, unspent transaction outputs (UTXOs), transaction details, broadcasting transactions, and fetching network fee recommendations.

This file serves as the authoritative schema for the API, describing available paths, request parameters, response formats, and data models (schemas). It enables automated client generation, API documentation, server stubs, and validation for the Bitcoin Cash API.

Components (Schemas)

The file defines multiple JSON schemas under [components.schemas](/projects/291/69205) to describe the structure of data objects returned or accepted by the API. These schemas ensure consistent data validation and provide detailed metadata for each entity.

Key Schemas Summary

API Paths and Operations

The API exposes the following main resource paths:

1. /api/v1/info

• Method: GET

• OperationId: GetInfo

• Description: Returns basic information about the running coinstack, such as network type.

• Response: JSON object conforming to BaseInfo schema.

**Example Usage:**

GET /api/v1/info
Accept: application/json

Response 200 OK
{
  "network": "bitcoincash"
}

2. /api/v1/account/{pubkey}

• Method: GET

• OperationId: GetAccount

• Description: Retrieves account details by address or extended public key.

• Path Parameter:

  • pubkey (string): account address or extended public key (required)

• Responses:

  • 200: Account schema

  • 400: BadRequestError

  • 422: ValidationError

  • 500: InternalServerError

**Example Usage:**

GET /api/v1/account/bitcoincash:qz0...xyz
Accept: application/json

Response 200 OK
{
  "balance": "1000000",
  "unconfirmedBalance": "50000",
  "pubkey": "xpub6CUGRUonZSQ4TWtTMmzXdrXDtypWKiK...",
  "addresses": [
    {
      "balance": "500000",
      "pubkey": "bitcoincash:qz..."
    }
  ],
  "nextReceiveAddressIndex": 5,
  "nextChangeAddressIndex": 2
}

3. /api/v1/account/{pubkey}/txs

• Method: GET

• OperationId: GetTxHistory

• Description: Retrieves paginated transaction history for an account/address.

• Path Parameter:

  • pubkey (string): account address or extended public key (required)

• Query Parameters:

  • cursor (string, optional): pagination cursor (base64 encoded)

  • pageSize (number, optional): number of records per page, default 10

• Responses:

  • 200: TxHistory schema

  • 400, 422, 500: error schemas

4. /api/v1/account/{pubkey}/utxos

• Method: GET

• OperationId: GetUtxos

• Description: Retrieves all unspent transaction outputs (UTXOs) for an account/address.

• Path Parameter:

  • pubkey (string): account address or extended public key (required)

• Responses:

  • 200: array of Utxo objects

  • 400, 422, 500: error schemas

5. /api/v1/tx/{txid}

• Method: GET

• OperationId: GetTransaction

• Description: Retrieves detailed information about a specific transaction by its hash.

• Path Parameter:

  • txid (string): transaction hash (required)

• Responses:

  • 200: Tx schema

  • 400, 422, 500: error schemas

6. /api/v1/tx/{txid}/raw

• Method: GET

• OperationId: GetRawTransaction

• Description: Retrieves raw transaction data directly from the node.

• Path Parameter:

  • txid (string): transaction hash (required)

• Responses:

  • 200: RawTx schema

  • 400, 422, 500: error schemas

7. /api/v1/send

• Method: POST

• OperationId: SendTx

• Description: Broadcasts a raw serialized transaction hex to the Bitcoin Cash node/network.

• Request Body:

  • JSON object with property hex (string) - serialized raw transaction hex (required)

• Responses:

  • 200: string transaction ID (txid)

  • 400, 422, 500: error schemas

**Example Request:**

POST /api/v1/send
Content-Type: application/json

{
  "hex": "0200000001abcdef..."
}

Response 200 OK
"txid1234567890abcdef"

8. /api/v1/fees

• Method: GET

• OperationId: GetNetworkFees

• Description: Retrieves current recommended network fees for different confirmation speeds.

• Responses:

  • 200: NetworkFees schema

  • 400, 500: error schemas

Important Implementation Details & Algorithms

• Pagination Support:
  The transaction history endpoint supports cursor-based pagination using a base64 encoded JSON cursor with a page property. This enables efficient navigation through large datasets without offset-based limitations.

• Schema Strictness:
  All schemas use "additionalProperties": false to enforce strict validation, ensuring that only explicitly defined properties are accepted or returned. This enhances robustness and API contract clarity.

• Fee Estimation:
  The NetworkFees schema distinguishes fees by confirmation speed (fast, average, slow), each containing sats per kilobyte and estimated blocks until confirmation. This implies an underlying fee estimation algorithm or service integration providing dynamic fee recommendations.

• Separation of Raw vs Parsed Transactions:
  The API differentiates between Tx (parsed, user-friendly transaction info) and RawTx (raw transaction data as returned from the node), enabling different levels of detail and use cases.

Interaction with Other System Components

• Bitcoin Cash Node:
  The API acts as a middleware layer interacting with a Bitcoin Cash node to fetch raw transaction data, broadcast transactions, and query blockchain state such as UTXOs and transaction history.

• Client Applications:
  Wallets, explorers, or other client apps consume this API to display account balances, transaction history, broadcast transactions, and estimate fees.

• Fee Estimator Module:
  A component or external service likely provides the fee recommendation data used in the /api/v1/fees endpoint.

Visual Diagram

Below is a flowchart representing the API's main endpoints and their relationships with key data schemas:

flowchart TD
    Info["GET /api/v1/info"]
    Account["GET /api/v1/account/{pubkey}"]
    TxHistory["GET /api/v1/account/{pubkey}/txs"]
    Utxos["GET /api/v1/account/{pubkey}/utxos"]
    Tx["GET /api/v1/tx/{txid}"]
    RawTx["GET /api/v1/tx/{txid}/raw"]
    SendTx["POST /api/v1/send"]
    Fees["GET /api/v1/fees"]

    Info -->|returns| BaseInfo[BaseInfo Schema]
    Account -->|returns| AccountSchema[Account Schema]
    TxHistory -->|returns| TxHistorySchema[TxHistory Schema]
    Utxos -->|returns| UtxoList[Array of Utxo Schema]
    Tx -->|returns| TxSchema[Tx Schema]
    RawTx -->|returns| RawTxSchema[RawTx Schema]
    SendTx -->|request with| SendTxBody[SendTxBody Schema]
    SendTx -->|returns| TxId[String]
    Fees -->|returns| NetworkFeesSchema[NetworkFees Schema]

    %% Error responses linked to all endpoints
    subgraph Errors
        BadReq[BadRequestError]
        ValErr[ValidationError]
        IntErr[InternalServerError]
    end

    Info --- Errors
    Account --- Errors
    TxHistory --- Errors
    Utxos --- Errors
    Tx --- Errors
    RawTx --- Errors
    SendTx --- Errors
    Fees --- Errors

Summary

The [swagger.json](/projects/291/68851) file comprehensively defines the REST API for a Bitcoin Cash coinstack service, including endpoints for querying blockchain data, managing accounts, transactions, and fees, as well as broadcasting transactions. It uses OpenAPI 3.0 standards to provide detailed schema definitions and response validation, facilitating integration by client applications and ensuring consistency and reliability of interactions with the Bitcoin Cash network.