Node chain reads

Endpoint: http://127.0.0.1:3413/v2/foreign
Credential: No credential by default. Optional, see foreign_api_secret_path
Methods here: 11
Documented against: node 4.1.0, wallet 4.1.0

ready_for_txs

Read only

Whether the node has finished syncing and will accept transactions. New in node 4.1.0.

Surface: /v2/foreign on port 3413
Parameters: none
Declared in: api/src/foreign_rpc.rs:39

True only when the sync status is no_sync. Wallet 4.1.0 and later use it for their node readiness check (impls/src/node_clients/http.rs:264), and fall back to the owner get_status only when the node answers -32601, method not found, as a node older than 4.1.0 does.

This method takes no parameters.

6 lines

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "ready_for_txs",
  "params": []
}

Response3 lines

{
  "ready_for_txs": true
}

get_tip

Read only

Current height, the last block hash, and total difficulty per algorithm.

Surface: /v2/foreign on port 3413
Parameters: none
Declared in: api/src/foreign_rpc.rs:340

The cheapest way to poll for new blocks, with no credential. get_status is on the owner surface.

This method takes no parameters.

6 lines

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_tip",
  "params": []
}

Response11 lines

{
  "height": 1439,
  "last_block_pushed": "9abbd80483f9b082a9362ebac0aba5619bdba7cf647cb15f5ed33102faf3cd1b",
  "prev_block_to_last": "6ceed7ff0ff7da1d44b01dc03189edeb1323bfa6d3625768520dd1a0498a0735",
  "total_difficulty": {
    "cuckaroo": 1440,
    "cuckatoo": 1440,
    "progpow": 1440,
    "randomx": 1440
  }
}

get_version

Read only

Node version and the block header version it produces.

Surface: /v2/foreign on port 3413
Parameters: none
Declared in: api/src/foreign_rpc.rs:305

Captured on node 4.0.3. A 4.1.0 node reports node_version 4.1.0.

This method takes no parameters.

6 lines

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_version",
  "params": []
}

Response4 lines

{
  "block_header_version": 7,
  "node_version": "4.0.3"
}

get_block

Read only

A full block, meaning its header, inputs, kernels and outputs.

Surface: /v2/foreign on port 3413
Parameters: 3 positional
Declared in: api/src/foreign_rpc.rs:245

Params are positional, so all three slots must be present even when two are null.
Kernels here are a flattened shape. get_kernel and get_last_n_kernels return the raw type with an externally tagged features field, so handle both.
The response is large: a single output carries a 512-character merkle proof and a 1344-character range proof.

Parameters

heightu64 or null

Height to fetch. Pass one of the three.

hashstring or null

Block hash, hex.

commitstring or null

Find the block containing this output commitment.

10 lines

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_block",
  "params": [
    1000,
    null,
    null
  ]
}

Response49 lines, two hex values shortened

{
  "header": {
    "edge_bits": 16,
    "hash": "f4df1b77a15954402c046bce478f1125d86041afe1bf02c6f19641f5cc22f830",
    "height": 1000,
    "kernel_root": "d53eccf2203f8def77a697d3901c1fb6d54f8241ee9f47573084250741e6059a",
    "nonce": 3372684772580217300,
    "output_root": "8c547ae08e0222e1c9e8cd0b5ba3860162b7878e3897129bf041622216d38ca1",
    "prev_root": "f9ae3121113bb7f0bcb57d0a3e2c28c6bbede25b4b9d4c7b0bb421790e859353",
    "previous": "b1ec92bb822cb6d7dc825e4cb38803364c0c0b35b0afb905dbcc347bd9043acd",
    "proof": "RandomX",
    "range_proof_root": "901b6493677b73d17cfc0111bd0c49bc802fb5f9f0bac20a72159c2539624856",
    "secondary_scaling": 82,
    "solution": {
      "RandomX": "69704626296585811988368077760168225474920531123485804765531458554027688650916"
    },
    "timestamp": "2026-08-23T19:06:15+07:00",
    "total_difficulty": {
      "cuckaroo": 1001,
      "cuckatoo": 1001,
      "progpow": 1001,
      "randomx": 1001
    },
    "total_kernel_offset": "fac7d2a41d684e7f02c4ff10d5cac3fc73a16bcdae8caba73cb5bd4d8cb5c51a",
    "version": 7
  },
  "inputs": [],
  "kernels": [
    {
      "excess": "09c6d883944af1713eeedfc956095d6bce3b42981b0f98dda02e193394604fdf74",
      "excess_sig": "a1d448f081a14ddfa7c906cb7a7687ae4bf747e653a413c92a67cd13e37228c3e56d18663e74c73b18e886116720a2925888b642b5ebe2c405a30a45cf648985",
      "features": "Coinbase",
      "fee": 0,
      "lock_height": 0
    }
  ],
  "outputs": [
    {
      "block_height": 1000,
      "commit": "08df3fd5b04cb6727345e3dafee611a8e9ea691685f373e5392f89ee374e708329",
      "mmr_index": 2003,
      "output_type": "Coinbase",
      "proof_hash": "7d504401b268620f2fe84580f4f1bf921c1b1345ca8370dc842986cf734273b6",
      "spent": false,
      "merkle_proof": "00000000000007d40000000000000008a3b3…truncated in this page, full value is 512 hex characters",
      "proof": "64e70f52fd2d292c2b8d08201f125c04c15f2a3617e015eefdd42cc4f0f7d94d…truncated in this page, full value is 1344 hex characters"
    }
  ]
}

