Skip to main content

XPHERE-Specific JSON-RPC (xp_*)

XPHERE nodes serve an xp_* namespace alongside the Ethereum-compatible methods. Most of it mirrors the eth_* namespace — xp_getBalance, xp_getCode, xp_blockNumber and xp_chainId return byte-identical results to their eth_* counterparts. A smaller set has no Ethereum equivalent: the council and committee, the block-level consensus record, the on-chain governance parameters, and the per-block reward breakdown.

Everything on this page was called

Every method documented below was invoked against a Foundation Mainnet endpoint node — en-hkg.x-phere.com, which rpc.x-phere.com also serves from (client Xphere/v0.9.0/linux-amd64/go1.22.12) — on 2026-08-05, and every response shown was captured from that node. Nothing is listed because it is expected to exist. Methods that were tried and did not answer are listed in Names that are not RPC methods.

Checking a method yourself

Call it with no arguments and read the error code:

curl -s -X POST https://rpc.x-phere.com \
-H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"xp_getCouncilSize","params":[],"id":1}'
ResponseMeaning
A resultThe method exists and needs no arguments
-32601 the method ... does not exist/is not availableThe method is not registered — do not use it
-32602 missing value for required argument NThe method exists and requires at least N + 1 arguments
-32000 ...The method exists and ran; the error came from the node, not from method lookup

Adding arguments one at a time until the -32602 stops is how the parameter counts on this page were established.

Namespaces on the public endpoints

curl -s -X POST https://rpc.x-phere.com \
-H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"rpc_modules","params":[],"id":1}'
# {"jsonrpc":"2.0","id":1,"result":{"eth":"1.0","net":"1.0","rpc":"1.0","xp":"1.0"}}
EndpointNamespaces served
https://rpc.x-phere.cometh, net, rpc, xp
https://en-hkg.x-phere.cometh, net, rpc, xp
https://en-bkk.x-phere.cometh, net, rpc, xp
wss://rpc.x-phere.com/ws, wss://en-hkg.x-phere.com/ws, wss://en-bkk.x-phere.com/wseth, net, rpc, xp
https://testnet.x-phere.comdebug, eth, net, rpc, xp

Third-party providers run their own configuration and may serve more. Run rpc_modules against any endpoint before assuming what it offers. To add xp to a node you operate, put it in RPC_API / WS_API (--rpcapi / --wsapi) — see Node JSON-RPC Setup.

Chain state

MethodParametersReturns
xp_blockNumbernoneQUANTITY — latest block number
xp_getBlockByNumberQUANTITY|TAG, BooleanBlock object (see block shape)
xp_getBlockByHashDATA 32 bytes, BooleanBlock object
xp_getHeaderByNumberQUANTITY|TAGHeader object
xp_getHeaderByHashDATA 32 bytesHeader object
xp_getBlockTransactionCountByNumberQUANTITY|TAGQUANTITY
xp_getBlockTransactionCountByHashDATA 32 bytesQUANTITY
xp_getBlockReceiptsQUANTITY|TAGArray of receipt objects
xp_getTotalSupplyQUANTITY|TAGSupply object
xp_gasPricenoneQUANTITY — suggested gas price in wei
xp_lowerBoundGasPricenoneQUANTITY — base-fee floor in wei
xp_upperBoundGasPricenoneQUANTITY — base-fee ceiling in wei
xp_maxPriorityFeePerGasnoneQUANTITY — suggested tip in wei
xp_feeHistoryQUANTITY block count, QUANTITY|TAG, Array of percentilesFee history object
xp_chainID, xp_chainIdnoneQUANTITY — chain ID (both spellings work)
xp_syncingnonefalse when in sync

The XPHERE block shape

xp_getBlockByNumber and xp_getBlockByHash do not return the Ethereum block object. There is no difficulty, totalDifficulty, miner, nonce, mixHash, sha3Uncles, uncles or gasLimit. Captured from Mainnet, with the long fields elided:

