Complete reference for all HTTP endpoints exposed by the Rivellum node RPC and the Mist indexer. Use these directly for custom integrations, dashboards, or when the SDK is not available.

Base URLs

All responses are JSON. All endpoints accept CORS from any origin.

Node RPC API

Health

GET /health

Returns node health status.

{
  "status": "ok",
  "service": "rivellum-node"
}

GET /v1/chain

Returns protocol version, chain ID, genesis hash, and active feature flags.

{
  "version": "1.2.0",
  "chain_id": "rivellum-mainnet",
  "genesis_hash": "hex...",
  "features": {
    "batching_enabled": true,
    "move_vm_enabled": true,
    "governance_enabled": true,
    "committee_rotation_enabled": true,
    "slashing_enabled": false,
    "light_client_enabled": true,
    "bridge_enabled": true,
    "private_intents_enabled": true,
    "zk_proofs_enabled": true
  }
}

Accounts & Balances

GET /v1/balance/{address}

Returns the native balance, nonce, and all asset sub-balances for an address.

Path params:

• address — 32-byte hex address (64 chars, no 0x prefix)

{
  "address": "a1b2...c3d4",
  "balance": "1000000000",
  "nonce": 42,
  "balances": {
    "assetId_hex": "500000"
  }
}

GET /v1/nonce/{address}

Returns the current nonce for an address.

{ "nonce": 42 }

GET /v1/state_roots

Returns the current ledger state root.

{
  "global_height": 123456,
  "meta_root": "hex...",
  "intent_count": 987654
}

Envelope Submission & Lifecycle

POST /v1/submit_envelope

Submit a single encrypted envelope. This is the canonical intent submission method.

Request body:

{
  "sender": "hex_64chars",
  "nonce": 42,
  "lane_hint": 3,
  "epoch_id": 100,
  "max_fee": "5000",
  "encrypted_payload": "hex_ciphertext",
  "signature": "dilithium3_sig_hex"
}

Response:

{
  "status": "accepted",
  "envelope_id": "hex_64chars",
  "batch_window_id": "hex..."
}

On rejection:

{
  "status": "rejected",
  "envelope_id": "hex_64chars",
  "rejection_reason": "nonce_too_low"
}

POST /v1/submit_envelope_batch

Submit up to 10,000 envelopes in one request. Body is a JSON array of envelope objects (same schema as single submit). Each envelope is validated independently.

{ "accepted": 9998, "rejected": 2 }

GET /v1/envelope/{envelope_id}/status

Returns the lifecycle stage of an envelope.

Path params:

• envelope_id — 64-hex envelope identifier

{
  "envelope_id": "hex...",
  "status": "finalized",
  "sender": "hex...",
  "nonce": 42,
  "lane_id": "hex...",
  "epoch_id": 100,
  "max_fee": "5000",
  "batch_id": "hex...",
  "rejection_reason": null,
  "admitted_at_ms": 1700000000000,
  "sealed_at_ms": 1700000001000,
  "intent_id": "uuid..."
}

Status values:

Returns 404 if envelope not found.

GET /v1/batch/{batch_id}

Returns metadata for a sealed batch.

{
  "batch_id": "hex...",
  "lane_id": "hex...",
  "epoch_id": 100,
  "state": "sealed",
  "envelope_count": 1200,
  "total_bytes": 240000,
  "seal_hash": "hex...",
  "envelope_ids": ["hex...", "..."],
  "sealed_at_ms": 1700000001000
}

Batch states: filling → sealed → decrypted → ordered → dispatched

GET /v1/admission/ticket/{intent_id}

Returns the admission ticket for an intent.

{
  "ticket": {
    "admission_id": "uuid...",
    "sender": "hex...",
    "validated_nonce": 42,
    "intent_id": "uuid...",
    "idempotency_key": null,
    "accepted_at_ms": 1700000000000,
    "status": "finalized"
  }
}

Returns 404 if not found.

Events & History

GET /v1/events/query

Query ledger events with filters and pagination.

Query params:

