swagger.json

Overview

This file is an OpenAPI 3.0.0 specification document describing the RESTful API for **@shapeshiftoss/blockbook**, a blockchain indexer backend primarily used by the Trezor wallet. The API exposes endpoints for querying blockchain data such as blocks, transactions, addresses, unspent transaction outputs (UTXOs), and sending transactions.

The specification provides detailed descriptions of request paths, query and path parameters, response schemas, and example payloads for supported operations across multiple blockchain types (notably Bitcoin and Ethereum). It defines a comprehensive set of reusable data models (schemas) describing blockchain entities like transactions, blocks, addresses, tokens, and backend status.

This API serves as a normalized interface for accessing blockchain data abstracted from coin-specific differences, enabling clients to interact uniformly with multiple coins and tokens.

Detailed Explanation of Components

Components Section

Schemas

The `components.schemas` section defines JSON schema models representing the domain entities used in requests and responses.

• BlockbookInfo
  Describes the status and metadata of the Blockbook service instance.

  • Properties include blockchain coin name, host, version, sync status, best block height, mempool info, database size, and descriptive about text.

  • All properties are required except for dbColumns which is an optional array.

• BackendInfo
  Represents the connected backend node's status details.

  • Includes chain name, block counts, difficulty, version info, protocol version, warnings, and consensus (coin-specific).

  • The error field is optionally present for error messages.

• Info
  Combines BlockbookInfo and BackendInfo into one object describing both the indexer and backend node status.

• BlockIndex
  Contains a single property hash representing the block hash for a given height.

• Vin (Transaction Input)
  Represents one input of a transaction, including previous txid, output index, sequence number, associated addresses, coinbase data (for mining rewards), script hex/asm, value, and a flag indicating if the input references an address.

• Vout (Transaction Output)
  Represents one output of a transaction, including value, output index, spent status and details, script hex/asm, addresses, address flag, and output type.

• MultiTokenValue
  Used for multi-token support, encapsulating a token ID and its associated value.

• TokenTransfer
  Represents a token transfer within a transaction, including type (e.g., ERC20), from/to addresses, contract, name, symbol, decimals, token value, and optionally multiple token values.

• EthereumSpecific
  Contains Ethereum-specific transaction data such as status, nonce, gas limit/used, gas price, and input data.

• Tx (Transaction)
  A normalized transaction model including txid, version, lock time, arrays of vin and vout, block info, confirmations, size, value fields, raw hex, replace-by-fee flag, associated token transfers, and coin-specific transaction data including Ethereum-specific.

• Token
  Represents tokens held by an address or xpub, including type, name, contract address, number of transfers, symbol, decimals, balance, total received/sent, and multi-token values.

• Erc20Contract
  Contains details about an ERC20 contract: contract address, name, symbol, and decimals.

• Address
  Contains an address's balances, transaction counts, list of transactions or txids, nonce, tokens held, and optionally an ERC20 contract. Supports pagination for transactions and filtering by details level.

• Xpub
  Extends Address schema, describing extended public keys and their derived addresses and transactions. Used for Bitcoin-type coins.

• Utxo
  Represents unspent transaction outputs including txid, output index, value, block height, confirmations, address, derivation path, locktime, and coinbase flag.

• Block
  Details a blockchain block including pagination info, hashes, height, confirmations, size, version, merkle root, nonce, difficulty, transaction count, and transactions (both txids and full objects).

• SendTx
  Represents the result of a send transaction operation with a single result property containing the txid.

• BalanceHistory
  Represents a point in time balance snapshot including timestamp, number of transactions, received/sent amounts, self-sent amounts, exchange rates, and optional txid.

Security Schemes

No security schemes are defined in this API specification.

API Paths and Operations

/api/v2 - GetInfo

• GET: Returns current status information about the Blockbook instance and the connected backend node.

• Response: Info schema (combined Blockbook and backend status).

• Use case: Clients can check the health and sync status of the indexer and blockchain node.

/api/v2/block-index/{height} - GetBlockHash

• GET: Returns the block hash for a given block height.

• Path parameter:

  • height (number): The block height to query.

• Response: BlockIndex schema with hash property.

• Use case: Retrieve block hash to reference or validate block height.

/api/v2/tx/{txid} - GetTransaction

• GET: Returns normalized transaction data for a given transaction ID.

