Reference
Testnet · v1.10 · all tests passing
Estimated read time: 9 minutes
JSON-RPC API
Endpoint and shape
Every Valdium node exposes a JSON-RPC 2.0 endpoint over HTTP and WebSocket. The public testnet endpoint is https://testnet.valdium.xyz/rpc (HTTP) and wss://testnet.valdium.xyz/ws (WebSocket). The wire format is standard JSON-RPC 2.0:
POST /rpc
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": 1,
"method": "eth_blockNumber",
"params": []
}
// response
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x37e9"
}
The method namespace is val_* — Valdium's native JSON-RPC surface. The request/response envelope follows the familiar JSON-RPC 2.0 shape used across the ecosystem, and breaks away cleanly where Valdium differs (Dilithium3 signature scheme, BLAKE3 hashing, account-model deltas).
Chain state methods
| Method | Returns |
|---|
eth_chainId | Chain ID hex (0x539 on testnet) |
eth_blockNumber | Latest block number, hex |
eth_getBlockByNumber | Full block by height |
eth_getBlockByHash | Full block by hash |
eth_getBlockTransactionCountByNumber | Number of txs in a block |
eth_syncing | false or sync status object |
Account methods
| Method | Returns |
|---|
eth_getBalance | Base unit balance of an address at a block |
eth_getTransactionCount | Next nonce for an address |
eth_getCode | Contract bytecode at an address (empty for EOAs) |
eth_getStorageAt | Storage slot value at an address |
eth_getProof | Full account object — balance, nonce, codeHash, storageRoot |
Transaction methods
| Method | Returns |
|---|
eth_sendRawTransaction | Tx hash; broadcasts a signed tx |
eth_getTransactionByHash | Tx object |
eth_getTransactionReceipt | Receipt with logs, gasUsed, status |
eth_getTransactionsByAddress | Page of txs for an address |
eth_estimateGas | Gas a call would consume |
eth_call | Eth-style read call against a contract; never broadcast |
Validator and consensus methods
| Method | Returns |
|---|
val_validators | Active validator set at a height |
val_validatorInfo | Per-validator stats: stake, missed slots, jailed |
val_epoch | Current epoch number and boundaries |
val_proposerSchedule | Upcoming N slots with the proposer for each |
Fee market methods
| Method | Returns |
|---|
eth_gasPrice | Suggested gas price (legacy) |
eth_feeHistory | Recent base fees and priority-fee percentiles |
eth_maxPriorityFeePerGas | Suggested tip for inclusion |
Wallet-bridging methods
These are intercepted by browser wallets and not directly served by nodes — included here because dapps call them through the same provider object:
| Method | Returns |
|---|
eth_requestAccounts | Permitted accounts after user approval |
eth_accounts | Already-permitted accounts (no prompt) |
eth_signTransaction | Signed (but not broadcast) tx |
eth_sendTransaction | Signed and broadcast tx — hash |
personal_sign | Dilithium3 signature over a domain-separated digest |
Subscriptions (WebSocket only)
The WebSocket endpoint accepts eth_subscribe with one of the following channels:
| Channel | Fires on |
|---|
newHeads | Every new block |
newPendingTransactions | Every tx entering the mempool |
logs | Event logs matching a filter |
syncing | Sync state changes |
// subscribe to new blocks
ws.send(JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'eth_subscribe',
params: ['newHeads']
}));
// → { result: '0x9c…', id: 1 }
// → { method: 'eth_subscription', params: { subscription: '0x9c…', result: { ...block } } }
Batching
The endpoint accepts JSON-RPC batch requests — an array of calls in one POST. The response is an array of results in the same order. Useful for indexers and frontends that need many cold reads in flight; cuts round-trip overhead by 5-10x for cold caches.
Errors
Error codes follow JSON-RPC 2.0 conventions plus Valdium-specific application codes:
| Code | Meaning |
|---|
| -32600 | Invalid request |
| -32601 | Method not found |
| -32602 | Invalid params |
| -32603 | Internal error |
| -32000 | Invalid input (e.g. malformed address) |
| -32001 | Resource not found |
| -32010 | Transaction underpriced |
| -32011 | Nonce too low |
| -32012 | Insufficient funds |
| 4001 | User rejected request (wallet only) |
Rate limits on public endpoints
The public testnet RPC enforces 60 requests/second per IP and a daily soft cap of 1,000,000 requests. Self-hosted nodes have no such limits. If you're indexing the chain or running a high-traffic dapp, run your own node — it's 10 GB of disk and zero ongoing cost.