curl -s -X POST https://rpc.x-phere.com \
-H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"xp_getHeaderByNumber","params":["latest"],"id":1}'
{
"baseFeePerGas": "0x5d21dba00",
"blockScore": "0x1",
"extraData": "0xda820900...",
"gasUsed": "0x44e21",
"governanceData": "0x",
"hash": "0x2df9f79cec256eebdb8c086d67184ea7dc229b0b77ad599e0a073f6b72244a30",
"logsBloom": "0x00...",
"number": "0x2b103dc",
"parentHash": "0x2ad29229321f55585754504e4b1020f2533408c21c447f7169844d581baf024a",
"receiptsRoot": "0x5fd88aadc3b7f93b04be728229cd027f117aca0b00a1367118e67e1f76814bc5",
"reward": "0x3c96c3ec7eb41a165a01f82199798ee986f57cf7",
"stateRoot": "0xead432e9133218308a02949e36c7c131c507e4cc1b2e9f5002bcb7c5d6b365f2",
"timestamp": "0x6a72f439",
"timestampFoS": "0x4e",
"transactionsRoot": "0xffb63f71241cbe0ef91a8a18b88611b017fdc30c04a3614495b46795135a52b2",
"voteData": "0x"
}

A full block adds size, totalBlockScore and transactions. Transaction objects carry senderTxHash, signatures and typeInt in addition to the usual Ethereum fields, and no v/r/s.

xp_getBlockReceipts

Returns every receipt in one block in a single call.

Parameters

  1. QUANTITY|TAG — block number or tag

Returns

Array — one entry per transaction; [] for an empty block. Each entry merges transaction and receipt fields: blockHash, blockNumber, contractAddress, effectiveGasPrice, from, gas, gasPrice, gasUsed, input, logs, logsBloom, nonce, senderTxHash, signatures, status, to, transactionHash, transactionIndex, type, typeInt, value.

curl -s -X POST https://rpc.x-phere.com \
-H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"xp_getBlockReceipts","params":["latest"],"id":1}'

xp_getTotalSupply

Returns the supply accounting for a block. This has no eth_* equivalent.

Parameters

  1. QUANTITY|TAG — block number or tag

Returns

Object with number, totalSupply, totalMinted, totalBurnt, burntFee, zeroBurn, deadBurn, all as hex quantities in wei.

curl -s -X POST https://rpc.x-phere.com \
-H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"xp_getTotalSupply","params":["latest"],"id":1}'
{
"number": "0x2b10270",
"totalSupply": "0x953192fe4a161c23f16f4d7",
"totalMinted": "0x111b0ec57e6499a1f4b1967f4f4f95bfd45f6ec0000",
"totalBurnt": "0x111b0ec57e6499a1f4b1014dbc514ba9b83b7d50b29",
"burntFee": "0x7304936c4727f083b29",
"zeroBurn": "0xb1a2bc2ec50000",
"deadBurn": "0x111b0ec57e6499a1f4b1014d494cad234550a07d000"
}
Some historical state is pruned

The public endpoints do not keep state for every past block. xp_getCommitteeSize answered normally for blocks up to 400 behind the head and returned -32000 missing trie node ... at 700 behind, on the node tested. Other state-reading methods can hit the same limit. Where the boundary sits is a property of the node you are querying, so check it against the endpoint you use rather than assuming a depth.

Accounts and transactions

