CHANGED METHODS

v4.0.7

Base URL

https://stacks.nownodes.ioNOWNodes Stacks RPC endpoint

Changes to existing RPC methods between stacks-node 4.0.5 and 4.0.7 (4.0.6 + 4.0.7). Newly added methods are not listed.

Summary:

GET /v3/sortitions - new response field canonical.
GET /v2/accounts/{principal} - documented PoX-5 semantics of locked and unlock_height; response format unchanged.
GET /v3/tenures/{block_id} - response size now leaves room for HTTP chunk framing (4.0.7 fix); response format unchanged.

Authentication

api-keyAuthapiKey

API Key: api-key in header

API CHANGES 4.0.5 > 4.0.7

Blocks

Fetch information about evaluated burnchain blocks (i.e., sortitions).

GET

https://stacks.nownodes.io/v3/sortitions/{lookup_kind}/{lookup}

Authorizations

ApiKeyAuthApiKeyAuth

api-key string

NOWNodes API key passed in the api-key header.

Changed in 4.0.6: every sortition object in the response now contains the canonical field.

canonical shows whether the sortition is on the node's canonical burnchain fork. false means a burnchain fork orphaned it, which voids everything the tenure it elected produced. Nodes older than 4.0.6 do not return the field; clients must treat its absence as "unknown", not as true or false.

Request parameters and all other response fields are unchanged.

Parameters

lookup_kindstringpath

One of consensus, burn_height, burn, latest_and_last. If not given, the most recent burn block processed is returned.

lookupstringpath

The value to use for the lookup if lookup_kind is consensus, burn_height, or burn

Response

200OK

Information for the burn block or, in the case of latest_and_last, multiple burn blocks

Fetch information about evaluated burnchain blocks (i.e., sortitions).

curl -X GET 'https://stacks.nownodes.io/v3/sortitions/{lookup_kind}/{lookup}'

const response = await fetch('https://stacks.nownodes.io/v3/sortitions/{lookup_kind}/{lookup}', {
  method: 'GET',
});

const data = await response.json();

require 'net/http'
require 'json'

uri = URI('https://stacks.nownodes.io/v3/sortitions/{lookup_kind}/{lookup}')
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://stacks.nownodes.io/v3/sortitions/{lookup_kind}/{lookup}')
data = response.json()

const response = await fetch('https://stacks.nownodes.io/v3/sortitions/{lookup_kind}/{lookup}', {
  method: 'GET',
});

const data = await response.json();

const endpoint = "https://stacks.nownodes.io/v3/sortitions/{lookup_kind}/{lookup}";
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://stacks.nownodes.io/v3/sortitions/{lookup_kind}/{lookup}', {
  method: 'GET',
});

const data = await response.json();

import requests

response = requests.get('https://stacks.nownodes.io/v3/sortitions/{lookup_kind}/{lookup}')
data = response.json()

require 'net/http'
require 'json'

uri = URI('https://stacks.nownodes.io/v3/sortitions/{lookup_kind}/{lookup}')
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)

200

[
  {
    "burn_block_hash": "0x046f54cd1924a5d80fc3b8186d0334b7521acae90f9e136e2bee680c720d0e83",
    "burn_block_height": 231,
    "burn_header_timestamp": 1726797570,
    "sortition_id": "0x8a5116b7b4306dc4f6db290d1adfff9e1347f3e921bb793fc4c33e2ff05056e2",
    "parent_sortition_id": "0xdaf479110cf859e58c56b6ae941f8a14e7c7992c57027183dfbda4a4b820897c",
    "consensus_hash": "0x8d2c51db737597a93191f49bcdc9c7bb44b90892",
    "was_sortition": true,
    "canonical": true,
    "miner_pk_hash160": "0x6bc51b33e9f3626944eb879147e18111581f8f9b",
    "stacks_parent_ch": "0x697357c72da55b759b1d6b721676c92c69f0b490",
    "last_sortition_ch": "0x697357c72da55b759b1d6b721676c92c69f0b490",
    "committed_block_hash": "0xeea47d6d639c565027110e192e308fb11656183d5c077bcd718d830652800183",
    "vrf_seed": "0x48b754acc291a5bfad1354ee19bbc471f14af2b21dc7eccc0f929bd16798defe"
  }
]