{
  "events": [
    {
      "event_id": "uuid...",
      "intent_id": "uuid...",
      "topic": "native.transfer",
      "contract": "hex...",
      "batch_height": 12345,
      "timestamp_ms": 1700000000000,
      "data": { "from": "hex...", "to": "hex...", "amount": "1000000" }
    }
  ],
  "next_cursor": "cursor_token",
  "total": 9999
}

Common topics:

• native.transfer — native token transfer
• native.mint — token mint
• native.burn — token burn
• native.asset_transfer — custom asset transfer
• contract.deployed — new contract deployed

Pagination example:

GET /v1/events/query?topic=native.transfer&limit=100
→ next_cursor: "abc123"

GET /v1/events/query?topic=native.transfer&limit=100&from_cursor=abc123
→ next page

GET /v1/events/recent

Returns recently executed intents, deduplicated and sorted by batch height descending.

Query params:

• limit — max number of results (default 50, max 1000)

{
  "events": [...],
  "total": N
}

PoUW (Proof of Useful Work)

GET /v1/pouw/provers

Returns statistics for all registered provers.

[
  {
    "prover_id": "hex...",
    "jobs_completed": 5000,
    "jobs_failed": 12,
    "total_fee_earned": "125000000",
    "avg_completion_time_ms": 4200.5,
    "last_seen_ms": 1700000000000
  }
]

GET /v1/pouw/jobs/pending

Returns pending proof jobs.

[
  {
    "job_id": "hex...",
    "tier": "High",
    "trace_hash": [1, 2, 3, ...],
    "fee_budget": "50000",
    "created_at_ms": 1700000000000,
    "deadline_ms": 1700000060000
  }
]

Native Ledger

GET /native-ledger/balance/{address}/{asset_id}

Returns the balance of a specific asset for an account.

{
  "address": "hex...",
  "asset_id": "hex...",
  "balance": "1000000"
}

GET /native-ledger/balances/{address}

Returns all asset balances for an account.

[
  { "address": "hex...", "asset_id": "hex...", "balance": "1000000" },
  { "address": "hex...", "asset_id": "hex...", "balance": "500000" }
]

POST /native-ledger/transfer

Transfer tokens.

{
  "from": "hex...",
  "to": "hex...",
  "asset_id": "hex...",
  "amount": "1000000",
  "privacy": true,
  "max_gas": 10000
}

POST /native-ledger/mint / POST /native-ledger/burn

Same structure with account instead of from/to.

POST /native-ledger/estimate-gas/transfer / …/mint / …/burn

Estimate gas without submitting.

{
  "base_gas": 500,
  "privacy_overhead": 2000,
  "total_gas": 2500,
  "fee_estimate": "2500"
}

GET /native-ledger/events

Query native ledger events.

Query params: asset_id, account, from_height, to_height, cursor, limit

Constraint Engine

GET /v1/constraints/asset/{asset_id}

Returns the constraint binding and policy for an asset.

{
  "asset_id": "hex...",
  "constrained": true,
  "policy_id": "hex...",
  "paused": false,
  "capabilities": ["transfer", "mint"]
}

GET /v1/constraints/preflight

Dry-run a constraint check.

Query params: asset_id, sender, receiver, amount

{
  "allowed": true
}

On denial:

{
  "allowed": false,
  "denial_reason": "sender_frozen"
}

GET /v1/constraints/policy/{policy_id}

Returns the policy definition.

GET /v1/constraints/frozen/{asset_id}/{account}

Returns freeze status.

{ "frozen": false }

Governance

GET /governance/params

Returns current governance parameters.

{
  "params": {
    "epoch_length_slots": 600,
    "slot_duration_ms": 500,
    "max_committee_size": 10,
    "min_stake_to_propose": "1000000",
    "voting_period_slots": 600,
    "execution_delay_slots": 100
  }
}

GET /governance/history

Returns the governance parameter change history.

