mirror of
https://github.com/alexgo-io/stacks-blockchain-api.git
synced 2026-01-12 22:43:34 +08:00
402 lines
12 KiB
Markdown
402 lines
12 KiB
Markdown
# @stacks/blockchain-api-client
|
|
[](https://www.npmjs.org/package/@stacks/blockchain-api-client)
|
|
[](https://github.com/hirosystems/stacks-blockchain-api/actions)
|
|
|
|
A JS Client for the Stacks Blockchain API
|
|
|
|
## Features
|
|
|
|
This package provides the ability to:
|
|
|
|
- Execute REST API requests against the Stacks Blockchain API
|
|
- Subscribe to WebSockets or Socket.io for real-time Stacks updates (see [Available Updates](#Available-Updates))
|
|
- Full type safety for WebSocket and API requests and responses
|
|
|
|
## Installation
|
|
|
|
You can install this package using NPM:
|
|
|
|
```shell
|
|
npm install --save @stacks/blockchain-api-client
|
|
```
|
|
|
|
## Usage
|
|
|
|
Here is example code that subscribes to updates for a specific Stacks address:
|
|
|
|
### Websockets
|
|
|
|
```js
|
|
import { connectWebSocketClient } from '@stacks/blockchain-api-client';
|
|
|
|
// for testnet, replace with wss://stacks-node-api.testnet.stacks.co/
|
|
const client = await connectWebSocketClient('wss://stacks-node-api.mainnet.stacks.co/');
|
|
|
|
const sub = await client.subscribeAddressTransactions('ST3GQB6WGCWKDNFNPSQRV8DY93JN06XPZ2ZE9EVMA', event =>
|
|
console.log(event);
|
|
);
|
|
|
|
await sub.unsubscribe();
|
|
```
|
|
|
|
### Socket.io
|
|
|
|
```js
|
|
import { io } from "socket.io-client";
|
|
import * as stacks from '@stacks/blockchain-api-client';
|
|
|
|
// for testnet, replace with https://stacks-node-api.testnet.stacks.co/
|
|
const socketUrl = "https://stacks-node-api.mainnet.stacks.co/";
|
|
|
|
const socket = io(socketUrl, {
|
|
transports: [ "websocket" ]
|
|
});
|
|
const sc = new stacks.StacksApiSocketClient(socket);
|
|
|
|
sc.subscribeAddressTransactions('ST3GQB6WGCWKDNFNPSQRV8DY93JN06XPZ2ZE9EVMA');
|
|
```
|
|
|
|
## Available Updates
|
|
|
|
### Block Updates
|
|
|
|
Sent every time a new Stacks block is mined.
|
|
|
|
Example message:
|
|
```json
|
|
{
|
|
"canonical": true,
|
|
"height": 3275,
|
|
"hash": "0xe77ba8cf6bb7c0e4f64adc83356289ed467d31a22354907b4bb814590058430f",
|
|
"parent_block_hash": "0x75ab21ef25cbff2caa14c27d830ed7886a4d1522e1b6f9e5dc3b59ccf73ed49f",
|
|
"burn_block_time": 1594233639,
|
|
"burn_block_time_iso": "2020-08-27T16:41:26.000Z",
|
|
"burn_block_hash": "0xb154c008df2101023a6d0d54986b3964cee58119eed14f5bed98e15678e18fe2",
|
|
"burn_block_height": 654439,
|
|
"miner_txid": "0xd7d56070277ccd87b42acf0c91f915dd181f9db4cf878a4e95518bc397c240cc",
|
|
"parent_microblock_hash": "0x590a1bb1d7bcbeafce0a9fc8f8a69e369486192d14687fe95fbe4dc1c71d49df",
|
|
"parent_microblock_sequence": 2,
|
|
"txs": [
|
|
"0x4262db117659d1ca9406970c8f44ffd3d8f11f8e18c591d2e3960f4070107754",
|
|
"0x383632cd3b5464dffb684082750fcfaddd1f52625bbb9f884ed8f45d2b1f0547",
|
|
"0xc99fe597e44b8bd15a50eec660c6e679a7144a5a8553d214b9d5f1406d278c22"
|
|
],
|
|
"microblocks_accepted": [
|
|
"0xce0b1a4099d3fc7d5885cc7a3baa952b6d999f9709d0683b98b843597208231c",
|
|
"0x4c0529b6448a5885991c5021bd869cc97f1692c128a98b382729dc962203c326",
|
|
"0x64968846291dfea1015228a9d4bbd60aac81378cd6774b810b08e59e6b0e7494"
|
|
],
|
|
"microblocks_streamed": [
|
|
"0xb5650ef855f7d90fc146942e85cf9fac3a8c47ec408aca02f3cf9ed7c82f6cc6",
|
|
"0xeeb9aa5741d84aa0bc5de4f2fbdeae57ae29694479475d45a67ae7bd7e2c98f3",
|
|
"0x4f4c368d5f06fdf6065c5bafd9cb37391fddc9c279cfc57be35e4bf8ee932cbd",
|
|
"0xde2fc8d99872c827f144c752c002d29f9315dfc09472a09572ac7447ae623dea"
|
|
],
|
|
"execution_cost_read_count": 2477,
|
|
"execution_cost_read_length": 1659409,
|
|
"execution_cost_runtime": 2520952000,
|
|
"execution_cost_write_count": 608,
|
|
"execution_cost_write_length": 80170
|
|
}
|
|
```
|
|
Subscribe via WebSockets:
|
|
```js
|
|
client.subscribeBlocks(event => {});
|
|
```
|
|
Subscribe via Socket.io:
|
|
```js
|
|
sc.subscribeBlocks();
|
|
```
|
|
|
|
### Microblock Updates
|
|
|
|
Sent every time a new Stacks microblock is streamed.
|
|
|
|
Example message:
|
|
```json
|
|
{
|
|
"canonical": true,
|
|
"microblock_canonical": true,
|
|
"microblock_hash": "0xa31ee2244ceee0d042c0b129a91df2433c4ffd3b94e7e4e5dfa3a15927684a6f",
|
|
"microblock_sequence": 0,
|
|
"microblock_parent_hash": "0x5d053c206a7bcc5dcfe8bb8a61d8699fc068179f388eb2aec62786b7318c36c4",
|
|
"block_height": 38224,
|
|
"parent_block_height": 38223,
|
|
"parent_block_hash": "0x5d053c206a7bcc5dcfe8bb8a61d8699fc068179f388eb2aec62786b7318c36c4",
|
|
"block_hash": "",
|
|
"txs": [
|
|
"0xe4b46358b7864c9db31e15e7db4f74042a2e1748db920b93480ed56463ac1c48",
|
|
"0x1de11ca776fc4a713465bc5974790cd3cdab7d8ad89fa474c10a4160cf89efdc",
|
|
"0x16b3a99d6d100562964f6f0f0ae02d47121386495c4fd903e4e9f72548ae0b35",
|
|
"0xc99f802dfffee9190e4b8ee5c128295f4eec51974d7cabdec0ba49c35b17bca5",
|
|
"0xeffa0b1d1e5b96dc1de1ff49b390752f35cbe49eddf5a6c7ff1ee80ea2b73886",
|
|
"0x93f927bdf15056f65ff3b0c6041287c9cfd070e4bddadedeb1aa1627d837022a",
|
|
"0xdbd62060daf483a7fdac2d76c3a88091690ff1f26827e2627c0894e5f73dcf0a",
|
|
"0x0d89a6edb51f96eec1dfbbaf1abc66861c96c75a6962545c0783d78773563a4b"
|
|
],
|
|
"parent_burn_block_height": 710158,
|
|
"parent_burn_block_hash": "0x00000000000000000007b6fa2dcd91e0c69d488f9742d7e5261286aefce29ee0",
|
|
"parent_burn_block_time": 1637167098,
|
|
"parent_burn_block_time_iso": "2021-11-17T16:38:18.000Z"
|
|
}
|
|
```
|
|
Subscribe via WebSockets:
|
|
```js
|
|
client.subscribeMicroblocks(event => {});
|
|
```
|
|
Subscribe via Socket.io:
|
|
```js
|
|
sc.subscribeMicroblocks();
|
|
```
|
|
|
|
### Mempool Updates
|
|
|
|
Sent every time a new transaction is submitted to the mempool. Transactions of different types and structures may be received.
|
|
|
|
Example message:
|
|
```json
|
|
{
|
|
"tx_id": "0x698096b646d17297836542beecfe8d6a30454b2ce5ce4e9b0e5d243b05dce998",
|
|
"nonce": 66,
|
|
"fee_rate": "554000",
|
|
"sender_address": "SPBDCE0KCWY56SX6XE7MB6DVVETABYM2WRDK6PCB",
|
|
"sponsored": false,
|
|
"post_condition_mode": "allow",
|
|
"post_conditions": [],
|
|
"anchor_mode": "any",
|
|
"tx_status": "pending",
|
|
"receipt_time": 1637172201,
|
|
"receipt_time_iso": "2021-11-17T18:03:21.000Z",
|
|
"tx_type": "contract_call",
|
|
"contract_call": {
|
|
"contract_id": "SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR.arkadiko-swap-v2-1",
|
|
"function_name": "swap-x-for-y",
|
|
"function_signature": "",
|
|
"function_args": [
|
|
{
|
|
"hex": "0x0616982f3ec112a5f5928a5c96a914bd733793b896a50e61726b6164696b6f2d746f6b656e",
|
|
"repr": "SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR.arkadiko-token",
|
|
"name": "token-x-trait",
|
|
"type": "trait_reference"
|
|
},
|
|
{
|
|
"hex": "0x0616982f3ec112a5f5928a5c96a914bd733793b896a50a757364612d746f6b656e",
|
|
"repr": "SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR.usda-token",
|
|
"name": "token-y-trait",
|
|
"type": "trait_reference"
|
|
},
|
|
{
|
|
"hex": "0x010000000000000000000000003b023380",
|
|
"repr": "u990000000",
|
|
"name": "dx",
|
|
"type": "uint"
|
|
},
|
|
{
|
|
"hex": "0x0100000000000000000000000062ea4a9f",
|
|
"repr": "u1659521695",
|
|
"name": "min-dy",
|
|
"type": "uint"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
Subscribe via WebSockets:
|
|
```js
|
|
client.subscribeMempool(event => {});
|
|
```
|
|
Subscribe via Socket.io:
|
|
```js
|
|
sc.subscribeMempool();
|
|
```
|
|
|
|
### Transaction Updates
|
|
|
|
Sent every time a single transaction (subscribed by transaction ID) is updated. Transactions of different types and structures may be received.
|
|
|
|
Example message if subscribed to updates for a transaction with ID `0xd78988664aaa9a1b751cd58c55b253914f790e95ca6f3d402a866559e1cbe0b3` after it was submitted to the mempool:
|
|
```json
|
|
{
|
|
"tx_id": "0xd78988664aaa9a1b751cd58c55b253914f790e95ca6f3d402a866559e1cbe0b3",
|
|
"nonce": 18,
|
|
"fee_rate": "74400",
|
|
"sender_address": "SP36ADRBVM8J00ZWR5QXC8V65WTJNCD1BF4EJ93ZZ",
|
|
"sponsored": false,
|
|
"post_condition_mode": "deny",
|
|
"post_conditions": [
|
|
{
|
|
"type": "stx",
|
|
"condition_code": "sent_less_than_or_equal_to",
|
|
"amount": "50000000",
|
|
"principal": {
|
|
"type_id": "principal_standard",
|
|
"address": "SP36ADRBVM8J00ZWR5QXC8V65WTJNCD1BF4EJ93ZZ"
|
|
}
|
|
}
|
|
],
|
|
"anchor_mode": "any",
|
|
"is_unanchored": false,
|
|
"block_hash": "0x4f957ac52af57196eea8ae6ca9e848fc7772da72365d9ed4d3452afddc7a3cf2",
|
|
"parent_block_hash": "0x4b7ea97418fd44fbc4af278424fbde67fbfb253398628f78319671d1eab48a47",
|
|
"block_height": 38231,
|
|
"burn_block_time": 1637173532,
|
|
"burn_block_time_iso": "2021-11-17T18:25:32.000Z",
|
|
"parent_burn_block_time": 1637173325,
|
|
"parent_burn_block_time_iso": "2021-11-17T18:22:05.000Z",
|
|
"canonical": true,
|
|
"tx_index": 27,
|
|
"tx_status": "success",
|
|
"tx_result": {
|
|
"hex": "0x070100000000000000000000000000000009",
|
|
"repr": "(ok u9)"
|
|
},
|
|
"microblock_hash": "",
|
|
"microblock_sequence": 2147483647,
|
|
"microblock_canonical": true,
|
|
"event_count": 4,
|
|
"events": [],
|
|
"execution_cost_read_count": 13,
|
|
"execution_cost_read_length": 4320,
|
|
"execution_cost_runtime": 5609000,
|
|
"execution_cost_write_count": 5,
|
|
"execution_cost_write_length": 21,
|
|
"tx_type": "contract_call",
|
|
"contract_call": {
|
|
"contract_id": "SPZW30K9VG6YCPYV4BX4V1FT0VJ66R1Q01W9DQ1W.nebula",
|
|
"function_name": "claim",
|
|
"function_signature": "(define-public (claim ))"
|
|
}
|
|
},
|
|
```
|
|
Subscribe via WebSockets:
|
|
```js
|
|
client.subscribeTxUpdates('0xd78988664aaa9a1b751cd58c55b253914f790e95ca6f3d402a866559e1cbe0b3', event => {});
|
|
```
|
|
Subscribe via Socket.io:
|
|
```js
|
|
sc.subscribeTransaction('0xd78988664aaa9a1b751cd58c55b253914f790e95ca6f3d402a866559e1cbe0b3');
|
|
```
|
|
|
|
### Address Transaction Updates
|
|
|
|
Sent every time a transaction is sent or received by a specific Stacks address. Transactions of different types and structures may be received.
|
|
|
|
Example message if subscribed to updates for an address `SP3C5SSYVKPAWTR8Y63CVYBR65GD3MG7K80526D1Q`:
|
|
```json
|
|
{
|
|
"tx_id": "0x1f9e737dfbebcb57f0879a44518c1cc909be0ceb8ab0bc9b38ce63e3b6847917",
|
|
"nonce": 6,
|
|
"fee_rate": "277600",
|
|
"sender_address": "SP3C5SSYVKPAWTR8Y63CVYBR65GD3MG7K80526D1Q",
|
|
"sponsored": false,
|
|
"post_condition_mode": "deny",
|
|
"post_conditions": [
|
|
{
|
|
"type": "stx",
|
|
"condition_code": "sent_less_than_or_equal_to",
|
|
"amount": "25000000",
|
|
"principal": {
|
|
"type_id": "principal_standard",
|
|
"address": "SP3C5SSYVKPAWTR8Y63CVYBR65GD3MG7K80526D1Q"
|
|
}
|
|
},
|
|
{
|
|
"type": "non_fungible",
|
|
"condition_code": "not_sent",
|
|
"principal": {
|
|
"type_id": "principal_contract",
|
|
"contract_name": "stacks-skaters",
|
|
"address": "SPJW1XE278YMCEYMXB8ZFGJMH8ZVAAEDP2S2PJYG"
|
|
},
|
|
"asset": {
|
|
"contract_name": "stacks-skaters",
|
|
"asset_name": "stacks-skaters",
|
|
"contract_address": "SPJW1XE278YMCEYMXB8ZFGJMH8ZVAAEDP2S2PJYG"
|
|
},
|
|
"asset_value": {
|
|
"hex": "0x0100000000000000000000000000000000",
|
|
"repr": "u0"
|
|
}
|
|
},
|
|
{
|
|
"type": "stx",
|
|
"condition_code": "sent_less_than_or_equal_to",
|
|
"amount": "20000000",
|
|
"principal": {
|
|
"type_id": "principal_contract",
|
|
"contract_name": "stacks-skaters",
|
|
"address": "SPJW1XE278YMCEYMXB8ZFGJMH8ZVAAEDP2S2PJYG"
|
|
}
|
|
}
|
|
],
|
|
"anchor_mode": "any",
|
|
"tx_status": "pending",
|
|
"receipt_time": 1637172946,
|
|
"receipt_time_iso": "2021-11-17T18:15:46.000Z",
|
|
"tx_type": "contract_call",
|
|
"contract_call": {
|
|
"contract_id": "SPJW1XE278YMCEYMXB8ZFGJMH8ZVAAEDP2S2PJYG.stacks-skaters",
|
|
"function_name": "mint",
|
|
"function_signature": ""
|
|
}
|
|
}
|
|
```
|
|
Subscribe via WebSockets:
|
|
```js
|
|
client.subscribeAddressTransactions('SP3C5SSYVKPAWTR8Y63CVYBR65GD3MG7K80526D1Q', event => {});
|
|
```
|
|
Subscribe via Socket.io:
|
|
```js
|
|
sc.subscribeAddressTransactions('SP3C5SSYVKPAWTR8Y63CVYBR65GD3MG7K80526D1Q');
|
|
```
|
|
|
|
### Address Balance Updates
|
|
|
|
Sent every time a specific address sends or receives a transaction that changes its balance.
|
|
|
|
Example message:
|
|
```json
|
|
{
|
|
"balance": "53349741093",
|
|
"total_sent": "6432000000",
|
|
"total_received": "60358503333",
|
|
"total_fees_sent": "576762240",
|
|
"total_miner_rewards_received": "0",
|
|
"lock_tx_id": "",
|
|
"locked": "0",
|
|
"lock_height": 0,
|
|
"burnchain_lock_height": 0,
|
|
"burnchain_unlock_height": 0,
|
|
"token_offering_locked": {
|
|
"total_locked": "0",
|
|
"total_unlocked": "18286444440",
|
|
"unlock_schedule": [
|
|
{
|
|
"amount": "2285805555",
|
|
"block_height": 24837
|
|
},
|
|
{
|
|
"amount": "2285805555",
|
|
"block_height": 29157
|
|
},
|
|
{
|
|
"amount": "2285805555",
|
|
"block_height": 33477
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
Subscribe via WebSockets:
|
|
```js
|
|
client.subscribeAddressBalanceUpdates('SP3C5SSYVKPAWTR8Y63CVYBR65GD3MG7K80526D1Q', event => {});
|
|
```
|
|
Subscribe via Socket.io:
|
|
```js
|
|
sc.subscribeAddressStxBalance('SP3C5SSYVKPAWTR8Y63CVYBR65GD3MG7K80526D1Q');
|
|
```
|
|
|
|
## Known Issues
|
|
|
|
- The TypeScript definitions for several objects involving type unions, including transactions, are incorrectly specified as only `object`.
|