Developers › API Reference

JSON-RPC Reference

Lichen exposes a JSON-RPC 2.0 API for querying blockchain state and submitting transactions. Every validator node runs the RPC server, typically on port 8899. Requests are rate-limited per IP (configurable, default 100 req/s). A companion WebSocket API provides real-time event subscriptions on port 8900.

Implementation-verified surface for v0.5.203: the live server exposes native, Solana-compatible, and EVM-compatible JSON-RPC dispatch, plus REST route families across the DEX, prediction market, launchpad, shielded APIs, and Neo X route/rewards reads. Neo route RPC coverage remains compatible with the original v0.5.197 baseline.

Endpoint & Format

Public testnet endpoint: https://testnet-api.lichen.network

Mainnet endpoint target: https://rpc.lichen.network

The request examples below use public testnet. Swap to the mainnet endpoint only when you are ready to target mainnet.

All requests are HTTP POST with Content-Type: application/json.

Security model: Production TLS terminates at the repo-managed Caddy reverse proxy. Raw RPC and WebSocket listeners on 8899/8900 or 9899/9900 are internal-only and direct public exposure is unsupported.

JSON 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "METHOD_NAME",
  "params": [...]
}

Successful responses contain a result field. Errors contain an error object with code and message.

Units: All LICN amounts are returned in spores (1 LICN = 1,000,000,000 spores) unless a separate lichen field is provided.

Chain Methods

getSlot

Returns the current slot number of the chain tip.

Parameters

None

Returns

u64 — Current slot number.

cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSlot","params":[]}'

# Response
{"jsonrpc":"2.0","id":1,"result":42}

getLatestBlock

Returns the most recently produced block.

Parameters

None

Returns

Object — { slot, hash, commit_round, parent_hash, state_root, tx_root, timestamp, validator, transaction_count }

cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getLatestBlock","params":[]}'

# Response
{"jsonrpc":"2.0","id":1,"result":{
  "slot":42,"hash":"a1b2c3...","parent_hash":"d4e5f6...",
  "state_root":"abc...","tx_root":"def...","transaction_count":5,
  "timestamp":1738800000,"validator":"7xK..."
}}

getRecentBlockhash

Returns a recent blockhash required for signing transactions. The blockhash is valid for a limited number of slots.

Parameters

None

Returns

Object — { blockhash, slot }, where blockhash is the hex-encoded hash of the latest block.

cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getRecentBlockhash","params":[]}'

# Response
{"jsonrpc":"2.0","id":1,"result":{"blockhash":"a1b2c3d4e5f6...","slot":3382206}}

getHealth

Returns node health status. Use this as a liveness probe.

Parameters

None

Returns

Object — { status, reason, slot, block_age_secs?, disk? }. The disk object includes available_bytes, total_bytes, used_percent, and critical when disk readiness is available.

cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth","params":[]}'

# Response
{"jsonrpc":"2.0","id":1,"result":{"status":"ok","reason":"ok","slot":3382206,"block_age_secs":0}}

getMetrics

Returns current chain performance metrics including TPS, total transactions, total blocks, and average block time.

Parameters

None

Returns

Object — { tps, peak_tps, total_transactions, daily_transactions, total_blocks, average_block_time, avg_block_time_ms, avg_txs_per_block, total_accounts, active_accounts, total_supply, projected_supply, circulating_supply, total_burned, total_minted, total_staked, treasury_balance, total_contracts, validator_count, slot_duration_ms, fee_burn_percent, current_epoch, slots_into_epoch, inflation_rate_bps }

cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getMetrics","params":[]}'

# Response
{"jsonrpc":"2.0","id":1,"result":{
    "tps":120.0,
    "peak_tps":180.0,
    "total_transactions":500000,
    "daily_transactions":12000,
    "total_blocks":42000,
    "average_block_time":0.8,
    "avg_block_time_ms":800.0,
    "avg_txs_per_block":11.9,
    "total_accounts":18420,
    "active_accounts":6912,
    "total_supply":500000000000000000,
    "projected_supply":500000012500000000,
    "circulating_supply":421500000000000000,
    "total_burned":2200000000,
    "total_minted":12500000000,
    "total_staked":185000000000000,
    "treasury_balance":32000000000000,
    "total_contracts":29,
    "validator_count":5,
    "slot_duration_ms":800,
    "fee_burn_percent":40,
    "current_epoch":12,
    "slots_into_epoch":3456,
    "inflation_rate_bps":395
}}

getChainStatus

Returns comprehensive chain status including current slot, validator count, total stake, TPS, transaction & block counts, average block time, and health flag.

Parameters

None

Returns

