Node API Documentation

Table of Contents

  1. Blocks Endpoint
    1. GET Blocks
  2. Headers Endpoint
    1. GET Headers
  3. Chain Endpoint
    1. GET Chain
    2. POST Chain Compact
    3. GET Chain Validate
    4. GET Chain Kernel by Commitment
    5. GET Chain Outputs by IDs
    6. GET Chain Outputs by Height
  4. Status Endpoint
    1. GET Status
  5. TxHashSet Endpoint
    1. GET TxHashSet Roots
    2. GET TxHashSet Last Outputs
    3. GET TxHashSet Last Range Proofs
    4. GET TxHashSet Last Kernels
    5. GET TxHashSet Outputs
    6. GET TxHashSet Merkle Proof
  6. Pool Endpoint
    1. GET Pool
    2. POST Pool Push
  7. Peers Endpoint
    1. POST Peers Ban
    2. POST Peers Unban
    3. GET Peers All
    4. GET Peers Connected
    5. GET Peers

Blocks Endpoint

GET Blocks

Returns data about a specific block given a hash, a height or an unspent commit.

Optionally, Merkle proofs can be excluded from the results by adding ?no_merkle_proof, rangeproofs can be included by adding ?include_proof or results can be returned as "compact blocks" by adding ?compact.

  • URL

    • /v1/blocks/hash
    • /v1/blocks/height
    • /v1/blocks/commit
  • Method:

    GET

  • URL Params

    Required: hash=[string] or height=[number] or commit=[string]

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:
    Field Type Description
    header object The block header
    - hash string Hash of the current block
    - version number Version of the block
    - height number Height of this block since the genesis block (height 0)
    - previous string Hash of the block previous to this in the chain
    - prev_root string Root hash of the header MMR at the previous header
    - timestamp string RFC3339 timestamp at which the block was built
    - output_root string Merklish root of all the commitments in the TxHashSet
    - range_proof_root string Merklish root of all range proofs in the TxHashSet
    - kernel_root string Merklish root of all transaction kernels in the TxHashSet
    - nonce number Nonce increment used to mine this block
    - edge_bits number Size of the cuckoo graph (2_log of number of edges)
    - cuckoo_solution []number The Cuckoo solution for this block
    - total_difficulty number Total accumulated difficulty since genesis block
    - secondary_scaling number Variable difficulty scaling factor for secondary proof of work
    - total_kernel_offset string Total kernel offset since genesis block
    inputs []string Input transactions
    outputs []object Outputs transactions
    - output_type string The type of output Coinbase
    - commit string The homomorphic commitment representing the output's amount (as hex string)
    - spent bool Whether the output has been spent
    - proof string Rangeproof (as hex string)
    - proof_hash string Rangeproof hash (as hex string)
    - block_height number Block height at which the output is found
    - merkle_proof string Merkle proof
    kernels []object Transaction Kernels (a proof that a transaction sums to zero)
    - features object Options for a kernel's structure or use
    - bits number Representation of the features in bits
    - fee number Fee originally included in the transaction this proof is for
    - lock_height number The max lock_height of all inputs to this transaction
    - excess []number Remainder of the sum of all transaction commitments
    - excess_sig []number The signature proving the excess is a valid public key (signs the tx fee)
  • Error Response:

    • Code: 404 or 500
    • Content: failed to parse input: Not found.
  • Sample Call:

    $.ajax({
      url: "/v1/blocks/1",
      dataType: "json",
      type : "GET",
      success : function(r) {
        console.log(r);
      }
    });

Headers Endpoint

GET Headers