MethodParametersReturns
xp_getBalanceDATA 20 bytes, QUANTITY|TAGQUANTITY — balance in wei
xp_getCodeDATA 20 bytes, QUANTITY|TAGDATA — deployed code, 0x for an EOA
xp_getTransactionCountDATA 20 bytes, QUANTITY|TAGQUANTITY — next nonce
xp_getStorageAtDATA 20 bytes, QUANTITY slot, QUANTITY|TAGDATA — 32-byte word
xp_getAccountDATA 20 bytes, QUANTITY|TAGAccount object
xp_isContractAccountDATA 20 bytes, QUANTITY|TAGBoolean
xp_accountCreatedDATA 20 bytes, QUANTITY|TAGBoolean
xp_callcall Object, QUANTITY|TAGDATA — return value
xp_estimateGascall ObjectQUANTITY — gas estimate
xp_getTransactionByHashDATA 32 bytesTransaction object
xp_getTransactionReceiptDATA 32 bytesReceipt object
xp_getTransactionBySenderTxHashDATA 32 bytesTransaction object
xp_getTransactionReceiptBySenderTxHashDATA 32 bytesReceipt object
xp_getRawTransactionByHashDATA 32 bytesDATA — RLP-encoded transaction
xp_getTransactionByBlockNumberAndIndexQUANTITY|TAG, QUANTITY indexTransaction object
xp_getTransactionByBlockHashAndIndexDATA 32 bytes, QUANTITY indexTransaction object
xp_getRawTransactionByBlockNumberAndIndexQUANTITY|TAG, QUANTITY indexDATA — RLP-encoded transaction
xp_pendingTransactionsnoneArray — pending transactions known to the node
xp_sha3DATADATA — keccak-256 of the input
xp_encodeAccountKey, xp_decodeAccountKeyregistered; require at least 1 argumentAccount-key encoding helpers
xp_getProof, xp_createAccessListregistered; require at least 1 argumentAs their eth_* counterparts

Unlike Ethereum's eth_estimateGas, xp_estimateGas answers with a single argument — the block parameter is optional.

curl -s -X POST https://rpc.x-phere.com \
-H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"xp_getAccount","params":["0x9e24c8ad703c8d9a638469f19e737da0e7c0b447","latest"],"id":1}'
{
"accType": 1,
"account": {
"nonce": 1,
"balance": "0x245b90f21eb8a45fed02d6",
"humanReadable": false,
"key": { "keyType": 1, "key": {} }
}
}

Logs and filters

MethodParametersReturns
xp_getLogsfilter ObjectArray of log objects
xp_newFilterfilter ObjectDATA — filter id
xp_newBlockFilternoneDATA — filter id
xp_newPendingTransactionFilternoneDATA — filter id
xp_getFilterChangesDATA filter idArray — new items since the last poll
xp_getFilterLogsDATA filter idArray of logs; -32000 filter not found for a block or pending filter
xp_uninstallFilterDATA filter idBoolean

A full round trip, all four calls verified against Mainnet:

EP=https://rpc.x-phere.com
ID=$(curl -s -X POST $EP -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"xp_newBlockFilter","params":[],"id":1}' \
| sed 's/.*"result":"//;s/".*//')
sleep 3
curl -s -X POST $EP -H "Content-Type: application/json" \
--data "{\"jsonrpc\":\"2.0\",\"method\":\"xp_getFilterChanges\",\"params\":[\"$ID\"],\"id\":1}"
curl -s -X POST $EP -H "Content-Type: application/json" \
--data "{\"jsonrpc\":\"2.0\",\"method\":\"xp_uninstallFilter\",\"params\":[\"$ID\"],\"id\":1}"
# {"jsonrpc":"2.0","id":1,"result":["0x4f9b1ce3...","0xa0d657a5...","0x9557734f..."]}
# {"jsonrpc":"2.0","id":1,"result":true}

Methods that need a node you control

xp_accounts, xp_sign, xp_signTransaction, xp_sendTransaction and xp_resend are registered on the public endpoints but act on the queried node's key store, which holds nothing for you — xp_accounts returns []. xp_sendRawTransaction is registered and takes one argument, the signed transaction; it was not exercised here because doing so writes to the chain. For application development, sign in your wallet or library and submit with eth_sendRawTransaction.

Consensus and governance

These have no Ethereum equivalent.

xp_getCouncil and xp_getCommittee

xp_getCouncil returns the validator set recorded on chain for a block; xp_getCommittee returns the set used for consensus at that block — the same list that appears in the committee field of xp_getBlockWithConsensusInfoByNumber. xp_getCouncilSize and xp_getCommitteeSize return the counts.

Parameters

  1. QUANTITY|TAGoptional. Omit for the latest block.

Returns