• Path parameter:

  • txid (string): Transaction identifier.

• Response: Tx schema with detailed transaction info suitable for multiple coin types.

• Notes: Coin-specific fields are excluded; for full coin-specific data use /tx-specific.

• Examples: Bitcoin and Ethereum transaction examples illustrate normalized data structure.

/api/v2/tx-specific/{txid} - GetTransactionSpecific

• GET: Returns transaction data exactly as returned by the backend node, including coin-specific fields.

• Path parameter:

  • txid (string): Transaction identifier.

• Response: Unspecified schema (backend specific).

• Use case: Access raw transaction data with full coin-specific details.

/api/v2/address/{address} - GetAddress

• GET: Returns balances and transactions for a given address.

• Path parameter:

  • address (string): Blockchain account address.

• Query parameters:

  • page (number): Pagination page number, default 1.

  • pageSize (number): Number of transactions per page, max 1000.

  • from (number): Filter transactions starting from this block height.

  • to (number): Filter transactions up to this block height.

  • details (string): Level of detail for transactions, enum: basic, tokens, tokenBalances, txids, txslight, txs (default).

  • contract (string): Filter transactions affecting the specified contract (for smart contract enabled coins).

• Response: Address schema with balances, transaction list, tokens, and pagination info.

• Use cases: Query account balances, transaction history, and token holdings.

/api/v2/xpub/{xpub} - GetXpub

• GET: Returns balances and transactions for an extended public key (xpub), applicable for Bitcoin-type coins.

• Path parameter:

  • xpub (string): Extended public key at derivation path level 3.

• Query parameters:

  • page, pageSize, from, to: Pagination and filtering similar to /address.

  • details (string): Detail level for returned data, enum: basic, tokens, tokenBalances, txids, txs.

  • tokens (string): Specifies which tokens (addresses) to return: nonzero (default), used, derived.

• Response: Xpub schema extending Address schema.

• Notes: Supports BIP44, BIP49, BIP84 derivation schemes.

• Use case: Wallets or services deriving addresses from an xpub and querying aggregated balances/transactions.

/api/v2/utxo/{account} - GetUtxo

• GET: Returns an array of unspent transaction outputs (UTXOs) for an address or xpub (Bitcoin-type coins only).

• Path parameter:

  • account (string): Address or xpub to query.

• Query parameter:

  • confirmed (boolean): If true, only confirmed UTXOs are returned; otherwise, both confirmed and unconfirmed.

• Response: Array of Utxo objects containing txid, vout, value, height, confirmations, and optionally address/path for xpubs.

• Notes: Unconfirmed UTXOs have confirmations = 0 and no height field.

• Use case: Wallets or services checking spendable outputs for building transactions.

/api/v2/block/{block} - GetBlock

• GET: Returns information about a block, including transactions, with support for pagination.

• Path parameter:

  • block (string): Block height or block hash.

• Query parameter:

  • page (number): Page number for transactions, default 1.

• Response: Block schema with block metadata and transactions (both txids and detailed Tx objects).

• Use case: Block explorers or services displaying block contents and metadata.

/api/v2/sendtx/{hex} - SendTransaction

• GET: Sends a new raw transaction to the backend node.

• Path parameter:

  • hex (string): Serialized transaction data in hex format.

• Response: SendTx schema containing the resulting transaction ID.

• Use case: Clients broadcasting transactions to the network.

/api/v2/balancehistory/{account} - BalanceHistory

• GET: Returns balance history points for a given xpub or address.

• Path parameter:

  • account (string): xpub or address to query.

• Query parameters:

  • from (number): Start timestamp for filtering.

  • to (number): End timestamp for filtering.

  • fiatcurrency (string): If specified, returns fiat rate at transaction time, e.g., "usd".

  • groupBy (number): Interval in seconds to group results, default 3600.

• Response: Array of BalanceHistory objects showing balance snapshots over time.

• Use case: Historical balance charting and analysis.

/api/v2/estimatefees - EstimateFees

• GET: Returns estimated network fees in BTC/kB for specified block confirmation targets.

• Query parameter:

  • blockTimes (array of numbers): Target confirmation times in blocks.

• Response: Array of strings representing fee estimations.

• Use case: Wallets estimating appropriate fees for timely transaction confirmation.

Important Implementation Details