Returns data about a block headers given either a hash or height or an output commit.

  • URL

    • /v1/headers/hash
    • /v1/headers/height
    • /v1/headers/commit
  • Method:

    GET

  • URL Params

    Required: hash=[string] or height=[number] or commit=[string]

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:
    Field Type Description
    header object The block header
    - hash string Hash of the current block
    - version number Version of the block
    - height number Height of this block since the genesis block (height 0)
    - previous string Hash of the block previous to this in the chain
    - prev_root string Root hash of the header MMR at the previous header
    - timestamp string RFC3339 timestamp at which the block was built
    - output_root string Merklish root of all the commitments in the TxHashSet
    - range_proof_root string Merklish root of all range proofs in the TxHashSet
    - kernel_root string Merklish root of all transaction kernels in the TxHashSet
    - nonce number Nonce increment used to mine this block
    - edge_bits number Size of the cuckoo graph (2_log of number of edges)
    - cuckoo_solution []number The Cuckoo solution for this block
    - total_difficulty number Total accumulated difficulty since genesis block
    - total_kernel_offset string Total kernel offset since genesis block
  • Error Response:

    • Code: 404 or 500
    • Content: failed to parse input: Not found.
  • Sample Call:

    $.ajax({
      url: "/v1/headers/1",
      dataType: "json",
      type : "GET",
      success : function(r) {
        console.log(r);
      }
    });

Chain Endpoint

GET Chain

Retrieves details about the state of the current fork tip.

  • URL

    /v1/chain

  • Method:

    GET

  • URL Params

    None

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:
    Field Type Description
    height number Height of the tip (max height of the fork)
    last_block_pushed string Last block pushed to the fork
    prev_block_to_last string Block previous to last
    total_difficulty number Total difficulty accumulated on that fork since genesis block
  • Error Response:

    • Code: 404 or 500
    • Content: failed to parse input: Not found.
  • Sample Call:

    $.ajax({
      url: "/v1/chain",
      dataType: "json",
      type : "GET",
      success : function(r) {
        console.log(r);
      }
    });

POST Chain Compact

Trigger a compaction of the chain state to regain storage space.

  • URL

    /v1/chain/compact

  • Method:

    POST

  • URL Params

    None

  • Data Params

    None

  • Success Response:

    • Code: 200
  • Error Response:

    • Code: 500
  • Sample Call:

    $.ajax({
      url: "/v1/chain/compact",
      dataType: "json",
      type : "POST",
      success : function(r) {
        console.log(r);
      }
    });

GET Chain Validate

Trigger a validation of the chain state.

  • URL

    /v1/chain/validate

  • Method:

    GET

  • URL Params

    None

  • Data Params

    None

  • Success Response:

    • Code: 200
  • Error Response:

    • Code: 500
  • Sample Call:

    $.ajax({
      url: "/v1/chain/validate",
      dataType: "json",
      type : "GET",
      success : function(r) {
        console.log(r);
      }
    });

GET Chain Kernel By Commitment

Look up an on-chain kernel and the height of the block it is included in. By default min_height is 0.

  • URL

    • /v1/chain/kernels/xxx?min_height=yyy&max_height=zzz
  • Method:

    GET

  • URL Params

    Required: commitment=[string]

    Optional: min_height=[number] max_height=[number]

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:
    Field Type Description
    tx_kernel object Transaction Kernel
    - features object The type of output Coinbase
    - features object The kernel features. Can either be Plain, Coinbase or HeightLocked.
    - excess string The kernel excess also called commitment
    - excess_sig string The excess signature
    height string THe height of the block this kernel is included in
    mmr_height string Position in the MMR
  • Error Response:

    • Code: 404 or 500
    • Content: []
  • Sample Call:

    $.ajax({
      url: "/v1/chain/kernels/0939fe3dc6a35350da91c6288138b7a257e0c0322eae30bda3938229d649e2e642?max_height=324300",
      dataType: "json",
      type : "GET",
      success : function(r) {
        console.log(r);
      }
    });

GET Chain Outputs By IDs

