Explorer API

The explorer API is a public, read-only view of the NULL chain at https://explorer.nullnet.sh/v1. NULL is shielded-only, so the chain reveals blocks, transaction ids, action counts, nullifiers, note commitments, fees and sizes, but never addresses, amounts or memos. There is no address search, balance or "related transactions" endpoint because the chain has no such data.

No authentication is needed. The machine-readable contract is the OpenAPI document at /v1/openapi.json, generated from the handlers.

Conventions

  • Ids, hashes, nullifiers and note commitments are 64 lowercase hex characters.
  • Amounts are decimal strings in smallest units: 1 NULL = 100,000,000 units.
  • Heights, counts, sizes (bytes) and timestamps (Unix seconds) are JSON numbers.
  • Lists are newest first. When more results exist, the response carries next; pass it back as before (blocks) or cursor (transactions). next is absent on the last page.
  • limit defaults to 20 and is clamped to 1–100.
  • Successful GET responses carry Cache-Control: public, max-age=5. Disclosure verification responses carry Cache-Control: no-store.
  • The explorer does not log request paths, query strings or client addresses.

Rate limits

Limits are per client IP and kept in memory only.

  • Name
    /v1/*
    Type
    600 per minute
    Description

    Every /v1 route, with a burst of 60 requests.

  • Name
    /v1/disclosures/verify
    Type
    10 per minute
    Description

    An additional, separate limit on disclosure verification.

Over the limit, the API returns 429 with error code rate_limited. /healthz and /readyz are not rate limited.

Errors

Every error has the same JSON body.

  • Name
    error
    Type
    string
    Description

    Stable machine-readable code (see below).

  • Name
    message
    Type
    string
    Description

    Human-readable detail, for example q: expected a block height or a 64-character hex id.

StatuserrorMeaning
400bad_requestA parameter or body is malformed. The message names the field.
404not_foundNothing on the indexed chain matches.
429rate_limitedToo many requests from this client.
500internalDatabase failure. No detail is returned.
503not_readyThe explorer has not indexed any block yet.
503node_unavailableThe node could not answer (disclosure verification only).

Error

{
  "error": "not_found",
  "message": "block not found"
}
GET/v1/status

Status

Indexer and node health: the highest indexed block and the node's state at the last indexer pass. Returns 503 not_ready before the first block is indexed. The node_* and last_pass_at fields are null until the indexer has recorded node status.

Response

  • Name
    network
    Type
    string
    Description

    main or test.

  • Name
    indexed_height
    Type
    integer
    Description

    Highest indexed block.

  • Name
    indexed_hash
    Type
    string
    Description

    Its hash.

  • Name
    node_height
    Type
    integer | null
    Description

    The node's tip at the last indexer pass.

  • Name
    node_syncing
    Type
    boolean | null
    Description

    Whether the node was still syncing with its peers.

  • Name
    node_connections
    Type
    integer | null
    Description

    Ready peer connections of the node.

  • Name
    last_pass_at
    Type
    integer | null
    Description

    Unix seconds of the last completed indexer pass.

Request

GET
/v1/status
curl https://explorer.nullnet.sh/v1/status

Response

{
  "network": "main",
  "indexed_height": 6206,
  "indexed_hash": "00000fc8d37f816b43e79acbaba7d736adbbcbfdca48182361e0dd943a456273",
  "node_height": 6206,
  "node_syncing": false,
  "node_connections": 42,
  "last_pass_at": 1793000908
}
GET/v1/stats

Stats

Network-wide figures at the indexed tip. Supply is computed exactly from the emission schedule. Returns 503 not_ready before the first block is indexed.

Response

  • Name
    network
    Type
    string
    Description

    main or test.

  • Name
    height
    Type
    integer
    Description

    Indexed tip.

  • Name
    supply.emitted
    Type
    string
    Description

    Units in existence at the indexed tip: premine plus subsidies.

  • Name
    supply.premine
    Type
    string
    Description

    The development fund paid by genesis.

  • Name
    supply.max
    Type
    string
    Description

    The supply cap.

  • Name
    supply.next_subsidy
    Type
    string
    Description

    Subsidy of the next block.

  • Name
    transactions
    Type
    integer
    Description

    Transactions ever mined, coinbases included.

  • Name
    actions
    Type
    integer
    Description

    Actions ever mined.

  • Name
    fees
    Type
    string
    Description

    Fees ever paid.

  • Name
    difficulty
    Type
    number | null
    Description

    Difficulty of the next block relative to the easiest target.

  • Name
    work_per_second
    Type
    string | null
    Description

    Estimated network Equihash solutions per second.

  • Name
    block_interval_secs
    Type
    integer | null
    Description

    Target seconds per block.

  • Name
    mean_block_time_secs
    Type
    number | null
    Description

    Mean seconds per block over the last 60 blocks.

  • Name
    mempool_size
    Type
    integer
    Description

    Pooled transactions.

Request

GET
/v1/stats
curl https://explorer.nullnet.sh/v1/stats

Response

{
  "network": "main",
  "height": 6206,
  "supply": {
    "emitted": "69019820000000",
    "premine": "63000000000000",
    "max": "2100000000000000",
    "next_subsidy": "970000000"
  },
  "transactions": 6920,
  "actions": 18832,
  "fees": "64180000",
  "difficulty": 59327.30547090157,
  "work_per_second": "7158",
  "block_interval_secs": 120,
  "mean_block_time_secs": 132.13333333333333,
  "mempool_size": 0
}
GET/v1/blocks

List blocks

Blocks, newest first. To page, pass the response's next as before.

Optional query parameters

  • Name
    before
    Type
    integer
    Description

    Return blocks with a height strictly below this one.

  • Name
    limit
    Type
    integer
    Description

    Page size, 1–100. Default 20.

Block summary

  • Name
    height
    Type
    integer
    Description

    Height.

  • Name
    hash
    Type
    string
    Description

    Block id.

  • Name
    time
    Type
    integer
    Description

    Block time, Unix seconds.

  • Name
    size
    Type
    integer
    Description

    Bytes.

  • Name
    tx_count
    Type
    integer
    Description

    Transactions, coinbase included.

  • Name
    action_count
    Type
    integer
    Description

    Actions across all transactions.

  • Name
    fees
    Type
    string
    Description

    Fees paid by the block's transactions.

  • Name
    subsidy
    Type
    string
    Description

    Subsidy the coinbase created.

Request

GET
/v1/blocks
curl "https://explorer.nullnet.sh/v1/blocks?limit=2"

Response

{
  "items": [
    {
      "height": 6206,
      "hash": "00000fc8d37f816b43e79acbaba7d736adbbcbfdca48182361e0dd943a456273",
      "time": 1793000789,
      "size": 10851,
      "tx_count": 1,
      "action_count": 2,
      "fees": "0",
      "subsidy": "970000000"
    },
    {
      "height": 6205,
      "hash": "00000b187671645a900f8b4f66bf63932bcebbd92982e86934f26db2de718567",
      "time": 1793000715,
      "size": 10851,
      "tx_count": 1,
      "action_count": 2,
      "fees": "0",
      "subsidy": "970000000"
    }
  ],
  "next": "6205"
}
GET/v1/blocks/{block}

Get a block

One block by height (decimal) or by hash (64 hex characters), with its header and transactions. Returns 400 for anything else and 404 when no such block is indexed.

The response has every block summary field plus the fields below.

Response

  • Name
    prev_hash
    Type
    string
    Description

    Parent block id.

  • Name
    next_hash
    Type
    string | null
    Description

    Next block's id, if indexed.

  • Name
    confirmations
    Type
    integer
    Description

    Confirmations at the indexed tip. The tip itself has 1.

  • Name
    version
    Type
    integer
    Description

    Header version.

  • Name
    target
    Type
    string
    Description

    Target, compact hex.

  • Name
    difficulty
    Type
    number | null
    Description

    Difficulty relative to the easiest target.

  • Name
    commitment_root
    Type
    string
    Description

    Note commitment tree root after this block.

  • Name
    tx_root
    Type
    string
    Description

    Root over the block's txids.

  • Name
    nonce
    Type
    string
    Description

    Proof-of-work nonce.

  • Name
    reward
    Type
    string
    Description

    Subsidy plus fees: what the miner received.

  • Name
    transactions
    Type
    array
    Description

    Transaction summaries, coinbase first. See list transactions.

Request

GET
/v1/blocks/{block}
curl https://explorer.nullnet.sh/v1/blocks/6201

Response

{
  "height": 6201,
  "hash": "0000034c502b7b5a47d3641de7729e242c3beb8f785b2dc9eb2d5c56476df4f0",
  "time": 1793000233,
  "size": 28981,
  "tx_count": 2,
  "action_count": 6,
  "fees": "40000",
  "subsidy": "970000000",
  "prev_hash": "0000041e3f6c9e069db217c9e40e047f0ef33e9113bb066fb106c1c83a7414f6",
  "next_hash": "00000acc98ef0c9f87cba0b398ddfb39b6fccf86de8f95b73a1cb18ba6077be2",
  "confirmations": 6,
  "version": 1,
  "target": "1e11b71c",
  "difficulty": 59190.45778250938,
  "commitment_root": "f2bfefc5a6dfe7825bedfb23c561a2b192b402e3beec23a0f504ebe570ff6639",
  "tx_root": "1437d04451f1ff75c57504b1c5031161d6a46a0255241b80f24536e4ff2f7581",
  "nonce": "0b4680cb94370000000000000000000000000000000000000000000000000000",
  "reward": "970040000",
  "transactions": [
    {
      "txid": "4db07ba5ab3cc93a9794501d9a7c39c09c12967bdf87a1be3926b51a58142fba",
      "height": 6201,
      "position": 0,
      "time": 1793000233,
      "coinbase": true,
      "action_count": 2,
      "fee": "0",
      "size": 10602
    },
    {
      "txid": "0b5e040a9059651f593d1a9da9f4a4283c421bca037ccb2bf6a1337b36a232bc",
      // ...
    }
  ]
}
GET/v1/transactions

List transactions

Mined transactions, newest first (by height, then position in the block). Coinbases are left out unless coinbase=true. To page, pass the response's next as cursor.

Optional query parameters

  • Name
    cursor
    Type
    string
    Description

    The next of a previous page, in the form <height>.<position>. Anything else returns 400.

  • Name
    limit
    Type
    integer
    Description

    Page size, 1–100. Default 20.

  • Name
    coinbase
    Type
    boolean
    Description

    Include coinbase transactions. Default false.

Transaction summary

  • Name
    txid
    Type
    string
    Description

    Transaction id.

  • Name
    height
    Type
    integer
    Description

    Block height.

  • Name
    position
    Type
    integer
    Description

    Position in the block; 0 is the coinbase.

  • Name
    time
    Type
    integer
    Description

    Block time, Unix seconds.

  • Name
    coinbase
    Type
    boolean
    Description

    Whether this is the block's coinbase.

  • Name
    action_count
    Type
    integer
    Description

    2, 4, 8 or 16.

  • Name
    fee
    Type
    string
    Description

    Fee; "0" for a coinbase.

  • Name
    size
    Type
    integer
    Description

    Bytes.

Request

GET
/v1/transactions
curl "https://explorer.nullnet.sh/v1/transactions?limit=2"

Response

{
  "items": [
    {
      "txid": "0b5e040a9059651f593d1a9da9f4a4283c421bca037ccb2bf6a1337b36a232bc",
      "height": 6201,
      "position": 1,
      "time": 1793000233,
      "coinbase": false,
      "action_count": 4,
      "fee": "40000",
      "size": 18130
    },
    {
      "txid": "e92f8ef17c2ca01b7ec024db56631d48d1984165a1012c5eee3f31a01e041bf2",
      "height": 6199,
      "position": 1,
      "time": 1792999989,
      "coinbase": false,
      "action_count": 8,
      "fee": "80000",
      "size": 33186
    }
  ],
  "next": "6199.1"
}
GET/v1/transactions/{txid}

Get a transaction

One transaction with its actions. The explorer looks on the indexed chain first, then in the mempool as of the last indexer pass. Returns 404 when neither has it.

Response

  • Name
    status
    Type
    string
    Description

    confirmed (mined) or pooled (waiting in the mempool).

  • Name
    txid
    Type
    string
    Description

    Transaction id.

  • Name
    height
    Type
    integer | null
    Description

    Block height, when confirmed.

  • Name
    position
    Type
    integer | null
    Description

    Position in the block, when confirmed.

  • Name
    time
    Type
    integer
    Description

    Block time (confirmed) or when the explorer first saw it in the mempool (pooled), Unix seconds.

  • Name
    confirmations
    Type
    integer
    Description

    Confirmations at the indexed tip; 0 while pooled.

  • Name
    coinbase
    Type
    boolean
    Description

    Whether this is a coinbase.

  • Name
    version
    Type
    integer
    Description

    Transaction format version.

  • Name
    anchor
    Type
    string
    Description

    Commitment tree root the proof is against.

  • Name
    anchor_height
    Type
    integer | null
    Description

    Height of the block that produced the anchor, if indexed.

  • Name
    action_count
    Type
    integer
    Description

    2, 4, 8 or 16.

  • Name
    fee
    Type
    string
    Description

    Fee; "0" for a coinbase.

  • Name
    size
    Type
    integer
    Description

    Bytes.

  • Name
    proof_size
    Type
    integer
    Description

    Proof bytes.

  • Name
    actions
    Type
    array
    Description

    Actions in order. Each has position, nullifier (revealed), rk (randomized spend validating key), cmx (note commitment created) and cv_net (net value commitment).

Request

GET
/v1/transactions/{txid}
curl https://explorer.nullnet.sh/v1/transactions/0b5e040a9059651f593d1a9da9f4a4283c421bca037ccb2bf6a1337b36a232bc

Response

{
  "status": "confirmed",
  "txid": "0b5e040a9059651f593d1a9da9f4a4283c421bca037ccb2bf6a1337b36a232bc",
  "height": 6201,
  "position": 1,
  "time": 1793000233,
  "confirmations": 6,
  "coinbase": false,
  "version": 1,
  "anchor": "78fd364601e2bad0a815d1e0d92eee5befe521c3f39d680c84b59c1446ca2f2d",
  "anchor_height": 6200,
  "action_count": 4,
  "fee": "40000",
  "size": 18130,
  "proof_size": 14496,
  "actions": [
    {
      "position": 0,
      "nullifier": "1843dfa29b3e64d891b7f5fbd2e338febd6fc7af3a95c0e4f97d108258bbe82f",
      "rk": "9376de40d472535231b06cecf7677e1ba42cbefe092260e695ed16a60c50bf8b",
      "cmx": "96a0a7ea0eee3a816b399e7559e8f3641c3cfa144c238385b89273b858929f10",
      "cv_net": "d03269672c0bc6ef96731de9c867deac836619d8c4b7329f022dfea82aff0110"
    },
    {
      "position": 1,
      // ...
    }
  ]
}
GET/v1/nullifiers/{nullifier}

Look up a nullifier

Where a nullifier was revealed on the indexed chain. A 404 means the note it belongs to has not been spent on the indexed chain.

Response

  • Name
    txid
    Type
    string
    Description

    Transaction id.

  • Name
    height
    Type
    integer
    Description

    Block height.

  • Name
    tx_position
    Type
    integer
    Description

    Transaction position in the block.

  • Name
    action_position
    Type
    integer
    Description

    Action position in the transaction.

Request

GET
/v1/nullifiers/{nullifier}
curl https://explorer.nullnet.sh/v1/nullifiers/1843dfa29b3e64d891b7f5fbd2e338febd6fc7af3a95c0e4f97d108258bbe82f

Response

{
  "txid": "0b5e040a9059651f593d1a9da9f4a4283c421bca037ccb2bf6a1337b36a232bc",
  "height": 6201,
  "tx_position": 1,
  "action_position": 0
}
GET/v1/commitments/{cmx}

Look up a note commitment

Where a note was created: the action whose cmx matches. Same response shape as the nullifier lookup. Returns 404 when no indexed action created it.

Request

GET
/v1/commitments/{cmx}
curl https://explorer.nullnet.sh/v1/commitments/96a0a7ea0eee3a816b399e7559e8f3641c3cfa144c238385b89273b858929f10

Response

{
  "txid": "0b5e040a9059651f593d1a9da9f4a4283c421bca037ccb2bf6a1337b36a232bc",
  "height": 6201,
  "tx_position": 1,
  "action_position": 0
}
GET/v1/search

Resolves a search string to the thing to open. Surrounding whitespace is ignored. A decimal number is treated as a block height. A 64-character hex string is matched, in order, against block hashes, mined transactions, pooled transactions, nullifiers and note commitments; the first match wins. Anything else, including addresses, returns 400. No match returns 404.

Query parameters

  • Name
    q
    Type
    string
    Description

    Required. A block height or a 64-character hex id.

Response

  • Name
    kind
    Type
    string
    Description

    block, transaction, nullifier or commitment.

  • Name
    id
    Type
    string
    Description

    The id to open: block hash, txid, nullifier or commitment.

  • Name
    height
    Type
    integer | null
    Description

    Block height, for blocks and mined matches; null for a pooled transaction.

Request

GET
/v1/search
curl "https://explorer.nullnet.sh/v1/search?q=1"

Response

{
  "kind": "block",
  "id": "0003dc7ed8900ed308ecf55e40a0e09aadbc8074dfd7f81a76cc9cc6ab30b05a",
  "height": 1
}
GET/v1/mempool

Mempool

Pooled transactions as of the last indexer pass, most recently seen first.

Optional query parameters

  • Name
    limit
    Type
    integer
    Description

    Number of items, 1–100. Default 20.

Response

  • Name
    size
    Type
    integer
    Description

    Pooled transactions in total.

  • Name
    items
    Type
    array
    Description

    Up to limit pooled transactions, each with txid, action_count, fee, size and first_seen (Unix seconds the explorer first saw it).

Request

GET
/v1/mempool
curl "https://explorer.nullnet.sh/v1/mempool?limit=20"

Response

{
  "size": 0,
  "items": []
}
POST/v1/disclosures/verify

Verify a payment disclosure

Checks a payment disclosure produced by the sender's wallet with getpaymentdisclosure (see selective disclosure). The explorer passes it to its node's verifypaymentdisclosure and returns the verdict.

The body is JSON, at most 4096 bytes. disclosure must be non-empty, even-length hex of at most 1024 characters; otherwise the API returns 400. If the node cannot answer, it returns 503 node_unavailable. This route has its own limit of 10 requests per minute per client, and responses are Cache-Control: no-store.

Request body

  • Name
    disclosure
    Type
    string
    Description

    Hex from the sender wallet's getpaymentdisclosure.

Response

  • Name
    valid
    Type
    boolean
    Description

    Whether the disclosure opens the output it names.

  • Name
    reason
    Type
    string
    Description

    Why it proves nothing. Present only when valid is false.

  • Name
    txid
    Type
    string
    Description

    Transaction. Present only when valid.

  • Name
    index
    Type
    integer
    Description

    Action index of the output. Present only when valid.

  • Name
    address
    Type
    string
    Description

    Recipient address. Present only when valid.

  • Name
    amount
    Type
    string
    Description

    Amount paid, in smallest units. Present only when valid.

  • Name
    memo
    Type
    string
    Description

    Memo text. Present only when valid and the note has a memo.

  • Name
    height
    Type
    integer
    Description

    Height, once mined.

  • Name
    confirmations
    Type
    integer
    Description

    Confirmations. Present only when valid.

Request

POST
/v1/disclosures/verify
curl https://explorer.nullnet.sh/v1/disclosures/verify \
  -H "Content-Type: application/json" \
  -d '{"disclosure": "<hex from getpaymentdisclosure>"}'

Response (invalid)

{
  "valid": false,
  "reason": "no such action"
}
GET/healthz

Health

Health checks live outside /v1, at https://explorer.nullnet.sh/healthz and https://explorer.nullnet.sh/readyz.

  • /healthz returns 200 with the body ok while the process is up.
  • /readyz returns 200 when the indexer completed a pass within the last 120 seconds, and 503 with an empty body otherwise.

Request

GET
/healthz
curl https://explorer.nullnet.sh/healthz
curl -o /dev/null -w "%{http_code}\n" https://explorer.nullnet.sh/readyz

Response

ok