Developer reference / Public REST API

Ravelnonce testnet API

The public HTTP interface for one hosted, append-only testnet node. Read endpoints expose that node's persisted state; signed submissions are validated before atomic database writes.

Node and mining reads

GET

/api/node/state

Returns chain ID, node mode, active tip, issued atoms, and pending mempool count.

GET

/api/node/template?address={address}

Returns the expected next header, minimum timestamp, height-based subsidy, coinbase for the supplied miner address, and selected valid mempool transactions.

Node state response shape

{
  "chainId": "ravelnonce-testnet-v1",
  "mode": "single-hosted-testnet",
  "tip": { "height": 0, "hash": "<64 lowercase hex>", "timestamp": 0, "target": "<64 lowercase hex>" },
  "issuedAtoms": "0",
  "mempoolCount": 0
}

Signed transaction and block submissions

POST

/api/node/transactions

Accepts one regular transaction after input lookup, address/key matching, Ed25519 signature verification, value checks, and pending outpoint reservation.

POST

/api/node/blocks

Accepts a candidate block only after header, target, proof of work, timestamp, merkle, coinbase, transaction, and UTXO checks.

Regular transaction JSON shape

{
  "type": 1,
  "version": 1,
  "chainId": "ravelnonce-testnet-v1",
  "inputs": [{ "txid": "<64 lowercase hex>", "outputIndex": 0, "publicKey": "<64 lowercase hex>", "signature": "<128 lowercase hex>" }],
  "outputs": [{ "amountAtoms": "1250000000", "address": "<79-character rvtest1 address>" }]
}

Stable mutation error shape

{
  "error": "An input is already reserved by a pending transaction.",
  "code": "double_spend"
}

HTTP 201 means a transaction entered the mempool or a block was atomically accepted.
HTTP 400 covers malformed JSON, contract violations, and consensus-invalid data.
HTTP 409 covers pending or confirmed double spends, duplicate records, and active-tip conflicts.
HTTP 413 means the JSON request exceeded its limit: 256 KiB for a transaction or 2 MiB for a block.
HTTP 500 uses a generic error and never returns database internals.

Explorer and status reads

GET

/api/explorer

Returns the latest 20 stored blocks and transactions, including the configured genesis block.

GET

/api/explorer/blocks/{hash}

Looks up a block by its 64-character lowercase header hash; an unknown valid hash returns HTTP 404.

GET

/api/explorer/transactions/{txid}

Looks up a pending or confirmed signed transaction by its 64-character lowercase ID.

GET

/api/explorer/addresses/{address}

Returns confirmed spendable UTXOs, balance atoms, and recent transactions for a checksummed testnet address.

GET

/api/status

Returns current values from this node's persisted tip and the testnet fee rule. This does not measure peer or network-wide health.

Successful read responses include Cache-Control: no-store. The browser UI validates all responses through the shared Zod contracts before rendering them.

Availability and operating limits

All public node endpoints are single-instance views over this app's PostgreSQL state. The chain rejects stale, competing, and side-branch blocks and has no P2P transport, synchronization, fork choice, or reorganization. The public faucet remains a pending-request recorder; it does not create or send funds.

For complete byte layouts, issuance vectors, transaction rules, and target calculation, read the testnet protocol page. To run a local server and signed demo, follow the node guide.