Retrieves details about specifics outputs. Supports retrieval of multiple outputs in a single request.

  • URL

    • /v1/chain/outputs/byids?id=x
    • /v1/chain/outputs/byids?id=x,y,z
    • /v1/chain/outputs/byids?id=x&id=y&id=z
  • Method:

    GET

  • URL Params

    Required: id=[string]

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:
    Field Type Description
    outputs []object Outputs
    - output_type string The type of output Coinbase
    - commit string The homomorphic commitment representing the output's amount (as hex string)
    - spent bool Whether the output has been spent
    - proof string Rangeproof (as hex string)
    - proof_hash string Rangeproof hash (as hex string)
    - block_height number Block height at which the output is found
    - merkle_proof string Merkle proof
  • Error Response:

    • Code: 404 or 500
    • Content: []
  • Sample Call:

    $.ajax({
      url: "/v1/chain/outputs/byids?id=0803516094a30830ed9fedff1c63251b51703ddffbb73f944d9e33e8fa5d17444f",
      dataType: "json",
      type : "GET",
      success : function(r) {
        console.log(r);
      }
    });

GET Chain Outputs By Height

Retrieves details about specifics outputs. Supports retrieval of multiple outputs in a single request.

  • URL

    /v1/chain/outputs/byheight?start_height=x&end_height=y

  • Method:

    GET

  • URL Params

    Required: start_height=[number] end_height=[number]

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:
    Field Type Description
    header object The block header
    - hash string Hash of the current block
    - height number Height of this block since the genesis block (height 0)
    - previous string Hash of the block previous to this in the chain
    outputs []object Outputs
    - output_type string The type of output Coinbase
    - commit string The homomorphic commitment representing the output's amount (as hex string)
    - spent bool Whether the output has been spent
    - proof string Rangeproof (as hex string)
    - proof_hash string Rangeproof hash (as hex string)
    - block_height number Block height at which the output is found
    - merkle_proof string Merkle proof
  • Error Response:

    • Code: 404 or 500
    • Content: []
  • Sample Call:

    $.ajax({
      url: "/v1/chain/outputs/byheight?start_height=101&end_height=200",
      dataType: "json",
      type : "GET",
      success : function(r) {
        console.log(r);
      }
    });

Status Endpoint

GET Status

Returns various information about the node and the network

  • URL

    /v1/status

  • Method:

    GET

  • URL Params

    None

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:
    Field Type Description
    protocol_version number The node protocol version
    user_agent number The node user agent
    connections number The current number of connections
    tip object The state of the current fork tip
    height number Height of the tip (max height of the fork)
    last_block_pushed string Last block pushed to the fork
    prev_block_to_last string Block previous to last
    total_difficulty number Total difficulty accumulated on that fork since genesis block
    sync_status string The current sync status
    sync_info object Additional sync information. This field is optional.
  • Error Response:

    • Code: 404 or 500
    • Content: failed to parse input: Not found.
  • Sample Call:

    $.ajax({
      url: "/v1/stats",
      dataType: "json",
      type : "GET",
      success : function(r) {
        console.log(r);
      }
    });

TxHashSet Endpoint

GET TxHashSet Roots

Retrieve the roots of the TxHashSet

  • URL

    /v1/txhashset/roots

  • Method:

    GET

  • URL Params

    None

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:
    Field Type Description
    output_root_hash string Output root hash
    range_proof_root_hash string Rangeproof root hash
    kernel_root_hash string Kernel set root hash
  • Error Response:

    • Code: 500
  • Sample Call:

    $.ajax({
      url: "/v1/txhashset/roots",
      dataType: "json",
      type : "GET",
      success : function(r) {
        console.log(r);
      }
    });

GET TxHashSet Last Outputs

Retrieves the last n outputs inserted into the tree.

  • URL

    • /v1/txhashset/lastoutputs (gets last 10)
    • /v1/txhashset/lastoutputs?n=x
  • Method:

    GET

  • URL Params

    Required: n=[number]

  • Data Params

    None

  • Success Response:

    • Code: 200
    • Content:

    Array of

    Field Type Description
    hash string hash of the outputs
  • Error Response:

    • Code: 500
  • Sample Call:

    $.ajax({
      url: "/v1/txhashset/lastoutputs?n=20",
      dataType: "json",
      type : "GET",
      success : function(r) {
        console.log(r);
      }
    });

GET TxHashSet Last Range Proofs