Array of DATA, 20 bytes for the list methods; Number (decimal, not hex) for the size methods.

curl -s -X POST https://rpc.x-phere.com \
-H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"xp_getCommitteeSize","params":[],"id":1}'
# {"jsonrpc":"2.0","id":1,"result":29}
{
"jsonrpc": "2.0",
"id": 1,
"result": [
"0x17d525d6437014abf62df0695338b46b3a0ce137",
"0x1aa28342397f437db5c425d8bec100c52bf98b23",
"0x26942edca606355fa72a0c7536f7f6772d53d374"
]
}

At the time of verification the two Mainnet sets were identical — 29 addresses each, with xp_getCouncilSize and xp_getCommitteeSize both returning 29, and xp_getCommittee for a given block returned the same list, in the same order, as that block's committee field. The governance parameter istanbul.committeesize was 31. Do not assume council and committee will always coincide — compare them for the block you care about.

xp_getBlockWithConsensusInfoByNumber

Returns a block together with who proposed it and who signed it.

Parameters

  1. QUANTITY|TAG — block number or tag

Returns

Object — a full block object plus these consensus fields:

FieldTypeMeaning
proposerDATA 20 bytesAddress that proposed the block
originProposerDATA 20 bytesProposer selected for round 0
roundNumberConsensus round that produced the block
committeeArray of DATACommittee for this block
committersArray of DATACommittee members whose signatures are in the block
sigHashDATA 32 bytesHash the committers signed
rewardDATA 20 bytesReward recipient recorded in the header
curl -s -X POST https://rpc.x-phere.com \
-H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"xp_getBlockWithConsensusInfoByNumber","params":["0x2b103da"],"id":1}'
{
"number": "0x2b103da",
"hash": "0x7c7b0b6751e3edb6ea2faebf626edd5876e283330e86bc32ab26179525fa64b7",
"proposer": "0xaff1c7909ce2dd5a8a19ab7a9f81e72a231c8496",
"originProposer": "0xaff1c7909ce2dd5a8a19ab7a9f81e72a231c8496",
"round": 0,
"committee": ["0x17d525d6437014abf62df0695338b46b3a0ce137", "..."],
"committers": ["0x485db80dca69e47b911611c28332682d6578ef8c", "..."],
"sigHash": "0xe06e10c1a3cb58034ce045f35044fb88fcb51b46a6bda763c550fd0676924a6c",
"reward": "0x3c96c3ec7eb41a165a01f82199798ee986f57cf7",
"blockScore": "0x1",
"totalBlockScore": "0x2b103db",
"gasUsed": "0x44e53",
"transactions": []
}

In that block committee held 29 addresses and committers 20 — the quorum that actually signed.

xp_getBlockWithConsensusInfoByHash

Same result, addressed by block hash.

Parameters

  1. DATA, 32 bytes — block hash

xp_getBlockWithConsensusInfoByNumberRange

Parameters

  1. QUANTITY — first block
  2. QUANTITY — last block

Returns

Object keyed by block number in hex, each value a consensus-info block object.

The range is capped. Asking for 200 blocks returns:

{"jsonrpc":"2.0","id":1,"error":{"code":-32000,"message":"number of requested blocks should be smaller than 50"}}

xp_getChainConfig

Returns the active chain configuration, including the governance and reward parameters. This is the authoritative source for XPHERE's emission settings — they are read from the chain, not from documentation.

Parameters — none, or an optional QUANTITY|TAG

ReturnsObject

curl -s -X POST https://rpc.x-phere.com \
-H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"xp_getChainConfig","params":[],"id":1}'
{
"chainId": 20250217,
"istanbul": { "epoch": 604800, "policy": 0, "sub": 31 },
"unitPrice": 0,
"deriveShaImpl": 0,
"governance": {
"governingNode": "0x9e24c8ad703c8d9a638469f19e737da0e7c0b447",
"governanceMode": "single",
"reward": {
"xifAddress": "0x05d4a19b4304b2de51ac2578aa0eec5de2301e62",
"mintingAmount": 2000000000000000000000,
"ratio": "40/40/20",
"blockInterval": 60
},
"dgp": {
"lowerboundbasefee": 25000000000,
"upperboundbasefee": 750000000000,
"gastarget": 30000000,
"maxblockgasusedforbasefee": 60000000,
"basefeedenominator": 20
}
}
}

