swagger.json

Overview

This file defines the OpenAPI 3.0 specification for the [@shapeshiftoss/bitcoin-api](/projects/291/69281) version `10.0.0`. It provides a comprehensive description of a RESTful HTTP API designed to interact with a Bitcoin coinstack. The API enables clients to retrieve information about the blockchain network, accounts (addresses or extended public keys), transactions, unspent transaction outputs (UTXOs), network fees, and to broadcast raw transactions.

The specification includes detailed schemas for request and response payloads, HTTP endpoints with methods, parameters, and expected responses, as well as metadata about the API.

Purpose and Functionality

The primary purpose of this file is to serve as a contract for the Bitcoin API, enabling developers and tools to understand and interact with the API effectively. It standardizes:

Retrieval of blockchain and account information.
Querying transaction details and histories.
Accessing unspent transaction outputs.
Fetching recommended network fees.
Broadcasting raw transactions to the Bitcoin network node.

This API is vital for wallet services, blockchain explorers, and other Bitcoin-related applications requiring programmatic access to blockchain data and transaction management.

Detailed Components

Schemas

The [components.schemas](/projects/291/69205) section defines the data models used throughout the API responses and requests. These schemas ensure consistent data structures and validation rules.

Below are key schemas with explanations:

BaseInfo

Description: Contains base information about the running coinstack.
Properties:
- network (string, required): The Bitcoin network name (e.g., mainnet, testnet).
Usage: Returned by the /api/v1/info endpoint.

Address

Description: Represents an address linked to an extended public key.
Properties:
- balance (string, required): The balance on this address.
- pubkey (string, required): The public key associated with the address.
Usage: Used within the Account schema to list addresses.

Account

Description: Details about an address or extended public key account.
Properties:
- balance (string, required): Confirmed balance of the account.
- unconfirmedBalance (string, required): Unconfirmed balance that might not yet be included in the blockchain.
- pubkey (string, required): The public key or address string.
- addresses (array of Address): List of associated addresses for extended public keys.
- nextReceiveAddressIndex (number): Next unused receive address index (change index 0).
- nextChangeAddressIndex (number): Next unused change address index (change index 1).
Usage: Returned by /api/v1/account/{pubkey} endpoint.

Vin (Transaction Input)

Description: Represents a transaction input.
Properties:
- txid (string): Transaction ID from which this input originates.
- vout (string): Output index in the previous transaction.
- sequence (number): Sequence number.
- coinbase (string): Coinbase data for coinbase transactions.
- scriptSig (object): Script signature in hex.
- addresses (array of strings): Addresses involved in this input.
- value (string): Amount from this input.
Usage: Part of a transaction (Tx).

Vout (Transaction Output)

Description: Represents a transaction output.
Properties:
- value (string, required): Amount sent.
- n (number, required): Output index.
- opReturn (string): Optional OP_RETURN data.
- scriptPubKey (object, required): Script public key in hex.
- addresses (array of strings): Addresses receiving this output.
Usage: Part of a transaction (Tx).

Tx (Transaction)

Description: Details about a Bitcoin transaction.
Properties:
- txid (string): Transaction ID/hash.
- blockHash (string): Hash of the block containing this transaction.
- blockHeight (number): Height of the block.
- timestamp (number): Time transaction was confirmed (epoch).
- vin (array of Vin): List of inputs.
- vout (array of Vout): List of outputs.
- confirmations (number): Number of confirmations.
- value (string): Total value transferred.
- fee (string): Transaction fee paid.
- hex (string): Raw hex representation of the transaction.
Usage: Returned by /api/v1/tx/{txid} endpoint.

TxHistory (Transaction History)

Description: Paginated transaction history for an account.
Properties:
- cursor (string): Cursor for pagination.
- pubkey (string, required): Public key or address.
- txs (array of Tx, required): List of transactions.
Usage: Returned by /api/v1/account/{pubkey}/txs endpoint.

Utxo (Unspent Transaction Output)

Description: Details of an unspent transaction output.
Properties:
- txid (string, required): Transaction ID.
- vout (number, required): Output index.
- value (string, required): Amount.
- height (number): Block height.
- confirmations (number, required): Number of confirmations.
- address (string): Associated address.
- path (string): Derivation path.
- locktime (number): Locktime.
- coinbase (boolean): Whether this UTXO is from a coinbase transaction.
Usage: Returned by /api/v1/account/{pubkey}/utxos endpoint.

RawTx (Raw Transaction)

Description: Full raw transaction details as returned by the node.
Properties: Includes transaction metadata (txid, hash, version, size, etc.), detailed vin and vout with script data, confirmations, block times, and hex.
Usage: Returned by /api/v1/tx/{txid}/raw endpoint.

SendTxBody

Description: Request body for sending a raw transaction.
Properties:
- hex (string, required): Serialized raw transaction hex string.
Usage: Sent as POST body to /api/v1/send.

NetworkFee and NetworkFees

NetworkFee:
- satsPerKiloByte (number, required): Fee rate in satoshis per kilobyte.
- blocksUntilConfirmation (number, required): Estimated blocks to confirmation.
NetworkFees:
- Contains fast, average, and slow network fee recommendations.
Usage: Returned by /api/v1/fees.

Error Schemas

BadRequestError: Contains an error message for 400 responses.
ValidationError: Contains a message and details object for 422 responses.
InternalServerError: Contains a message for 500 responses.