Retrieves the last n rangeproofs inserted in to the tree.

  • URL

    • /v1/txhashset/lastrangeproofs (gets last 10)
    • /v1/txhashset/lastrangeproofs?n=x
  • Method:

    GET

  • URL Params

    Required: n=[number]

  • Data Params

    None

  • Success Response:

    • Code: 200
    • Content:

    Array of

    Field Type Description
    hash string hash of the rangeproofs
  • Error Response:

    • Code: 500
  • Sample Call:

    $.ajax({
      url: "v1/txhashset/lastrangeproofs",
      dataType: "json",
      type : "GET",
      success : function(r) {
        console.log(r);
      }
    });

GET TxHashSet Last Kernels

Retrieves the last n kernels inserted in to the tree.

  • URL

    • /v1/txhashset/lastkernels (gets last 10)
    • /v1/txhashset/lastkernels?n=x
  • Method:

    GET

  • URL Params

    Required: n=[number]

  • Data Params

    None

  • Success Response:

    • Code: 200
    • Content:

    Array of

    Field Type Description
    hash string hash of the kernels
  • Error Response:

    • Code: 500
  • Sample Call:

    $.ajax({
      url: "/v1/txhashset/lastkernels?n=20",
      dataType: "json",
      type : "GET",
      success : function(r) {
        console.log(r);
      }
    });

GET TxHashSet Outputs

UTXO traversal. Retrieves last utxos since a start index until a max.

  • URL

    /v1/txhashset/outputs?start_index=x&max=y

  • Method:

    GET

  • URL Params

    Required: start_index=[number] max=[number]

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:
    Field Type Description
    highest_index number The last available output index
    last_retrieved_index number The last insertion index retrieved
    outputs []object Outputs
    - output_type string The type of output Coinbase
    - commit string The homomorphic commitment representing the output's amount (as hex string)
    - spent bool Whether the output has been spent
    - proof string Rangeproof (as hex string)
    - proof_hash string Rangeproof hash (as hex string)
    - block_height number Block height at which the output is found
    - merkle_proof string Merkle proof
    kernels []object Transaction Kernels (a proof that a transaction sums to zero)
    - features object Options for a kernel's structure or use
    - bits number Representation of the features in bits
    - fee number Fee originally included in the transaction this proof is for
    - lock_height number The max lock_height of all inputs to this transaction
    - excess []number Remainder of the sum of all transaction commitments
    - excess_sig []number The signature proving the excess is a valid public key (signs the tx fee)
  • Error Response:

    • Code: 500
  • Sample Call:

    $.ajax({
      url: "/v1/txhashset/outputs?start_index=1&max=100",
      dataType: "json",
      type : "GET",
      success : function(r) {
        console.log(r);
      }
    });

GET TxHashSet Merkle Proof

Build a merkle proof for a given output id and return a dummy output with merkle proof for position filled out.

  • URL

    /v1/txhashset/merkleproof?id=x

  • Method:

    GET

  • URL Params

    Required: id=[string]

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:
    Field Type Description
    outputs []object Outputs
    - output_type string The type of output Coinbase
    - commit string The homomorphic commitment representing the output's amount (as hex string)
    - spent bool Whether the output has been spent
    - proof string Rangeproof (as hex string)
    - proof_hash string Rangeproof hash (as hex string)
    - block_height number Block height at which the output is found
    - merkle_proof string Merkle proof
  • Error Response:

    • Code: 404 or 500
  • Sample Call:

    $.ajax({
      url: "/v1/txhashset/merkleproof?id=0803516094a30830ed9fedff1c63251b51703ddffbb73f944d9e33e8fa5d17444f",
      dataType: "json",
      type : "GET",
      success : function(r) {
        console.log(r);
      }
    });

Pool Endpoint

GET Pool

Retrieves basic information about the transaction pool.

  • URL

    /v1/pool

  • Method:

    GET

  • URL Params

    None

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:
    Field Type Description
    pool_size number Number of transactions in the memory pool
  • Error Response:

    • Code: 500
  • Sample Call:

    $.ajax({
      url: "/v1/pool",
      dataType: "json",
      type : "GET",
      success : function(r) {
        console.log(r);
      }
    });

