325 lines
8.0 KiB
Markdown
325 lines
8.0 KiB
Markdown
# Insight API
|
|
|
|
A Bitcoin blockchain REST and web socket API service for [Bitcore Node](https://github.com/bitpay/bitcore-node).
|
|
|
|
This is a backend-only service. If you're looking for the web frontend application, take a look at https://github.com/bitpay/insight.
|
|
|
|
## Getting Started
|
|
|
|
```bash
|
|
npm install -g bitcore-node@latest
|
|
bitcore-node create mynode
|
|
cd mynode
|
|
bitcore-node add insight-api
|
|
bitcore-node start
|
|
```
|
|
|
|
The API endpoints will be available by default at: 'http://localhost:3001/insight-api/`
|
|
|
|
## Prerequisites
|
|
|
|
- [Bitcore Node 0.2.x](https://github.com/bitpay/bitcore-node)
|
|
|
|
**Note:** You can use an existing Bitcoin data directory, however `txindex` needs to be set to true in `bitcoin.conf`.
|
|
|
|
## API HTTP Endpoints
|
|
|
|
### Block
|
|
```
|
|
/api/block/[:hash]
|
|
/api/block/00000000a967199a2fad0877433c93df785a8d8ce062e5f9b451cd1397bdbf62
|
|
```
|
|
|
|
### Block index
|
|
Get block hash by height
|
|
```
|
|
/api/block-index/[:height]
|
|
/api/block-index/0
|
|
```
|
|
This would return:
|
|
```
|
|
{"blockHash":"000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f"}
|
|
```
|
|
which is the hash of the Genesis block (0 height)
|
|
|
|
### Transaction
|
|
```
|
|
/api/tx/[:txid]
|
|
/api/tx/525de308971eabd941b139f46c7198b5af9479325c2395db7f2fb5ae8562556c
|
|
/api/raw/[:rawid]
|
|
/api/raw/525de308971eabd941b139f46c7198b5af9479325c2395db7f2fb5ae8562556c
|
|
```
|
|
|
|
### Address
|
|
```
|
|
/api/addr/[:addr][?noTxList=1&noCache=1]
|
|
/api/addr/mmvP3mTe53qxHdPqXEvdu8WdC7GfQ2vmx5?noTxList=1
|
|
```
|
|
|
|
### Address Properties
|
|
```
|
|
/api/addr/[:addr]/balance
|
|
/api/addr/[:addr]/totalReceived
|
|
/api/addr/[:addr]/totalSent
|
|
/api/addr/[:addr]/unconfirmedBalance
|
|
```
|
|
The response contains the value in Satoshis.
|
|
|
|
### Unspent Outputs
|
|
```
|
|
/api/addr/[:addr]/utxo[?noCache=1]
|
|
```
|
|
Sample return:
|
|
``` json
|
|
[
|
|
{
|
|
"address": "n2PuaAguxZqLddRbTnAoAuwKYgN2w2hZk7",
|
|
"txid": "dbfdc2a0d22a8282c4e7be0452d595695f3a39173bed4f48e590877382b112fc",
|
|
"vout": 0,
|
|
"ts": 1401276201,
|
|
"scriptPubKey": "76a914e50575162795cd77366fb80d728e3216bd52deac88ac",
|
|
"amount": 0.001,
|
|
"confirmations": 3
|
|
},
|
|
{
|
|
"address": "n2PuaAguxZqLddRbTnAoAuwKYgN2w2hZk7",
|
|
"txid": "e2b82af55d64f12fd0dd075d0922ee7d6a300f58fe60a23cbb5831b31d1d58b4",
|
|
"vout": 0,
|
|
"ts": 1401226410,
|
|
"scriptPubKey": "76a914e50575162795cd77366fb80d728e3216bd52deac88ac",
|
|
"amount": 0.001,
|
|
"confirmation": 6,
|
|
"confirmationsFromCache": true
|
|
}
|
|
]
|
|
```
|
|
Please note that in case confirmations are cached (which happens by default when the number of confirmations is bigger that INSIGHT_SAFE_CONFIRMATIONS) the response will include the pair confirmationsFromCache:true, and confirmations will equal INSIGHT_SAFE_CONFIRMATIONS. See noCache and INSIGHT_IGNORE_CACHE options for details.
|
|
|
|
|
|
|
|
### Unspent Outputs for multiple addresses
|
|
GET method:
|
|
```
|
|
/api/addrs/[:addrs]/utxo
|
|
/api/addrs/2NF2baYuJAkCKo5onjUKEPdARQkZ6SYyKd5,2NAre8sX2povnjy4aeiHKeEh97Qhn97tB1f/utxo
|
|
```
|
|
|
|
POST method:
|
|
```
|
|
/api/addrs/utxo
|
|
```
|
|
|
|
POST params:
|
|
```
|
|
addrs: 2NF2baYuJAkCKo5onjUKEPdARQkZ6SYyKd5,2NAre8sX2povnjy4aeiHKeEh97Qhn97tB1f
|
|
```
|
|
|
|
### Transactions by Block
|
|
```
|
|
/api/txs/?block=HASH
|
|
/api/txs/?block=00000000fa6cf7367e50ad14eb0ca4737131f256fc4c5841fd3c3f140140e6b6
|
|
```
|
|
### Transactions by Address
|
|
```
|
|
/api/txs/?address=ADDR
|
|
/api/txs/?address=mmhmMNfBiZZ37g1tgg2t8DDbNoEdqKVxAL
|
|
```
|
|
|
|
### Transactions for multiple addresses
|
|
GET method:
|
|
```
|
|
/api/addrs/[:addrs]/txs[?from=&to=]
|
|
/api/addrs/2NF2baYuJAkCKo5onjUKEPdARQkZ6SYyKd5,2NAre8sX2povnjy4aeiHKeEh97Qhn97tB1f/txs?from=0&to=20
|
|
```
|
|
|
|
POST method:
|
|
```
|
|
/api/addrs/txs
|
|
```
|
|
|
|
POST params:
|
|
```
|
|
addrs: 2NF2baYuJAkCKo5onjUKEPdARQkZ6SYyKd5,2NAre8sX2povnjy4aeiHKeEh97Qhn97tB1f
|
|
from (optional): 0
|
|
to (optional): 20
|
|
```
|
|
|
|
Sample output:
|
|
```
|
|
{ totalItems: 100,
|
|
from: 0,
|
|
to: 20,
|
|
items:
|
|
[ { txid: '3e81723d069b12983b2ef694c9782d32fca26cc978de744acbc32c3d3496e915',
|
|
version: 1,
|
|
locktime: 0,
|
|
vin: [Object],
|
|
vout: [Object],
|
|
blockhash: '00000000011a135e5277f5493c52c66829792392632b8b65429cf07ad3c47a6c',
|
|
confirmations: 109367,
|
|
time: 1393659685,
|
|
blocktime: 1393659685,
|
|
valueOut: 0.3453,
|
|
size: 225,
|
|
firstSeenTs: undefined,
|
|
valueIn: 0.3454,
|
|
fees: 0.0001 },
|
|
{ ... },
|
|
{ ... },
|
|
...
|
|
{ ... }
|
|
]
|
|
}
|
|
```
|
|
|
|
Note: if pagination params are not specified, the result is an array of transactions.
|
|
|
|
### Transaction broadcasting
|
|
POST method:
|
|
```
|
|
/api/tx/send
|
|
```
|
|
POST params:
|
|
```
|
|
rawtx: "signed transaction as hex string"
|
|
|
|
eg
|
|
|
|
rawtx: 01000000017b1eabe0209b1fe794124575ef807057c77ada2138ae4fa8d6c4de0398a14f3f00000000494830450221008949f0cb400094ad2b5eb399d59d01c14d73d8fe6e96df1a7150deb388ab8935022079656090d7f6bac4c9a94e0aad311a4268e082a725f8aeae0573fb12ff866a5f01ffffffff01f0ca052a010000001976a914cbc20a7664f2f69e5355aa427045bc15e7c6c77288ac00000000
|
|
|
|
```
|
|
POST response:
|
|
```
|
|
{
|
|
txid: [:txid]
|
|
}
|
|
|
|
eg
|
|
|
|
{
|
|
txid: "c7736a0a0046d5a8cc61c8c3c2821d4d7517f5de2bc66a966011aaa79965ffba"
|
|
}
|
|
```
|
|
|
|
### Historic blockchain data sync status
|
|
```
|
|
/api/sync
|
|
```
|
|
|
|
### Live network p2p data sync status
|
|
```
|
|
/api/peer
|
|
```
|
|
|
|
### Status of the bitcoin network
|
|
```
|
|
/api/status?q=xxx
|
|
```
|
|
|
|
Where "xxx" can be:
|
|
|
|
* getInfo
|
|
* getDifficulty
|
|
* getTxOutSetInfo
|
|
* getBestBlockHash
|
|
* getLastBlockHash
|
|
|
|
|
|
### Utility methods
|
|
```
|
|
/api/utils/estimatefee[?nbBlocks=2]
|
|
```
|
|
|
|
|
|
## Web Socket API
|
|
The web socket API is served using [socket.io](http://socket.io).
|
|
|
|
The following are the events published by insight:
|
|
|
|
'tx': new transaction received from network. This event is published in the 'inv' room. Data will be a app/models/Transaction object.
|
|
Sample output:
|
|
```
|
|
{
|
|
"txid":"00c1b1acb310b87085c7deaaeba478cef5dc9519fab87a4d943ecbb39bd5b053",
|
|
"processed":false
|
|
...
|
|
}
|
|
```
|
|
|
|
|
|
'block': new block received from network. This event is published in the 'inv' room. Data will be a app/models/Block object.
|
|
Sample output:
|
|
```
|
|
{
|
|
"hash":"000000004a3d187c430cd6a5e988aca3b19e1f1d1727a50dead6c8ac26899b96",
|
|
"time":1389789343,
|
|
...
|
|
}
|
|
```
|
|
|
|
'<bitcoinAddress>': new transaction concerning <bitcoinAddress> received from network. This event is published in the '<bitcoinAddress>' room.
|
|
|
|
'status': every 1% increment on the sync task, this event will be triggered. This event is published in the 'sync' room.
|
|
|
|
Sample output:
|
|
```
|
|
{
|
|
blocksToSync: 164141,
|
|
syncedBlocks: 475,
|
|
upToExisting: true,
|
|
scanningBackward: true,
|
|
isEndGenesis: true,
|
|
end: "000000000933ea01ad0ee984209779baaec3ced90fa3f408719526f8d77f4943",
|
|
isStartGenesis: false,
|
|
start: "000000009f929800556a8f3cfdbe57c187f2f679e351b12f7011bfc276c41b6d"
|
|
}
|
|
```
|
|
|
|
### Example Usage
|
|
|
|
The following html page connects to the socket.io insight API and listens for new transactions.
|
|
|
|
html
|
|
```
|
|
<html>
|
|
<body>
|
|
<script src="http://<insight-server>:<port>/socket.io/socket.io.js"></script>
|
|
<script>
|
|
eventToListenTo = 'tx'
|
|
room = 'inv'
|
|
|
|
var socket = io("http://<insight-server>:<port>/");
|
|
socket.on('connect', function() {
|
|
// Join the room.
|
|
socket.emit('subscribe', room);
|
|
})
|
|
socket.on(eventToListenTo, function(data) {
|
|
console.log("New transaction received: " + data.txid)
|
|
})
|
|
</script>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
## License
|
|
(The MIT License)
|
|
|
|
Permission is hereby granted, free of charge, to any person obtaining
|
|
a copy of this software and associated documentation files (the
|
|
'Software'), to deal in the Software without restriction, including
|
|
without limitation the rights to use, copy, modify, merge, publish,
|
|
distribute, sublicense, and/or sell copies of the Software, and to
|
|
permit persons to whom the Software is furnished to do so, subject to
|
|
the following conditions:
|
|
|
|
The above copyright notice and this permission notice shall be
|
|
included in all copies or substantial portions of the Software.
|
|
|
|
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
|
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
|
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
|
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
|
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|