bitcoin-source-api v0.2.2

Bitcoin Source API

Bitcoin Source API provides a simplified programming model to access public REST APIs for networks supported by bitcoin-source. It simplifies working with the Insight API for various coins.

Bitcoin Source API supports the following coins:

• Bitcoin Cash (BTC)
• Bitcoin SV (BSV)
• Bitcoin (BTC)
• Litecoin (LTC)

Install using npm

npm install bitcoin-source-api

Usage

An example of how to use the API is shown below.

const Insight = require('bitcoin-source-api').Insight
const api = Insight.create('bch')

;(async () => {
    const blk = await api.getLastBlockHash()
    console.log(`Last block for ${api.coin} is ${blk}`)
})()

The general syntax for creating an API is

const api = Insight.create(coin, network, url)

where network and url are optional.

Here are more examples of creating an API.

const api = Insight.create('bsv', 'mainnet')

const api = Insight.create('ltc', 'testnet', 'https://localhost:3000/api')

Developer Installation

• clone repo: git clone https://github.com/the-bitcoin-token/bitcoin-source-api.git
• move to folder: cd bitcoin-source-api
• install: npm install

Test

• run unit tests: npm run test
• run Flow: npm run flow
• run Lint: npm run lint
• generate docs: npm run docs
• test coverage: npm run coverage

Integration tests are currently skipped to make the app easily portable.

Contact

If you have any problems or questions, please email brentongunning@gmail.com

Troubleshooting

Missing packages or objects during lint

If the npm run lint returns Flow errors complaining about missing packages or objects that should be present then Flow's cache is likely out of date. Run npx flow stop.

API

Table of Contents

• IInsightApiBasic
  • Properties
  • getBalance
    • Parameters
  • sendTransaction
    • Parameters
  • getBlockHash
    • Parameters
  • getLastBlockHash
  • getTransaction
    • Parameters
  • getRawTransaction
    • Parameters
  • getUtxos
    • Parameters
  • getTxo
    • Parameters
• coin
• network
• url
• getAddress
  • Parameters
• IInsightApi
  • Properties
  • getBlock
    • Parameters
  • getRawBlock
    • Parameters
• ApiInsightBase
  • Parameters
• BchInsightApi
  • Parameters
• BsvInsightApi
  • Parameters
• BTC_BITPAY_MAINNET_URL
• BTC_BITPAY_TESTNET_URL
• BtcInsightApi
  • Parameters
• LTC_LITECORE_MAINNET_URL
• LTC_LITECORE_TESTNET_URL
• LtcInsightApi
  • Parameters
• ApiError
  • Parameters
• Coin
• Network

IInsightApiBasic

REST API interface that all supported chains must implement.

Properties

• coin Coin
• network Network
• url string
• getAddress function (address: Address): Promise<Object>
• getBalance function (address: Address): Promise<number>
• sendTransaction function (transaction: Transaction): Promise<TransactionId>
• getBlockHash function (height: number): Promise<string>
• getLastBlockHash function (): Promise<string>
• getTransaction function (txId: string): Promise<Object>
• getRawTransaction function (txId: string): Promise<Object>
• getUtxos function (address: Address): Promise<Array<Txo>>
• getTxo function (outputId: OutputId): Promise<Txo>

getBalance

Retrieves a given address' balance in satoshis.

Parameters

• address Address to get balance of

• Throws ApiError if the request cannot be completed.

Returns Promise<number> the balance of the address

sendTransaction

Sends a transaction for broadcasting to the network.

Parameters

• the Transaction transaction to send

• Throws ApiError if the request cannot be completed.

Returns any the resulting transaction id

Returns Promise<TransactionId> a json object with the TxId that was sent

getBlockHash

Retrieves the hash of a block from its height.

Parameters

• height any Block height

• Throws ApiError if the request cannot be completed.

Returns Promise<string> a hex string containing the block hash

getLastBlockHash

Retrives the hash of the latest block.

• Throws ApiError if the request cannot be completed.

