JSON-RPC API

Core exposes JSON-RPC 2.0 over HTTP. WebSocket upgrades are rejected. The default endpoint is:

http://127.0.0.1:9601

Every method has the paranoid_ namespace prefix. Parameters are positional JSON arrays. Request bodies are limited to 2,237,632 bytes, and JSON-RPC batches remain supported within that body limit.

curl --silent --show-error \
  -H 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "paranoid_getChainInfo",
    "params": []
  }' \
  http://127.0.0.1:9601

Conventions

• Monetary integer fields are in μNOID.
• One NOID equals 1,000,000 μNOID.
• Hashes are lowercase hexadecimal without 0x.
• Targets and nonce bytes use their canonical little-endian encoding.
• Addresses use canonical bech32m o1… unless a field explicitly says hex.
• Unknown permanent objects generally return null.
• Old block bodies return null after the 42-block retention window; their headers remain queryable.
• Decimal strings carry aggregates that may exceed exact JSON-number range.
• *_noid floating-point fields are display conveniences. Accounting code should use the corresponding *_micronoid integer.

Authentication

RPC has no authentication by default and must remain on loopback. Core refuses to start if an unauthenticated listener is configured on any non-loopback address.

An originless connection accepted from the actual TCP loopback address receives local owner access without an Authorization header, even when mining or operator credentials are configured. This keeps the GUI and CLI passwordless on the node host. If an Authorization header is supplied, it is always validated and selects only that credential's scope. Non-loopback clients must supply a configured credential. Host, Forwarded, X-Forwarded-For and other HTTP headers cannot claim local access.

Starting Core with --mining-key TOKEN or --mining-key-file FILE requires:

Authorization: Bearer TOKEN

on external-mining requests. A missing or different token receives HTTP 401 without a JSON-RPC result. A valid mining credential is restricted to paranoid_getBlockTemplate and paranoid_submitBlock; it cannot authorize wallet, node-control or other RPC methods. The token authenticates but does not encrypt the connection, so use a private transport or TLS proxy remotely.

Pools with accounting or payouts on a separate host may configure a distinct --operator-key TOKEN or --operator-key-file FILE. That credential is limited to exactly:

• paranoid_walletMinedBlocks
• paranoid_walletGetBalance
• paranoid_walletStatus
• paranoid_walletPlanSend
• paranoid_walletSend
• paranoid_walletPlanConsolidation
• paranoid_walletConsolidate
• paranoid_walletReceipts
• paranoid_walletQueryReceipts
• paranoid_walletExportReceipt
• paranoid_getTx
• paranoid_getMempoolEntry
• paranoid_verifyReceipt
• paranoid_submitTxIntent
• paranoid_validateAddress
• paranoid_getChainInfo
• paranoid_estimateFee
• paranoid_estimateFeeDetailed

It cannot call mining methods, paranoid_stop, wallet scanning and discovery, address-management methods, unbounded wallet history or UTXO listings, or any other current or future RPC method. Mining and operator tokens must differ. When both are configured, each request receives only the scope of the token it supplied. Scopes are never combined.

The operator credential can spend the active wallet through walletSend. Bearer authentication is not transport encryption. Bind to a private interface, restrict the source addresses with a firewall, and use a VPN, SSH tunnel, or authenticated TLS proxy whenever the network is not fully trusted. A reverse proxy that connects to the node through loopback must forward the Bearer header. If it removes Authorization, the node sees the proxy as a local owner client and does not apply a remote credential scope.

Generate independent tokens with openssl rand -hex 32. Command-line tokens remain supported for compatibility. Owner-only key files are preferred because they keep tokens out of process arguments.

Chain methods

getBlockDetails.retained describes the canonical body while that body is retained. Intermediate blocks of a multi-block commit are included even when their validity is carried by the suffix tip's terminal. For those blocks, history_step_bytes and bundle_bytes are zero because no standalone proof bundle is available; block_bytes and transactions still describe the body. Once the body is pruned, getBlock returns null and getBlockDetails keeps the permanent header with retained: null. Each retained transaction has contract: "call", "close" or null, derived from its contract and terminal bits. This field is unavailable after pruning.

getRecentTransactions scans retained canonical bodies, including intermediate blocks of multi-block commits. Page numbering starts at one; page size is clamped to 1–32. Supplying an address adds exact spent and received aggregates for that owner.

getSlot returns an error for an index outside the current 2^log_slots domain. An in-range empty slot returns empty: true, zero value and an empty owner string.

Node, network and fee methods

