Get XPUB or descriptor account details.

GET

https://xvg-blockbook.nownodes.io/api/v2/xpub/{xpub}

Authorizations

ApiKeyAuthApiKeyAuth

api-key string

NOWNodes API key passed in the api-key header.

Modified in 0.6.0: extreme page/pageSize values are validated, xpub change-list expansion is bounded, and the in-memory xpub cache is capped with LRU eviction. Documented as it exists in 0.6.0.

Returns balances and transactions of an XPUB or output descriptor for Bitcoin-type coins. Transactions are sorted by block height with newest blocks first. URL-encode descriptors before placing them after /xpub/.

Blockbook expects XPUBs at level 3 of the derivation path, for example m/purpose'/coin_type'/account'. It derives the remaining change/address_index path. The BIP scheme is inferred from the XPUB prefix; unknown prefixes default to BIP44.

Supported descriptors are pkh(xpub), sh(wpkh(xpub)), wpkh(xpub), and tr(xpub). Descriptors can include origin paths and change selectors such as <0;1> or {0,1}; when change is omitted, Blockbook defaults to <0;1>.

Note: usedTokens always reports the total number of used addresses for the XPUB, regardless of the tokens query filter.

Load estimate: High for broad accounts; grows with derived addresses, gap, used address count, pageSize, transaction history, token rows, and protocol enrichment.

live-verified behavior:

Live: an invalid XPUB on the deployed instance answers HTTP 500 {"error":"Internal server error"}.

Parameters

xpubstringrequiredpath

Extended public key or output descriptor to query in Blockbook.

pageinteger<int32>>= 11query

Page number of the returned transaction list. Pagination starts from 1.

pageSizeinteger<int32>[1, 1000]1000query

Maximum number of transactions returned on one page.

frominteger<int64>>= 0query

Start block height filter for transactions, inclusive.

tointeger<int64>>= 0query

End block height filter for transactions, inclusive.

detailsstringbasictokenstokenBalancestxidstxslighttxstxidsquery

Controls how much transaction or token detail is included in the response. Supported values: basic, tokens, tokenBalances, txids, txslight, txs.

tokensstringnonzerousedderivednonzeroquery

Controls which XPUB-derived address rows are included.

filterstring | integerquery

Filter by input/output side or numeric id.

contractstringquery

Contract address filter.

protocolsArray<string>query

Protocol enrichments.

secondarystringquery

Secondary currency code.

gapinteger[0, 10000]query

XPUB/address derivation gap limit.

Response

200OK

HTTP 200 Verge Blockbook response for getXpub.

400Bad Request

Domain or validation error. live-verified: JSON body {"error": "..."} (unknown block/transaction, invalid address, malformed broadcast hex, missing filter parameters).

401Unauthorized

Unauthorized: missing or invalid api-key header. The NOWNodes gateway returns the plain-text body "Unknown API_key".

405Method Not Allowed

Method Not Allowed: gateway-level response for unknown routes (and for the v1 GET broadcast route on this instance).

500Internal Server Error

Internal Server Error. live-verified on the deployed instance: JSON body {"error":"Internal server error"} (observed on /api/rawtx and invalid XPUB lookups).

Get XPUB or descriptor account details.

curl -X GET 'https://xvg-blockbook.nownodes.io/api/v2/xpub/{xpub}'

const response = await fetch('https://xvg-blockbook.nownodes.io/api/v2/xpub/{xpub}', {
  method: 'GET',
});

const data = await response.json();

require 'net/http'
require 'json'

uri = URI('https://xvg-blockbook.nownodes.io/api/v2/xpub/{xpub}')
request = Net::HTTP::Get.new(uri)

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
data = JSON.parse(response.body)

import requests

response = requests.get('https://xvg-blockbook.nownodes.io/api/v2/xpub/{xpub}')
data = response.json()

const response = await fetch('https://xvg-blockbook.nownodes.io/api/v2/xpub/{xpub}', {
  method: 'GET',
});

const data = await response.json();

const endpoint = "https://xvg-blockbook.nownodes.io/api/v2/xpub/{xpub}";
const apiKey = "YOUR_API_KEY";

async function nownodesRequest(payload) {
  const response = await fetch(endpoint, {
    method: "GET",
    headers: {
      "Content-Type": "application/json",
      "api-key": apiKey,
    },
    body: JSON.stringify(payload),
  });

  return response.json();
}

const result = await nownodesRequest({});
console.log(result);

const response = await fetch('https://xvg-blockbook.nownodes.io/api/v2/xpub/{xpub}', {
  method: 'GET',
});

const data = await response.json();

import requests

response = requests.get('https://xvg-blockbook.nownodes.io/api/v2/xpub/{xpub}')
data = response.json()

require 'net/http'
require 'json'

uri = URI('https://xvg-blockbook.nownodes.io/api/v2/xpub/{xpub}')
request = Net::HTTP::Get.new(uri)

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
data = JSON.parse(response.body)

{
  "page": 1,
  "totalPages": 1,
  "itemsOnPage": 1000,
  "address": "dgub8sbe5Mi8LA4dXB9zPfLZW8arm...9Vjp2HHx91xdDEmWYpmD49fpoUYF",
  "balance": "0",
  "totalReceived": "0",
  "totalSent": "0",
  "unconfirmedBalance": "0",
  "unconfirmedTxs": 0,
  "txs": 0
}

{
  "error": "Internal server error"
}

{
  "error": "Internal server error"
}

Unknown API_key

Method Not Allowed

{
  "error": "Internal server error"
}