github.com/cryptohub-digital/blockbook-fork@v0.0.0-20230713133354-673c927af7f1/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>/*])[#checkum]`, 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>×tamp=<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 - estimateFee 912 - sendTransaction 913 - ping 914 915 The client can subscribe to the following events: 916 917 - `subscribeNewBlock` - new block added to blockchain 918 - `subscribeNewTransaction` - new transaction added to blockchain (all addresses) 919 - `subscribeAddresses` - new transaction for a given address (list of addresses) added to mempool 920 - `subscribeFiatRates` - new currency rate ticker 921 922 There can be always only one subscription of given event per connection, i.e. new list of addresses replaces previous list of addresses. 923 924 The subscribeNewTransaction event is not enabled by default. To enable support, blockbook must be run with the `-enablesubnewtx` flag. 925 926 _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_ 927 928 Websocket communication format 929 930 ```javascript 931 { 932 "id":"1", //an id to help to identify the response 933 "method":"<The method that you would like to call>", 934 "params":<The params (same as in the API call> 935 } 936 ``` 937 938 Example for subscribing to an address (or multiple addresses) 939 940 ```javascript 941 { 942 "id":"1", 943 "method":"subscribeAddresses", 944 "params":{ 945 "addresses":["mnYYiDCb2JZXnqEeXta1nkt5oCVe2RVhJj", "tb1qp0we5epypgj4acd2c4au58045ruud2pd6heuee"] 946 } 947 } 948 ``` 949 950 ## Legacy API V1 951 952 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. 953 954 ### REST API 955 956 ``` 957 GET /api/v1/block-index/<block height> 958 GET /api/v1/tx/<txid> 959 GET /api/v1/address/<address> 960 GET /api/v1/utxo/<address> 961 GET /api/v1/block/<block height | block hash> 962 GET /api/v1/estimatefee/<number of blocks> 963 GET /api/v1/sendtx/<hex tx data> 964 POST /api/v1/sendtx/ (hex tx data in request body) 965 ``` 966 967 ### Socket.io API 968 969 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`. 970 971 The legacy API is provided as is and will not be further developed. 972 973 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.