Detailed fee counts must be 1–1,020 inputs and 1–256 outputs. The returned fee includes the current relay floor.

The fee estimator accepts format-level counts; it does not approve block capacity. Wallet planning and admission enforce the 504-input and class page budgets.

Utility and submission methods

Slot hints are not reservations. Both methods exclude currently reserved mempool outputs, return at most 256 entries and may return fewer if the node cannot find enough empty slots. Salt is bounded to 256 decoded bytes.

submitTxIntent accepts canonical payment, ABI 3 contract, native operation and trade-policy intents, including the detached authorization capsule. Ordinary intents are bounded to 303,495 decoded bytes. Native operations and trade policies use their own bounded canonical formats before proof verification.

Mempool methods

Mempool responses describe atomic logical transactions rather than physical pages. getMempoolEntry returns the admitted 699-byte public opening in contract_opening_hex for a pending contract call, or null for an ordinary transaction. getMempoolInfo stays metadata-only. The opening is no longer available through this method after the call leaves the mempool, so polling is not a complete contract archive.

Receipt method

Receipt input is bounded to 128 KiB after hex decoding. merkle_valid and canonical are separate: a mathematically consistent receipt can claim a root that is not on this node's canonical chain.

External-mining methods

The node must run in external-miner mode. An empty miner_address uses the node payout. A non-empty address is accepted only when the node enabled custom coinbase.

nonce_hex is exactly 32 lowercase hex characters encoding 16 little-endian bytes. Templates are single-use and expire 30 seconds after proof preparation finishes. The RPC request itself can take longer while the node prepares the proof; the external worker's default request timeout is 180 seconds.

Node control

The first call requests graceful shutdown. Later calls are harmless while the process is exiting.

Wallet methods

walletReceipts accepts an optional family: all, noid, tokens, trades or nfts. Omitting it keeps the original call. walletQueryReceipts filters the complete saved library by exact asset or collection ID, operation, UTC time bounds and verification status, then sorts before pagination. See saved receipt queries for the query fields and response.

Amounts and fees are μNOID. A send or plan fee of zero requests automatic fee selection.

walletUtxoSnapshot returns a full utxos array when called without a revision or with a stale revision. Send its returned revision on subsequent polls. A matching revision returns utxos: null, meaning the client should retain its existing vector. revision: null means the implementation always returns the full vector. Revisions are opaque, change on reservations and owner-cache replacement, and cannot be reused after a wallet/node restart. The original walletListUtxos method remains unchanged. The GUI falls back to that method when conditional snapshots are unavailable. Operator scope is not broadened.

Receipt and mined-block pages start at one and accept sizes 1–50. walletDiscoverAddresses accepts 1–20 and stops at the first empty derived owner.

walletConsolidate is quote-bound. Its slot list, fee and output value must exactly match the latest plan; otherwise it fails and the caller must request a new quote.

Contract methods

All methods below use the paranoid_ prefix and local owner scope. walletFundObject, previewObjectCall and walletCallObject require an authenticated runtime (runtime_available = true).

getObjectInstances uses an inclusive slot cursor and limit 1–256. State and activity lists use exclusive nullable cursors and limit 1–64; responses carry the observed height and tip hash. Activity includes retained calls of both parties and their canonical status. Imports merge verified evidence by txid without deleting existing local records. All balances are queried from State.

The contract API guide defines constructor variants, custom program fields, review guards, error recovery and CLI workflows. Contract receipts use verifyObjectReceipt / walletImportObjectReceipt, with a 1,110,624-byte decoded cap. Ordinary verifyReceipt retains its separate 128 KiB payment format. createObject creates public terms without a fee; max_fee_micronoid caps a later call. Counter and instruction immediate values are canonical decimal u64 strings.

Contract schemas

ObjectDefinition and ObjectProgramStep follow the tagged definitions and instruction format in API integration and core. Flattened ObjectCallDetails fields appear directly in receipt and activity objects. A receipt authenticates a past call; query current State separately.

ObjectInfo {
  abi_version: u16
  state: [decimal u64 string, decimal u64 string]
  address: string
  opening_hex: string
  code_id: string
  state_hex: string
  program: ObjectProgramStep[16]
  claim_authority: string
  recovery_authority: string
  claim_recipient: string
  recovery_recipient: string
  deadline_height: u64
  max_fee_micronoid: u64
  max_payout_micronoid: u64
  min_retained_micronoid: u64
  claim_can_continue: bool
  claim_can_close: bool
  recovery_can_continue: bool
  recovery_can_close: bool
  unrestricted_payout_recipient: bool
}

