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
- Derivation schemes
- Groups
- Addresses
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. If true 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: Use Deposit to get a deposit address (0/x), Change to get a change address (1/x), Direct to get x or Custom if customKeyPathTemplate 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: If true, 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 if testMempoolAccept is true, 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 started
Pending the scan is in progress
Complete the scan is successful
Error 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 since lastEventId, 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 (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 the substractFee=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, if disableFingerprintRandomization is true)
timeLock: Optional, The timelock of the transaction, activate RBF if not null (default: 0, if disableFingerprintRandomization is true)
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, if disableFingerprintRandomization is true)
reserveChangeAddress: default to false, whether the creation of this PSBT will reserve a new change address.
spendAllMatchingOutpoints: If true, 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 money
destinations[].destination: Required, the destination address
destinations[].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 that fee-estimation-unavailable is never sent. (Mutually exclusive with: explicitFeeRate, explicitFee)
discourageFeeSniping: If timeLock is not set, set the timeLock to a random value to discourage fee sniping (default to true, if disableFingerprintRandomization is true)
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 rebase
rebaseKeyPaths[].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 are version, timeLock, rbf, discourageFeeSniping)
alwaysIncludeNonWitnessUTXO: Try to set the full transaction in non_witness_utxo, even for segwit inputs (default to false)
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 if disableFingerprintRandomization is set to false)
suggestions.shouldEnforceLowR: If true, 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 rebase
rebaseKeyPaths[].accountKeyPath: The path from the root to the account key prefixed by the master public key fingerprint.
alwaysIncludeNonWitnessUTXO: Try to set the full transaction in non_witness_utxo, even for segwit inputs (default to false)

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 réussir louve alliage péplum innocent filmer stipuler chignon utopie effusion heureux lé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, see accountKeyPath in the response. (Default: 0)
existingMnemonic: Optional, an existing BIP39 mnemonic seed to import instead of generating.
wordList: Optional, the BIP39 wordlist to use when generating the mnemonic, available: English, French, Japanese, Spanish, ChineseSimplified (Defaut: English)
wordCount: Optional, the BIP39 word count in the mnemonic (Default: 12)
scriptPubKeyType: Optional, the type of scriptPubKey (address) to generate, available: Legacy, Segwit, SegwitP2SH, Taproot (Default: Segwit or Legacy if cryptoCode does not support segwit)
passphrase: Optional, the BIP39 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's importprivkey. (Default: false)
savePrivateKeys: If true, private keys will be saved inside the following metadata Mnemonic, MasterHDKey and AccountHDKey.
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 réussir louve alliage péplum innocent filmer stipuler chignon utopie effusion heureux lé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 mnemonic.
passphrase: The BIP39 passphrase.
wordList: The BIP39 wordlist to use when generating the mnemonic.
wordCount: The BIP39 word count in the mnemonic.
masterHDKey: The BIP32 master key derived from the mnemonic and passphrase.
accountHDKey: The BIP32 account key derived from the masterHDKey and accountKeyPath.
accountKeyPath: The fingerprint of the master key as defined by The BIP174, followed by the derivation path used to generate the derivationScheme. (Purpose field based on BIP44, BIP49 or BIP84 and SLIP44 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. (if savePrivateKeys is true)
MasterHDKey: The xpriv master key generated by the mnemonic and passphrase. (if savePrivateKeys is true)
AccountHDKey: The derived xpriv account key from the MasterHDKey and AccountKeyPath. (if savePrivateKeys is true)
AccountKeyPath: The fingerprint of the master key as defined by The BIP174, followed by the derivation path used to generate the derivationScheme. (Purpose field based on BIP44, BIP49 or BIP84 and SLIP44 for the coin type)
ImportAddressToRPC: Legacy (or True, for old wallet) if the generated addresses are added to legacy style Bitcoin core wallet. Descriptors or DescriptorsReadOnly 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 type AssetMoney.
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 a JSON 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 the scriptPubKey 0/2 is generated, the blinding private key used by NBXplorer is the SHA256 of the scriptPubKey at 0/2/0.
SLIP77, 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

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.

Files

API.md

Latest commit

History

API.md

File metadata and controls

API Specification

Table of content

Configuration

Tracked Sources

Derivation scheme

Groups

Addresses

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

Get scan status

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

Liquid Confidential Addresses

Liquid Transactions support

Groups

Create group

Get group

Add group children

Delete group children

Add address to group