Fetch a sequence of Nakamoto blocks in a tenure

GET

https://stacks.nownodes.io/v3/tenures/{block_id}

Authorizations

ApiKeyAuthApiKeyAuth

api-key string

NOWNodes API key passed in the api-key header.

Changed in 4.0.7 (bug fix): a response could previously hold up to 16 MiB of blocks, but the receiving side counted HTTP chunk framing against the same limit and dropped the connection, so tenures larger than ~16 MiB could not be downloaded. The node now leaves room for chunk framing, so its responses can always be read in full.

Request parameters and the response format are unchanged.

Parameters

block_idstringrequiredpath

The tenure-start block ID of the tenure to query

Response

200OK

Nakamoto blocks of the tenure (binary)

Fetch a sequence of Nakamoto blocks in a tenure

curl -X GET 'https://stacks.nownodes.io/v3/tenures/{block_id}'

const response = await fetch('https://stacks.nownodes.io/v3/tenures/{block_id}', {
  method: 'GET',
});

const data = await response.json();

require 'net/http'
require 'json'

uri = URI('https://stacks.nownodes.io/v3/tenures/{block_id}')
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://stacks.nownodes.io/v3/tenures/{block_id}')
data = response.json()

const response = await fetch('https://stacks.nownodes.io/v3/tenures/{block_id}', {
  method: 'GET',
});

const data = await response.json();

const endpoint = "https://stacks.nownodes.io/v3/tenures/{block_id}";
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://stacks.nownodes.io/v3/tenures/{block_id}', {
  method: 'GET',
});

const data = await response.json();

import requests

response = requests.get('https://stacks.nownodes.io/v3/tenures/{block_id}')
data = response.json()

require 'net/http'
require 'json'

uri = URI('https://stacks.nownodes.io/v3/tenures/{block_id}')
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)

Accounts

Get account info

GET

https://stacks.nownodes.io/v2/accounts/{principal}

Authorizations

ApiKeyAuthApiKeyAuth

api-key string

NOWNodes API key passed in the api-key header.

Changed in 4.0.6 (documentation only): the meaning of balance, locked and unlock_height under PoX-5 is now documented. Request parameters and the response format are unchanged.

Under PoX-5, unstake keeps the amount locked and moves unlock_height to the first Bitcoin block of the next reward cycle. STX paired with a protocol bond stays locked until the bond ends. When the burn block height of the queried tip reaches unlock_height, the amount moves into balance with no transaction.

Parameters

principalstringrequiredpath

Stacks address or a Contract identifier (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info)

Response

200OK

Success

Get account info

curl -X GET 'https://stacks.nownodes.io/v2/accounts/{principal}'

const response = await fetch('https://stacks.nownodes.io/v2/accounts/{principal}', {
  method: 'GET',
});

const data = await response.json();

require 'net/http'
require 'json'

uri = URI('https://stacks.nownodes.io/v2/accounts/{principal}')
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://stacks.nownodes.io/v2/accounts/{principal}')
data = response.json()

const response = await fetch('https://stacks.nownodes.io/v2/accounts/{principal}', {
  method: 'GET',
});

const data = await response.json();

const endpoint = "https://stacks.nownodes.io/v2/accounts/{principal}";
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://stacks.nownodes.io/v2/accounts/{principal}', {
  method: 'GET',
});

const data = await response.json();

import requests

response = requests.get('https://stacks.nownodes.io/v2/accounts/{principal}')
data = response.json()

require 'net/http'
require 'json'

uri = URI('https://stacks.nownodes.io/v2/accounts/{principal}')
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)

200

{
  "balance": "string",
  "locked": "string",
  "unlock_height": 0
}