ObjectStatus {
  object: ObjectInfo
  slot: SlotInfo
  matches_opening: bool
  tip_height: u64
  next_call_height: u64
  active_authority: string
}

ObjectInstances {
  address: string
  height: u64
  tip_hash: string
  slots: SlotInfo[]
  next_slot: u32 | null
}

ObjectKnownState {
  object: ObjectInfo
  has_balance: bool
}

ObjectKnownStates {
  states: ObjectKnownState[]
  height: u64
  tip_hash: string
  next_root: string | null
}

ObjectPayout {
  address: string
  amount_micronoid: u64
}

ObjectCallRequest {
  opening_hex: string
  slot_index: u32
  creation_id: u64
  terminal: bool
  payout: ObjectPayout | null
  fee_micronoid: u64
  expected_recovery: bool | null
  expected_authority: string | null
  expected_call_height: u64 | null
  expected_txid: string | null
}

ObjectCallPreview {
  txid: string
  call_height: u64
  authority: string
  recovery: bool
  terminal: bool
  fee_micronoid: u64
  retained_micronoid: u64
  payout: ObjectPayout | null
  successor: ObjectInfo | null
}

ObjectCallResult {
  transaction: WalletSendResult
  call_height: u64
  successor: ObjectInfo | null
  output_slot: u32
}

ObjectReceiptResult {
  valid: bool
  ...ObjectCallDetails
}

ObjectCallDetails {
  height: u64
  txid: string
  terminal: bool
  authority: string
  original: ObjectInfo
  successor: ObjectInfo | null
  input_micronoid: u64
  fee_micronoid: u64
  retained_micronoid: u64
  payout: ObjectPayout | null
}

ObjectActivityEntry {
  ...ObjectCallDetails
  block_hash: string
  canonical: bool
}

ObjectActivityPage {
  height: u64
  tip_hash: string
  entries: ObjectActivityEntry[]
  next_cursor: string | null
}

ObjectClassLimits {
  class: string
  pages: usize
  live_inputs: usize
  contract_calls: usize
}

ObjectProtocolInfo {
  tip_height: u64
  activation_height: u64 | null
  active_at_next_block: bool
  runtime_available: bool
  next_block_time_seconds: u64
  abi_version: u16
  instructions: usize
  persistent_registers: usize
  classes: ObjectClassLimits[]
}

Optional request guards may be omitted or null. creation_id is mandatory. Closing uses terminal: true, payout: null; the semantic result reports the closing payment and no successor. A zero call fee requests the current minimum, subject to the policy ceiling. Submission responses still require inclusion.

Response schemas

The following schemas use ? for optional fields and null where JSON can explicitly carry no value.

Chain and State

ChainInfo {
  height: u64
  best_hash: string
  difficulty_target: string
  active_slot_count: u64
  log_slots: u32
  circulating_supply_micronoid: decimal string
}

BlockHeaderInfo {
  height: u64
  hash: string
  prev_hash: string
  state_root: string
  tx_root: string
  timestamp: u64
  miner: string
  nonce_hex: string
  difficulty_target: string
  log_slots: u32
  active_slot_count: u64
  alloc_counter: u64
}

SlotInfo {
  slot_index: u32
  value: u64
  creation_id: u64
  owner: string
  empty: bool
}

TxInfo {
  tx_hash: string
  height: u64
  block_hash: string
  tx_position: u32
}

circulating_supply_micronoid is the exact sum of all UTXO values in Live State, expressed in μNOID. It is encoded as a decimal string so JSON does not lose precision.

StateInfo {
  log_slots: u32
  capacity: u64
  active_slots: u64
  fill_pct: number
  slots_until_expand: i64
  expand_trigger_pct: u8
  log_slots_max: u32
  state_bytes: u64
  state_size_human: string
}

StateMapInfo {
  log_slots: u32
  bucket_capacity: u64
  live_counts: u64[]
}

state_bytes is canonical encoded segment data. It excludes MDBX page, indexing and filesystem overhead.

Block details

BlockDetailsInfo {
  header: BlockHeaderInfo
  retained: RetainedBlockInfo | null
}

RetainedBlockInfo {
  proof_class: string
  logical_transactions: u16
  user_pages: u16
  live_inputs: u16
  live_outputs: u16
  reward_micronoid: u64
  reward_noid: number
  total_fees_micronoid: decimal string
  block_bytes: u64
  history_step_bytes: u64
  bundle_bytes: u64
  transactions: BlockTransactionInfo[]
}