Object — { slot, _slot, epoch, _epoch, block_height, _block_height, current_slot, latest_block, validator_count, validators, _validators, total_stake, total_staked, tps, peak_tps, total_transactions, total_blocks, average_block_time, block_time_ms, total_supply, projected_supply, total_burned, total_minted, peer_count, chain_id, network, is_healthy, inflation_rate_bps }

cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":1,"method":"getChainStatus","params":[]}'

# Response
{"jsonrpc":"2.0","id":1,"result":{
    "slot":12345,
    "_slot":12345,
    "epoch":12,
    "_epoch":12,
    "block_height":12345,
    "_block_height":12345,
    "current_slot":12345,
    "latest_block":12345,
    "validator_count":5,
    "validators":5,
    "_validators":5,
    "total_stake":185000000000000,
    "total_staked":185000000000000,
    "tps":120.0,
    "peak_tps":180.0,
    "total_transactions":500000,
    "total_blocks":42000,
    "average_block_time":0.8,
    "block_time_ms":800.0,
    "total_supply":500000000000000000,
    "projected_supply":500000012500000000,
    "total_burned":2200000000,
    "total_minted":12500000000,
    "peer_count":8,
    "chain_id":"lichen-testnet-1",
    "network":"testnet",
    "is_healthy":true,
    "inflation_rate_bps":395
}}

Account Methods

getBalance

Returns the LICN balance for the given public key, in both spores (raw) and LICN.

Parameters

Name Type Required Description
pubkey string Yes Base58-encoded public key

Returns

Object — { spores, licn, spendable, spendable_licn, staked, staked_licn, locked, locked_licn, moss_staked, moss_staked_licn, moss_value, moss_value_licn }. LICN values are decimal strings; spore values are integers.

cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getBalance","params":["7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"]}'

# Response
{"jsonrpc":"2.0","id":1,"result":{"spores":5000000000,"licn":"5.0000","spendable":5000000000,"spendable_licn":"5.0000","staked":0,"staked_licn":"0.0000","locked":0,"locked_licn":"0.0000","moss_staked":0,"moss_staked_licn":"0.0000","moss_value":0,"moss_value_licn":"0.0000"}}

getAccount

Returns raw account data including balance, owner, executable flag, and data field.

Parameters

Name Type Required Description
pubkey string Yes Base58-encoded public key

Returns

Object — { pubkey, evm_address, spores, licn, spendable, spendable_licn, staked, staked_licn, locked, locked_licn, owner, executable, data_len }. LICN values are decimal strings; spore values are integers.

cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getAccount","params":["7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"]}'

getAccountProof

Returns an anchored inclusion proof for an existing account and binds it to the requested block commitment context. This is an inclusion-proof surface for existing accounts, not a full authenticated-state or non-existence-proof protocol.

Parameters

Name Type Required Description
pubkey string Yes Base58-encoded public key for an existing account
commitment string No Anchor context to use: processed, confirmed, or finalized. Defaults to finalized.

Returns

Object — { pubkey, account_data, inclusion_proof, anchor }. The inclusion_proof.proof_type is sparse_v1.

Notes

  • Returns an error if the account does not exist or if the proof cannot be anchored to the requested block context.
  • sparse_v1 proofs include sparse_path and steps.
  • anchor.root_source is header_state_root when the proof root matches the block header, or post_state_v1 when it matches the canonical post-block sidecar anchor for that slot.
  • Proof reads wait behind the canonical block-apply barrier. They are existing-account inclusion proofs and do not provide non-existence proofs.
cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getAccountProof","params":["7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU", {"commitment":"finalized"}]}'

# Response
{"jsonrpc":"2.0","id":1,"result":{
  "pubkey":"7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "account_data":"deadbeef...",
  "inclusion_proof":{
    "proof_type":"sparse_v1",
    "leaf_hash":"...",
    "siblings":[],
    "path":[],
    "sparse_path":"...",
    "steps":[{"prefix_bits":12,"prefix":"...","sibling":"...","target_went_right":true}]
  },
  "anchor":{
    "slot":1,
    "commitment":"finalized",
    "root_source":"post_state_v1",
    "state_root":"...",
    "header_state_root":"...",
    "block_hash":"...",
    "commit_round":0
  }
}}

getAccountAtSlot

Returns historical account state at or before the given slot. Non-development testnet and mainnet validators enable archive mode automatically and retain old block, transaction, index, and account-snapshot history in the canonical sibling cold store.

Parameters

Name Type Required Description
pubkey string Yes Base58-encoded public key
slot integer Yes Target slot number (returns latest snapshot at or before this slot)

Returns

