RanchiMall/blockbook
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: update and enrich API docs

Browse Source
This commit is contained in:
grdddj 2024-09-24 14:20:09 +02:00 committed by Martin
parent a2aa489b65
commit 1c70a269b0
1 changed files with 169 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

255
docs/api.md
View File

@ -11,6 +11,8 @@ Common principles used in API V2:
- all crypto 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.
See all the referred types (`typescript` interfaces) in the [blockbook-api.ts](../blockbook-api.ts) file.
### REST API
The following methods are supported:
@ -33,43 +35,47 @@ The following methods are supported:
Status page returns current status of Blockbook and connected backend.
```
GET /api
GET /api/status
```
Response:
Response (`SystemInfo` type):
<!-- https://btc1.trezor.io/api/status -->
```javascript
{
"blockbook": {
"coin": "Bitcoin",
"host": "blockbook",
"network": "BTC",
"host": "backend5",
"version": "0.4.0",
"gitCommit": "3d9ad91",
"buildTime": "2019-05-17T14:34:00+00:00",
"gitCommit": "a0960c8e",
"buildTime": "2024-08-08T12:32:50+00:00",
"syncMode": true,
"initialSync": false,
"inSync": true,
"bestHeight": 577261,
"lastBlockTime": "2019-05-22T18:03:33.547762973+02:00",
"bestHeight": 860730,
"lastBlockTime": "2024-09-10T08:19:04.471017534Z",
"inSyncMempool": true,
"lastMempoolTime": "2019-05-22T18:10:10.27929383+02:00",
"mempoolSize": 17348,
"lastMempoolTime": "2024-09-10T08:42:39.38871351Z",
"mempoolSize": 232021,
"decimals": 8,
"dbSize": 191887866502,
"about": "Blockbook - blockchain indexer for Trezor wallet https://trezor.io/. Do not use for any other purpose."
"dbSize": 761283489075,
"hasFiatRates": true,
"currentFiatRatesTime": "2024-09-10T08:42:00.898792419Z",
"historicalFiatRatesTime": "2024-09-10T00:00:00Z",
"about": "Blockbook - blockchain indexer for Trezor Suite https://trezor.io/trezor-suite. Do not use for any other purpose."
},
"backend": {
"chain": "main",
"blocks": 577261,
"headers": 577261,
"bestBlockHash": "0000000000000000000ca8c902aa58b3118a7f35d093e25a07f17bcacd91cabf",
"difficulty": "6704632680587.417",
"sizeOnDisk": 250504188580,
"version": "180000",
"subversion": "/Satoshi:0.18.0/",
"protocolVersion": "70015",
"timeOffset": 0,
"warnings": ""
"blocks": 860730,
"headers": 860730,
"bestBlockHash": "00000000000000000000effeb0c4460480e6a347deab95332c63007a68646ee5",
"difficulty": "89471664776970.77",
"sizeOnDisk": 681584532221,
"version": "270100",
"subversion": "/Satoshi:27.1.0/",
"protocolVersion": "70016"
}
}
```
@ -82,9 +88,11 @@ GET /api/v2/block-index/<block height>
Response:
<!-- https://btc1.trezor.io/api/v2/block-index/666666 -->
```javascript
{
"blockHash": "ed8f3af8c10ca70a136901c6dd3adf037f0aea8a93fbe9e80939214034300f1e"
"blockHash": "0000000000000000000b7b8574bc6fd285825ec2dbcbeca149121fc05b0c828c"
}
```
@ -98,104 +106,168 @@ Get transaction returns "normalized" data about transaction, which has the same
GET /api/v2/tx/<txid>
```
Response for Bitcoin-type coins, confirmed transaction:
Response for Bitcoin-type coins, confirmed transaction (`Tx` type):
<!-- https://btc1.trezor.io/api/v2/tx/8c1e3dec662d1f2a5e322ccef5eca263f98eb16723c6f990be0c88c1db113fb1 -->
```javascript
{
"txid": "9e2bc8fbd40af17a6564831f84aef0cab2046d4bad19e91c09d21bff2c851851",
"version": 1,
"txid": "8c1e3dec662d1f2a5e322ccef5eca263f98eb16723c6f990be0c88c1db113fb1",
"version": 2,
"lockTime": 860729,
"vin": [
{
"txid": "f124e6999bf67e710b9e8a8ac4dbb08a64aa9c264120cf98793455e36a531615",
"vout": 2,
"sequence": 4294967295,
"txid": "0eb7b574373de2c88d0dc1444f49947c681d0437d21361f9ebb4dd09c62f2a66",
"vout": 1,
"sequence": 4294967293,
"n": 0,
"addresses": [
"DDhUv8JZGmSxKYV95NLnbRTUKni9cDZD3S"
"bc1qmgwnfjlda4ns3g6g3yz74w6scnn9yu2ts82yyc"
],
"isAddress": true,
"value": "55795108999999",
"hex": "473...2c7ec77bb982"
"value": "10106300"
}
],
"vout": [
{
"value": "55585679000000",
"value": "175000",
"n": 0,
"hex": "76a914feaca9d9fa7120c7c587c00c639bb18d40faadd388ac",
"hex": "76a914ecc999d554eaa3efa5e871c28f58b549c36ec51788ac",
"addresses": [
"DUMh1rPrXTrCN2Z9EHsLPg7b78rACHB2h7"
"1Nb1ykSD7J5k4RFjJQGsrD9gxBE6jzfNa9"
],
"isAddress": true
},
{
"value": "209329999999",
"value": "9888100",
"n": 1,
"hex": "76a914ea8984be785868391d92f49c14933f47c152ea0a88ac",
"hex": "001496f152a0919487624bf4f13f46f0d20fa10d9acc",
"addresses": [
"DSXDQ6rnwLX47WFRnemctoXPHA9pLMxqXn"
"bc1qjmc49gy3jjrkyjl57yl5duxjp7ssmxkvh5t2q5"
],
"isAddress": true
}
],
"blockHash": "78d1f3de899a10dd2e580704226ebf9508e95e1706f177fc9c31c47f245d2502",
"blockHeight": 2647927,
"blockHash": "00000000000000000000effeb0c4460480e6a347deab95332c63007a68646ee5",
"blockHeight": 860730,
"confirmations": 1,
"blockTime": 1553088212,
"size": 234,
"vsize": 153,
"value": "55795008999999",
"valueIn": "55795108999999",
"fees": "100000000",
"hex": "0100000...0011000"
"blockTime": 1725956288,
"size": 225,
"vsize": 144,
"value": "10063100",
"valueIn": "10106300",
"fees": "43200",
"hex": "02000000000101662a2fc609ddb4ebf96113d237041d687c94494f44c10d8dc8e23d3774b5b70e0100000000fdffffff0298ab0200000000001976a914ecc999d554eaa3efa5e871c28f58b549c36ec51788ac64e196000000000016001496f152a0919487624bf4f13f46f0d20fa10d9acc0247304402202bb0591180cdbbe0f639af6eb21abdb993fc5a667b09e6392d5c11b025a9187102201ef2e84fc91a5d2c6fbbc9f943482d230256a3640f8ecb83c1f3f17242cf011001210314f03889e1667feb696ee280625943195189cfabe46d54204d987f631fe6892739220d00"
}
```
Response for Bitcoin-type coins, unconfirmed transaction (_blockHeight_: -1, _confirmations_: 0, mining estimates _confirmationETABlocks_ and _confirmationETASeconds_):
Response for Bitcoin-type coins, unconfirmed transaction:
Special fields:
- _blockHeight_: -1
- _confirmations_: 0
- _confirmationETABlocks_: number
- _confirmationETASeconds_: number
<!-- https://btc1.trezor.io/api/v2/tx/73b1ad97194e426031e5c692869de2d83dc2ff6033fc6f0ab5514345f92eaf0d -->
```javascript
{
"txid": "cd8ec77174e426070d0a50779232bba7312b712e2c6843d82d963d7076c61366",
"txid": "73b1ad97194e426031e5c692869de2d83dc2ff6033fc6f0ab5514345f92eaf0d",
"version": 2,
"vin": [
{
"txid": "47687cc4abb58d815168686465a38113a0608b2568a6d6480129d197e653f6dc",
"sequence": 4294967295,
"txid": "bccbebb64b1613ada74eefa96753088a80fefa53a10e42c66eef1899371bc096",
"n": 0,
"addresses": ["bc1qka0gpenex558g8gpxmpx247mwhw695k6a7yhs4"],
"addresses": [
"bc1q9lh77es6m8ztr7muwcec00ewn8fxakpl9jwv8y"
],
"isAddress": true,
"value": "1983687"
"value": "371042"
}
],
"vout": [
{
"value": "3106",
"value": "293135",
"n": 0,
"hex": "0020d7da4868055fde790a8581637ab81c216e17a3f8a099283da6c4a27419ffa539",
"hex": "0014aafd7386f99f4b508ec05ee8f7edc2e07126620a",
"addresses": [
"bc1q6ldys6q9tl08jz59s93h4wquy9hp0glc5zvjs0dxcj38gx0l55uspu8x86"
"bc1q4t7h8phena94prkqtm500mwzupcjvcs2akcdy9"
],
"isAddress": true
},
{
"value": "1979101",
"value": "74022",
"n": 1,
"hex": "0014381be30ca46ddf378ef69ebc4a601bd6ff30b754",
"addresses": ["bc1q8qd7xr9ydh0n0rhkn67y5cqm6mlnpd65dcyeeg"],
"hex": "0014a3de0fbba89c17d43093164ea955bad65bc260bf",
"addresses": [
"bc1q500qlwagnstagvynze82j4d66eduyc9lf64ksh"
],
"isAddress": true
}
],
"blockHeight": -1,
"confirmations": 0,
"confirmationETABlocks": 3,
"confirmationETASeconds": 2055,
"blockTime": 1675270935,
"size": 234,
"vsize": 153,
"value": "1982207",
"valueIn": "1983687",
"fees": "1480",
"hex": "020000000001...b18f00000000"
"confirmationETABlocks": 1,
"confirmationETASeconds": 619,
"blockTime": 1725959035,
"size": 222,
"vsize": 141,
"value": "367157",
"valueIn": "371042",
"fees": "3885",
"hex": "0200000000010196c01b379918ef6ec6420ea153fafe808a085367a9ef4ea7ad13164bb6ebcbbc000000000000000000020f79040000000000160014aafd7386f99f4b508ec05ee8f7edc2e07126620a2621010000000000160014a3de0fbba89c17d43093164ea955bad65bc260bf0247304402204a5bdf8a8d19b0a19044b0c0de3ced92b92e8d0c629ffca83178c85a608f719e02203841d40dd92db48715f9f41a732e139ac3cc7696a23adc87136bd8037a594e9f012102824a5e7b878f8d63887bdcb1b0982cdb0b375068b3798c4c96799476a19a389e00000000",
"rbf": true,
"coinSpecificData": {
"txid": "73b1ad97194e426031e5c692869de2d83dc2ff6033fc6f0ab5514345f92eaf0d",
"hash": "91deb6a9d0f5a37e2e83d1e602ba14cd9811fd3605f582154c9bd1337f7f4c8a",
"version": 2,
"size": 222,
"vsize": 141,
"weight": 561,
"locktime": 0,
"vin": [
{
"txid": "bccbebb64b1613ada74eefa96753088a80fefa53a10e42c66eef1899371bc096",
"vout": 0,
"scriptSig": {
"asm": "",
"hex": ""
},
"txinwitness": [
"304402204a5bdf8a8d19b0a19044b0c0de3ced92b92e8d0c629ffca83178c85a608f719e02203841d40dd92db48715f9f41a732e139ac3cc7696a23adc87136bd8037a594e9f01",
"02824a5e7b878f8d63887bdcb1b0982cdb0b375068b3798c4c96799476a19a389e"
],
"sequence": 0
}
],
"vout": [
{
"value": 0.00293135,
"n": 0,
"scriptPubKey": {
"asm": "0 aafd7386f99f4b508ec05ee8f7edc2e07126620a",
"desc": "addr(bc1q4t7h8phena94prkqtm500mwzupcjvcs2akcdy9)#qmxeweuu",
"hex": "0014aafd7386f99f4b508ec05ee8f7edc2e07126620a",
"address": "bc1q4t7h8phena94prkqtm500mwzupcjvcs2akcdy9",
"type": "witness_v0_keyhash"
}
},
{
"value": 0.00074022,
"n": 1,
"scriptPubKey": {
"asm": "0 a3de0fbba89c17d43093164ea955bad65bc260bf",
"desc": "addr(bc1q500qlwagnstagvynze82j4d66eduyc9lf64ksh)#mynfp6xy",
"hex": "0014a3de0fbba89c17d43093164ea955bad65bc260bf",
"address": "bc1q500qlwagnstagvynze82j4d66eduyc9lf64ksh",
"type": "witness_v0_keyhash"
}
}
],
"hex": "0200000000010196c01b379918ef6ec6420ea153fafe808a085367a9ef4ea7ad13164bb6ebcbbc000000000000000000020f79040000000000160014aafd7386f99f4b508ec05ee8f7edc2e07126620a2621010000000000160014a3de0fbba89c17d43093164ea955bad65bc260bf0247304402204a5bdf8a8d19b0a19044b0c0de3ced92b92e8d0c629ffca83178c85a608f719e02203841d40dd92db48715f9f41a732e139ac3cc7696a23adc87136bd8037a594e9f012102824a5e7b878f8d63887bdcb1b0982cdb0b375068b3798c4c96799476a19a389e00000000"
}
}
```
@ -210,6 +282,8 @@ Response for Ethereum-type coins. Data of the transaction consist of:
- internal transfers (type `0` transfer, type `1` contract creation, type `2` contract destruction)
- _addressAliases_ - maps addresses in the transaction to names from contract or ENS. Only addresses with known names are returned.
<!-- https://eth1.trezor.io/tx/0xa6c8ae1f91918d09cf2bd67bbac4c168849e672fd81316fa1d26bb9b4fc0f790 -->
```javascript
{
"txid": "0xa6c8ae1f91918d09cf2bd67bbac4c168849e672fd81316fa1d26bb9b4fc0f790",
@ -324,10 +398,14 @@ GET /api/v2/tx-specific/<txid>
Example response:
<!-- https://zec1.trezor.io/api/v2/tx-specific/7a0a0ff6f67bac2a856c7296382b69151949878de6fb0d01a8efa197182b2913 -->
```javascript
{
"hex": "040000808...8e6e73cb009",
"txid": "7a0a0ff6f67bac2a856c7296382b69151949878de6fb0d01a8efa197182b2913",
"authdigest": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
"size": 1809,
"overwintered": true,
"version": 4,
"versiongroupid": "892f2085",
@ -337,6 +415,7 @@ Example response:
"vout": [],
"vjoinsplit": [],
"valueBalance": 0,
"valueBalanceZat": 0,
"vShieldedSpend": [
{
"cv": "50258bfa65caa9f42f4448b9194840c7da73afc8159faf7358140bfd0f237962",
@ -367,7 +446,8 @@ Example response:
],
"bindingSig": "bc018af8808387...5130bb382ad8e6e73cb009",
"blockhash": "0000000001c4aa394e796dd1b82e358f114535204f6f5b6cf4ad58dc439c47af",
"confirmations": 5222,
"height": 495665,
"confirmations": 2145803,
"time": 1552301566,
"blocktime": 1552301566
}
@ -396,30 +476,33 @@ The optional query parameters:
- _contract_: return only transactions which affect specified contract (applicable only to coins which support contracts)
- _secondary_: specifies secondary (fiat) currency in which the token and total balances are returned in addition to crypto values
Example response for bitcoin type coin, _details_ set to _txids_:
Example response for bitcoin type coin, _details_ set to _txids_ (`Address` type):
<!-- https://btc1.trezor.io/api/v2/address/bc1q0wd209cv5k9pd9mhk7nspacywcj038xxdhnt5u?details=txids -->
```javascript
{
"page": 1,
"totalPages": 1,
"itemsOnPage": 1000,
"address": "D5Z7XrtJNg7hAtznSDMXvfiFmMYphwuWz7",
"balance": "2432468097999991",
"totalReceived": "3992283916999979",
"totalSent": "1559815818999988",
"address": "bc1q0wd209cv5k9pd9mhk7nspacywcj038xxdhnt5u",
"balance": "4225100",
"totalReceived": "4225100",
"totalSent": "0",
"unconfirmedBalance": "0",
"unconfirmedTxs": 0,
"txs": 3,
"txs": 2,
"txids": [
"461dd46d5d6f56d765f82e60e6bf0727a3a1d1cb8c4144373d805b152a21d308",
"bdb5b47603c5d174eae3384c368068c8e9d2183b398ed0e31d125defa4447a10",
"5c1d2686d70d82bd8e84b5d3dc4bd0e8485e28cdc865336db6a5e40b2098277d"
"0db6010dc0815a4bdaa505bd1ccc851056b0d53c7e4ea7af39c4d648a2c0c019",
"7532920ddc506218337cceac978cce9c7f98e27ad3226dee55f3e934e0b32e80"
]
}
```
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:
<!-- https://eth1.trezor.io/api/v2/address/0x2df3951b2037bA620C20Ed0B73CCF45Ea473e83B?details=tokenBalances&secondary=usd -->
```javascript
{
"address": "0x2df3951b2037bA620C20Ed0B73CCF45Ea473e83B",
@ -500,7 +583,7 @@ The optional query parameters:
- _derived_: return all derived addresses
- _secondary_: specifies secondary (fiat) currency in which the balances are returned in addition to crypto values
Response:
Response (`Address` type):
```javascript
{
@ -562,7 +645,7 @@ Coinbase utxos have field _coinbase_ set to true, however due to performance rea
GET /api/v2/utxo/<address|xpub|descriptor>[?confirmed=true]
```
Response:
Response (`Utxo[]` type):
```javascript
[
@ -606,7 +689,7 @@ Returns information about block with transactions, subject to paging.
GET /api/v2/block/<block height|block hash>
```
Response:
Response (`Block` type):
```javascript
{
@ -737,7 +820,7 @@ The query parameters:
- _timestamp_: specifies a Unix timestamp to return available tickers for.
Example response:
Example response (`AvailableVsCurrencies` type):
```javascript
{
@ -763,7 +846,7 @@ 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):
Example response (no parameters, `FiatTicker` type):
```javascript
{
@ -815,7 +898,7 @@ The optional query parameters:
- _fiatcurrency_: if specified, the response will contain secondary (fiat) rate at the time of transaction. If not, all available currencies will be returned.
- _groupBy_: an interval in seconds, to group results by. Default is 3600 seconds.
Example response (_fiatcurrency_ not specified):
Example response (_fiatcurrency_ not specified, `BalanceHistory[]` type):
```javascript
[
@ -927,7 +1010,7 @@ The subscribeNewTransaction event is not enabled by default. To enable support,
_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_
Websocket communication format
Websocket communication format (`WsReq` type)
```javascript
{
@ -951,7 +1034,7 @@ Example for subscribing to an address (or multiple addresses)
## Legacy API V1
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.
The legacy API is a compatible subset of API provided by **Bitcore Insight**. It is supported only for Bitcoin-type coins. The details of the REST/socket.io requests can be found in the Insight's documentation.
### REST API
@ -972,4 +1055,4 @@ Socket.io interface is provided at `/socket.io/`. The interface also can be expl
The legacy API is provided as is and will not be further developed.
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.
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.