POST Pool Push

Push new transaction to our local transaction pool. Add ?fluff at the end of the URL to bypass Dandelion relay.

  • URL

    /v1/pool/push

  • Method:

    POST

  • URL Params

    None

  • Data Params

    file=[string] (hex encoded transaction)

  • Success Response:

    • Code: 200
  • Error Response:

    • Code: 500
  • Sample Call:

    $.ajax({
      url: "/v1/pool/push",
      dataType: "json",
      type : "POST",
      data: {
        file: tx
      },
      success : function(r) {
        console.log(r);
      }
    });

Peers Endpoint

POST Peers Ban

Ban a specific peer.

  • URL

    /v1/peers/a.b.c.d:p/ban

  • Method:

    POST

  • URL Params

    a.b.c.d:p=[string]

  • Data Params

    None

  • Success Response:

    • Code: 200
  • Error Response:

    • Code: 400
  • Sample Call:

    $.ajax({
      url: "/v1/peers/192.168.1.1:17414/ban",
      dataType: "json",
      type : "POST",
      success : function(r) {
        console.log(r);
      }
    });

POST Peers Unban

Unban a specific peer.

  • URL

    /v1/a.b.c.d:p/unban

  • Method:

    POST

  • URL Params

    a.b.c.d:p=[string]

  • Data Params

    None

  • Success Response:

    • Code: 200
  • Error Response:

    • Code: 400
  • Sample Call:

    $.ajax({
      url: "/v1/192.168.1.1:17414/unban",
      dataType: "json",
      type : "POST",
      success : function(r) {
        console.log(r);
      }
    });

GET Peers All

Retrieves all peers in db.

  • URL

    /v1/peers/all

  • Method:

    GET

  • URL Params

    None

  • Data Params

    None

  • Success Response:

    • Code: 200
    • Content:

    Array of

    Field Type Description
    addr string Network address of the peer
    capabilities object What capabilities the peer advertises
    - bits number Representation of the capabilities in bits
    user_agent string The peer user agent
    flags string State the peer has been detected with.
    last_banned number The time the peer was last banned
    ban_reason string The reason for the ban
  • Error Response:

    • Code: 500
  • Sample Call:

    $.ajax({
      url: "/v1/peers/all",
      dataType: "json",
      type : "GET",
      success : function(r) {
        console.log(r);
      }
    });

GET Peers Connected

Retrieves all connected peers

  • URL

    /v1/peers/connected

  • Method:

    GET

  • URL Params

    None

  • Data Params

    None

  • Success Response:

    • Code: 200
    • Content:

    Array of

    Field Type Description
    capabilities object What capabilities the peer advertises
    - bits number Representation of the capabilities in bits
    user_agent string The peer user agent
    version number Software version of the peer
    addr string Network address of the peer
    total_difficulty number Total of difficulty of the peer
    height number Height of the peer
    direction string Direction of the connection (Inbound
  • Error Response:

    • Code: 500
  • Sample Call:

    $.ajax({
      url: "/v1/peers/connected",
      dataType: "json",
      type : "GET",
      success : function(r) {
        console.log(r);
      }
    });

GET Peers

Retrieves information about a specific peer.

  • URL

    /v1/peers/a.b.c.d

  • Method:

    GET

  • URL Params

    a.b.c.d=[string]

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:
    Field Type Description
    addr string Network address of the peer
    capabilities object What capabilities the peer advertises
    - bits number Representation of the capabilities in bits
    user_agent string The peer user agent
    flags string State the peer has been detected with.
    last_banned number The time the peer was last banned
    ban_reason string The reason for the ban
  • Error Response:

    • Code: 404 or 500
  • Sample Call:

    $.ajax({
      url: "/v1/peers/192.168.1.2",
      dataType: "json",
      type : "GET",
      success : function(r) {
        console.log(r);
      }
    });