Object — { pubkey, slot, spores, licn, spendable, staked, locked, owner, executable, data_len }

Errors

  • -32003 — Archive mode is not enabled on this node
  • -32001 — No snapshot found for the account at or before the given slot
cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getAccountAtSlot","params":["7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU", 1000]}'

getAccountInfo

Returns enhanced account information including balance, transaction count, and additional metadata.

Parameters

Name Type Required Description
pubkey string Yes Base58-encoded public key

Returns

Object — Enhanced account details with balance, owner, executable flag, transaction history summary.

cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getAccountInfo","params":["7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"]}'

getAccountTxCount

Returns the number of transactions involving the given account.

Parameters

Name Type Required Description
pubkey string Yes Base58-encoded public key

Returns

Object — { address, count }.

Block Methods

getBlock

Returns a block by its slot number, including header fields and transaction list.

Parameters

Name Type Required Description
slot u64 Yes Slot number of the block

Returns

Object — { slot, hash, commit_round, parent_hash, state_root, tx_root, timestamp, validator, transaction_count, transactions, block_reward, commit_signatures, commit_validator_count }

cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getBlock","params":[42]}'

# Response
{"jsonrpc":"2.0","id":1,"result":{
  "slot":42,"hash":"a1b2...","parent_hash":"d4e5...",
  "state_root":"abc...","tx_root":"def...","transaction_count":2,
  "transactions":[...],"timestamp":1738800000
}}

getBlockCommit

Returns the canonical finality certificate for a block. For a non-tip block produced by the current protocol, the certificate is committed by its child and independently verified before it is served.

Parameters

[slot], where slot is an unsigned block height.

Returns

Object containing slot, block_hash, certificate_version, validators_hash, exact sorted validator_powers, parent_post_state_root, commit_round, commit_signatures, commit_validator_count, commit_source, and bft_timestamp.

commit_source = canonical_child is the archive-stable proof. A local_pending_child response is tip-local evidence until the next block commits it.

cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getBlockCommit","params":[42]}'

Transaction Methods

getTransaction

Returns detailed transaction information by its signature hash.

Parameters

Name Type Required Description
signature string Yes Hex-encoded transaction signature

Returns

Object — Transaction details including signatures, instructions, slot, timestamp, fee, and status.

Hash fields:

  • signature — Canonical transaction ID: SHA-256(bincode(message) || sig_0 || sig_1 || ...). Includes signatures for unique deduplication (matches Cosmos/CometBFT and Bitcoin wtxid convention).
  • message_hash — Message-only hash: SHA-256(bincode(message)). Signature-independent — useful for multi-sig coordination and client-side txid prediction before all parties have signed.

Contract execution fields (present for contract call transactions):

  • return_code — Raw WASM return value. For contracts with ABI result_semantics, validators use this field to decide commit versus revert. Omitted when null.
  • return_data — Base64-encoded bytes set via set_return_data(). Omitted when empty.
  • contract_logs — Array of log strings emitted via log(). Omitted when empty.
cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getTransaction","params":["a1b2c3d4..."]}'

sendTransaction

Submits a signed, serialized transaction to the mempool. The transaction must be a base64-encoded lichen_tx_v1 envelope with chain-ID-domain signatures.

Parameters

Name Type Required Description
transaction string Yes Base64-encoded lichen_tx_v1 envelope

Returns

string — Hex-encoded transaction signature.

cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"sendTransaction","params":["BASE64_ENCODED_TX"]}'

# Response
{"jsonrpc":"2.0","id":1,"result":"a1b2c3d4e5f6..."}

simulateTransaction

Dry-runs a transaction without committing it to the chain. Useful for estimating fees and checking validity.

Parameters

Name Type Required Description
transaction string Yes Base64-encoded serialized transaction

Returns

Object — Simulation result with logs, runtime error messages, and returnCode for contract-level result inspection.

Debugging tip: A transaction can be structurally valid but contract-semantically rejected. Inspect success, runtime errors, ABI result_semantics, and returnCode together.

getTransactionsByAddress

Returns a list of transactions involving the given address.

Parameters

Name Type Required Description
pubkey string Yes Base58-encoded public key
options object No { limit?: number, before_slot?: number }; newest first, default limit 50

Returns

Object — { transactions, has_more, next_before_slot }. Each transaction includes amount in LICN and amount_spores in base units.

getTransactionProof

Returns a binary Merkle inclusion proof for a confirmed transaction. The proof can be used to verify that a transaction is included in a block's tx_root without downloading the entire block.

Parameters

Name Type Required Description
signature string Yes Hex-encoded transaction hash

Returns

Object with the following fields:

Field Type Description
slot u64 Block slot containing the transaction
tx_index u64 Index of the transaction within the block
tx_hash string Hex-encoded transaction hash (leaf)
root string Hex-encoded Merkle root (matches block tx_root)
proof array Array of proof steps, each with hash (hex) and direction ("left" or "right")

Example

curl -s https://testnet-api.lichen.network -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getTransactionProof","params":["a1b2c3d4..."]}'
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "slot": 162,
    "tx_index": 0,
    "tx_hash": "a1b2c3d4...",
    "root": "efca18b2...",
    "proof": [
      { "hash": "86bf5cf6...", "direction": "right" },
      { "hash": "d1f8afed...", "direction": "right" }
    ]
  }
}

Verification

The Merkle tree uses domain-separated SHA-256: leaves are prefixed with 0x00, internal nodes with 0x01. To verify a proof, start with the leaf hash SHA256(0x00 || tx_hash), then for each step combine with the sibling according to direction: SHA256(0x01 || left || right). The final result must equal the root.

Validator Methods

getValidators

Returns the list of all registered validators with their stake, reputation, blocks proposed, votes cast, and last active slot.

Parameters

None

Returns

Object — { validators: [ { pubkey, stake, reputation, blocks_proposed, transactions_processed, votes_cast, correct_votes, last_active_slot, last_vote_slot, bootstrap_debt, vesting_status, earned_amount, graduation_slot } ], count }

cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getValidators","params":[]}'

getValidatorInfo

Returns detailed information for a specific validator by its public key.

Parameters

Name Type Required Description
pubkey string Yes Validator's base58-encoded public key

Returns

Object — Validator details including stake, reputation, and performance counters.

getValidatorPerformance

Returns performance metrics for a validator including block production rate, vote accuracy, and uptime.

Parameters

Name Type Required Description
pubkey string Yes Validator's base58-encoded public key

Returns

Object — Performance metrics.

Staking Methods

getStakingStatus

Returns staking status for an account — active stake, delegated validator, rewards earned.

Parameters

Name Type Required Description
pubkey string Yes Staker's base58-encoded public key

Returns

Object — Staking status details.

getStakingRewards

Returns settled and projected staking reward details for the given account.

Parameters

Name Type Required Description
pubkey string Yes Staker's base58-encoded public key

Returns

Object — Reward details including pending_rewards (settled but unclaimed), projected_pending and projected_epoch_reward (current-epoch estimates), claimed_rewards / liquid_claimed_rewards (historical liquid rewards only), and claimed_total_rewards (liquid rewards plus bootstrap debt repayment already credited through claims).

getStakingPosition

Returns the account's MossStake position, including stLICN shares, deposited LICN, redeemable LICN value, lock tier, multiplier, and accrued rewards.

Parameters

Name Type Required Description
pubkey string Yes Staker's base58-encoded public key

Returns

Object including st_licn_amount, licn_deposited, current_value_licn, rewards_earned, lock_tier_name, reward_multiplier, and any position lock fields.

getMossStakePoolInfo

Returns MossStake pool-level metrics and the canonical tier table.

Parameters

None.

Returns

Object including total_supply_st_licn, total_licn_staked, exchange_rate, total_validators, average_apy_percent, total_stakers, tiers, and cooldown_days.

getUnstakingQueue

Returns pending MossStake unstake requests and the canonical claimability state for the requested account.

MossStake unstakes are slot-based. A request becomes claimable when current_slot >= claimable_at; LICN is not moved back to spendable balance automatically. Submit a MossStake claim transaction after maturity.

Parameters

Name Type Required Description
pubkey string Yes Staker's base58-encoded public key

Returns

Object with owner, pending_requests, total_claimable, current_slot, and cooldown_slots. Each pending request includes st_licn_amount, licn_to_receive, requested_at, claimable_at, claimable, remaining_slots, and estimated_remaining_seconds.

JSON
{
  "owner": "7xKX...",
  "pending_requests": [{
    "st_licn_amount": 11000000000,
    "licn_to_receive": 18134176580087,
    "requested_at": 3058382,
    "claimable_at": 4570382,
    "claimable": false,
    "remaining_slots": 280000,
    "estimated_remaining_seconds": 112000
  }],
  "total_claimable": 0,
  "current_slot": 4290382,
  "cooldown_slots": 1512000
}

getRewardAdjustmentInfo

Returns current reward adjustment parameters for staking economics.

Parameters

None.

Returns

Object including current_multiplier, target_price, current_price, totalSupply, projectedSupply, totalMinted, and inflationRateBps.

stake

Submits a signed stake transaction (system instruction opcode 9).