BlockTransactionInfo {
  position: u16
  txid: string
  page_count: u16
  live_inputs: u16
  live_outputs: u16
  fee_micronoid: u64
  coinbase: bool
  development_payout: bool
  contract: "call" | "close" | null
  epoch_anchor: string
  input_owner: string | null
  input_sum_micronoid: decimal string
  output_sum_micronoid: decimal string
  page_hashes: string[]
  inputs: BlockTransactionInputInfo[]
  outputs: BlockTransactionOutputInfo[]
}

BlockTransactionInputInfo {
  page: u16
  lane: u8
  slot_index: u32
  amount_micronoid: u64
  creation_id: u64
}

BlockTransactionOutputInfo {
  page: u16
  lane: u8
  slot_index: u32
  amount_micronoid: u64
  owner: string
  creation_id: u64
}

RecentTransactionsPage {
  page: u32
  page_size: u32
  total: usize
  total_pages: u32
  tip_height: u64
  retained_from_height: u64
  address: string | null
  transactions: RecentTransactionInfo[]
}

RecentTransactionInfo {
  height: u64
  block_hash: string
  timestamp: u64
  position: u16
  txid: string
  page_count: u16
  live_inputs: u16
  live_outputs: u16
  fee_micronoid: u64
  coinbase: bool
  development_payout: bool
  input_owner: string | null
  input_sum_micronoid: decimal string
  output_sum_micronoid: decimal string
  address_spent_micronoid: decimal string | null
  address_received_micronoid: decimal string | null
}

Node and mining

MiningInfo {
  height: u64
  difficulty_bits: u32
  difficulty_target: string
  block_reward_micronoid: u64
  block_reward_noid: number
  active_slot_count: u64
}

NodeStatus {
  synced: bool
  sync_stage: "headers" | "state" | "tip"
  mining: bool
  mining_ready: bool
  mining_confirmed_peers: usize
  mining_required_peers: usize
  isolated_mining: bool
  backend: string
  available_threads: usize
  worker_threads: usize
}

isolated_mining is status information from a node started in a special operator context. Public deployments should not use it as a remote control or peer property.

Fees

FeeEstimate {
  n_inputs: usize
  n_outputs: usize
  net_new_slots: u64
  active_slot_count: u64
  log_slots: u32
  fee_micronoid: u64
  breakdown: FeeBreakdownInfo
}

FeeBreakdownInfo {
  base: u64
  input: u64
  output: u64
  io: u64
  state_growth: u64
  required_total: u64
  relay_floor: u64
  relay_total: u64
  paid_total: u64
  burned: u64
  miner_claimable: u64
}

Mempool

MempoolInfo {
  size: usize
  fee_floor: u64
  txs: MempoolTxInfo[]
}

MempoolStats {
  size: usize
  capacity: usize
  intent_bytes: u64
  max_intent_bytes: u64
  fee_floor: u64
}

MempoolTxInfo {
  tx_hash: string
  fee_micronoid: u64
  fee_rate: u64
  n_inputs: usize
  n_outputs: usize
  page_count: usize
  minimum_proof_class: string
  requires_b255_miner: bool
  admitted_height: u64
  has_authorization: bool
}

MempoolEntryInfo {
  ...MempoolTxInfo
  contract_opening_hex: string | null
}

Fee rate uses weighted units:

inputs + outputs + 4 × net_new_slots

minimum_proof_class reflects the installed bank's actual page capacity. The existing requires_b255_miner field is retained for API compatibility and indicates that the spend needs the larger class; its name does not imply a 255-page v2 limit.

Address validation

AddressInfo {
  valid: bool
  bech32: string | null
  hex: string | null
  error: string | null
}

Invalid address syntax is represented as valid: false, not a JSON-RPC transport error.

Wallet identity and balance

WalletAddressInfo {
  address: string
  key_index: u32
  is_active: bool
}

WalletStatus {
  exists: bool
  address: string
  active_index: u32
  balance_micronoid: u64
  balance_noid: number
  utxo_count: usize
  address_count: u32
}

WalletBalance {
  balance_micronoid: u64
  balance_noid: number
  utxo_count: usize
  pending_outbound_micronoid: u64
  pending_incoming_micronoid: u64
  spendable_micronoid: u64
  spendable_noid: number
}

WalletUtxoInfo {
  slot_index: u32
  value_micronoid: u64
  creation_id: u64
  value_noid: number
  address: string
  key_index: u32
  confirmed_height: u64
  reserved: bool
}