{
  "changes": [
    {
      "key": "epoch_length_slots",
      "old_value": "500",
      "new_value": "600",
      "proposed_at_slot": 10000,
      "activation_slot": 10100,
      "proposed_by": "hex..."
    }
  ]
}

POST /governance/propose / POST /governance/vote / POST /governance/execute

Governance lifecycle endpoints. See Core TS SDK for request/response schemas.

Epoch

Derived from /governance/params + /v1/state_roots

Epoch ID = floor(global_height / epoch_length_slots)

epoch_id = global_height // epoch_length_slots
start_height = epoch_id * epoch_length_slots
end_height = (epoch_id + 1) * epoch_length_slots - 1
progress = (global_height % epoch_length_slots) / epoch_length_slots

Randomness

GET /randomness/beacon/latest

Returns the latest VRF randomness beacon.

{
  "height": 12345,
  "output": "hex...",
  "proof": "hex...",
  "producer": "hex...",
  "timestamp_ms": 1700000000000,
  "verified": true
}

NFTs

GET /nfts/{nft_id}

Returns NFT metadata.

GET /nfts/owned/{address}?page=1&limit=50

Returns NFTs owned by an address (paginated).

GET /nfts/{nft_id}/transfers?page=1&limit=50

Returns transfer history for an NFT.

GET /collections?page=1&limit=50

Lists all collections.

GET /collections/{collection_id}

Returns collection metadata.

GET /collections/{collection_id}/nfts?page=1&limit=50

Lists NFTs in a collection.

Bridge

GET /bridge/messages?status=&chain=&direction=

Returns bridge messages with optional filters.

Query params: status, chain, direction (inbound|outbound)

POST /bridge/lock

Lock assets on Rivellum for bridging.

{
  "from": "hex...",
  "asset": "hex...",
  "amount": "1000000",
  "destination_chain": "ethereum-mainnet",
  "foreign_recipient": "0x..."
}

POST /bridge/mint

Mint bridged assets after proof from foreign chain.

Cross-Chain Messaging (XCM)

GET /xcm/messages?source_chain=&dest_chain=&src_address=&dest_address=&status=&limit=&cursor=

Lists XCM messages with filters and pagination.

GET /xcm/message/{msg_id}

Returns full details for a specific XCM message.

Simulation

POST /intents/simulate

Dry-run an intent without committing state.

Request:

{
  "intent": { ... },
  "at_height": 12345,
  "max_gas_override": 100000,
  "validate_signature": false
}

Response:

{
  "status": "success",
  "gas_used": 1500,
  "fee_estimate": "1500",
  "state_diff": {
    "touched_accounts": ["hex..."],
    "balance_changes": [["hex...", "asset_hex", "-1000000"], ["hex...", "asset_hex", "+1000000"]]
  }
}

Light Client

GET /batches/{batch_id}/proof-bundle

Returns the ZK proof bundle for a sealed batch (for light client verification).

{
  "batch": { "batch_id": "hex...", "height": 12345, "intent_count": 1200 },
  "traceProofs": [ { "trace_hash": "hex...", "proof": "hex..." } ],
  "batchProof": null
}

Prefabs

GET /prefabs?category=CASUAL|WORLD|UNIVERSAL

Lists available prefab contracts.

GET /prefabs/manifest

Returns the full prefab manifest (cached 5 minutes).

Tokenomics (Public Indexer)

Base: https://api.rivellum.network

Fee distribution: 65% validator/proving pool · 25% Rivellum treasury · 10% burn

Analytics (Public Indexer)

Base: https://api.rivellum.network

Protocol

GET /protocol/upgrades

Returns all past and scheduled protocol upgrades.

Mist Contract Indexer API

Base: https://mist-indexer.rivellum.network

The Mist indexer indexes all deployed contracts, execution receipts, PVI dependency graphs, and settlement effects from the Mist VM.

Health

GET /healthz

{
  "status": "ok",
  "service": "rivellum-mist-indexer",
  "version": "1.0.0"
}

Statistics

GET /api/stats

Returns aggregate statistics about the Mist indexer.