Parameters

Name Type Required Description
transaction_base64 string Yes Base64-encoded signed transaction payload. Call shape: stake([transaction_base64])

Returns

string — Transaction signature.

unstake

Submits a signed unstake transaction (system instruction opcode 10).

Parameters

Name Type Required Description
transaction_base64 string Yes Base64-encoded signed transaction payload. Call shape: unstake([transaction_base64])

Returns

string — Transaction signature.

Network Methods

getNetworkInfo

Returns network-level information including chain ID, network ID, version, current slot, validator count, and peer count.

Parameters

None

Returns

Object — { chain_id, network_id, version, current_slot, validator_count, peer_count }

cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getNetworkInfo","params":[]}'

getPeers

Returns a list of connected P2P peers.

Parameters

None

Returns

Object — { peers: [{ peer_id, address, connected }], count }

Contract Methods

getContractInfo

Returns information about a deployed smart contract including owner, code size, storage, call count, and token metadata. For tokens registered in the symbol registry, includes total_supply resolved from on-chain storage with a fallback to registry metadata.

Parameters

Name Type Required Description
contractId string Yes Base58-encoded contract public key

Returns

Object — Contract metadata including: contract_id, owner, code_size, is_executable, has_abi, abi_functions, code_hash, version.

For tokens registered in the symbol registry, also includes a token_metadata object:

Field Type Description
total_supply number Total supply in base units (resolved from on-chain storage, fallback to registry). JavaScript clients should treat large u64 values carefully once they exceed the safe-integer range.
decimals number Decimal precision (e.g. 9)
token_symbol string Registry symbol (e.g. "LICN")
token_name string Display name from registry metadata
mintable boolean Whether the contract has a mint function
burnable boolean Whether the contract has a burn function

The registry metadata JSON (set via --metadata at deploy) must be a flat object of strings, numbers, and booleans (1024 bytes max). Common profile fields: description, website, logo_url, twitter, telegram, discord. Capability flags such as mintable and burnable in getContractInfo are derived from the contract ABI.

cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getContractInfo","params":["ContractPubkey..."]}'

getAllContracts

Returns deployed contracts with pagination metadata.

Parameters

Optional: [{ limit, cursor }].

Returns

Object — { contracts, count, has_more, next_cursor }. Each contract entry includes program_id, registry metadata, owner, code size, ABI summary, and lifecycle fields.

getContractLogs

Returns execution logs emitted by a contract.

Parameters

Name Type Required Description
contractId string Yes Base58-encoded contract public key

Returns

Object — { logs, count }.

getContractAbi

Returns the ABI/IDL (machine-readable interface definition) for a contract, if one has been registered.

Parameters

Name Type Required Description
contractId string Yes Base58-encoded contract public key

Returns

Object — ABI JSON, or null if not set.

Program Methods

getProgram

Returns detailed information about a deployed program.

Parameters

Name Type Required Description
programId string Yes Base58-encoded program public key

Returns

Object — Program info including owner, code size, deploy slot.

getPrograms

Returns a list of all deployed programs.

Parameters

Optional: [{ limit, cursor }].

Returns

Object — { programs, count, has_more, next_cursor }.

getProgramStats

Returns execution statistics for a program — call count, unique callers, storage used.

Parameters

Name Type Required Description
programId string Yes Base58-encoded program public key

Returns

Object — Program stats.

getProgramCalls

Returns recent call history for a program.

Parameters

Name Type Required Description
programId string Yes Base58-encoded program public key
options object No { limit?: number, before_slot?: number }; newest first, default limit 50

Returns

Object — { program, count, calls }.

getProgramStorage

Returns on-chain storage summary for a program.

Parameters

Name Type Required Description
programId string Yes Base58-encoded program public key
options object No { limit?: number, after_key?: string }; cursor-paginated by the last returned key_hex

Returns

Object — { program, count, entries }.

Token Methods

getTokenAccounts

Returns token balances held by a native Lichen address.

Parameters

Name Type Required Description
holder string Yes Base58-encoded native account address

Returns

Object — { accounts, count }. Each account entry includes mint, raw balance, ui_amount, decimals, symbol, and name.

getTokenBalance

Returns the balance of a specific token for an account.

Parameters

Name Type Required Description
owner string Yes Base58-encoded owner public key
tokenMint string Yes Base58-encoded token mint address

Returns

Object — Token balance details.

getTokenHolders

Returns a list of holders for a given token.

Parameters

Name Type Required Description
tokenMint string Yes Base58-encoded token mint address

Returns

Array — Token holder entries.

getTokenTransfers

Returns recent transfer events for a token.