Returns Promise<string> a hex string containing the block hash of the most recent block

getTransaction

Retrieves a JSON-formatted transaction from its hash.

Parameters

• txId string Transaction hash

• Throws ApiError if the request cannot be completed.

Returns Promise<string> a JSON object of the decoded transaction

getRawTransaction

Retrieves a hex-formatted transaction given its hash.

Parameters

• txId string Transaction hash

• Throws ApiError if the request cannot be completed.

Returns Promise<string> a hex string containing the transaction bytes

getUtxos

Retrieves a given address' unspent outputs (UTXO set).

Parameters

• address Address Address whose UTXOs are to be retrieved

• Throws ApiError if the request cannot be completed.

Returns Promise<Array<Txo>> An array of unspent transaction outputs (UTXO) for the address

getTxo

Gets a transaction output given an output id.

Parameters

• outputId OutputId a JSON object containing the Transaction Id and output index to get

• Throws ApiError if the request cannot be completed.

Returns Promise<Txo> A Transaction output

coin

The coin that the api is configured for.

network

The network that the api is configured for. (i.e. mainnet vs testnet)

url

The url string for the REST API.

getAddress

Retrieves a given address' history.

Parameters

• address Address to get history for

• Throws ApiError If the request cannot be completed.

Returns Promise<Object> Address balance and a list of transaction history for the address

IInsightApi

Extends IInsightApiBasic

A REST API interface that all Insight APIs should implement to be considered complete

Properties

• getBlock function (hashOrHeight: (string | number)): Promise<Object>
• getRawBlock function (hashOrHeight: (string | number)): Promise<string>

getBlock

Retrieves a JSON-formatted block from its hash or height.

Parameters

• hashOrHeight (string | number) Hash or height of the block

• Throws ApiError if the request cannot be completed.

Returns Promise<Object> a JSON object of the block contents

getRawBlock

Retrives a hex-formatted block given its hash or height.

Parameters

• hashOrHeight (string | number) Hash or height of the block

• Throws ApiError if the request cannot be completed.

Returns Promise<string> a hex string of the block contents

ApiInsightBase

Base class for implementing Api

Parameters

• coin Coin
• network Network
• url string Insight API URL

BchInsightApi

Extends ApiInsight

API for BCH Insight nodes

Parameters

• network string mainnet or testnet
• url string Insight API URL endpoint

BsvInsightApi

Extends ApiInsightBase

API for BSV Insight nodes

Parameters

• network string mainnet or testnet
• url string Insight API URL

BTC_BITPAY_MAINNET_URL

Default BTC mainnet insight node url

Type: string

BTC_BITPAY_TESTNET_URL

Default BTC testnet insight node url

Type: string

BtcInsightApi

Extends ApiInsight

API for BTC Insight nodes

Parameters

• network Network
• url string Insight API URL

LTC_LITECORE_MAINNET_URL

Default LTC mainnet insight node url

Type: string

LTC_LITECORE_TESTNET_URL

Default LTC testnet insight node url

Type: string

LtcInsightApi

Extends ApiInsight

API for LTC Insight nodes

Parameters

• network Network
• url string Insight API URL

ApiError

Extends Error

A custom Error class to get better stack traces.

Parameters

• title
• detail
• params ...any

The Insight class is a Factory that constructs an Insight Api object for the caller. If passed a known coin then it creates a concrete class of that type. Example: Insight.create('bch', 'mainnet', 'http://localhost:3000') If passed known coin then we can find reasonable defaults for network and url example: Insight.create('bch') If passed an unknonwn coin then caller must also pass a url to give back a generic API implementation Example: Insight.create('mycoin', 'mainnet', 'http://localhost:3000') If passed an unknown coin then caller must also pass a url Example: Insight.create('throwsErrorBecauseNoUrl')

Coin

Coins that have been tested with the API

Type: ("bch" | "bsv" | "btc" | "ltc")

Network

Coin Networks

Type: ("mainnet" | "testnet")