governance.reward.ratio is the split applied to newly minted XP — proposer/miner/xif — and it matches the figures returned by xp_getRewards. dgp.lowerboundbasefee and dgp.upperboundbasefee are the same wei values that xp_lowerBoundGasPrice and xp_upperBoundGasPrice return in hex.

xp_getParams

The same governance parameters as a flat map. Useful because the large numbers come back as strings here.

Parameters — none, or an optional QUANTITY|TAG

curl -s -X POST https://rpc.x-phere.com \
-H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"xp_getParams","params":[],"id":1}'
{
"dgp.basefeedenominator": 20,
"dgp.gastarget": 30000000,
"dgp.lowerboundbasefee": 25000000000,
"dgp.maxblockgasusedforbasefee": 60000000,
"dgp.upperboundbasefee": 750000000000,
"governance.deriveshaimpl": 0,
"governance.governancemode": "single",
"governance.governingnode": "0x9e24c8ad703c8d9a638469f19e737da0e7c0b447",
"governance.unitprice": 0,
"istanbul.committeesize": 31,
"istanbul.epoch": 604800,
"istanbul.policy": 0,
"reward.blockinterval": 60,
"reward.mintingamount": "2000000000000000000000",
"reward.ratio": "40/40/20",
"reward.xifaddress": "0x05d4a19b4304b2de51ac2578aa0eec5de2301e62"
}

xp_getRewards

Returns the reward and fee breakdown for a block: what was minted, what was burnt, and what each recipient received.

Parameters

  1. QUANTITY|TAGoptional. Omit for the latest block.

Returns

FieldTypeMeaning
mintedNumberXP newly issued at this block, in wei. 0 for most blocks
totalFeeNumberTransaction fees collected in the block, in wei
burntFeeNumberPortion of totalFee burnt
proposerNumberAmount credited to the block proposer
minerNumberAmount credited to the miner share
xifNumberAmount credited to the XIF address from xp_getChainConfig
rewardsObjectAddress → amount actually paid
curl -s -X POST https://rpc.x-phere.com \
-H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"xp_getRewards","params":["0x2b10358"],"id":1}'
{
"minted": 1474400000000000262144,
"totalFee": 7055125000000000,
"burntFee": 3527562500000000,
"proposer": 589761411025000104857,
"miner": 589761411025000104857,
"xif": 294880705512500052428,
"rewards": {
"0x05d4a19b4304b2de51ac2578aa0eec5de2301e62": 294880705512500052428,
"0x26942edca606355fa72a0c7536f7f6772d53d374": 589761411025000104857,
"0x29fe01d3adc64ba2f8ac2e64f08204a33a676f17": 589761411025000104857
}
}

The numbers are internally consistent and reproduce the split held in governance. On the sampled blocks:

QuantityIdentity
burntFee50% of totalFee
proposer40% of minted + 20% of totalFee
miner40% of minted + 20% of totalFee
xif20% of minted + 10% of totalFee

The 40/40/20 part is exactly governance.reward.ratio from xp_getChainConfig. Blocks with no transactions and no minting return all zeros, which is normal.

These are JSON numbers, not hex strings

Unlike the eth_* namespace, xp_getRewards, xp_getChainConfig and xp_getParams emit plain JSON numbers. Values above 253 lose precision in any parser backed by IEEE-754 doubles — 1474400000000000262144 above is the double nearest to 1474400000000000000000, and the trailing digits are an artifact. Parse with a big-number-aware JSON reader, or take reward.mintingamount from xp_getParams, where it is a string.

Node information