{
  "total_contracts": 4200,
  "total_receipts": 9800000,
  "latest_slot": 1234567
}

Contracts

GET /api/contracts?deployer=&limit=50&offset=0

Lists indexed Mist contracts with optional filters.

Query params:

{
  "items": [
    {
      "contract_id": "hex...",
      "code_hash": "hex...",
      "deployer": "hex...",
      "contract_name": "MyCounter",
      "deployed_at": "2024-01-01T00:00:00Z",
      "deployed_slot": 10000,
      "bundle_size_bytes": 4096,
      "pvi_spec_version": 1,
      "compiler_hash": "hex...",
      "intent_id": "uuid..."
    }
  ],
  "limit": 50,
  "offset": 0
}

GET /api/contracts/{id}

Returns full metadata for a single contract.

Path params:

• id — contract ID (hex)

Returns 404 {"error": "contract_not_found", "contract_id": "..."} if not found.

Receipts

GET /api/receipts?contract_id=&status=&min_slot=&max_slot=&cursor=&limit=

Lists execution receipts with optional filters and cursor-based pagination.

Query params:

{
  "items": [
    {
      "receipt_id": "uuid...",
      "intent_id": "uuid...",
      "contract_id": "hex...",
      "function_name": "transfer",
      "is_deploy": false,
      "status": "ok",
      "failure_code": null,
      "failure_detail": null,
      "slot": 123456,
      "settled_at": "2024-01-01T00:00:00Z",
      "fee_charged": 1500,
      "execution_hash": "hex...",
      "receipt_json": { ... }
    }
  ],
  "next_cursor": "cursor_token",
  "total": 9800000
}

Receipt fields:

GET /api/receipts/{id}

Returns a single receipt by ID.

Returns 404 {"error": "receipt_not_found", "id": "..."} if not found.

PVI Graphs

GET /api/receipts/{id}/pvi

Returns the PVI (Public Verifiable Interface) dependency graph for a receipt. Used for verifying execution correctness.

{
  "receipt_id": "uuid...",
  "pvi_graphs": [
    {
      "node_id": "hex...",
      "receipt_id": "uuid...",
      "node_type": "transfer_source",
      "asset": "hex...",
      "amount": 1000000,
      "account": "hex...",
      "weight_bp": 10000,
      "condition": null
    }
  ]
}

PVI node fields:

Settlement Effects

GET /api/receipts/{id}/effects

Returns the balance changes (settlement effects) produced by a receipt.

{
  "receipt_id": "uuid...",
  "effects": [
    {
      "receipt_id": "uuid...",
      "account": "hex...",
      "asset": "hex...",
      "delta": -1000000,
      "balance_after": 9000000
    },
    {
      "receipt_id": "uuid...",
      "account": "hex...",
      "asset": "hex...",
      "delta": 1000000,
      "balance_after": 2000000
    }
  ]
}

Effect fields:

Replay Inputs

GET /api/receipts/{id}/replay

Returns the full raw receipt JSON for local replay and debugging.

{
  "receipt_id": "uuid...",
  "replay_inputs": { ... }
}

Pagination

The Node RPC uses cursor-based pagination for event queries. The Mist indexer also supports cursor pagination for receipts plus offset pagination for contracts.

Cursor Pagination Pattern

GET /v1/events/query?topic=native.transfer&limit=100
→ { "events": [...], "next_cursor": "abc123" }

GET /v1/events/query?topic=native.transfer&limit=100&from_cursor=abc123
→ { "events": [...], "next_cursor": "def456" }

Cursors are opaque tokens — do not parse or construct them manually. A missing or null next_cursor means you have reached the end.

Error Responses

All endpoints return structured errors:

{ "error": "error_code_string" }
{ "error": "error description", "contract_id": "optional_context" }

Common HTTP status codes:

Rate Limits

Public endpoints are rate-limited per IP. For high-throughput use cases, run your own node or contact the team for a dedicated API key.

Typical limits:

• Event queries: 100 req/min
• Balance queries: 300 req/min
• Envelope submission: 1000 req/min