get_header

Read only

One block header, by height, hash or output commitment.

Surface: /v2/foreign on port 3413
Parameters: 3 positional
Declared in: api/src/foreign_rpc.rs:127

The header shape matches the header field of get_block.

Parameters

heightu64 or null

Height to fetch.

hashstring or null

Block hash, hex.

commitstring or null

Output commitment.

10 lines

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_header",
  "params": [
    1000,
    null,
    null
  ]
}

Response

N/A

get_blocks

Read only

A range of blocks in one call.

Surface: /v2/foreign on port 3413
Parameters: 4 positional
Declared in: api/src/foreign_rpc.rs:266

Leave include_proof false unless you need the proofs: each output proof is over a kilobyte of hex.

Parameters

start_heightu64required

First height, inclusive.

end_heightu64required

Last height, inclusive.

maxu64required

Hard cap on how many blocks come back.

include_proofbool or null

Include range proofs. They dominate the response size.

11 lines

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_blocks",
  "params": [
    1000,
    1002,
    10,
    false
  ]
}

Response

N/A

get_kernel

Read only

Find a kernel by its excess commitment, with the height it was included at.

Surface: /v2/foreign on port 3413
Parameters: 3 positional
Declared in: api/src/foreign_rpc.rs:378

This is how you confirm a specific transaction made it into the chain, since there are no transaction ids to look up.

Parameters

excessstringrequired

Kernel excess commitment, hex.

min_heightu64 or null

Lower bound for the search.

max_heightu64 or null

Upper bound for the search.

10 lines

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_kernel",
  "params": [
    "09c6d883944af1713eeedfc956095d6bce3b42981b0f98dda02e193394604fdf74",
    null,
    null
  ]
}

Response

N/A

get_outputs

Read only

Look up outputs by commitment, or by a height range.

Surface: /v2/foreign on port 3413
Parameters: 5 positional
Declared in: api/src/foreign_rpc.rs:498

Parameters

commitsarray of string or null

Output commitments to fetch.

start_heightu64 or null

Range start.

end_heightu64 or null

Range end.

include_proofbool or null

Include range proofs.

include_merkle_proofbool or null

Include merkle proofs.

12 lines

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_outputs",
  "params": [
    [],
    null,
    null,
    false,
    false
  ]
}

Response

N/A

get_unspent_outputs

Read only

Walk the unspent output set from a PMMR index.

Surface: /v2/foreign on port 3413
Parameters: 4 positional
Declared in: api/src/foreign_rpc.rs:560

Pair it with get_pmmr_indices to find where a height sits in the index space.

Parameters

start_indexu64required

PMMR index to start from.

end_indexu64 or null

Index to stop at.

maxu64required

Cap on returned outputs.

include_proofbool or null

Include range proofs.

11 lines

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_unspent_outputs",
  "params": [
    1,
    null,
    100,
    false
  ]
}

Response

N/A

get_pmmr_indices

Read only

The PMMR index range covering a block height range.

Surface: /v2/foreign on port 3413
Parameters: 2 positional
Declared in: api/src/foreign_rpc.rs:599

Parameters

start_block_heightu64required

First height.

end_block_heightu64 or null

Last height.

9 lines

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_pmmr_indices",
  "params": [
    1000,
    null
  ]
}

Response

N/A

get_last_n_kernels

Read only

The most recent kernels, newest first.

Surface: /v2/foreign on port 3413
Parameters: 1 positional
Declared in: api/src/foreign_rpc.rs:418

Parameters

distanceu64required

How many kernels to return.

8 lines

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_last_n_kernels",
  "params": [
    5
  ]
}

Response

N/A

Node administration

On the owner surface, which needs the node credential.

Mempool and submission

The same surface, for transactions that have not been mined yet.

Node queries in code

These calls wired into a working client.

Next​

Next