# API Specification
NBXplorer is a multi crypto currency lightweight block explorer.
NBXplorer does not index the whole blockchain, rather, it listens transactions and blocks from a trusted full node and index only addresses and transactions which belongs to a DerivationScheme
that you decide to track.
# Table of content
- Configuration
- Tracked Sources
- Authentication
- Tracking derivation scheme or address
- Query transactions of tracked sources
- Query specifc transactions of tracked sources
- Get balance of tracked sources
- Get a transaction
- Get connection status to the chain
- Get a new unused address
- Get scriptPubKey information of a Derivation Scheme
- Get available Unspent Transaction Outputs (UTXOs) of tracked sources
- Notifications via websocket
- Broadcast a transaction
- Rescan a transaction
- Get fee rate
- Scan UTXO Set
- Wipe derivation scheme transactions
- Query event stream
- Query event stream from most recent
- Create Partially Signed Bitcoin Transaction
- Update Partially Signed Bitcoin Transaction
- Attach metadata to a derivation scheme
- Detach metadata from a derivation scheme
- Retrieve metadata from a derivation scheme
- Manual pruning
- Generate a wallet
- Node RPC Proxy
- Health check
- Liquid integration
- Create group
- Get group
- Add group children
- Add address to group
# Configuration
You can check the available settings with --help
.
NBXplorer can be configured in three way:
- Through command line arguments (eg.
--chains btc
) - Through environment variables (eg.
NBXPLORER_CHAINS=btc
) - Through configuration file (eg.
chains=btc
)
If you use configuration file, you can find it on windows in:
C:\Users\<user>\AppData\Roaming\NBXplorer\<network>\settings.config
On linux or mac:
~/.nbxplorer/<network>/settings.config
Be careful, if you run NBXplorer with dotnet run
, you should do it this way, with settings after the --
:
dotnet run --no-launch-profile --no-build -c Release -p .\NBXplorer\NBXplorer.csproj -- --chains btc
Else, launch profiles, which are settings meant to be used only for debugging time, might be taken into account.
# Tracked Sources
A tracked source is a generic way to track a set of scripts (addresses) and its UTXOs, transactions, and balances.
# Derivation scheme
A derivation scheme, also called derivationStrategy
in the code, is a flexible way to define how to generate deterministic addresses for a wallet.
NBXplorer will track any addresses on the 0/x
, 1/x
and x
path.
Here a documentation of the different derivation scheme supported:
Address type | Format |
---|---|
P2WPKH | xpub1 |
P2SH-P2WPKH | xpub1-[p2sh] |
P2PKH | xpub-[legacy] |
Multi-sig P2WSH | 2-of-xpub1-xpub2 |
Multi-sig P2SH-P2WSH | 2-of-xpub1-xpub2-[p2sh] |
Multi-sig P2SH | 2-of-xpub1-xpub2-[legacy] |
P2TR | xpub1-[taproot] |
For multisig, the public keys are ordered before generating the address by default for privacy reason, use -[keeporder]
to disable it.
You can use more than one options at same time, example: 2-of-xpub1-xpub2-[legacy]-[keeporder]
Most of routes asks for a cryptoCode
. This identify the crypto currency to request data from. (eg. BTC
, LTC
...)
Note: Taproot is incompatible with all other options.
You can create one by calling Tracking derivation scheme or address.
# Groups
A group is a tracked source which serves as a logical method for grouping several tracked sources into a single entity. You can add or remove tracked sources to and from a group.
Additionally, specific addresses can be tracked through the group.
Every address attached by a child tracked source will be added to the group, including all related UTXOs and transactions.
A group can have any number of children, and a group can also be a child of another group. Please note that all the children are returned by Get a group. As such, it is advised not to add too many children to avoid slowing down this call.
A group tracked source's format is GROUP:groupid
.
You can create a new group by calling Create a group.
# Addresses
This refers to a tracked source that monitors a single address. It functions similarly to a group, but with only one specific address to it.
The address tracked source's format is ADDRESS:bc1...
.
You can create one by calling Tracking derivation scheme or address.
# Authentication
By default a cookie file is generated when NBXplorer is starting, for windows in:
C:\Users\<user>\AppData\Roaming\NBXplorer\<network>\.cookie
On linux or mac:
~/.nbxplorer/<network>/.cookie
The content of this cookie must be used is used as HTTP BASIC authentication to use the API.
This can be disabled with --noauth
.
Also, NBXPlorer listen by default on 127.0.0.1
, if you want to access it from another machine, run --bind "0.0.0.0"
.
# Tracking derivation scheme or address
This call add a derivation scheme tracked source, or a address tracked source.
HTTP POST v1/cryptos/{cryptoCode}/derivations/{derivationScheme}
HTTP POST v1/cryptos/{cryptoCode}/addresses/{address}
Returns nothing.
Optionally, you can attach a json body:
{
"derivationOptions": [
{
"feature": "Deposit",
"minAddresses": 30,
"maxAddresses": null
}
],
"wait": true
}
wait
: Optional. Iftrue
the call will return when all addresses has been generated, addresses will be generated in the background (default:false
)derivationOptions
: Optional. Options to manually start the address generation process. (default: empty)derivationOptions.feature
: Optional. Define to which feature this option should be used. (defaut: null, which match all feature)derivationOptions.minAddresses
: Optional. The minimum addresses that need to be generated with this call. (default: null, make sure the number of address in the pool is between MinGap and MaxGap)derivationOptions.maxAddresses
: Optional. The maximum addresses that need to be generated with this call. (default: null, make sure the number of address in the pool is between MinGap and MaxGap)
# Query transactions of tracked sources
To query all transactions of a tracked source:
HTTP GET v1/cryptos/{cryptoCode}/derivations/{derivationScheme}/transactions
HTTP GET v1/cryptos/{cryptoCode}/addresses/{address}/transactions
HTTP GET v1/cryptos/{cryptoCode}/groups/{groupId}/transactions
Optional Parameters:
includeTransaction
includes the hex of the transaction, not only information (default: true)
Returns:
{
"height": 104,
"confirmedTransactions": {
"transactions": [
{
"blockHash": "3e7bcca309f92ab78a47c1cdd1166de9190fa49e97165c93e2b10ae1a14b99eb",
"confirmations": 1,
"height": 104,
"transactionId": "cc33dfaf2ed794b11af83dc6e29303e2d8ff9e5e29303153dad1a1d3d8b43e40",
"transaction": "020000000166d6befa387fd646f77a10e4b0f0e66b3569f18a83f77104a0c440e4156f80890000000048473044022064b1398653171440d3e79924cb6593633e7b2c3d80b60a2e21d6c6e287ee785a02203899009df443d0a0a1b06cb970aee0158d35166fd3e26d4e3e85570738e706d101feffffff028c02102401000000160014ee0a1889783da2e1f9bba47be4184b6610efd00400e1f5050000000016001452f88af314ef3b6d03d40a5fd1f2c906188a477567000000",
"outputs": [
{
"keyPath": "0/0",
"scriptPubKey": "001452f88af314ef3b6d03d40a5fd1f2c906188a4775",
"index": 1,
"value": 100000000
}
],
"inputs": [
{
"inputIndex": 0,
"transactionId": "194d6dc4e1c4c983b5235ad2b82cc7c48c36def4960fdcf37697253c9d9854a2",
"scriptPubKey": "001409249118830af97a029217f3a8744973c5a4a02e",
"index": 4,
"value": 90000000,
"address": "bcrt1qpyjfzxyrptuh5q5jzle6sazfw0z6fgpwuz2rye"
},
{
"inputIndex": 1,
"transactionId": "194d6dc4e1c4c983b5235ad2b82cc7c48c36def4960fdcf37697253c9d9854a2",
"scriptPubKey": "0014d83837bd474d799ad4decba4bac561a7356e0371",
"index": 1,
"value": 50000000,
"address": "bcrt1qmqur0028f4ue44x7ewjt43tp5u6kuqm3eqa3ua"
}
],
"timestamp": 1540381888,
"balanceChange": 100000000,
"replaceable": false,
"replacing": null,
"replacedBy": null
}
]
},
"unconfirmedTransactions": {
"transactions": [
{
"blockHash": null,
"confirmations": 0,
"height": null,
"transactionId": "7ec0bcbd3b7685b6bbdb4287a250b64bfcb799dbbbcffa78c00e6cc11185e5f1",
"transaction": null,
"outputs": [
{
"keyPath": "0",
"scriptPubKey": "0014b39fc4eb5c6dd238d39449b70a2e30d575426d99",
"index": 1,
"value": 100000000
}
],
"inputs": [],
"timestamp": 1540381889,
"balanceChange": 100000000,
"replaceable": false,
"replacing": "e070e213a0815b84b4ae96d4d64ce551158524364d3522e7d6bd5415c6c15d3f",
"replacedBy": null
}
]
},
"replacedTransactions": {
"transactions": [
{
"blockHash": null,
"confirmations": 0,
"height": null,
"transactionId": "7ec0bcbd3b7685b6bbdb4287a250b64bfcb799dbbbcffa78c00e6cc11185e5f1",
"transaction": null,
"outputs": [
{
"keyPath": "0",
"scriptPubKey": "0014b39fc4eb5c6dd238d39449b70a2e30d575426d99",
"index": 1,
"value": 100000000
}
],
"inputs": [],
"timestamp": 1540381889,
"balanceChange": 100000000,
"replaceable": false,
"replacing": null,
"replacedBy": "7ec0bcbd3b7685b6bbdb4287a250b64bfcb799dbbbcffa78c00e6cc11185e5f1"
}
]
},
"immatureTransactions": {
"transactions": []
}
}
inputs
: The spent outputs of this transaction.inputs.inputIndex
: The index of the input in this transaction.replaceable
:true
if the transaction can be replaced (the transaction has RBF activated, is in the unconfirmed list and is not an intermediate transaction in a chain of unconfirmed transaction)replacing
: Only set in the unconfirmed list, and is pointing to a transaction id in the replaced list.replacedBy
: Only set in the replaced list, and is pointing to a transaction id in the unconfirmed list.immatureTransactions
: Coinbase transactions with less than 100 confirmations.
Note for liquid, balanceChange
is an array of AssetMoney.
Note that the list of confirmed transaction also include immature transactions.
# Query specifc transactions of tracked sources
HTTP GET v1/cryptos/{cryptoCode}/derivations/{derivationScheme}/transactions/{txId}
HTTP GET v1/cryptos/{cryptoCode}/addresses/{address}/transactions/{txId}
HTTP GET v1/cryptos/{cryptoCode}/groups/{groupId}/transactions/{txId}
Error codes:
- HTTP 404: Transaction not found
Optional Parameters:
includeTransaction
includes the hex of the transaction, not only information (default: true)
Returns:
{
"blockHash": null,
"confirmations": 0,
"height": null,
"transactionId": "7ec0bcbd3b7685b6bbdb4287a250b64bfcb799dbbbcffa78c00e6cc11185e5f1",
"transaction": null,
"outputs": [
{
"scriptPubKey": "0014b39fc4eb5c6dd238d39449b70a2e30d575426d99",
"index": 1,
"value": 100000000
}
],
"inputs": [],
"timestamp": 1540381889,
"balanceChange": 100000000
}
# Get balance of tracked sources
HTTP GET v1/cryptos/{cryptoCode}/derivations/{derivationScheme}/balance
HTTP GET v1/cryptos/{cryptoCode}/addresses/{address}/balance
HTTP GET v1/cryptos/{cryptoCode}/groups/{groupId}/balance
Returns:
{
"unconfirmed": 110000000,
"confirmed": 100000000,
"available": 210000000,
"immature": 0,
"total": 210000000
}
Note for liquid, the values are array of AssetMoney.
unconfirmed
: How the confirmed balance would be updated once all the unconfirmed transactions were confirmed.confirmed
: The balance of all funds in confirmed transactions.total
: The total of funds owned (ie,confirmed + unconfirmed
)immature
: The total unspendable funds (ie, coinbase reward which need 100 confirmations before being spendable)available
: The total spendable balance. (ie,total - immature
)
Immature funds is the sum of UTXO's belonging to a coinbase transaction with less than 100 confirmations.
# Get a transaction
HTTP GET v1/cryptos/{cryptoCode}/transactions/{txId}
Optional Parameters:
includeTransaction
includes the hex of the transaction, not only information (default: true)
Error codes:
- HTTP 404: Transaction not found
Returns:
{
"confirmations": 3,
"blockId": "5efa23803df818cd21faa0c11e84db28c8352e76acb93d0c0adfe123db827190",
"transactionHash": "ed86c55b519c26ab4ba8130c976294753934c1f9f6d30203e65bb222648a8cdf",
"transaction": "0200000001205dcde69a5bd2b3281d387e6f125338f9ccb904d94df383ff56d9923599681e000000004847304402200b9d78e01691339acb238d7cd7a40ae620796bdcf8cb167dff4e100b71a2b0950220518e3a955ea7229d57c0160ecf491e8048662d7112fe5feaa312ff71388fda9701feffffff028c02102401000000160014a4ccb74ada7dd01b3018c3308894fea27b4813be00e1f5050000000016001408f86300ddff26ddf779ddce833f7e9e7442156c67000000",
"height": 104,
"timestamp": 1540390804,
"replacedBy": "7ec0bcbd3b7685b6bbdb4287a250b64bfcb799dbbbcffa78c00e6cc11185e5f1"
}
height
and blockId
will be null if the transaction is not confirmed.
# Get connection status to the chain
HTTP GET v1/cryptos/{cryptoCode}/status
Returns:
{
"bitcoinStatus": {
"blocks": 103,
"headers": 103,
"verificationProgress": 1.0,
"isSynched": true,
"incrementalRelayFee": 1,
"minRelayTxFee": 1,
"capabilities": {
"canScanTxoutSet": true,
"canSupportSegwit": true,
"canSupportTaproot": true,
"canSupportTransactionCheck": true
}
},
"isFullySynched": true,
"chainHeight": 103,
"syncHeight": 103,
"networkType": "Regtest",
"cryptoCode": "BTC",
"instanceName": "MyInstance",
"supportedCryptoCodes": [
"BTC"
],
"version": "1.0.3.5"
}
instanceName
can be configured via configuration's key instancename
.
# Get a new unused address
HTTP GET v1/cryptos/{cryptoCode}/derivations/{derivationScheme}/addresses/unused
Error codes:
- HTTP 404:
cryptoCode-not-supported
- HTTP 400:
strategy-not-found
Optional parameters:
feature
: UseDeposit
to get a deposit address (0/x
),Change
to get a change address (1/x
),Direct
to getx
orCustom
ifcustomKeyPathTemplate
is configured (default:Deposit
)skip
: How many addresses to skip, needed if the user want multiple unused addresses (default:0)reserve
: Mark the returned address as used (default: false)
Returns:
{
"trackedSource": "DERIVATIONSCHEME:tpubD6NzVbkrYhZ4Wo2RMq8Xbnrorf1xnABkKMS3EGshPkQ3Z4N4GN8uyLuDPvnK7Ekc2FHdXbLvcuZny1gPiohMksFGKmaX3APD2DbTeBWj751-[p2sh]",
"feature": "Deposit",
"derivationStrategy": "tpubD6NzVbkrYhZ4Wo2RMq8Xbnrorf1xnABkKMS3EGshPkQ3Z4N4GN8uyLuDPvnK7Ekc2FHdXbLvcuZny1gPiohMksFGKmaX3APD2DbTeBWj751-[p2sh]",
"keyPath": "0/2",
"scriptPubKey": "a91412cbf6154ef6d9aecf9c978dc2bdc43f1881dd5f87",
"address": "2MtxcVDMiRrJ3V4zfsAwZGbZfPiDUxSXDY2",
"redeem": "0014e2eb89edba1fe6c6c0863699eeb78f6ec3271b45"
}
Note: redeem
is returning the segwit redeem if the derivation scheme is a P2SH-P2WSH or P2WSH, or the p2sh redeem if just a p2sh.
# Get scriptPubKey information of a Derivation Scheme
HTTP GET v1/cryptos/{cryptoCode}/derivations/{derivationScheme}/scripts/{script}
Error codes:
- HTTP 404:
cryptoCode-not-supported
Returns:
{
"trackedSource": "DERIVATIONSCHEME:tpubD6NzVbkrYhZ4WcPozSqALNCrJEt4C45sPDhEBBuokoCeDgjX6YTs4QVvhD9kao6f2uZLqZF4qcXprYyRqooSXr1uPp1KPH1o4m6aw9nxbiA",
"feature": "Deposit",
"derivationStrategy": "tpubD6NzVbkrYhZ4WcPozSqALNCrJEt4C45sPDhEBBuokoCeDgjX6YTs4QVvhD9kao6f2uZLqZF4qcXprYyRqooSXr1uPp1KPH1o4m6aw9nxbiA",
"keyPath": "0/0",
"scriptPubKey": "001460c25d29559774803f262acf5ee5c922eff52ccd",
"address": "tb1qvrp96224ja6gq0ex9t84aewfythl2txdkpdmu0"
}
# Get available Unspent Transaction Outputs (UTXOs) of tracked sources
HTTP GET v1/cryptos/{cryptoCode}/derivations/{derivationScheme}/utxos
HTTP GET v1/cryptos/{cryptoCode}/addresses/{address}/utxos
HTTP GET v1/cryptos/{cryptoCode}/groups/{groupId}/utxos
Error:
- HTTP 404:
cryptoCode-not-supported
Result:
{
"trackedSource": "DERIVATIONSCHEME:tpubD6NzVbkrYhZ4XQVi1sSEDBWTcicDqVSCTnYDxpwGwcSZVbPii2b7baRg57YfL64ed36sBRe6GviihHwhy3D1cnBe5uXb27DjrDZCKUA7PQi",
"derivationStrategy": "tpubD6NzVbkrYhZ4XQVi1sSEDBWTcicDqVSCTnYDxpwGwcSZVbPii2b7baRg57YfL64ed36sBRe6GviihHwhy3D1cnBe5uXb27DjrDZCKUA7PQi",
"currentHeight": 107,
"unconfirmed": {
"utxOs": [
{
"feature": "Deposit",
"outpoint": "10ba4bcadd03130b1bd98b0bc7aea9910f871b25b87ec06e484456e84440c88a01000000",
"index": 1,
"transactionHash": "8ac84044e85644486ec07eb8251b870f91a9aec70b8bd91b0b1303ddca4bba10",
"scriptPubKey": "00149681ae465a045e2068460b9d281cf97dede87cd8",
"address": "bcrt1qj6q6u3j6q30zq6zxpwwjs88e0hk7slxcunru7u",
"value": 100000000,
"keyPath": "0/0",
"timestamp": 1540376171,
"confirmations": 0
}
],
"spentOutpoints": [],
"hasChanges": true
},
"confirmed": {
"utxOs": [
{
"feature": "Deposit",
"outpoint": "29ca6590f3f03a6523ad79975392e74e385bf2b7dafe6c537ffa12f9e124348800000000",
"index": 0,
"transactionHash": "883424e1f912fa7f536cfedab7f25b384ee792539779ad23653af0f39065ca29",
"scriptPubKey": "001436a37f2f508650f7074bec4d091fc82bb01cc57f",
"address": "bcrt1qx63h7t6sseg0wp6ta3xsj87g9wcpe3tlgqgnql",
"value": 50000000,
"keyPath": "0/3",
"timestamp": 1540376174,
"confirmations": 1
}
],
"spentOutpoints": [
"9345f9585d643a31202e686ec7a4c2fe17917a5e7731a79d2327d24d25c0339f01000000"
],
"spentUnconfirmed": [
{
"feature": "Deposit",
"outpoint": "c8fd6675624d0b88056b9eaf945c5fd0c4614f7ddf44eb81911b3a66ba0e57a001000000",
"index": 1,
"transactionHash": "a0570eba663a1b9181eb44df7d4f61c4d05f5c94af9e6b05880b4d627566fdc8",
"scriptPubKey": "0014d77089591a85fa3a91e14f587c50e4b777ffd833",
"address": "bcrt1q6acgjkg6shar4y0pfav8c58ykamllkpnz6rnxh",
"value": 100000,
"keyPath": "0/0",
"timestamp": 1699930040,
"confirmations": 0
}
],
"hasChanges": true
},
"hasChanges": true
}
Response:
confirmed.utxOs
: UTXOs that are confirmed. (UTXO spent by an unconfirmed transaction are also included)unconfirmed.spentOutpoints
: Always empty.unconfirmed.utxOs
: UTXOs that will be confirmed once the unconfirmed transactions are confirmed.unconfirmed.spentOutpoints
: Confirmed UTXOs that will spent once the transactions are confirmed.spentUnconfirmed
: UTXOs that are spent by an unconfirmed transaction.
This call does not returns conflicted unconfirmed UTXOs. Note that confirmed utxo, do not include immature UTXOs. (ie. UTXOs belonging to a coinbase transaction with less than 100 confirmations)
# Notifications via websocket
NBXplorer implements real-time notification via websocket supports for new block or transaction.
HTTP GET v1/cryptos/{cryptoCode}/connect
Once you are connected to the websocket, you can subscribe to block notifications by sending the following JSON to it.
{
"type": "subscribeblock",
"data": {
"cryptoCode": "BTC"
}
}
Then a notification will be delivered through the websocket when a new block is mined:
{
"type": "newblock",
"eventId": 1,
"data": {
"height": 104,
"hash": "10b0e5178aaf42c4a938f0d37430413b7d76feae14b01fc07e1f23300b8821ce",
"previousBlockHash": "4c6a9c1cadf143c87249519639e86e236feac9d3cea2904e4c42bc5bc32a48a7",
"cryptoCode": "BTC",
"confirmations": 1
}
}
For notification concerning Derivation Scheme
transactions, you can subscribe by sending through the websocket:
{
"type": "subscribetransaction",
"data": {
"cryptoCode": "BTC",
"derivationSchemes": [
"tpubD6NzVbkrYhZ4YL91Ez5fdgaBPQbFhedFdn5gQL4tSCJn1usmHsV1L6VokzLbgcqzh9hiBnfnQANp5BYW15QdFGRKspZVSW1v2QY917RDs1V-[legacy]"
]
}
}
Then you will receive such notifications when a transaction is impacting the derivation scheme
:
{
"type": "newtransaction",
"eventId": 2,
"data": {
"blockId": null,
"trackedSource": "DERIVATIONSCHEME:tpubD6NzVbkrYhZ4X2p2D8kx6XV9V5iCJKMBHuBim1BLnZAZC1JobYkdwSrwF8R74V2oUWkJG3H24LwxnXs9wb6Ksivs2gj4RudMteyVai2AsmA-[p2sh]",
"derivationStrategy": "tpubD6NzVbkrYhZ4X2p2D8kx6XV9V5iCJKMBHuBim1BLnZAZC1JobYkdwSrwF8R74V2oUWkJG3H24LwxnXs9wb6Ksivs2gj4RudMteyVai2AsmA-[p2sh]",
"transactionData": {
"confirmations": 0,
"blockId": null,
"transactionHash": "f135537b40ac7a524273176b60e464b7f279f622031ec53af302d959966d7364",
"transaction": "0200000001dd7f53b09438fed83abe25dd6cdc30ee2092ce8c855cb9e7b0faa38aba8bc0f500000000484730440220093a837ff4be4b64b2ed4625abb128966caad0cb7830cac7af4f615bbf6b52ce02206227a3ddec3fac9e49f414eeab1388d0e67829620ac3a8fb2f4bbfc5b67bd02901feffffff0200e1f5050000000017a91476de0c5d07fd202880672bc702162b7f18e13aca87640210240100000017a9147cfa038496438a6d3c95cfac990f4dffc6cb44f28768000000",
"height": null,
"timestamp": 1540434424
},
"inputs": [
{
"inputIndex": 0,
"transactionId": "194d6dc4e1c4c983b5235ad2b82cc7c48c36def4960fdcf37697253c9d9854a2",
"scriptPubKey": "001409249118830af97a029217f3a8744973c5a4a02e",
"index": 4,
"value": 90000000,
"address": "bcrt1qpyjfzxyrptuh5q5jzle6sazfw0z6fgpwuz2rye"
},
{
"inputIndex": 1,
"transactionId": "194d6dc4e1c4c983b5235ad2b82cc7c48c36def4960fdcf37697253c9d9854a2",
"scriptPubKey": "0014d83837bd474d799ad4decba4bac561a7356e0371",
"index": 1,
"value": 50000000,
"address": "bcrt1qmqur0028f4ue44x7ewjt43tp5u6kuqm3eqa3ua"
}],
"outputs": [
{
"keyPath": "0/1",
"scriptPubKey": "a91476de0c5d07fd202880672bc702162b7f18e13aca87",
"address": "2N45jj76a7YjGLDoKs2mnQ4tt5N7t6R9xoM",
"redeem": "00147d31e1c7959cd047bb7b9b35e4c877a28efe2f0b",
"index": 0,
"value": 100000000
}
],
"cryptoCode": "BTC",
"replacing": ["25d6bc1b2812670550aca8b2984670203b5ebf00e75f9b2bbf1940c3fa27841e", "81a20eb55ec16b92c65d4e142278fd521caa9e5dcad9d941c8e256dbd917ae84"]
}
}
If you want all transactions of all derivation schemes of BTC, send this to the WebSocket:
{
"type": "subscribetransaction",
"data": {
"cryptoCode": "BTC"
}
}
If you want all transactions of all derivation schemes of all crypto currencies, send this to the WebSocket:
{
"type": "subscribetransaction",
"data": {
"cryptoCode": "*"
}
}
As an alternative to get notification, you can also use long polling with the event stream.
Fields:
replacing
: The list of the unconfirmed transactions of this wallet which have been replaced by this new transaction. This can typically be used to detect when the sender is bumping fee. This can't be used to detect when the sender is attempting to abort a transaction.
# Broadcast a transaction
HTTP POST v1/cryptos/{cryptoCode}/transactions
Body:
Raw bytes of the transaction.
Parameter:
testMempoolAccept
: Iftrue
, will not attempt to broadcast the transaction but just test its acceptance in the mempool. (default:false
)
Error codes:
- HTTP 404:
cryptoCode-not-supported
- HTTP 400:
rpc-unavailable
- HTTP 400:
not-supported
iftestMempoolAccept
istrue
, but the underlying node does not support it
Returns:
{
"success":false,
"rpcCode":-25,
"rpcCodeMessage":"General error during transaction submission",
"rpcMessage":"Missing inputs"
}
# Rescan a transaction
NBXplorer does not rescan the whole blockchain when tracking a new derivation scheme. This means that if the derivation scheme already received UTXOs in the past, NBXplorer will not be aware of it and might reuse addresses already generated in the past, and will not show past transactions.
By using this route, you can ask NBXplorer to rescan specific transactions found in the blockchain. This way, the transactions and the UTXOs present before tracking the derivation scheme will appear correctly.
HTTP POST v1/cryptos/{cryptoCode}/rescan
Body:
{
"transactions":[
// Specify the blockId and transactionId to scan. Your node must not be pruned for this to work.
{
"blockId":"19b44484c79c40d4e74da406e25390348b86a252c1ab784cfd7198c724a0169f",
"transactionId":"f83c7f31e2c39202bbbca619ab354ca8841721cf3440a253e056a7bea43e9745",
},
// Only the transactionId is specified. Your node must run --txindex=1 for this to work
{
"transactionId":"754c14060b958de0ff4e77e2ccdca617964c939d40ec9a01ef21fca2aad78d00",
},
// This will index the transaction without using RPC. Careful: A wrong blockId will corrupt the database.
{
"blockId":"19b44484c79c40d4e74da406e25390348b86a252c1ab784cfd7198c724a0169f",
"transaction":"02000000000101008dd7aaa2fc21ef019aec409d934c9617a6dccce2774effe08d950b06144c750000000000feffffff026c3e2e12010000001600143072110b34b66acd9469b2882d6d57a8ae27183900e1f505000000001600140429b3eebb7d55c50ca36ace12ae874ff2fd16af0247304402202e32739cc6e42877699d4159159941f3cc39027c7626f9962cca9a865816d43502205389e9d6c1a4cab41f2c504413cf0f46a5c1f8814f368e03c9bf1f8017c6787e012103b8858085f2a0c9c906fb793bedb2c115c340de1f7b279d6099f675ddf3eec0bf67000000"
}
]
}
Returns:
HTTP 200
Error codes:
- HTTP 400:
rpc-unavailable
# Get fee rate
HTTP GET v1/cryptos/{cryptoCode}/fees/{blockCount}
Get expected fee rate for being confirmed in blockCount
blocks.
Error codes:
- HTTP 400:
fee-estimation-unavailable
- HTTP 404:
cryptoCode-not-supported
- HTTP 400:
rpc-unavailable
Returns:
{
"feeRate": 5,
"blockCount": 1
}
The fee rate is in satoshi/byte.
# Scan UTXO Set
NBXplorer can scan the UTXO Set for output belonging to your derivationScheme.
HTTP POST v1/cryptos/BTC/derivations/{derivationScheme}/utxos/scan
In order to not consume too much RAM, NBXplorer splits the addresses to scan in several batch
and scan the whole UTXO set sequentially.
Three branches are scanned: 0/x, 1/x and x.
If a UTXO in one branch get found at a specific x, then all addresses inferior to index x will be considered used and not proposed when fetching a new unused address.
Query parameters:
batchSize
the number of addresses scanned at once per derivation scheme branch (default: 1000)gapLimit
If no UTXO are detected in this interval, the scan stop (default: 10000)from
the first address index to check (default: 0)
This call queue the request for scanning and returns immediately.
Error codes:
- HTTP 405:
scanutxoset-not-suported
ScanUTXOSet is not supported for this currency - HTTP 409:
scanutxoset-in-progress
ScanUTXOSet has already been called for this derivationScheme - HTTP 400:
rpc-unavailable
# Get scan status
You can poll the status of the scan. Note that if the scan is complete, the result will be kept for 24H. The state can be:
Queued
the demand has been done, but the scan request is queuing to be startedPending
the scan is in progressComplete
the scan is successfulError
the scan errored
{
"error": null,
"queuedAt": 1540439841,
"status": "Pending",
"progress": {
"startedAt": 1540439841,
"completedAt": null,
"found": 2,
"batchNumber": 9,
"remainingBatches": 1,
"currentBatchProgress": 50,
"remainingSeconds": 10,
"overallProgress": 91,
"from": 900,
"count": 100,
"totalSearched": 2700,
"totalSizeOfUTXOSet": null,
"highestKeyIndexFound": {
"change": null,
"deposit": 51,
"direct": null
}
}
}
TotalSizeOfUTXOSet
is set only when the scan is complete.
Error codes:
- HTTP 404
scanutxoset-info-not-found
if the scan has been done above the last 24H.
# Wipe derivation scheme transactions
Wipe all the transactions from a derivation scheme.
HTTP POST cryptos/{cryptoCode}/derivations/{derivationScheme}/utxos/wipe
# Query event stream
All notifications sent through websocket are also saved in a crypto specifc event stream.
HTTP GET v1/cryptos/{cryptoCode}/events
Query parameters:
lastEventId
: Will query all events which happened after this event id, the first event has id 1 (default: 0)longPolling
: If no events have been received sincelastEventId
, the call will block (default: false)limit
: Limit the maximum number of events to return (default: null)
All events are registered in a query stream which you can replay by keeping track of the lastEventId
.
The smallest eventId
is 1.
[
{
"eventId": 1,
"type": "newblock",
"data": {
"height": 104,
"hash": "1f31c605c0a5d54b65fa39dc8cb4db025be63c66280279ade9338571a9e63d35",
"previousBlockHash": "7639350b31f3ce07ff976ebae772fef1602b30a10ccb8ca69047fe0fe8b9083c",
"cryptoCode": "BTC",
"confirmations": 1
}
},
{
"eventId": 2,
"type": "newtransaction",
"data": {
"blockId": null,
"trackedSource": "DERIVATIONSCHEME:tpubD6NzVbkrYhZ4XfeFUTn2D4RQ7D5HpvnHywa3eZYhxZBriRTsfe8ZKFSDMcEMBqGrAighxxmq5VUqoRvo7DnNMS5VbJjRHwqDfCAMXLwAL5j",
"derivationStrategy": "tpubD6NzVbkrYhZ4XfeFUTn2D4RQ7D5HpvnHywa3eZYhxZBriRTsfe8ZKFSDMcEMBqGrAighxxmq5VUqoRvo7DnNMS5VbJjRHwqDfCAMXLwAL5j",
"transactionData": {
"confirmations": 0,
"blockId": null,
"transactionHash": "500359d971698c021587ea952bd38bd57dafc2b99615f71f7f978af394682737",
"transaction": "0200000001b8af58c5dbed4bd0ea60ae8ba7e68e66143440b8c1c69b6eaaf719566676ab1b0000000048473044022040b419aeb9042a53fb2d03abec911901ed42fc50d6a143e322bc61d51e4e35a9022073c10fe827b53332d50fbde581e36ad31f57b98ec35a125562dc8c739762ec8901feffffff028c02102401000000160014b6bedaf0cb795c01a1e427bd7752d6ef058964f100e1f50500000000160014c5e0b07f40b8dbe69b22864d84d83d5b4120835368000000",
"height": null,
"timestamp": 1542703963
},
"outputs": [
{
"keyPath": "0/0",
"scriptPubKey": "0014c5e0b07f40b8dbe69b22864d84d83d5b41208353",
"address": "bcrt1qchstql6qhrd7dxezsexcfkpatdqjpq6nntvtrd",
"index": 1,
"value": 100000000
}
],
"cryptoCode": "BTC",
}
}
]
# Query event stream (from most recent)
Exact same as event stream but it returns a maximum number #limit
of the most recent events.
HTTP GET v1/cryptos/{cryptoCode}/events/latest
Query parameters:
limit
: Limit the maximum number of events to return (default: 10)
# Create Partially Signed Bitcoin Transaction
Create a Partially Signed Bitcoin Transaction (opens new window) (PSBT).
A PSBT is a standard format to represent a transaction with pending signatures associated to it. A PSBT can be signed independently by many signers, and combined together before broadcast.
HTTP POST v1/cryptos/{cryptoCode}/derivations/{derivationScheme}/psbt/create
Error codes:
- HTTP 400:
not-enough-funds
- HTTP 400:
output-too-small
(if the output on which thesubstractFee=true
is too small to cover the fees) - HTTP 400:
fee-estimation-unavailable
- HTTP 404:
cryptoCode-not-supported
Fields:
{
"seed": 1,
"rbf": false,
"version": 1,
"timeLock": 512000,
"includeGlobalXPub": false,
"explicitChangeAddress": "mu5kevv6FiLygJfVvxQnB4hArXCUArMC7C",
"destinations": [
{
"destination": "mu5kevv6FiLygJfVvxQnB4hArXCUArMC7C",
"amount": 50000000,
"substractFees": false,
"sweepAll": false
}
],
"feePreference": {
"explicitFeeRate": 10,
"explicitFee": 23000,
"blockTarget": 1,
"fallbackFeeRate": 100
},
"discourageFeeSniping": true,
"reserveChangeAddress": false,
"spendAllMatchingOutpoints": false,
"minConfirmations": 0,
"excludeOutpoints": [
"7c02d7d6923ab5e9bbdadf7cf6873a5454ae5aa86d15308ed8d68840a79cf644-1",
"7c02d7d6923ab5e9bbdadf7cf6873a5454ae5aa86d15308ed8d68840a79cf644-2"
],
"includeOnlyOutpoints": [ "7c02d7d6923ab5e9bbdadf7cf6873a5454ae5aa86d15308ed8d68840a79cf644-1" ],
"minValue": 1000,
"rebaseKeyPaths": [
{
"accountKey": "tpubD6NzVbkrYhZ4XfeFUTn2D4RQ7D5HpvnHywa3eZYhxZBriRTsfe8ZKFSDMcEMBqGrAighxxmq5VUqoRvo7DnNMS5VbJjRHwqDfCAMXLwAL5j",
"accountKeyPath": "ab5ed9ab/49'/0'/0'"
}
],
"disableFingerprintRandomization": false,
"alwaysIncludeNonWitnessUTXO": false,
"mergeOutputs": true
}
seed
: Optional, default to null, a seed to specific to get a deterministic PSBT (useful for tests)version
: Optional, the version of the transaction (default: 1, ifdisableFingerprintRandomization
istrue
)timeLock
: Optional, The timelock of the transaction, activate RBF if not null (default: 0, ifdisableFingerprintRandomization
istrue
)includeGlobalXPub
: Optional. Whether or not to include the global xpubs of the derivation scheme in the PSBT. (default: false)rbf
: Optional, determine if the transaction should have Replace By Fee (RBF) activated (default:true
, ifdisableFingerprintRandomization
istrue
)reserveChangeAddress
: default to false, whether the creation of this PSBT will reserve a new change address.spendAllMatchingOutpoints
: Iftrue
, all the UTXOs that have been selected will be used as input in the PSBT. (default to false)explicitChangeAddress
: default to null, use a specific change address (Optional, mutually exclusive with reserveChangeAddress)minConfirmations
: default to 0, the minimum confirmations a UTXO need to be selected. (by default unconfirmed and confirmed UTXO will be used)includeOnlyOutpoints
: Only select the following outpoints for creating the PSBT. Note that it can also select outpoints that has been already spent, but where the spending is unconfirmed, so it can be used for RBF. (default to null)excludeOutpoints
: Do not select the following outpoints for creating the PSBT (default to empty)minValue
: UTXO's with value below this amount will be ignored (default to null)destinations
: Required, the destinations where to send the moneydestinations[].destination
: Required, the destination addressdestinations[].amount
Send this amount to the destination (Mutually exclusive with: sweepAll)destinations[].substractFees
Default to false, will substract the fees of this transaction to this destination (Mutually exclusive with: sweepAll)destinations[].sweepAll
Deault to false, will sweep all the balance of your wallet to this destination (Mutually exclusive with: amount, substractFees)feePreference
: Optional, determines how fees for the transaction are calculated, default to the full node estimation for 1 block target.feePreference.explicitFeeRate
: An explicit fee rate for the transaction in Satoshi per vBytes (Mutually exclusive with: blockTarget, explicitFee, fallbackFeeRate)feePreference.explicitFee
: An explicit fee for the transaction in Satoshi (Mutually exclusive with: blockTarget, explicitFeeRate, fallbackFeeRate)feePreference.blockTarget
: A number of blocks after which the user expect one confirmation (Mutually exclusive with: explicitFeeRate, explicitFee)feePreference.fallbackFeeRate
: If the NBXplorer's node does not have proper fee estimation, this specific rate will be use in Satoshi per vBytes, this make sure thatfee-estimation-unavailable
is never sent. (Mutually exclusive with: explicitFeeRate, explicitFee)discourageFeeSniping
: IftimeLock
is not set, set the timeLock to a random value to discourage fee sniping (default totrue
, ifdisableFingerprintRandomization
istrue
)rebaseKeyPaths
: Optional. rebase the hdkey paths (if no rebase, the key paths are relative to the xpub that NBXplorer knows about), a rebase can transform (PubKey0, 0/0, accountFingerprint) by (PubKey0, m/49'/0'/0/0, masterFingerprint)rebaseKeyPaths[].accountKey
: The account key to rebaserebaseKeyPaths[].accountKeyPath
: The path from the root to the account key prefixed by the master public key fingerprint.disableFingerprintRandomization
: Disable the randomization of default parameter's value to match the network's fingerprint distribution. (randomized default values areversion
,timeLock
,rbf
,discourageFeeSniping
)alwaysIncludeNonWitnessUTXO
: Try to set the full transaction innon_witness_utxo
, even for segwit inputs (default tofalse
)mergeOutputs
: Optional, default to true, whether the outputs sending to the same scriptPubKey should be merged into a single output.
Response:
{
"psbt": "cHNidP8BAHcBAAAAASjvZHM29AbxO4IGGHbk3IE82yciSQFr2Ihge7P9P1HeAQAAAAD/////AmzQMAEAAAAAGXapFG1/TpHnIajdweam5Z3V9s6oGWBRiKyAw8kBAAAAABl2qRSVNmCfrnVeIwVkuTrCR6EvRFCP7IisAAAAAAABAP10AQEAAAACe9C2c9VL+gfYpic4c+Wk/Nn7bvhewA82owtcUDo/tPoAAAAAakcwRAIgUlLS0SDj7IXeY44x21eUg16Vh4qbJe+NDQ/ywUrB84kCIGLU5Vec2bjL1DZhUmDueLrf0uh/PycOK7FWg/Ptvwi0ASED7OpQGf+HzIRwWKZ1Hmd8h6vxkFOt5RlJ3u/flzNTesv/////818+qp4hLnw9DWOD+a601fLjFciZ/4iCNT1M9g+kMvkAAAAAakcwRAIgfk+bUUYfRs6AU1mt5unV4fZxCit34g8pE5fsawUM7H0CIBGpSil8+JCHdAHxKU2I7CvEBzAyz3ggd9RlH+QQSnlkASEC/wwlQ07b3xdSQaEf+wRJEnzEJT2GPNTY4Wb3Gg1hxFz/////AoDw+gIAAAAAGXapFHoZHSjaWNcmJk7sSHvRG29RaqIiiKxQlPoCAAAAABl2qRTSKm2x4ITWeuYLwCv3PUDtt+CL+YisAAAAACIGA1KRWHyJqdpbUzuezCSzj4+bj1+gNWGEibLG0BMj9/RmDDAn+hsBAAAAAgAAAAAiAgIuwas0MohgjmGIXoOgS95USEDawK//ZqrVEi5UIfP/FAwwJ/obAQAAAAMAAAAAAA==",
"changeAddress": "mqVvTQKsdJ36Z8m5uFWQSA5nhrJ5NHQ2Hs",
"suggestions":
{
"shouldEnforceLowR": true
}
}
psbt
: The partially signed bitcoin transaction in Base64.changeAddress
: The change address of the transaction, useful for tests (can be null)suggestions
: Suggestions to the signer of the PSBT (null value ifdisableFingerprintRandomization
is set tofalse
)suggestions.shouldEnforceLowR
: Iftrue
, the signer should enforce the creation of 71 bytes ECDSA signature to maximize privacy.
Note, in the example above, if the metadata AccountKeyPath
is set to ab5ed9ab/49'/0'/0'
, then you don't have to pass rebaseKeyPaths
.
# Update Partially Signed Bitcoin Transaction
HTTP POST v1/cryptos/{cryptoCode}/psbt/update
NBXplorer will take to complete as much information as it can about this PSBT.
{
"psbt": "cHNidP8BAHcBAAAAASjvZHM29AbxO4IGGHbk3IE82yciSQFr2Ihge7P9P1HeAQAAAAD/////AmzQMAEAAAAAGXapFG1/TpHnIajdweam5Z3V9s6oGWBRiKyAw8kBAAAAABl2qRSVNmCfrnVeIwVkuTrCR6EvRFCP7IisAAAAAAABAP10AQEAAAACe9C2c9VL+gfYpic4c+Wk/Nn7bvhewA82owtcUDo/tPoAAAAAakcwRAIgUlLS0SDj7IXeY44x21eUg16Vh4qbJe+NDQ/ywUrB84kCIGLU5Vec2bjL1DZhUmDueLrf0uh/PycOK7FWg/Ptvwi0ASED7OpQGf+HzIRwWKZ1Hmd8h6vxkFOt5RlJ3u/flzNTesv/////818+qp4hLnw9DWOD+a601fLjFciZ/4iCNT1M9g+kMvkAAAAAakcwRAIgfk+bUUYfRs6AU1mt5unV4fZxCit34g8pE5fsawUM7H0CIBGpSil8+JCHdAHxKU2I7CvEBzAyz3ggd9RlH+QQSnlkASEC/wwlQ07b3xdSQaEf+wRJEnzEJT2GPNTY4Wb3Gg1hxFz/////AoDw+gIAAAAAGXapFHoZHSjaWNcmJk7sSHvRG29RaqIiiKxQlPoCAAAAABl2qRTSKm2x4ITWeuYLwCv3PUDtt+CL+YisAAAAACIGA1KRWHyJqdpbUzuezCSzj4+bj1+gNWGEibLG0BMj9/RmDDAn+hsBAAAAAgAAAAAiAgIuwas0MohgjmGIXoOgS95USEDawK//ZqrVEi5UIfP/FAwwJ/obAQAAAAMAAAAAAA==",
"derivationScheme": "tpubD6NzVbkrYhZ4WcPozSqALNCrJEt4C45sPDhEBBuokoCeDgjX6YTs4QVvhD9kao6f2uZLqZF4qcXprYyRqooSXr1uPp1KPH1o4m6aw9nxbiA",
"includeGlobalXPub": false,
"rebaseKeyPaths": [
{
"accountKey": "tpubD6NzVbkrYhZ4XfeFUTn2D4RQ7D5HpvnHywa3eZYhxZBriRTsfe8ZKFSDMcEMBqGrAighxxmq5VUqoRvo7DnNMS5VbJjRHwqDfCAMXLwAL5j",
"accountKeyPath": "ab5ed9ab/49'/0'/0'"
}
]
}
psbt
: Required. A potentially incomplete PSBT that you want to update (Input WitnessUTXO, NonWitnessUTXO)derivationScheme
: Optional. If specified, will complete HDKeyPaths, witness script and redeem script information in the PSBT belonging to this derivationScheme.includeGlobalXPub
: Optional. Whether or not to include the global xpubs of the derivation scheme in the PSBT. (default: false)rebaseKeyPaths
: Optional. Rebase the hdkey paths (if no rebase, the key paths are relative to the xpub that NBXplorer knows about), a rebase can transform (PubKey0, 0/0, accountFingerprint) by (PubKey0, m/49'/0'/0/0, masterFingerprint)rebaseKeyPaths[].accountKey
: The account key to rebaserebaseKeyPaths[].accountKeyPath
: The path from the root to the account key prefixed by the master public key fingerprint.alwaysIncludeNonWitnessUTXO
: Try to set the full transaction innon_witness_utxo
, even for segwit inputs (default tofalse
)
Response:
{
"psbt": "cHNidP8BAHcBAAAAASjvZHM29AbxO4IGGHbk3IE82yciSQFr2Ihge7P9P1HeAQAAAAD/////AmzQMAEAAAAAGXapFG1/TpHnIajdweam5Z3V9s6oGWBRiKyAw8kBAAAAABl2qRSVNmCfrnVeIwVkuTrCR6EvRFCP7IisAAAAAAABAP10AQEAAAACe9C2c9VL+gfYpic4c+Wk/Nn7bvhewA82owtcUDo/tPoAAAAAakcwRAIgUlLS0SDj7IXeY44x21eUg16Vh4qbJe+NDQ/ywUrB84kCIGLU5Vec2bjL1DZhUmDueLrf0uh/PycOK7FWg/Ptvwi0ASED7OpQGf+HzIRwWKZ1Hmd8h6vxkFOt5RlJ3u/flzNTesv/////818+qp4hLnw9DWOD+a601fLjFciZ/4iCNT1M9g+kMvkAAAAAakcwRAIgfk+bUUYfRs6AU1mt5unV4fZxCit34g8pE5fsawUM7H0CIBGpSil8+JCHdAHxKU2I7CvEBzAyz3ggd9RlH+QQSnlkASEC/wwlQ07b3xdSQaEf+wRJEnzEJT2GPNTY4Wb3Gg1hxFz/////AoDw+gIAAAAAGXapFHoZHSjaWNcmJk7sSHvRG29RaqIiiKxQlPoCAAAAABl2qRTSKm2x4ITWeuYLwCv3PUDtt+CL+YisAAAAACIGA1KRWHyJqdpbUzuezCSzj4+bj1+gNWGEibLG0BMj9/RmDDAn+hsBAAAAAgAAAAAiAgIuwas0MohgjmGIXoOgS95USEDawK//ZqrVEi5UIfP/FAwwJ/obAQAAAAMAAAAAAA=="
}
Note, in the example above, if the metadata AccountKeyPath
is set to ab5ed9ab/49'/0'/0'
, then you don't have to pass rebaseKeyPaths
.
# Attach metadata to a derivation scheme
You can attach JSON metadata to a derivation scheme:
HTTP POST v1/cryptos/{cryptoCode}/derivations/{derivationScheme}/metadata/{key}
The body can be any JSON token.
Body:
{
"example": "value"
}
# Detach metadata from a derivation scheme
HTTP POST v1/cryptos/{cryptoCode}/derivations/{derivationScheme}/metadata/{key}
HTTP POST v1/cryptos/{cryptoCode}/addresses/{derivationScheme}/metadata/{key}
HTTP POST v1/groups/{derivationScheme}/metadata/{key}
Call without body and without content type.
# Retrieve metadata from a derivation scheme
You retrieve the JSON metadata of a derivation scheme:
HTTP GET v1/cryptos/{cryptoCode}/derivations/{derivationScheme}/metadata/{key}
HTTP GET v1/cryptos/{cryptoCode}/addresses/{derivationScheme}/metadata/{key}
HTTP GET v1/groups/{derivationScheme}/metadata/{key}
Error codes:
- HTTP 404: The key is not found
The body can be any piece of JSON.
Body:
{
"example": "value"
}
# Manual pruning
NBXplorer has an auto pruning feature configurable with --autopruning x
where x
is in second. If a call to NBXplorer's Get utxo
or Get PSBT
takes more time than x seconds
, then the auto pruning will delete transactions whose all UTXOs have been already spent and which are old enough.
You can however force pruning by calling:
HTTP POST v1/cryptos/{cryptoCode}/derivations/{derivationScheme}/prune
Request:
{
"daysToKeep": 1.0
}
daysToKeep
: Optional. The number of days of history to keep. (Default: 1.0)
Response:
{
"totalPruned": 10
}
totalPruned
is the number of transactions pruned from the derivation scheme
# Generate a wallet
NBXplorer will generate and save a mnemonic and create a derivationScheme.
HTTP POST v1/cryptos/{cryptoCode}/derivations
Request:
{
"accountNumber": 2,
"wordList": "French",
"existingMnemonic": "musicien sinistre divertir réussir louve alliage péplum innocent filmer stipuler chignon utopie effusion heureux légal",
"wordCount": 15,
"scriptPubKeyType": "SegwitP2SH",
"passphrase": "hello",
"importKeysToRPC": true,
"savePrivateKeys": true,
"additionalOptions": { "slip77": "6c2de18eabeff3f7822bc724ad482bef0557f3e1c1e1c75b7a393a5ced4de616"}
}
accountNumber
: Optional, the account number used for determining the keypath that NBXplorer will track, seeaccountKeyPath
in the response. (Default:0
)existingMnemonic
: Optional, an existing BIP39 (opens new window) mnemonic seed to import instead of generating.wordList
: Optional, the BIP39 (opens new window) wordlist to use when generating the mnemonic, available: English, French, Japanese, Spanish, ChineseSimplified (Defaut:English
)wordCount
: Optional, the BIP39 (opens new window) word count in the mnemonic (Default:12
)scriptPubKeyType
: Optional, the type of scriptPubKey (address) to generate, available: Legacy, Segwit, SegwitP2SH, Taproot (Default:Segwit
orLegacy
ifcryptoCode
does not support segwit)passphrase
: Optional, the BIP39 (opens new window) passphrase. (Default: empty string)importKeysToRPC
: Optional, if true, every times a call to get a new unused address is called, the private key will be imported into the underlying node via RPC'simportprivkey
. (Default:false
)savePrivateKeys
: If true, private keys will be saved inside the following metadataMnemonic
,MasterHDKey
andAccountHDKey
.additionalOptions
: Optional, additional options that a derivation scheme of some networks may support, such as Liquid
The importKeysToRPC
is only useful if one need to manage his wallet via the node's cli tooling.
Response:
{
"mnemonic": "musicien sinistre divertir réussir louve alliage péplum innocent filmer stipuler chignon utopie effusion heureux légal",
"passphrase": "hello",
"wordList": "French",
"wordCount": 15,
"masterHDKey": "tprv8ZgxMBicQKsPdv26BvirqqQCZJPSYEkSW7Por7a7r2PpsCUKHjjT18Gwk8k4FtkvqvakMFnsv9uaXHHoibieRd5BMhGCPYxVLaVY9vqpaxb",
"accountHDKey": "tprv8gPRns62uoh4zbRatcxUWZY7aX3XsTchHBp79YL6E3fEocsgd6XjThU4r7E3iUemBffeLSjcjXyD1VrmHMwNceVipFL7txTFMgKm4kehuSR",
"accountKeyPath": "a0aa59b4/49'/1'/2'",
"accountDescriptor": "sh(wpkh([a0aa59b4/49'/1'/2']tpubDD5TwH8H4BNjt4TNnGd4uyCE9YZU2nobrVQtS4NPeKTde78TFVMKeC5w2G1nj7amQbGDptv4FtDBLuVQhofegQaZdFVuuxuCGpZQ4jZ6L5q))",
"derivationScheme": "tpubDD5TwH8H4BNjt4TNnGd4uyCE9YZU2nobrVQtS4NPeKTde78TFVMKeC5w2G1nj7amQbGDptv4FtDBLuVQhofegQaZdFVuuxuCGpZQ4jZ6L5q-[p2sh]"
}
mnemonic
: The generated BIP39 (opens new window) mnemonic.passphrase
: The BIP39 (opens new window) passphrase.wordList
: The BIP39 (opens new window) wordlist to use when generating the mnemonic.wordCount
: The BIP39 (opens new window) word count in the mnemonic.masterHDKey
: The BIP32 (opens new window) master key derived from the mnemonic and passphrase.accountHDKey
: The BIP32 (opens new window) account key derived from themasterHDKey
andaccountKeyPath
.accountKeyPath
: The fingerprint of the master key as defined by The BIP174 (opens new window), followed by the derivation path used to generate thederivationScheme
. (Purpose field (opens new window) based on BIP44 (opens new window), BIP49 (opens new window) or BIP84 (opens new window) and SLIP44 (opens new window) for the coin type)accountDescriptor
: The output descriptor of the created account public key.derivationScheme
: The derivation scheme that is being tracked by NBXplorer.
Metadata for this derivation scheme after this call:
Mnemonic
: The mnemonic generated. (ifsavePrivateKeys
istrue
)MasterHDKey
: The xpriv (opens new window) master key generated by the mnemonic and passphrase. (ifsavePrivateKeys
istrue
)AccountHDKey
: The derived xpriv (opens new window) account key from theMasterHDKey
andAccountKeyPath
. (ifsavePrivateKeys
istrue
)AccountKeyPath
: The fingerprint of the master key as defined by The BIP174 (opens new window), followed by the derivation path used to generate thederivationScheme
. (Purpose field (opens new window) based on BIP44 (opens new window), BIP49 (opens new window) or BIP84 (opens new window) and SLIP44 (opens new window) for the coin type)ImportAddressToRPC
:Legacy
(orTrue
, for old wallet) if the generated addresses are added to legacy style Bitcoin core wallet.Descriptors
orDescriptorsReadOnly
if the generated addresses and private keys are added to a descriptor enabled Bitcoin Core wallet.AccountDescriptor
: The output descriptor format of the derivation scheme.Birthdate
: The birthdate of the wallet in ISO-8601 format.
Note that the metadata AccountKeyPath
is leveraged by Create a PSBT and Update a PSBT.
# Node RPC Proxy
NBXplorer allows you to query the node's JSON-RPC through it when exposerpc
option is enabled
HTTP POST v1/cryptos/{cryptoCode}/rpc
with Header Content-Type
set to value application/json
or application/json-rpc
Error codes:
- HTTP 415: You did not send the correct
Content-Type
header. - HTTP 404:
cryptoCode-not-supported
- HTTP 401:
json-rpc-not-exposed
- HTTP 400:
rpc-unavailable
- HTTP 422:
no-json-rpc-request
Request:
{"jsonrpc": "1.0", "id":"1", "method": "getblockchaininfo", "params": [] }
Response:
{
"error": null,
"result": {
"chain": "regtest",
...
},
"resultString": "..."
}
NOTE: Batch commands are also supported by sending the JSON-RPC requests in an array. The result is also returned in an array.
# Health check
A endpoint that can be used without the need for authentication which will returns HTTP 200 only if all nodes connected to NBXplorer are ready.
HTTP GET /health
It will output the state for each nodes in JSON, whose format might change in the future.
# Liquid integration
NBXplorer supports liquid, the API is the same as all the other coins, except for the following:
- All references to
value
which normally contains an integer of the amount of the altcoin will instead output a JSON Object of typeAssetMoney
. - If NBXplorer is unable to unblind a value, then the value will be
null
. - When listing the transaction of a derivation scheme, the
balanceChange
elements is instead aJSON array of AssetMoney
. - Get Balance returns values as
JSON array of AssetMoney
. - Get a new unused address returns a confidential address. (See note below)
- Create Partially Signed Bitcoin Transaction is not supported.
- Update Partially Signed Bitcoin Transaction is not supported
- Scan UTXO Set is not supported.
- Any sort of recovery is not supported.
The AssetMoney
JSON format is:
{
"assetId": "abc",
"value": 123
}
# Liquid Confidential Addresses
Liquid confidential addresses are supported in two ways:
- By default, the blinding key of the confidential address is derived directly from the
derivationScheme
. If thescriptPubKey
0/2
is generated, the blinding private key used by NBXplorer is the SHA256 of the scriptPubKey at0/2/0
. - SLIP77 (opens new window), by suffixing the derivation scheme with either:
- the mnemonic seed derivation (usually the same as your wallet's)
-[slip77=all all all all all all all all all all all all]
- the master blinding key in hex or wif format
-[slip77=6c2de18eabeff3f7822bc724ad482bef0557f3e1c1e1c75b7a393a5ced4de616]
You may also choose to not use confidential addresses by applying the suffix-[unblinded]
to the derivation scheme
- the mnemonic seed derivation (usually the same as your wallet's)
# Liquid Transactions support
Due to the changes in the transaction format in Elements networks to support assets, we do not support transaction building features.
In order to send in and out of liquid, we advise you to rely on the RPC command line interface of the liquid deamon.
For doing this you need to Generate a wallet with importAddressToRPC
and savePrivateKeys
set to true
.
Be careful to not expose your NBXplorer server on internet, your private keys can be retrieved trivially.
# Groups
# Create group
Create a new empty group.
HTTP POST v1/groups
No body required
Response
{
"trackedSource": "GROUP:6N23bHztah546P6xQT",
"groupId": "6N23bHztah546P6xQT",
"children": []
}
# Get group
HTTP GET v1/groups/{groupId}
Get the group
{
"trackedSource": "GROUP:6N23bHztah546P6xQT",
"groupId": "6N23bHztah546P6xQT",
"children": [
{
"trackedSource": "GROUP:Es26NSg5xTqbpRz3FY"
},
{
"cryptoCode": "BTC",
"trackedSource": "DERIVATIONSCHEME:tpubDC6xFicnheK85vUNGjegu4HuJGg8nPiRk26jhW7n8GTCnb2aqizTFzyG1Jw42ZUs19nKU8V3Xi38WyVqem5ytbjFsREMWUH8QMYpzgmNdus"
},
{
"cryptoCode": "BTC",
"trackedSource": "DERIVATIONSCHEME:tpubDC45vUDsFAAqwYKz5hSLi5yJLNduJzpmTw6QTMRPrwdXURoyL81H8oZAaL8EiwEgg92qgMa9h1bB4Y1BZpy9CTNPfjfxvFcWxeiKBHCqSdc"
}
]
}
# Add group children
Add children to a group.
HTTP POST v1/groups/{groupId}/children
Request:
[
{
"trackedSource": "GROUP:Es26NSg5xTqbpRz3FY"
},
{
"cryptoCode": "BTC",
"trackedSource": "DERIVATIONSCHEME:tpubDC6xFicnheK85vUNGjegu4HuJGg8nPiRk26jhW7n8GTCnb2aqizTFzyG1Jw42ZUs19nKU8V3Xi38WyVqem5ytbjFsREMWUH8QMYpzgmNdus"
},
{
"cryptoCode": "BTC",
"trackedSource": "DERIVATIONSCHEME:tpubDC45vUDsFAAqwYKz5hSLi5yJLNduJzpmTw6QTMRPrwdXURoyL81H8oZAaL8EiwEgg92qgMa9h1bB4Y1BZpy9CTNPfjfxvFcWxeiKBHCqSdc"
}
]
Response:
{
"trackedSource": "GROUP:6N23bHztah546P6xQT",
"groupId": "6N23bHztah546P6xQT",
"children": [
{
"trackedSource": "GROUP:Es26NSg5xTqbpRz3FY"
},
{
"cryptoCode": "BTC",
"trackedSource": "DERIVATIONSCHEME:tpubDC6xFicnheK85vUNGjegu4HuJGg8nPiRk26jhW7n8GTCnb2aqizTFzyG1Jw42ZUs19nKU8V3Xi38WyVqem5ytbjFsREMWUH8QMYpzgmNdus"
},
{
"cryptoCode": "BTC",
"trackedSource": "DERIVATIONSCHEME:tpubDC45vUDsFAAqwYKz5hSLi5yJLNduJzpmTw6QTMRPrwdXURoyL81H8oZAaL8EiwEgg92qgMa9h1bB4Y1BZpy9CTNPfjfxvFcWxeiKBHCqSdc"
}
]
}
# Delete group children
Remove children from a group.
HTTP DELETE v1/groups/{groupId}/children
Request:
[
{
"trackedSource": "GROUP:Es26NSg5xTqbpRz3FY"
},
{
"cryptoCode": "BTC",
"trackedSource": "DERIVATIONSCHEME:tpubDC6xFicnheK85vUNGjegu4HuJGg8nPiRk26jhW7n8GTCnb2aqizTFzyG1Jw42ZUs19nKU8V3Xi38WyVqem5ytbjFsREMWUH8QMYpzgmNdus"
},
{
"cryptoCode": "BTC",
"trackedSource": "DERIVATIONSCHEME:tpubDC45vUDsFAAqwYKz5hSLi5yJLNduJzpmTw6QTMRPrwdXURoyL81H8oZAaL8EiwEgg92qgMa9h1bB4Y1BZpy9CTNPfjfxvFcWxeiKBHCqSdc"
}
]
Response:
{
"trackedSource": "GROUP:6N23bHztah546P6xQT",
"groupId": "6N23bHztah546P6xQT",
"children": []
}
# Add address to group
You can add addresses manually inside the group.
HTTP POST v1/cryptos/BTC/groups/{groupId}/addresses
Request:
[
"n3XyBWEKWLxm5EzrrvLCJyCQrRhVWQ8YGa",
"n4FBNYjZny7sC4pzAVaTtnGTtiwMHV5nkY",
"mxrkNvovmmatB2vHVkNtVZ7dLLuDkPe5nr",
"mh43vYeeJAzzSXBPaQ3D9qXzLFwWhmZEGw",
"mkNfpqBrKyHs5wTsreLLhWAwnZPPH6seqe",
"n4nzmHnKsByo5pgdjVDuvbXMMY7gKAcZJy",
"mrxCU6b7RmyNXz1WJ4uJRZfdKSnwzagRov",
"msy6dEmKav8CpDX6TR8wsLPVFUoy4HDk2t",
"mw84oRAoojVPxHm9J514KTqpr6ozVFcWtH",
"muNtSq7tG3gBwh2L1ZHEKQRYuNuHPm5YZC"
]
Response: HTTP 200.