github.com/trezor/blockbook@v0.4.1-0.20240328132726-e9a08582ee2c/docs/api.md (about)

     1  # Blockbook API
     2  
     3  **Blockbook** provides REST and websocket API to the indexed blockchain.
     4  
     5  ## API V2
     6  
     7  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.
     8  
     9  Common principles used in API V2:
    10  
    11  - all crypto amounts are transferred as strings, in the lowest denomination (satoshis, wei, ...), without decimal point
    12  - 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.
    13  
    14  ### REST API
    15  
    16  The following methods are supported:
    17  
    18  - [Status](#status)
    19  - [Get block hash](#get-block-hash)
    20  - [Get transaction](#get-transaction)
    21  - [Get transaction specific](#get-transaction-specific)
    22  - [Get address](#get-address)
    23  - [Get xpub](#get-xpub)
    24  - [Get utxo](#get-utxo)
    25  - [Get block](#get-block)
    26  - [Send transaction](#send-transaction)
    27  - [Tickers list](#tickers-list)
    28  - [Tickers](#tickers)
    29  - [Balance history](#balance-history)
    30  
    31  #### Status page
    32  
    33  Status page returns current status of Blockbook and connected backend.
    34  
    35  ```
    36  GET /api
    37  ```
    38  
    39  Response:
    40  
    41  ```javascript
    42  {
    43    "blockbook": {
    44      "coin": "Bitcoin",
    45      "host": "blockbook",
    46      "version": "0.4.0",
    47      "gitCommit": "3d9ad91",
    48      "buildTime": "2019-05-17T14:34:00+00:00",
    49      "syncMode": true,
    50      "initialSync": false,
    51      "inSync": true,
    52      "bestHeight": 577261,
    53      "lastBlockTime": "2019-05-22T18:03:33.547762973+02:00",
    54      "inSyncMempool": true,
    55      "lastMempoolTime": "2019-05-22T18:10:10.27929383+02:00",
    56      "mempoolSize": 17348,
    57      "decimals": 8,
    58      "dbSize": 191887866502,
    59      "about": "Blockbook - blockchain indexer for Trezor wallet https://trezor.io/. Do not use for any other purpose."
    60    },
    61    "backend": {
    62      "chain": "main",
    63      "blocks": 577261,
    64      "headers": 577261,
    65      "bestBlockHash": "0000000000000000000ca8c902aa58b3118a7f35d093e25a07f17bcacd91cabf",
    66      "difficulty": "6704632680587.417",
    67      "sizeOnDisk": 250504188580,
    68      "version": "180000",
    69      "subversion": "/Satoshi:0.18.0/",
    70      "protocolVersion": "70015",
    71      "timeOffset": 0,
    72      "warnings": ""
    73    }
    74  }
    75  ```
    76  
    77  #### Get block hash
    78  
    79  ```
    80  GET /api/v2/block-index/<block height>
    81  ```
    82  
    83  Response:
    84  
    85  ```javascript
    86  {
    87    "blockHash": "ed8f3af8c10ca70a136901c6dd3adf037f0aea8a93fbe9e80939214034300f1e"
    88  }
    89  ```
    90  
    91  _Note: Blockbook always follows the main chain of the backend it is attached to. See notes on **Get Block** below_
    92  
    93  #### Get transaction
    94  
    95  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).
    96  
    97  ```
    98  GET /api/v2/tx/<txid>
    99  ```
   100  
   101  Response for Bitcoin-type coins, confirmed transaction:
   102  
   103  ```javascript
   104  {
   105    "txid": "9e2bc8fbd40af17a6564831f84aef0cab2046d4bad19e91c09d21bff2c851851",
   106    "version": 1,
   107    "vin": [
   108      {
   109        "txid": "f124e6999bf67e710b9e8a8ac4dbb08a64aa9c264120cf98793455e36a531615",
   110        "vout": 2,
   111        "sequence": 4294967295,
   112        "n": 0,
   113        "addresses": [
   114          "DDhUv8JZGmSxKYV95NLnbRTUKni9cDZD3S"
   115        ],
   116        "isAddress": true,
   117        "value": "55795108999999",
   118        "hex": "473...2c7ec77bb982"
   119      }
   120    ],
   121    "vout": [
   122      {
   123        "value": "55585679000000",
   124        "n": 0,
   125        "hex": "76a914feaca9d9fa7120c7c587c00c639bb18d40faadd388ac",
   126        "addresses": [
   127          "DUMh1rPrXTrCN2Z9EHsLPg7b78rACHB2h7"
   128        ],
   129        "isAddress": true
   130      },
   131      {
   132        "value": "209329999999",
   133        "n": 1,
   134        "hex": "76a914ea8984be785868391d92f49c14933f47c152ea0a88ac",
   135        "addresses": [
   136          "DSXDQ6rnwLX47WFRnemctoXPHA9pLMxqXn"
   137        ],
   138        "isAddress": true
   139      }
   140    ],
   141    "blockHash": "78d1f3de899a10dd2e580704226ebf9508e95e1706f177fc9c31c47f245d2502",
   142    "blockHeight": 2647927,
   143    "confirmations": 1,
   144    "blockTime": 1553088212,
   145    "size": 234,
   146    "vsize": 153,
   147    "value": "55795008999999",
   148    "valueIn": "55795108999999",
   149    "fees": "100000000",
   150    "hex": "0100000...0011000"
   151  }
   152  ```
   153  
   154  Response for Bitcoin-type coins, unconfirmed transaction (_blockHeight_: -1, _confirmations_: 0, mining estimates _confirmationETABlocks_ and _confirmationETASeconds_):
   155  
   156  ```javascript
   157  {
   158    "txid": "cd8ec77174e426070d0a50779232bba7312b712e2c6843d82d963d7076c61366",
   159    "version": 2,
   160    "vin": [
   161      {
   162        "txid": "47687cc4abb58d815168686465a38113a0608b2568a6d6480129d197e653f6dc",
   163        "sequence": 4294967295,
   164        "n": 0,
   165        "addresses": ["bc1qka0gpenex558g8gpxmpx247mwhw695k6a7yhs4"],
   166        "isAddress": true,
   167        "value": "1983687"
   168      }
   169    ],
   170    "vout": [
   171      {
   172        "value": "3106",
   173        "n": 0,
   174        "hex": "0020d7da4868055fde790a8581637ab81c216e17a3f8a099283da6c4a27419ffa539",
   175        "addresses": [
   176          "bc1q6ldys6q9tl08jz59s93h4wquy9hp0glc5zvjs0dxcj38gx0l55uspu8x86"
   177        ],
   178        "isAddress": true
   179      },
   180      {
   181        "value": "1979101",
   182        "n": 1,
   183        "hex": "0014381be30ca46ddf378ef69ebc4a601bd6ff30b754",
   184        "addresses": ["bc1q8qd7xr9ydh0n0rhkn67y5cqm6mlnpd65dcyeeg"],
   185        "isAddress": true
   186      }
   187    ],
   188    "blockHeight": -1,
   189    "confirmations": 0,
   190    "confirmationETABlocks": 3,
   191    "confirmationETASeconds": 2055,
   192    "blockTime": 1675270935,
   193    "size": 234,
   194    "vsize": 153,
   195    "value": "1982207",
   196    "valueIn": "1983687",
   197    "fees": "1480",
   198    "hex": "020000000001...b18f00000000"
   199  }
   200  ```
   201  
   202  Response for Ethereum-type coins. Data of the transaction consist of:
   203  
   204  - always only one _vin_, only one _vout_
   205  - an array of _tokenTransfers_ (ERC20, ERC721 or ERC1155)
   206  - _ethereumSpecific_ data
   207    - _type_ (returned only for contract creation - value `1` and destruction value `2`)
   208    - _status_ (`1` OK, `0` Failure, `-1` pending), potential _error_ message, _gasLimit_, _gasUsed_, _gasPrice_, _nonce_, input _data_
   209    - parsed input data in the field _parsedData_, if a match with the 4byte directory was found
   210    - internal transfers (type `0` transfer, type `1` contract creation, type `2` contract destruction)
   211  - _addressAliases_ - maps addresses in the transaction to names from contract or ENS. Only addresses with known names are returned.
   212  
   213  ```javascript
   214  {
   215    "txid": "0xa6c8ae1f91918d09cf2bd67bbac4c168849e672fd81316fa1d26bb9b4fc0f790",
   216    "vin": [
   217      {
   218        "n": 0,
   219        "addresses": ["0xd446089cf19C3D3Eb1743BeF3A852293Fd2C7775"],
   220        "isAddress": true
   221      }
   222    ],
   223    "vout": [
   224      {
   225        "value": "5615959129349132871",
   226        "n": 0,
   227        "addresses": ["0xC36442b4a4522E871399CD717aBDD847Ab11FE88"],
   228        "isAddress": true
   229      }
   230    ],
   231    "blockHash": "0x10ea8cfecda89d6d864c1d919911f819c9febc2b455b48c9918cee3c6cdc4adb",
   232    "blockHeight": 16529834,
   233    "confirmations": 3,
   234    "blockTime": 1675204631,
   235    "value": "5615959129349132871",
   236    "fees": "19141662404282012",
   237    "tokenTransfers": [
   238      {
   239        "type": "ERC20",
   240        "from": "0xd446089cf19C3D3Eb1743BeF3A852293Fd2C7775",
   241        "to": "0x3B685307C8611AFb2A9E83EBc8743dc20480716E",
   242        "contract": "0x4E15361FD6b4BB609Fa63C81A2be19d873717870",
   243        "name": "Fantom Token",
   244        "symbol": "FTM",
   245        "decimals": 18,
   246        "value": "15362368338194882707417"
   247      },
   248      {
   249        "type": "ERC20",
   250        "from": "0xC36442b4a4522E871399CD717aBDD847Ab11FE88",
   251        "to": "0x3B685307C8611AFb2A9E83EBc8743dc20480716E",
   252        "contract": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
   253        "name": "Wrapped Ether",
   254        "symbol": "WETH",
   255        "decimals": 18,
   256        "value": "5615959129349132871"
   257      },
   258      {
   259        "type": "ERC721",
   260        "from": "0x0000000000000000000000000000000000000000",
   261        "to": "0xd446089cf19C3D3Eb1743BeF3A852293Fd2C7775",
   262        "contract": "0xC36442b4a4522E871399CD717aBDD847Ab11FE88",
   263        "name": "Uniswap V3 Positions NFT-V1",
   264        "symbol": "UNI-V3-POS",
   265        "decimals": 18,
   266        "value": "428189"
   267      }
   268    ],
   269    "ethereumSpecific": {
   270      "status": 1,
   271      "nonce": 505,
   272      "gasLimit": 550941,
   273      "gasUsed": 434686,
   274      "gasPrice": "44035608242",
   275      "data": "0xac9650d800000000000000000000",
   276      "parsedData": {
   277        "methodId": "0xfa2b068f",
   278        "name": "Mint",
   279        "function": "mint(address, uint256, uint32, bytes32[], address)",
   280        "params": [
   281          {
   282            "type": "address",
   283            "values": ["0xa5fD1Da088598e88ba731B0E29AECF0BC2A31F82"]
   284          },
   285          { "type": "uint256", "values": ["688173296"] },
   286          { "type": "uint32", "values": ["0"] }
   287        ]
   288      },
   289      "internalTransfers": [
   290        {
   291          "type": 0,
   292          "from": "0xC36442b4a4522E871399CD717aBDD847Ab11FE88",
   293          "to": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
   294          "value": "5615959129349132871"
   295        }
   296      ]
   297    },
   298    "addressAliases": {
   299      "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2": {
   300        "Type": "Contract",
   301        "Alias": "Wrapped Ether"
   302      },
   303      "0xC36442b4a4522E871399CD717aBDD847Ab11FE88": {
   304        "Type": "Contract",
   305        "Alias": "Uniswap V3 Positions NFT-V1"
   306      }
   307    }
   308  }
   309  
   310  ```
   311  
   312  A note about the `blockTime` field:
   313  
   314  - for already mined transaction (`confirmations > 0`), the field `blockTime` contains time of the block
   315  - 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.
   316  
   317  #### Get transaction specific
   318  
   319  Returns transaction data in the exact format as returned by backend, including all coin specific fields:
   320  
   321  ```
   322  GET /api/v2/tx-specific/<txid>
   323  ```
   324  
   325  Example response:
   326  
   327  ```javascript
   328  {
   329    "hex": "040000808...8e6e73cb009",
   330    "txid": "7a0a0ff6f67bac2a856c7296382b69151949878de6fb0d01a8efa197182b2913",
   331    "overwintered": true,
   332    "version": 4,
   333    "versiongroupid": "892f2085",
   334    "locktime": 0,
   335    "expiryheight": 495680,
   336    "vin": [],
   337    "vout": [],
   338    "vjoinsplit": [],
   339    "valueBalance": 0,
   340    "vShieldedSpend": [
   341      {
   342        "cv": "50258bfa65caa9f42f4448b9194840c7da73afc8159faf7358140bfd0f237962",
   343        "anchor": "6beb3b64ecb30033a9032e1a65a68899917625d1fdd2540e70f19f3078f5dd9b",
   344        "nullifier": "08e5717f6606af7c2b01206ff833eaa6383bb49c7451534b2e16d588956fd10a",
   345        "rk": "36841a9be87a7022445b77f433cdd0355bbed498656ab399aede1e5285e9e4a2",
   346        "proof": "aecf824dbae8eea863ec6...73878c37391f01df520aa",
   347        "spendAuthSig": "65b9477cb1ec5da...1178fe402e5702c646945197108339609"
   348      },
   349      {
   350        "cv": "a5aab3721e33d6d6360eabd21cbd07524495f202149abdc3eb30f245d503678c",
   351        "anchor": "6beb3b64ecb30033a9032e1a65a68899917625d1fdd2540e70f19f3078f5dd9b",
   352        "nullifier": "60e790d6d0e12e777fb2b18bc97cf42a92b1e47460e1bd0b0ffd294c23232cc9",
   353        "rk": "2d741695e76351597712b4a04d2a4e108a116f376283d2d104219b86e2930117",
   354        "proof": "a0c2a6fdcbba966b9894...3a9c3118b76c8e2352d524cbb44c02decaeda7",
   355        "spendAuthSig": "feea902e01eac9ebd...b43b4af6b607ce5b0b38f708"
   356      }
   357    ],
   358    "vShieldedOutput": [
   359      {
   360        "cv": "23db384cde862f20238a1004e57ba18f114acabc7fd2ac029757f82af5bd4cab",
   361        "cmu": "3ff5a5ff521fabefb5287fef4feb2642d69ead5fe18e6ac717cfd76a8d4088bc",
   362        "ephemeralKey": "057ff6e059967784fa6ac34ad9ecfd9c0c0aba743b7cd444a65ecc32192d5870",
   363        "encCiphertext": "a533d3b99b...a0204",
   364        "outCiphertext": "4baabc15199504b1...c1ad6a",
   365        "proof": "aa1fb2706cba5...1ec7e81f5deea90d4f57713f3b4fc8d636908235fa378ebf1"
   366      }
   367    ],
   368    "bindingSig": "bc018af8808387...5130bb382ad8e6e73cb009",
   369    "blockhash": "0000000001c4aa394e796dd1b82e358f114535204f6f5b6cf4ad58dc439c47af",
   370    "confirmations": 5222,
   371    "time": 1552301566,
   372    "blocktime": 1552301566
   373  }
   374  ```
   375  
   376  #### Get address
   377  
   378  Returns balances and transactions of an address. The returned transactions are sorted by block height, newest blocks first.
   379  
   380  ```
   381  GET /api/v2/address/<address>[?page=<page>&pageSize=<size>&from=<block height>&to=<block height>&details=<basic|tokens|tokenBalances|txids|txs>&contract=<contract address>&secondary=usd]
   382  ```
   383  
   384  The optional query parameters:
   385  
   386  - _page_: specifies page of returned transactions, starting from 1. If out of range, Blockbook returns the closest possible page.
   387  - _pageSize_: number of transactions returned by call (default and maximum 1000)
   388  - _from_, _to_: filter of the returned transactions _from_ block height _to_ block height (default no filter)
   389  - _details_: specifies level of details returned by request (default _txids_)
   390    - _basic_: return only address balances, without any transactions
   391    - _tokens_: _basic_ + tokens belonging to the address (applicable only to some coins)
   392    - _tokenBalances_: _basic_ + tokens with balances + belonging to the address (applicable only to some coins)
   393    - _txids_: _tokenBalances_ + list of txids, subject to _from_, _to_ filter and paging
   394    - _txslight_: _tokenBalances_ + list of transaction with limited details (only data from index), subject to _from_, _to_ filter and paging
   395    - _txs_: _tokenBalances_ + list of transaction with details, subject to _from_, _to_ filter and paging
   396  - _contract_: return only transactions which affect specified contract (applicable only to coins which support contracts)
   397  - _secondary_: specifies secondary (fiat) currency in which the token and total balances are returned in addition to crypto values
   398  
   399  Example response for bitcoin type coin, _details_ set to _txids_:
   400  
   401  ```javascript
   402  {
   403    "page": 1,
   404    "totalPages": 1,
   405    "itemsOnPage": 1000,
   406    "address": "D5Z7XrtJNg7hAtznSDMXvfiFmMYphwuWz7",
   407    "balance": "2432468097999991",
   408    "totalReceived": "3992283916999979",
   409    "totalSent": "1559815818999988",
   410    "unconfirmedBalance": "0",
   411    "unconfirmedTxs": 0,
   412    "txs": 3,
   413    "txids": [
   414      "461dd46d5d6f56d765f82e60e6bf0727a3a1d1cb8c4144373d805b152a21d308",
   415      "bdb5b47603c5d174eae3384c368068c8e9d2183b398ed0e31d125defa4447a10",
   416      "5c1d2686d70d82bd8e84b5d3dc4bd0e8485e28cdc865336db6a5e40b2098277d"
   417    ]
   418  }
   419  ```
   420  
   421  Example response for ethereum type coin, _details_ set to _tokenBalances_ and _secondary_ set to _usd_. The _baseValue_ is value of the token in the base currency (ETH), _secondaryValue_ is value of the token in specified _secondary_ currency:
   422  
   423  ```javascript
   424  {
   425    "address": "0x2df3951b2037bA620C20Ed0B73CCF45Ea473e83B",
   426    "balance": "21004631949601199",
   427    "unconfirmedBalance": "0",
   428    "unconfirmedTxs": 0,
   429    "txs": 5,
   430    "nonTokenTxs": 3,
   431    "nonce": "1",
   432    "tokens": [
   433      {
   434        "type": "ERC20",
   435        "name": "Tether USD",
   436        "contract": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
   437        "transfers": 3,
   438        "symbol": "USDT",
   439        "decimals": 6,
   440        "balance": "4913000000",
   441        "baseValue": 3.104622978658881,
   442        "secondaryValue": 4914.214559070491
   443      }
   444    ],
   445    "secondaryValue": 33.247601671503574,
   446    "tokensBaseValue": 3.104622978658881,
   447    "tokensSecondaryValue": 4914.214559070491,
   448    "totalBaseValue": 3.125627610608482,
   449    "totalSecondaryValue": 4947.462160741995
   450  }
   451  
   452  ```
   453  
   454  #### Get xpub
   455  
   456  Returns balances and transactions of an xpub or output descriptor, applicable only for Bitcoin-type coins.
   457  
   458  Blockbook supports BIP44, BIP49, BIP84 and BIP86 (Taproot) derivation schemes, using either xpubs or output descriptors (see https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md)
   459  
   460  - Xpubs
   461  
   462    Blockbook 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.
   463    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.
   464  
   465  - Output descriptors
   466  
   467    Output descriptors are in the form `<type>([<path>]<xpub>[/<change>/*])[#checksum]`, for example `pkh([5c9e228d/44'/0'/0']xpub6BgBgses...Mj92pReUsQ/<0;1>/*)#abcd`
   468  
   469    Parameters `type` and `xpub` are mandatory, the rest is optional
   470  
   471    Blockbook supports a limited set of `type`s:
   472  
   473    - BIP44: `pkh(xpub)`
   474    - BIP49: `sh(wpkh(xpub))`
   475    - BIP84: `wpkh(xpub)`
   476    - BIP86 (Taproot single key): `tr(xpub)`
   477  
   478    Parameter `change` can be a single number or a list of change indexes, specified either in the format `<index1;index2;...>` or `{index1,index2,...}`. If the parameter `change` is not specified, Blockbook defaults to `<0;1>`.
   479  
   480  The returned transactions are sorted by block height, newest blocks first.
   481  
   482  ```
   483  GET /api/v2/xpub/<xpub|descriptor>[?page=<page>&pageSize=<size>&from=<block height>&to=<block height>&details=<basic|tokens|tokenBalances|txids|txs>&tokens=<nonzero|used|derived>&secondary=eur]
   484  ```
   485  
   486  The optional query parameters:
   487  
   488  - _page_: specifies page of returned transactions, starting from 1. If out of range, Blockbook returns the closest possible page.
   489  - _pageSize_: number of transactions returned by call (default and maximum 1000)
   490  - _from_, _to_: filter of the returned transactions _from_ block height _to_ block height (default no filter)
   491  - _details_: specifies level of details returned by request (default _txids_)
   492    - _basic_: return only xpub balances, without any derived addresses and transactions
   493    - _tokens_: _basic_ + tokens (addresses) derived from the xpub, subject to _tokens_ parameter
   494    - _tokenBalances_: _basic_ + tokens (addresses) derived from the xpub with balances, subject to _tokens_ parameter
   495    - _txids_: _tokenBalances_ + list of txids, subject to _from_, _to_ filter and paging
   496    - _txs_: _tokenBalances_ + list of transaction with details, subject to _from_, _to_ filter and paging
   497  - _tokens_: specifies what tokens (xpub addresses) are returned by the request (default _nonzero_)
   498    - _nonzero_: return only addresses with nonzero balance
   499    - _used_: return addresses with at least one transaction
   500    - _derived_: return all derived addresses
   501  - _secondary_: specifies secondary (fiat) currency in which the balances are returned in addition to crypto values
   502  
   503  Response:
   504  
   505  ```javascript
   506  {
   507    "page": 1,
   508    "totalPages": 1,
   509    "itemsOnPage": 1000,
   510    "address": "dgub8sbe5Mi8LA4dXB9zPfLZW8arm...9Vjp2HHx91xdDEmWYpmD49fpoUYF",
   511    "balance": "90000000",
   512    "totalReceived": "3093381250",
   513    "totalSent": "3083381250",
   514    "unconfirmedBalance": "0",
   515    "unconfirmedTxs": 0,
   516    "txs": 5,
   517    "txids": [
   518      "383ccb5da16fccad294e24a2ef77bdee5810573bb1b252d8b2af4f0ac8c4e04c",
   519      "75fb93d47969ac92112628e39148ad22323e96f0004c18f8c75938cffb6c1798",
   520      "e8cd84f204b4a42b98e535e72f461dd9832aa081458720b0a38db5856a884876",
   521      "57833d50969208091bd6c950599a1b5cf9d66d992ae8a8d3560fb943b98ebb23",
   522      "9cfd6295f20e74ddca6dd816c8eb71a91e4da70fe396aca6f8ce09dc2947839f",
   523    ],
   524    "usedTokens": 2,
   525    "tokens": [
   526      {
   527        "type": "XPUBAddress",
   528        "name": "DUCd1B3YBiXL5By15yXgSLZtEkvwsgEdqS",
   529        "path": "m/44'/3'/0'/0/0",
   530        "transfers": 3,
   531        "decimals": 8,
   532        "balance": "90000000",
   533        "totalReceived": "2903986975",
   534        "totalSent": "2803986975"
   535      },
   536      {
   537        "type": "XPUBAddress",
   538        "name": "DKu2a8Wo6zC2dmBBYXwUG3fxWDHbKnNiPj",
   539        "path": "m/44'/3'/0'/1/0",
   540        "transfers": 2,
   541        "decimals": 8,
   542        "balance": "0",
   543        "totalReceived": "279394275",
   544        "totalSent": "279394275"
   545      }
   546    ],
   547    "secondaryValue": 21195.47633568
   548  }
   549  ```
   550  
   551  Note: _usedTokens_ always returns total number of **used** addresses of xpub.
   552  
   553  #### Get utxo
   554  
   555  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 or output descriptors, the response also contains address and derivation path of the utxo.
   556  
   557  Unconfirmed utxos do not have field _height_, the field _confirmations_ has value _0_ and may contain field _lockTime_, if not zero.
   558  
   559  Coinbase utxos 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.
   560  
   561  ```
   562  GET /api/v2/utxo/<address|xpub|descriptor>[?confirmed=true]
   563  ```
   564  
   565  Response:
   566  
   567  ```javascript
   568  [
   569    {
   570      txid: "13d26cd939bf5d155b1c60054e02d9c9b832a85e6ec4f2411be44b6b5a2842e9",
   571      vout: 0,
   572      value: "1422303206539",
   573      confirmations: 0,
   574      lockTime: 2648100,
   575    },
   576    {
   577      txid: "a79e396a32e10856c97b95f43da7e9d2b9a11d446f7638dbd75e5e7603128cac",
   578      vout: 1,
   579      value: "39748685",
   580      height: 2648043,
   581      confirmations: 47,
   582      coinbase: true,
   583    },
   584    {
   585      txid: "de4f379fdc3ea9be063e60340461a014f372a018d70c3db35701654e7066b3ef",
   586      vout: 0,
   587      value: "122492339065",
   588      height: 2646043,
   589      confirmations: 2047,
   590    },
   591    {
   592      txid: "9e8eb9b3d2e8e4b5d6af4c43a9196dfc55a05945c8675904d8c61f404ea7b1e9",
   593      vout: 0,
   594      value: "142771322208",
   595      height: 2644885,
   596      confirmations: 3205,
   597    },
   598  ];
   599  ```
   600  
   601  #### Get block
   602  
   603  Returns information about block with transactions, subject to paging.
   604  
   605  ```
   606  GET /api/v2/block/<block height|block hash>
   607  ```
   608  
   609  Response:
   610  
   611  ```javascript
   612  {
   613    "page": 1,
   614    "totalPages": 1,
   615    "itemsOnPage": 1000,
   616    "hash": "760f8ed32894ccce9c1ea11c8a019cadaa82bcb434b25c30102dd7e43f326217",
   617    "previousBlockHash": "786a1f9f38493d32fd9f9c104d748490a070bc74a83809103bcadd93ae98288f",
   618    "nextBlockHash": "151615691b209de41dda4798a07e62db8429488554077552ccb1c4f8c7e9f57a",
   619    "height": 2648059,
   620    "confirmations": 47,
   621    "size": 951,
   622    "time": 1553096617,
   623    "version": 6422787,
   624    "merkleRoot": "6783f6083788c4f69b8af23bd2e4a194cf36ac34d590dfd97e510fe7aebc72c8",
   625    "nonce": "0",
   626    "bits": "1a063f3b",
   627    "difficulty": "2685605.260733312",
   628    "txCount": 2,
   629    "txs": [
   630      {
   631        "txid": "2b9fc57aaa8d01975631a703b0fc3f11d70671953fc769533b8078a04d029bf9",
   632        "vin": [
   633          {
   634            "n": 0,
   635            "value": "0"
   636          }
   637        ],
   638        "vout": [
   639          {
   640            "value": "1000100000000",
   641            "n": 0,
   642            "addresses": [
   643              "D6ravJL6Fgxtgp8k2XZZt1QfUmwwGuLwQJ"
   644            ],
   645            "isAddress": true
   646          }
   647        ],
   648        "blockHash": "760f8ed32894ccce9c1ea11c8a019cadaa82bcb434b25c30102dd7e43f326217",
   649        "blockHeight": 2648059,
   650        "confirmations": 47,
   651        "blockTime": 1553096617,
   652        "value": "1000100000000",
   653        "valueIn": "0",
   654        "fees": "0"
   655      },
   656      {
   657        "txid": "d7ce10ecf9819801ecd6ee045cbb33436eef36a7db138206494bacedfd2832cf",
   658        "vin": [
   659          {
   660            "n": 0,
   661            "addresses": [
   662              "9sLa1AKzjWuNTe1CkLh5GDYyRP9enb1Spp"
   663            ],
   664            "isAddress": true,
   665            "value": "1277595845202"
   666          }
   667        ],
   668        "vout": [
   669          {
   670            "value": "9900000000",
   671            "n": 0,
   672            "addresses": [
   673              "DMnjrbcCEoeyvr7GEn8DS4ZXQjwq7E2zQU"
   674            ],
   675            "isAddress": true
   676          },
   677          {
   678            "value": "1267595845202",
   679            "n": 1,
   680            "spent": true,
   681            "addresses": [
   682              "9sLa1AKzjWuNTe1CkLh5GDYyRP9enb1Spp"
   683            ],
   684            "isAddress": true
   685          }
   686        ],
   687        "blockHash": "760f8ed32894ccce9c1ea11c8a019cadaa82bcb434b25c30102dd7e43f326217",
   688        "blockHeight": 2648059,
   689        "confirmations": 47,
   690        "blockTime": 1553096617,
   691        "value": "1277495845202",
   692        "valueIn": "1277595845202",
   693        "fees": "100000000"
   694      }
   695    ]
   696  }
   697  ```
   698  
   699  _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)_
   700  
   701  #### Send transaction
   702  
   703  Sends new transaction to backend.
   704  
   705  ```
   706  GET /api/v2/sendtx/<hex tx data>
   707  POST /api/v2/sendtx/ (hex tx data in request body)  NB: the '/' symbol at the end is mandatory.
   708  ```
   709  
   710  Response:
   711  
   712  ```javascript
   713  {
   714    "result": "7c3be24063f268aaa1ed81b64776798f56088757641a34fb156c4f51ed2e9d25"
   715  }
   716  ```
   717  
   718  or in case of error
   719  
   720  ```javascript
   721  {
   722    "error": {
   723      "message": "error message"
   724    }
   725  }
   726  ```
   727  
   728  #### Tickers list
   729  
   730  Returns a list of available currency rate tickers (secondary currencies) for the specified date, along with an actual data timestamp.
   731  
   732  ```
   733  GET /api/v2/tickers-list/?timestamp=<timestamp>
   734  ```
   735  
   736  The query parameters:
   737  
   738  - _timestamp_: specifies a Unix timestamp to return available tickers for.
   739  
   740  Example response:
   741  
   742  ```javascript
   743  {
   744    "ts":1574346615,
   745    "available_currencies": [
   746      "eur",
   747      "usd"
   748    ]
   749  }
   750  ```
   751  
   752  #### Tickers
   753  
   754  Returns currency rate for the specified currency and date. If the currency is not available for that specific timestamp, the next closest rate will be returned.
   755  All responses contain an actual rate timestamp.
   756  
   757  ```
   758  GET /api/v2/tickers/[?currency=<currency>&timestamp=<timestamp>]
   759  ```
   760  
   761  The optional query parameters:
   762  
   763  - _currency_: specifies a currency of returned rate ("usd", "eur", "eth"...). If not specified, all available currencies will be returned.
   764  - _timestamp_: a Unix timestamp that specifies a date to return currency rates for. If not specified, the last available rate will be returned.
   765  
   766  Example response (no parameters):
   767  
   768  ```javascript
   769  {
   770    "ts": 1574346615,
   771    "rates": {
   772      "eur": 7134.1,
   773      "usd": 7914.5
   774      }
   775  }
   776  ```
   777  
   778  Example response (currency=usd):
   779  
   780  ```javascript
   781  {
   782    "ts": 1574346615,
   783    "rates": {
   784      "usd": 7914.5
   785    }
   786  }
   787  ```
   788  
   789  Example error response (e.g. rate unavailable, incorrect currency...):
   790  
   791  ```javascript
   792  {
   793    "ts":7980386400,
   794    "rates": {
   795      "usd": -1
   796    }
   797  }
   798  ```
   799  
   800  #### Balance history
   801  
   802  Returns a balance history for the specified XPUB or address.
   803  
   804  ```
   805  GET /api/v2/balancehistory/<XPUB | address>?from=<dateFrom>&to=<dateTo>[&fiatcurrency=<currency>&groupBy=<groupBySeconds>]
   806  ```
   807  
   808  Query parameters:
   809  
   810  - _from_: specifies a start date as a Unix timestamp
   811  - _to_: specifies an end date as a Unix timestamp
   812  
   813  The optional query parameters:
   814  
   815  - _fiatcurrency_: if specified, the response will contain secondary (fiat) rate at the time of transaction. If not, all available currencies will be returned.
   816  - _groupBy_: an interval in seconds, to group results by. Default is 3600 seconds.
   817  
   818  Example response (_fiatcurrency_ not specified):
   819  
   820  ```javascript
   821  [
   822    {
   823      "time": 1578391200,
   824      "txs": 5,
   825      "received": "5000000",
   826      "sent": "0",
   827      "sentToSelf":"100000",
   828      "rates": {
   829        "usd": 7855.9,
   830        "eur": 6838.13,
   831        ...
   832      }
   833    },
   834    {
   835      "time": 1578488400,
   836      "txs": 1,
   837      "received": "0",
   838      "sent": "5000000",
   839      "sentToSelf":"0",
   840      "rates": {
   841        "usd": 8283.11,
   842        "eur": 7464.45,
   843        ...
   844      }
   845    }
   846  ]
   847  ```
   848  
   849  Example response (fiatcurrency=usd):
   850  
   851  ```javascript
   852  [
   853    {
   854      time: 1578391200,
   855      txs: 5,
   856      received: "5000000",
   857      sent: "0",
   858      sentToSelf: "0",
   859      rates: {
   860        usd: 7855.9,
   861      },
   862    },
   863    {
   864      time: 1578488400,
   865      txs: 1,
   866      received: "0",
   867      sent: "5000000",
   868      sentToSelf: "0",
   869      rates: {
   870        usd: 8283.11,
   871      },
   872    },
   873  ];
   874  ```
   875  
   876  Example response (fiatcurrency=usd&groupBy=172800):
   877  
   878  ```javascript
   879  [
   880    {
   881      time: 1578355200,
   882      txs: 6,
   883      received: "5000000",
   884      sent: "5000000",
   885      sentToSelf: "0",
   886      rates: {
   887        usd: 7734.45,
   888      },
   889    },
   890  ];
   891  ```
   892  
   893  The value of `sentToSelf` is the amount sent from the same address to the same address or within addresses of xpub.
   894  
   895  ### Websocket API
   896  
   897  Websocket interface is provided at `/websocket/`. The interface can be explored using Blockbook Websocket Test Page found at `/test-websocket.html`.
   898  
   899  The websocket interface provides the following requests:
   900  
   901  - getInfo
   902  - getBlockHash
   903  - getAccountInfo
   904  - getAccountUtxo
   905  - getTransaction
   906  - getTransactionSpecific
   907  - getBalanceHistory
   908  - getCurrentFiatRates
   909  - getFiatRatesTickersList
   910  - getFiatRatesForTimestamps
   911  - getMempoolFilters
   912  - getBlockFilter
   913  - estimateFee
   914  - sendTransaction
   915  - ping
   916  
   917  The client can subscribe to the following events:
   918  
   919  - `subscribeNewBlock` - new block added to blockchain
   920  - `subscribeNewTransaction` - new transaction added to blockchain (all addresses)
   921  - `subscribeAddresses` - new transaction for a given address (list of addresses) added to mempool
   922  - `subscribeFiatRates` - new currency rate ticker
   923  
   924  There can be always only one subscription of given event per connection, i.e. new list of addresses replaces previous list of addresses.
   925  
   926  The subscribeNewTransaction event is not enabled by default. To enable support, blockbook must be run with the `-enablesubnewtx` flag.
   927  
   928  _Note: If there is reorg on the backend (blockchain), you will get a new block hash with the same or even smaller height if the reorg is deeper_
   929  
   930  Websocket communication format
   931  
   932  ```javascript
   933  {
   934    "id":"1", //an id to help to identify the response
   935    "method":"<The method that you would like to call>",
   936    "params":<The params (same as in the API call>
   937  }
   938  ```
   939  
   940  Example for subscribing to an address (or multiple addresses)
   941  
   942  ```javascript
   943  {
   944    "id":"1",
   945    "method":"subscribeAddresses",
   946    "params":{
   947      "addresses":["mnYYiDCb2JZXnqEeXta1nkt5oCVe2RVhJj", "tb1qp0we5epypgj4acd2c4au58045ruud2pd6heuee"]
   948     }
   949  }
   950  ```
   951  
   952  ## Legacy API V1
   953  
   954  The legacy API is a compatible subset of API provided by **Bitcore Insight**. It is supported only Bitcoin-type coins. The details of the REST/socket.io requests can be found in the Insight's documentation.
   955  
   956  ### REST API
   957  
   958  ```
   959  GET /api/v1/block-index/<block height>
   960  GET /api/v1/tx/<txid>
   961  GET /api/v1/address/<address>
   962  GET /api/v1/utxo/<address>
   963  GET /api/v1/block/<block height | block hash>
   964  GET /api/v1/estimatefee/<number of blocks>
   965  GET /api/v1/sendtx/<hex tx data>
   966  POST /api/v1/sendtx/ (hex tx data in request body)
   967  ```
   968  
   969  ### Socket.io API
   970  
   971  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`.
   972  
   973  The legacy API is provided as is and will not be further developed.
   974  
   975  The legacy API is currently (as of Blockbook v0.4.0) also accessible without the _/v1/_ prefix, however in the future versions the version less access will be removed.