• The API provides a normalized transaction model (Tx) to unify data across multiple blockchain types, abstracting away coin-specific differences for easier consumption.

• Supports pagination and filtering extensively for transactions and blocks to handle large datasets efficiently.

• Token support is integrated, including multi-token values and token transfers, to support Ethereum ERC20 tokens and similar token standards.

• The API supports xpub (extended public key) querying for Bitcoin-type wallets, with derivation according to BIP44/49/84 standards.

• For raw blockchain data, the /tx-specific endpoint exposes backend node data verbatim.

• The /sendtx endpoint supports broadcasting transactions by providing serialized hex data.

• Balance history endpoint enables time-based balance snapshots with optional fiat currency conversion.

• Fee estimation is provided to assist wallet applications in setting dynamic fees.

Interaction with Other System Components

• This API interfaces between clients (wallets, block explorers, services) and blockchain backend nodes (full nodes of Bitcoin, Ethereum, etc.).

• It acts as a blockchain indexer, maintaining an indexed database of blockchain states and transactions to provide fast query responses.

• Integrates closely with backend nodes to fetch raw blockchain data while exposing normalized and coin-agnostic views.

• Used by frontend wallet applications (e.g., Trezor wallet) to present blockchain data and enable transaction management.

• The data schemas defined here align with the internal data models of the Blockbook indexer and backend nodes, facilitating consistent data flow.

Usage Examples

Example: Retrieve Blockchain Info

Request: `GET /api/v2`

Response snippet:

{
  "blockbook": {
    "coin": "Bitcoin",
    "host": "indexer-sts-1",
    "version": "0.3.4",
    "syncMode": true,
    "bestHeight": 577261,
    "inSync": true,
    "mempoolSize": 17348,
    "decimals": 8,
    "dbSize": 191887866502,
    "about": "Blockbook - blockchain indexer for Trezor wallet"
  },
  "backend": {
    "chain": "main",
    "blocks": 577261,
    "headers": 577261,
    "bestBlockHash": "0000000000000000000ca8c902aa58b3118a7f35d093e25a07f17bcacd91cabf",
    "difficulty": "6704632680587.417",
    "version": "180000"
  }
}

Example: Get Transaction Details (Bitcoin)

Request: `GET /api/v2/tx/75d18ecf1a785fe7d08c6092e0e57bc6b6c180da317424ed5d38dc82cdfc0966`

Response includes transaction inputs, outputs, block info, confirmations, fees, and raw hex.

Mermaid Diagram: API Structure and Schema Relationships

flowchart TD
    Info["Info\n(blockbook + backend)"]
    BlockbookInfo["BlockbookInfo\n(blockbook status)"]
    BackendInfo["BackendInfo\n(backend node status)"]
    Tx["Tx\n(transaction)"]
    Vin["Vin\n(tx input)"]
    Vout["Vout\n(tx output)"]
    TokenTransfer["TokenTransfer"]
    MultiTokenValue["MultiTokenValue"]
    EthereumSpecific["EthereumSpecific"]
    Token["Token\n(tokens held)"]
    Erc20Contract["Erc20Contract"]
    Address["Address\n(account address)"]
    Xpub["Xpub\n(extends Address)"]
    Utxo["Utxo\n(unspent outputs)"]
    Block["Block\n(block data)"]
    SendTx["SendTx\n(send transaction response)"]
    BalanceHistory["BalanceHistory\n(balance time point)"]
    BlockIndex["BlockIndex\n(block hash)"]

    Info --> BlockbookInfo
    Info --> BackendInfo

    Tx --> Vin
    Tx --> Vout
    Tx --> TokenTransfer
    Tx --> EthereumSpecific

    TokenTransfer --> MultiTokenValue

    Address --> Tx
    Address --> Token
    Address --> Erc20Contract

    Xpub --> Address

    Block --> Tx

    Utxo

    SendTx

    BalanceHistory

    BlockIndex

Summary

The [swagger.json](/projects/291/68851) file comprehensively defines the REST API for the Blockbook blockchain indexer backend. It focuses on normalized blockchain data access for blocks, transactions, addresses, and tokens across multiple coins, with special support for Bitcoin and Ethereum ecosystems. The specification enables client applications to query blockchain states efficiently with rich filtering, pagination, and token support, as well as send transactions and estimate fees. The detailed schemas and example payloads serve as a robust contract for both API consumers and implementers.