Parameters

Name Type Required Description
tokenMint string Yes Base58-encoded token mint address

Returns

Array — Transfer event records.

NFT & Marketplace Methods

getCollection

Returns metadata for an NFT collection.

Parameters

Name Type Required Description
collectionId string Yes Base58-encoded collection public key

Returns

Object — Collection metadata (name, symbol, total supply, etc.).

getNFT

Returns a specific NFT by collection and token ID.

Parameters

Name Type Required Description
collectionId string Yes Collection public key
tokenId u64 Yes Token ID within the collection

Returns

Object — NFT details (owner, metadata URI, attributes).

getNFTsByOwner

Returns all NFTs owned by a given address.

Parameters

Name Type Required Description
owner string Yes Base58-encoded owner public key
options object No { limit?: number }

Returns

Object — { owner, count, nfts }.

getNFTsByCollection

Returns NFTs in a collection.

Parameters

[collection_pubkey, { limit?: number }?]

Returns

Object — { collection, count, nfts }.

getNFTActivity

Returns recent mint and transfer activity for a collection.

Parameters

[collection_pubkey, { limit?: number }?]

Returns

Object — { collection, count, activity }.

getMarketListings

Returns active marketplace listings with price, seller, and collection info.

Parameters

Array containing one options object — [{ collection?, limit?, price_min?, price_max?, seller?, sort_by? }].

Returns

Object — { collection, count, listings, filters }.

getMarketActivity

Returns recent marketplace activity, optionally filtered by collection, token, token ID, and limit.

Parameters

Array containing one options object — [{ collection?, token?, token_id?, limit? }].

Returns

Object — { collection, count, activity }.

getMarketSales

Returns recent marketplace sales history.

Parameters

Array containing one options object — [{ collection?, limit? }].

Returns

Object — { collection, count, sales }.

getMarketOffers

Returns active marketplace offers (bids) optionally filtered by collection or token.

Parameters

Array containing one options object — [{ collection?, token?, token_id?, include_collection_offers?, limit? }].

Returns

Object — { collection, count, offers }.

getMarketAuctions

Returns active and recent marketplace auctions with current bid state.

Parameters

Array containing one options object — [{ collection?, token?, token_id?, limit? }].

Returns

Object — { collection, count, auctions }.

Burn Methods

getTotalBurned

Returns the total amount of LICN that has been permanently burned (removed from circulation).

Parameters

None

Returns

Object — { spores: u64, licn: f64 }

cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getTotalBurned","params":[]}'

# Response
{"jsonrpc":"2.0","id":1,"result":{"spores":1500000000000,"licn":1500.0}}

Fee & Rent Methods

getFeeConfig

Returns the current fee configuration for the chain (base fee, priority fee multiplier).

Parameters

None

Returns

Object — { base_fee_spores, contract_deploy_fee_spores, contract_upgrade_fee_spores, nft_mint_fee_spores, nft_collection_fee_spores, fee_burn_percent, fee_producer_percent, fee_voters_percent, fee_treasury_percent, fee_community_percent }.

getRentParams

Returns the current rent parameters (rent per byte per epoch, rent-exempt minimum).

Parameters

None

Returns

Object — Rent parameters.

getSignedMetadataManifest

Returns the release-signed metadata envelope used by browser apps to verify token, symbol, and contract-resolution metadata.

Parameters

None

Returns

Object — { schema_version, manifest_type, signed_at, signer, payload, signature }.

Trust boundary: Wallet, DEX, Explorer, Marketplace, Monitoring, and Programs verify this envelope against the pinned release signer before trusting payload.symbol_registry. Custom RPC overrides stay transport-only for generic reads and do not replace this signer check.

cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSignedMetadataManifest","params":[]}'

# Response
{"jsonrpc":"2.0","id":1,"result":{
  "schema_version":1,
  "manifest_type":"signed_metadata",
  "signed_at":"2026-04-03T12:00:00Z",
  "signer":"7xK...ReleaseSigner",
    "payload":{"schema_version":1,"network":"testnet","generated_at":"2026-04-03T12:00:00Z","symbol_registry":[]},
  "signature":{"scheme_version":1,"public_key":{"scheme_version":1,"bytes":"..."},"sig":"..."}
}}

DEX REST Indexed Reads

The DEX market-data API is exposed through REST routes under /api/v1. Current orderbook, pair-trade, and trader-trade reads use persisted block-apply indexes that are rebuilt or backfilled from canonical DEX contract storage during startup, rather than scanning every order or trade on each request.