MethodParametersReturns
xp_clientVersionnoneString — e.g. "Xphere/v0.9.0/linux-amd64/go1.22.12"
xp_protocolVersionnoneString — e.g. "0x40"
xp_nodeAddressnoneDATA 20 bytes — the queried node's own address
xp_syncingnonefalse when the node is in sync
xp_accountsnoneArray — the node's key store, [] on public endpoints
xp_rewardbasenoneThe node's reward address; returns -32000 rewardbase must be explicitly specified when the operator did not set one
curl -s -X POST https://rpc.x-phere.com \
-H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"xp_clientVersion","params":[],"id":1}'
# {"jsonrpc":"2.0","id":1,"result":"Xphere/v0.9.0/linux-amd64/go1.22.12"}

xp_nodeAddress describes the endpoint you happen to be talking to, not the network.

Subscriptions

xp_subscribe and xp_unsubscribe are WebSocket-only. Over HTTP the node answers:

curl -s -X POST https://rpc.x-phere.com \
-H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"xp_subscribe","params":["newHeads"],"id":1}'
# {"jsonrpc":"2.0","id":1,"error":{"code":-32000,"message":"notifications not supported"}}

Connect to wss://rpc.x-phere.com/ws or wss://en-bkk.x-phere.com/ws instead. The bare host without /ws is not a WebSocket endpoint — it answers HTTP 200 and the handshake fails.

Topics confirmed to subscribe: newHeads, logs, newPendingTransactions. An unknown topic returns -32601 no "<topic>" subscription in xp namespace.

xp_subscribe returns a subscription id. Notifications then arrive with method xp_subscription and a params object holding subscription and result. xp_unsubscribe takes the id and returns true.

import asyncio, json, websockets

async def main():
async with websockets.connect("wss://rpc.x-phere.com/ws") as ws:
await ws.send(json.dumps({"jsonrpc":"2.0","method":"xp_subscribe","params":["newHeads"],"id":1}))
sub = json.loads(await ws.recv())["result"]
print("subscription", sub)
msg = json.loads(await ws.recv())
print(msg["method"], msg["params"]["result"]["number"])
await ws.send(json.dumps({"jsonrpc":"2.0","method":"xp_unsubscribe","params":[sub],"id":2}))

asyncio.run(main())
subscription 0x8a68571c3149f0d562dbb20e2d219e7
xp_subscription 0x2b102c5

eth_subscribe works over the same connection and behaves the same way.

Names that are not RPC methods

These names appear in tooling and in documentation ported from other chains, but they are not registered on XPHERE nodes — every one returns -32601. Use the method in the right-hand column instead.

NameStatusUse instead
xp_getBlock-32601xp_getBlockByNumber, xp_getBlockByHash
xp_getBlockNumber-32601xp_blockNumber
xp_getBlockTransactionCount-32601xp_getBlockTransactionCountByNumber, xp_getBlockTransactionCountByHash
xp_getBlockWithConsensusInfo-32601xp_getBlockWithConsensusInfoByNumber, xp_getBlockWithConsensusInfoByHash
xp_getBlockWithConsensusInfoRange-32601xp_getBlockWithConsensusInfoByNumberRange
curl -s -X POST https://rpc.x-phere.com \
-H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"xp_getBlockWithConsensusInfo","params":[],"id":1}'
# {"jsonrpc":"2.0","id":1,"error":{"code":-32601,"message":"the method xp_getBlockWithConsensusInfo does not exist/is not available"}}

Two clarifications:

  • This is a statement about RPC only. A name in the table above may still exist as a member of the xp object in the XEN JavaScript console. Console helpers are JavaScript wrappers that call whatever RPC method they are bound to, and that name need not match the one you type. If a console call works, that does not make the console's name a valid RPC method. See XEN CLI Commands.
  • Two response shapes commonly assumed do not exist. No XPHERE response contains a consensus object with prepareMsgNum, commitMsgNum and validators — the real consensus fields are listed above. And xp_getChainConfig returns no xpHashForkBlock, blockTime, consensus or proofChain fields; its actual response is above.

xp_getCode, by contrast, is real — see Accounts and transactions.

See Also