API Endpoints Summary

Path	Method	OperationId	Description	Response Schema
/api/v1/info	GET	GetInfo	Get info about the running coinstack	`BaseInfo`
/api/v1/account/{pubkey}	GET	GetAccount	Get account details by address or extended public key	`Account`
/api/v1/account/{pubkey}/txs	GET	GetTxHistory	Get transaction history for an account	`TxHistory`
/api/v1/account/{pubkey}/utxos	GET	GetUtxos	Get UTXOs for an account	array of `Utxo`
/api/v1/tx/{txid}	GET	GetTransaction	Get transaction details by txid	`Tx`
/api/v1/tx/{txid}/raw	GET	GetRawTransaction	Get raw transaction details from the node	`RawTx`
`/api/v1/send`	POST	SendTx	Broadcast a raw transaction	string (txid)
/api/v1/fees	GET	GetNetworkFees	Get current recommended network fees	`NetworkFees`

Important Implementation Details

Pagination: Transaction history endpoint supports pagination via a cursor query parameter encoding page state in base64.
Validation and Error Handling: Most endpoints return detailed error schemas (400, 422, 500) to standardize error responses.
Schema Referencing: The specification uses $ref extensively to reuse schema definitions, improving maintainability.
Type Safety: Properties specify types and constraints (e.g., required fields, enums) to enforce strict data validation.
Network Fee Estimation: Network fee info provides three fee tiers to allow clients to select based on urgency.

Interaction with Other System Components

This OpenAPI spec likely serves as the interface layer between the Bitcoin node/coinstack and client applications such as wallets, explorers, or other blockchain services.
The backend implementing this API interacts directly with the Bitcoin node for transaction and blockchain data.
The API abstracts raw node data into structured, validated JSON responses.
Client applications use this API to display account balances, transaction histories, and to broadcast new transactions.
The specification can be used to auto-generate client SDKs or server stubs, facilitating integration.

Usage Examples

Example: Get Account Details

GET /api/v1/account/03a34b... HTTP/1.1
Host: api.example.com
Accept: application/json

Response:

{
  "balance": "150000",
  "unconfirmedBalance": "5000",
  "pubkey": "03a34b...",
  "addresses": [
    {
      "balance": "100000",
      "pubkey": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
    }
  ],
  "nextReceiveAddressIndex": 5,
  "nextChangeAddressIndex": 2
}

Example: Send Raw Transaction

POST /api/v1/send HTTP/1.1
Host: api.example.com
Content-Type: application/json

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

Response:

"b6f6991d3a0e7eeb0f8b..."

Visual Diagram

Below is a Mermaid class diagram illustrating the key data schemas and their relationships in this API specification.

classDiagram
    class BaseInfo {
        +string network
    }
    class Address {
        +string balance
        +string pubkey
    }
    class Account {
        +string balance
        +string unconfirmedBalance
        +string pubkey
        +Address[] addresses
        +number nextReceiveAddressIndex
        +number nextChangeAddressIndex
    }
    class Vin {
        +string txid
        +string vout
        +number sequence
        +string coinbase
        +object scriptSig
        +string[] addresses
        +string value
    }
    class Vout {
        +string value
        +number n
        +string opReturn
        +object scriptPubKey
        +string[] addresses
    }
    class Tx {
        +string txid
        +string blockHash
        +number blockHeight
        +number timestamp
        +Vin[] vin
        +Vout[] vout
        +number confirmations
        +string value
        +string fee
        +string hex
    }
    class TxHistory {
        +string cursor
        +string pubkey
        +Tx[] txs
    }
    class Utxo {
        +string txid
        +number vout
        +string value
        +number height
        +number confirmations
        +string address
        +string path
        +number locktime
        +boolean coinbase
    }
    class RawTx {
        +string txid
        +string hash
        +number version
        +number size
        +number vsize
        +number weight
        +number locktime
        +object[] vin
        +object[] vout
        +string hex
        +string blockhash
        +number confirmations
        +number time
        +number blocktime
    }
    class SendTxBody {
        +string hex
    }
    class NetworkFee {
        +number satsPerKiloByte
        +number blocksUntilConfirmation
    }
    class NetworkFees {
        +NetworkFee fast
        +NetworkFee average
        +NetworkFee slow
    }
    class BadRequestError {
        +string error
    }
    class ValidationError {
        +string message
        +object details
    }
    class InternalServerError {
        +string message
    }

    Account "1" -- "*" Address : contains
    Tx "1" -- "*" Vin : contains
    Tx "1" -- "*" Vout : contains
    TxHistory "1" -- "*" Tx : contains
    NetworkFees "1" -- "1" NetworkFee : fast
    NetworkFees "1" -- "1" NetworkFee : average
    NetworkFees "1" -- "1" NetworkFee : slow

Summary

This [swagger.json](/projects/291/68851) file is a detailed OpenAPI specification that acts as the blueprint for the Bitcoin API developed by ShapeShift. It defines how clients can query blockchain data, manage accounts and transactions, and broadcast new transactions efficiently and reliably. The schemas provide strong typing and validation, while the paths describe RESTful operations with clear request and response structures. This file facilitates integration, documentation, and automation for applications interacting with the Bitcoin blockchain via this API.

End of Documentation for swagger.json