Indexed Routes

  • GET /api/v1/pairs/:id/orderbook?depth=20 — L2 orderbook levels from the persisted orderbook-level index. depth is capped at 100.
  • GET /api/v1/pairs/:id/trades?limit=50 — recent pair trades from the pair trade index. limit is capped at 200.
  • GET /api/v1/pairs/:id/trades?trader=<address>&limit=50 — pair trades filtered by taker address, accepting hex or Base58 account input.
  • GET /api/v1/traders/:address/trades?limit=50 — trader trade history across pairs from the taker trade index.

Read semantics: responses include the node's current slot and reflect canonical indexed state. If an older database is upgraded, the validator backfills the DEX indexes before serving the accelerated reads; clients should treat transient index read errors as node health/backfill issues rather than missing pairs.

Neo X Route, Reserves & Rewards

These methods are the public read surface for Neo X integration. They are read-only. Rewards and liquidity controls remain fail-closed until the public beta and liquidity corridor gates are approved for the selected network.

DEX pair reads use the same indexed getDexPairs path as the existing markets. Fresh genesis includes all launch wrapped markets: wNEO/lUSD pair/pool ID 8, wNEO/LICN ID 9, wGAS/lUSD ID 10, wGAS/LICN ID 11, wBTC/lUSD ID 12, and wBTC/LICN ID 13. Legacy/live-chain additions are additive only and must not rewrite historical state.

wNEO order entry and LP flows must preserve whole-NEO lots. Neo LP reward fields only accrue after a governed dex_rewards.configure_lp_campaign payload is approved; pair visibility alone does not mean incentives are active.

getBridgeRouteRestrictionStatus

Returns the governed pause state for an external bridge route. Neo routes use neox/gas for wGAS and neox/neo for whole-lot wNEO.

Parameters

[chain, asset] or an object with chain and asset.

cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getBridgeRouteRestrictionStatus","params":["neox","gas"]}'

getWneoStats

Returns wNEO supply, reserve attestation, pause, and circuit-breaker state. wNEO preserves whole-NEO lot semantics until official divisibility support is approved.

Parameters

None

Returns

Object containing supply, reserve_attested, reserve_ratio, attestation_count, last_attestation_slot, paused, and circuit-breaker fields when present.

cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getWneoStats","params":[]}'

getWgasStats

Returns wGAS supply, reserve attestation, pause, and circuit-breaker state for Neo X GAS deposits represented on Lichen.

Parameters

None

Returns

Object containing supply, reserve_attested, reserve_ratio, attestation_count, last_attestation_slot, paused, and circuit-breaker fields when present.

cURL
curl -X POST https://testnet-api.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getWgasStats","params":[]}'

getNeoGasRewardsStats

Returns storage-backed Neo GAS rewards vault accounting: configured state, caps, imported rewards, claims, evidence counters, stale-evidence slots, and disclosure/policy versions.

Parameters

None

Returns

Object containing configured, paused, wneo_token, wgas_token, cap fields, total_principal, total_imported, total_claimed, outstanding_claimable, evidence_count, last_evidence_slot, last_import_slot, disclosure_version, and policy_version.

getNeoGasRewardsPosition

Returns per-wallet Neo GAS rewards vault accounting.

Parameters

[address] where address is a Base58 Lichen account.

Returns

Object containing principal, claimable, claimed, reward_index, disclosure_accepted, and disclosure_version.

getNeoZkProofServiceStatus

Returns NX-960 Neo reserve/liability proof-service verifier metadata for wNEO, wGAS, and NEOGASRWD.

Returns

Object containing supported_proofs, zk_scheme, verifier_version, privacy_model, public_inputs, domain_separation, and verifier_method.

verifyNeoReserveLiabilityProof

Verifies a zk-prove reserve-liability proof envelope against its Plonky3 public inputs. Consumers must compare the proof domain to the route/asset they intended to consume.

Parameters

[proofEnvelope] with proof hex and stark_public_inputs.

Returns

Object containing verified, reserve_amount, liability_amount, solvency_margin, domain_hash, statement_hash, and witness_commitment.

Additional Implemented Methods

These JSON-RPC methods are implemented in the live server dispatch (`rpc/src/lib.rs`). Some entries below are compact cross-references to full method cards on this page.

RPC endpoints: use POST / for native Lichen JSON-RPC, POST /solana-compat for Solana-format compatibility methods, and POST /evm for EVM-compatible methods.

Chain / Account / Tx

  • confirmTransaction
  • getRecentTransactions
  • getTokenAccounts
  • getTreasuryInfo
  • getGenesisAccounts
  • getBlockCommit — BFT commit certificate for a block (signatures, voter set)
  • getGovernedProposal — query a governed transfer proposal by ID