WalletHistoryEntry {
  tx_hash: string
  height: u64
  direction: "sent" | "received"
  is_coinbase: bool
  amount_micronoid: u64
  amount_noid: number
  peer_address: string | null
  timestamp: u64
  own_address: string | null
  own_key_index: u32 | null
}

Wallet send and consolidation

WalletSendPlan {
  amount_micronoid: u64
  fee_micronoid: u64
  total_spend_micronoid: u64
  input_count: usize
  output_count: usize
  change_micronoid: u64
  fee_breakdown: FeeBreakdownInfo
}

WalletSendResult {
  txid: string
  amount_micronoid: u64
  fee_micronoid: u64
  input_count: usize
  output_count: usize
}

WalletConsolidationPlan {
  input_value_micronoid: u64
  fee_micronoid: u64
  output_value_micronoid: u64
  balance_before_micronoid: u64
  balance_after_micronoid: u64
  input_count: usize
  untouched_count: usize
  remaining_count: usize
  freed_slots: usize
  selected_input_slots: u32[]
  fee_breakdown: FeeBreakdownInfo
}

WalletConsolidationResult {
  txid: string
  input_value_micronoid: u64
  fee_micronoid: u64
  output_value_micronoid: u64
  input_count: usize
  output_count: usize
  freed_slots: usize
}

Wallet scan and pages

WalletScanResult {
  found_utxos: usize
  balance_micronoid: u64
  balance_noid: number
  active_index: u32
  snapshot_height: u64
  snapshot_tip_hash: string
  snapshot_state_root: string
}

WalletReceiptsPage {
  page: u32
  page_size: u32
  total: usize
  total_pages: u32
  receipts: WalletReceiptInfo[]
}

WalletReceiptInfo {
  txid: string
  height: u64
  timestamp: u64
  amount_micronoid: u64
  fee_micronoid: u64
  peer_address: string | null
  own_address: string | null
  own_key_index: u32 | null
  input_count: usize
  output_count: usize
  receipt_bytes: usize
}

WalletMinedBlocksPage {
  page: u32
  page_size: u32
  total: usize
  total_pages: u32
  blocks: WalletMinedBlockInfo[]
}

WalletMinedBlockInfo {
  height: u64
  block_hash: string
  coinbase_txid: string
  timestamp: u64
  reward_micronoid: u64
  reward_noid: number
  payout_address: string
  payout_key_index: u32
  confirmations: u64
  full_block_available: bool
}

Receipt verification

ReceiptVerifyResult {
  merkle_valid: bool
  canonical: bool
  confirmed: bool
  error: string | null
  authenticated_summary?: ReceiptSummaryInfo
}

ReceiptSummaryInfo {
  txid: string
  claimed_height: u64
  confirmed_unix: u64
  tx_index: u16
  tx_count: u16
  fee_micronoid: u64
  inputs: ReceiptInputInfo[]
  outputs: ReceiptOutputInfo[]
}

ReceiptInputInfo {
  slot_index: u32
  owner: string
}

ReceiptOutputInfo {
  slot_index: u32
  amount_micronoid: u64
  owner: string
}

authenticated_summary is present only when the Merkle proof is valid.

External template

BlockTemplateResponse {
  template_id: string
  pow_fields_hex: string
  nonce_field_index: usize
  difficulty_target_hex: string
  height: u64
  expires_in_seconds: u64
  n_txs: usize
  tx_input_counts?: usize[]
  tx_output_counts?: usize[]
  coinbase_value_micronoid: u64
  claimable_fees_micronoid: u64
}

pow_fields_hex contains 16 consecutive 16-byte little-endian fields. The worker replaces field nonce_field_index, canonically 10.

Errors

Standard JSON-RPC parse, invalid-request, method and parameter errors use the normal JSON-RPC codes.

Application failures normally use:

-32000

with a human-readable message.

One wallet planning error has a stable machine-readable contract:

{
  "code": -32011,
  "message": "InputLimitExceeded",
  "data": {
    "max_inputs": 504
  }
}

This means sufficient value may exist, but no legal payment can be built inside the canonical input bound.

Clients should:

1. test HTTP status before decoding JSON;
2. inspect the JSON-RPC error object;
3. branch on documented stable codes;
4. present other application messages to the operator without parsing their prose.

Contract-held outputs are queried through the object methods. Ordinary wallet balance methods enumerate wallet owners and do not include arbitrary contract commitments. getTx retains an index pointer after body pruning.