**Blockbook** provides REST, websocket and socket.io API to the indexed blockchain.
There are two versions of provided API.
## Legacy API V1
The legacy API is a compatible subset of API provided by **Bitcore Insight**. It supports only Bitcoin-type coins. The details of the REST/socket.io requests can be found in the Insight's documentation.
### REST API
```
GET /api/v1/block-index/<blockheight>
GET /api/v1/tx/<txid>
GET /api/v1/address/<address>
GET /api/v1/utxo/<address>
GET /api/v1/block/<blockheight|blockhash>
GET /api/v1/estimatefee/<numberofblocks>
GET /api/v1/sendtx/<hextxdata>
POST /api/v1/sendtx (hex tx data in request body)
```
### Socket.io API
Socket.io interface is provided at `/socket.io/`. The interface also can be explored using Blockbook Socket.io Test Page found at `/test-socketio.html`.
The legacy API is provided as is and will not be further developed.
The legacy API is currently (Blockbook v0.3.1) also accessible without the */v1/* prefix, however in the future versions the version less access will be removed.
API V2 is the current version of API. It can be used with all coin types that Blockbook supports. API V2 can be accessed using REST and websocket interface.
Common principles used in API V2:
- all amounts are transferred as strings, in the lowest denomination (satoshis, wei, ...), without decimal point
- empty fields are omitted. Empty field is a string of value *null* or *""*, a number of value *0*, an object of value *null* or an array without elements. The reason for this is that the interface serves many different coins which use only subset of the fields. Sometimes this principle can lead to slightly confusing results, for example when transaction version is 0, the field *version* is omitted.
Get transaction returns "normalized" data about transaction, which has the same general structure for all supported coins. It does not return coin specific fields (for example information about Zcash shielded addresses).
Response for Ethereum-type coins. There is always only one *vin*, only one *vout*, possibly an array of *tokenTransfers* and *ethereumSpecific* part. Missing is *hex* field:
- for transactions in mempool (`confirmations == 0`), the field contains time when the running instance of Blockbook was first time notified about the transaction. This time may be different in different instances of Blockbook.
Returns balances and transactions of an xpub, applicable only for Bitcoin-type coins.
Blockbook supports BIP44, BIP49 and BIP84 derivation schemes. It expects xpub at level 3 derivation path, i.e. *m/purpose'/coin_type'/account'/*. Blockbook completes the *change/address_index* part of the path when deriving addresses.
The BIP version is determined by the prefix of the xpub. The prefixes for each coin are defined by fields `xpub_magic`, `xpub_magic_segwit_p2sh`, `xpub_magic_segwit_native` in the [trezor-common](https://github.com/trezor/trezor-common/tree/master/defs/bitcoin) library. If the prefix is not recognized, Blockbook defaults to BIP44 derivation scheme.
The returned transactions are sorted by block height, newest blocks first.
GET /api/v2/xpub/<xpub>[?page=<page>&pageSize=<size>&from=<blockheight>&to=<blockheight>&details=<basic|tokens|tokenBalances|txids|txs>&tokens=<nonzero|used|derived>]
```
The optional query parameters:
- *page*: specifies page of returned transactions, starting from 1. If out of range, Blockbook returns the closest possible page.
- *pageSize*: number of transactions returned by call (default and maximum 1000)
- *from*, *to*: filter of the returned transactions *from* block height *to* block height (default no filter)
- *details*: specifies level of details returned by request (default *txids*)
- *basic*: return only xpub balances, without any derived addresses and transactions
- *tokens*: *basic* + tokens (addresses) derived from the xpub, subject to *tokens* parameter
- *tokenBalances*: *basic* + tokens (addresses) derived from the xpub with balances, subject to *tokens* parameter
- *txids*: *tokenBalances* + list of txids, subject to *from*, *to* filter and paging
- *txs*: *tokenBalances* + list of transaction with details, subject to *from*, *to* filter and paging
- *tokens*: specifies what tokens (xpub addresses) are returned by the request (default *nonzero*)
- *nonzero*: return only addresses with nonzero balance
- *used*: return addresses with at least one transaction
Returns array of unspent transaction outputs of address or xpub, applicable only for Bitcoin-type coins. By default, the list contains both confirmed and unconfirmed transactions. The query parameter *confirmed=true* disables return of unconfirmed transactions. The returned utxos are sorted by block height, newest blocks first. For xpubs the response also contains address and derivation path of the utxo.
Coinbase utxos do have field *coinbase* set to true, however due to performance reasons only up to minimum coinbase confirmations limit (100). After this limit, utxos are not detected as coinbase.
_Note: Blockbook always follows the main chain of the backend it is attached to. If there is a rollback-reorg in the backend, Blockbook will also do rollback. When you ask for block by height, you will always get the main chain block. If you ask for block by hash, you may get the block from another fork but it is not guaranteed (backend may not keep it)_
Returns a list of available currency rate tickers for the specified timestamp.
```
GET /api/v2/tickers-list/?timestamp=<timestamp>
```
The query parameters:
- *timestamp*: specifies a UNIX timestamp to return available tickers for.
Example response:
```javascript
{
"ts":1574346615,
"available_currencies": [
"eur",
"usd"
]
}
```
#### Tickers
Returns currency rate for the specified currency and date. If the currency is not available for that specific timestamp, the closest rate will be returned.
All responses contain an actual rate timestamp.
```
GET /api/v2/tickers/[?currency=<currency>×tamp=<timestamp>]
```
The optional query parameters:
- *currency*: specifies a currency of returned rate ("usd", "eur", "eth"...). If not specified, all available currencies will be returned.
- *timestamp*: a UNIX timestamp that specifies a date to return currency rates for. If not specified, the last available rate will be returned.
Example response (no parameters):
```javascript
{
"ts":1574346615,
"rates": {
"eur":7134.1,
"usd":7914.5
}
}
```
Example response (currency=usd):
```javascript
{
"ts":1574346615,
"rate":7914.5
}
```
Example error response (e.g. rate unavailable, incorrect currency...):
```javascript
{
"ts":7980386400,
"rate":-1
}
```
#### Balance history
Returns a balance history for the specified XPUB or address.
```
GET /api/v2/balancehistory/<XPUB|address>?from=<dateFrom>&to=<dateTo>[&fiatcurrency=<currency>&gap=<gap>&groupBy=<groupBySeconds>]
```
Query parameters:
- *from*: specifies a start date, format is YYYY-MM-DD.
- *to*: specifies an end date, same format.
The optional query parameters:
- *fiatcurrency*: if specified, the response will contain calculated fiat amounts at the time of transaction.
- *gap*: TODO
- *groupBy*: an interval in seconds, to group results by. Default is 3600 seconds.