Fee / Network / Validator

  • getOraclePrices — returns a top-level object { source, LICN, wSOL, wETH, wBNB, wNEO, wGAS, wBTC, lUSD }.
  • getClusterInfo

Liquid Staking

  • getStakingPosition
  • getMossStakePoolInfo
  • getUnstakingQueue
  • getRewardAdjustmentInfo

Contracts / Registry / Program

  • getContractEvents
  • getGovernanceEvents
  • getSignedMetadataManifest
  • getSymbolRegistry
  • getSymbolRegistryByProgram
  • getAllSymbolRegistry

LichenID / Names / Identity

  • getLichenIdIdentity, getLichenIdReputation, getLichenIdSkills, getLichenIdVouches, getLichenIdAchievements, getLichenIdProfile
  • resolveLichenName, reverseLichenName, batchReverseLichenNames, searchLichenNames
  • getLichenIdAgentDirectory, getLichenIdStats
  • getEvmRegistration, lookupEvmAddress

NFT / Market / Prediction / Platform Stats

  • getNFTsByCollection
  • getNFTActivity
  • getPredictionMarketStats, getPredictionMarkets, getPredictionMarket, getPredictionPositions, getPredictionTraderStats, getPredictionLeaderboard, getPredictionTrending, getPredictionMarketAnalytics
  • getDexCoreStats, getDexAmmStats, getDexMarginStats, getDexRewardsStats, getDexRouterStats, getDexAnalyticsStats, getDexGovernanceStats
  • getThallLendStats, getSporePayStats, getSporeVaultStats, getBountyBoardStats, getComputeMarketStats, getMossStorageStats, getLichenMarketStats, getLichenAuctionStats, getLichenPunksStats
  • getLusdStats, getWethStats, getWsolStats, getWbnbStats, getWneoStats, getWgasStats, getWbtcStats, getLichenBridgeStats, getLichenDaoStats, getLichenOracleStats
  • getNeoGasRewardsStats, getNeoGasRewardsPosition, getNeoZkProofServiceStatus, verifyNeoReserveLiabilityProof
  • requestAirdrop — testnet utility; params [address, amount_licn], where amount_licn is a whole integer from 1 to 10. Returns { success, signature, amount, amount_licn, recipient, message }.

Bridge

  • createBridgeDeposit — initiate a cross-chain bridge deposit with a wallet-signed bridge access auth object; each new deposit request must use a freshly signed auth envelope, while exact retries with the same request remain idempotent
  • getBridgeDeposit — query a bridge deposit by ID for the authenticated wallet address using the current unexpired bridge auth

Shielded Pool (Privacy)

  • getShieldedPoolState — query shielded pool state (tree size, root, nullifier count)
  • getShieldedMerkleRoot — current Merkle tree root
  • getShieldedMerklePath — Merkle proof for a leaf index
  • isNullifierSpent — check if a nullifier has been spent
  • getShieldedCommitments — list commitments in the tree, including encrypted wallet note payloads when present
  • computeShieldCommitment — compute commitment hash for shield operation
  • computeShieldNullifier — compute the native Poseidon2 nullifier from a note serial and spending key
  • generateShieldProof — generate ZK proof for shield (deposit)
  • generateUnshieldProof — generate ZK proof for unshield (withdraw)
  • generateTransferProof — generate ZK proof for private transfer

Contract Execution

  • callContract — execute a read-only contract call (no state change). Accepts optional from pubkey to set the calling context (defaults to zero address).
  • getNameAuction — query LichenID .lichen name auction by name

Solana-Format Endpoint (/solana-compat)

Accepts Lichen transactions in Solana wire format. Does not accept native Solana transactions.

  • getLatestBlockhash, getRecentBlockhash, getBalance, getAccountInfo, getBlock, getBlockHeight, getSignaturesForAddress, getSignatureStatuses, getSlot, getTransaction, getTokenAccountsByOwner, getTokenAccountBalance, sendTransaction, getHealth, getVersion

EVM-Compatible Endpoint (/evm)

  • eth_getBalance, eth_sendRawTransaction, eth_call, eth_chainId, eth_blockNumber, eth_getTransactionReceipt, eth_getTransactionByHash, eth_accounts, net_version
  • eth_gasPrice, eth_maxPriorityFeePerGas, eth_estimateGas, eth_getCode, eth_getTransactionCount
  • eth_getBlockByNumber, eth_getBlockByHash, eth_getLogs, eth_getStorageAt
  • net_listening, web3_clientVersion

Looking for real-time events? Check out the WebSocket Reference for subscription-based streaming of blocks, transactions, and account changes.