Citrea JSON-RPC Endpoints
Complete reference for Citrea's special JSON-RPC API endpoints for interacting with the ledger data and debugging, outside of the standard Ethereum JSON-RPC methods.
Base URLs
Local node:
http://0.0.0.0:8080
Public Testnet:
https://rpc.testnet.citrea.xyz
Replace these with your node's RPC URL and port as needed.
Table of Contents
Sync & Status Endpoints
citrea_syncStatus
citrea_syncStatus
Description Returns the current synchronization status of the local Citrea node for both L1 (Bitcoin) and L2 (Citrea).
HTTP Request
curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"citrea_syncStatus","params":[],"id":1}' \
http://0.0.0.0:8080
JSON-RPC Body
{
"jsonrpc": "2.0",
"method": "citrea_syncStatus",
"params": [],
"id": 1
}
Parameters
None
Example Response
If fully synced:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"l1Status": { "Synced": 19224 },
"l2Status": { "Synced": 2326433 }
}
}
If still syncing:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"l1Status": { "Synced": 19224 },
"l2Status": {
"Syncing": {
"headBlockNumber": 264052,
"syncedBlockNumber": 27050
}
}
}
}
Response Fields
l1Status
object
L1 (Bitcoin) synchronization status
l2Status
object
L2 (Citrea) synchronization status
Synced
number
Block height when fully synced
Syncing.headBlockNumber
number
Latest known block number
Syncing.syncedBlockNumber
number
Current synced block number
L2 Block Endpoints
ledger_getL2BlockByNumber
ledger_getL2BlockByNumber
Description Returns a complete L2 block by its block number.
HTTP Request
curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"ledger_getL2BlockByNumber","params":[1000333],"id":1}' \
https://rpc.testnet.citrea.xyz
JSON-RPC Body
{
"jsonrpc": "2.0",
"method": "ledger_getL2BlockByNumber",
"params": [1000333],
"id": 1
}
Parameters
number
integer
Yes
L2 block height to fetch
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"header": {
"height": "0xf438d",
"hash": "999528b4d08dc8d0b05cbace0f5e661f36d824cedde1ffa75dc0c197b355c111",
"prev_hash": "3dd4a535bc994f8f8d7d1f814be99f73dc522aa314905ca9985e479b350f17e7",
"state_root": "c55d26ed7c1733d6be6283f68ab87db37271bf476008eba5231f5d321e0efe2c",
"signature": "69f712ea23731ce8432867526084e260d1aeef9290f4c26889361e3bb5e168724bfe328986a56752778a2a93c360b9c291614ce4e15d4b1c2fac7bf31c7068e9",
"l1_fee_rate": "0x9502f900",
"timestamp": "0x67089f9c",
"tx_merkle_root": "13148bcd464a1ef2824f13372513eda01d2f83d498790bf558060dc0bf4cbcbb"
},
"txs": [
"00400000004f3fe920c0195eab45c67026fde19b23853c34e709c18e625e43702ca325f13f7a924be8beed58eb6afdaa596392fa7b40ccff1ead3a33e4db7617034366c2600201edff3b3ee593dbef54e2fbdd421070db55e2de2aebe75f398bd85ac97ed364ba0000000101000000b100000002f8ae8213fb6e018401312d0183021953945da3155a299558bcaa8da073ad74ed0827fb64a380b844a9059cbb000000000000000000000000ae45cbe2d1e90358cbd216bc16f2c9267a4ea80a00000000000000000000000000000000000000000000003b16c9e8eeb7c80000c080a04d09d171896b18b3651da059780fd92748b9813f1a6a11f26550cd759862fb99a03cb268a677ffdb6eb2e563e5ffda0fb32df547828ecf67affb03c087772daadc00000000000000009994040000000000"
]
}
}
Response Fields
header.height
string
Block height in hex format
header.hash
string
32-byte block hash
header.prev_hash
string
Previous block hash
header.state_root
string
State root after this block
header.signature
string
Sequencer signature
header.l1_fee_rate
string
L1 fee rate in hex
header.timestamp
string
Block timestamp in hex
header.tx_merkle_root
string
Merkle root of transactions
txs
array
Array of transaction data (hex-encoded)
ledger_getL2BlockByHash
ledger_getL2BlockByHash
Description Returns a complete L2 block by its block hash.
HTTP Request
curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"ledger_getL2BlockByHash","params":["999528b4d08dc8d0b05cbace0f5e661f36d824cedde1ffa75dc0c197b355c111"],"id":1}' \
https://rpc.testnet.citrea.xyz
JSON-RPC Body
{
"jsonrpc": "2.0",
"method": "ledger_getL2BlockByHash",
"params": ["999528b4d08dc8d0b05cbace0f5e661f36d824cedde1ffa75dc0c197b355c111"],
"id": 1
}
Parameters
hash
string
Yes
32-byte L2 block hash (hex)
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
/* Same structure as ledger_getL2BlockByNumber */
}
}
ledger_getL2BlockRange
ledger_getL2BlockRange
Description
Returns all L2 blocks in the inclusive range [start, end]
.
HTTP Request
curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"ledger_getL2BlockRange","params":[1000333,1000335],"id":1}' \
https://rpc.testnet.citrea.xyz
JSON-RPC Body
{
"jsonrpc": "2.0",
"method": "ledger_getL2BlockRange",
"params": [1000333, 1000335],
"id": 1
}
Parameters
start
integer
Yes
First block number in range
end
integer
Yes
Last block number in range
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": [
{ /* Block 1000333 in ledger_getL2BlockByNumber response structure */ },
{ /* Block 1000334 in ledger_getL2BlockByNumber response structure */ },
{ /* Block 1000335 in ledger_getL2BlockByNumber response structure */ }
]
}
ledger_getHeadL2Block
ledger_getHeadL2Block
Description Returns the latest (head) L2 block.
HTTP Request
curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"ledger_getHeadL2Block","params":[],"id":1}' \
https://rpc.testnet.citrea.xyz
JSON-RPC Body
{
"jsonrpc": "2.0",
"method": "ledger_getHeadL2Block",
"params": [],
"id": 1
}
Parameters
None
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
/* Same structure as ledger_getL2BlockByNumber */
}
}
ledger_getHeadL2BlockHeight
ledger_getHeadL2BlockHeight
Description Returns the block number of the latest L2 block.
HTTP Request
curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"ledger_getHeadL2BlockHeight","params":[],"id":1}' \
https://rpc.testnet.citrea.xyz
JSON-RPC Body
{
"jsonrpc": "2.0",
"method": "ledger_getHeadL2BlockHeight",
"params": [],
"id": 1
}
Parameters
None
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": "0xbed0d6"
}
Response Fields
result
string
Latest L2 block height in hex format
Genesis & State Endpoints
ledger_getL2GenesisStateRoot
ledger_getL2GenesisStateRoot
Description Returns the 32-byte genesis state root for L2.
HTTP Request
curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"ledger_getL2GenesisStateRoot","params":[],"id":1}' \
https://rpc.testnet.citrea.xyz
JSON-RPC Body
{
"jsonrpc": "2.0",
"method": "ledger_getL2GenesisStateRoot",
"params": [],
"id": 1
}
Parameters
None
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x785c6d461111b5e9fdc515e0955d55baddfd8eb2dd2769342cc58060d6f5e0c5"
}
Response Fields
result
string
32-byte genesis state root (hex)
Sequencer Commitment Endpoints
ledger_getSequencerCommitmentsOnSlotByNumber
ledger_getSequencerCommitmentsOnSlotByNumber
Description Returns sequencer commitment(s) found in the specified DA slot height.
HTTP Request
curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"ledger_getSequencerCommitmentsOnSlotByNumber","params":[88001],"id":1}' \
https://rpc.testnet.citrea.xyz
JSON-RPC Body
{
"jsonrpc": "2.0",
"method": "ledger_getSequencerCommitmentsOnSlotByNumber",
"params": [88001],
"id": 1
}
Parameters
height
integer
Yes
L1 DA slot height
Example Response
If commitments exist:
{
"jsonrpc": "2.0",
"id": 1,
"result": [
{
"merkleRoot": "0xd6dc3eb1a59be7bc1ece68318f82a60919f0f98d8c648337d588ce243a17f473",
"index": "0xba5",
"l2EndBlockNumber": "0xb7a20b"
},
{
"merkleRoot": "0xf85a8f3f872fe8079fe778a2f6a8ebd92cf3d1a7c6324af025c8bffbb46d1811",
"index": "0xba6",
"l2EndBlockNumber": "0xb7a5f3"
}
]
}
If no commitments:
{
"jsonrpc": "2.0",
"id": 1,
"result": null
}
Response Fields
merkleRoot
string
Merkle root of sequencer commitment
index
string
Global commitment index (hex)
l2EndBlockNumber
string
Last L2 block in this commitment (hex)
ledger_getSequencerCommitmentsOnSlotByHash
ledger_getSequencerCommitmentsOnSlotByHash
Description Returns sequencer commitment(s) found in the DA slot identified by its L1 block hash.
HTTP Request
curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"ledger_getSequencerCommitmentsOnSlotByHash","params":["788636f732f490c5072582c7dcde85e34d737c8a4d98e792a59c9d0100000000"],"id":1}' \
https://rpc.testnet.citrea.xyz
JSON-RPC Body
{
"jsonrpc": "2.0",
"method": "ledger_getSequencerCommitmentsOnSlotByHash",
"params": ["788636f732f490c5072582c7dcde85e34d737c8a4d98e792a59c9d0100000000"],
"id": 1
}
Parameters
hash
string
Yes
32-byte DA slot hash (hex)
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": [
{
"merkleRoot": "0xd6dc3eb1a59be7bc1ece68318f82a60919f0f98d8c648337d588ce243a17f473",
"index": "0xba5",
"l2EndBlockNumber": "0xb7a20b"
}
]
}
ledger_getSequencerCommitmentByIndex
ledger_getSequencerCommitmentByIndex
Description Returns a sequencer commitment by its global index.
HTTP Request
curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"ledger_getSequencerCommitmentByIndex","params":["0xba5"],"id":1}' \
https://rpc.testnet.citrea.xyz
JSON-RPC Body
{
"jsonrpc": "2.0",
"method": "ledger_getSequencerCommitmentByIndex",
"params": ["0xba5"],
"id": 1
}
Parameters
index
string
Yes
Commitment index (hex)
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"merkleRoot": "0xd6dc3eb1a59be7bc1ece68318f82a60919f0f98d8c648337d588ce243a17f473",
"index": "0xba5",
"l2EndBlockNumber": "0xb7a20b"
}
}
Proof Endpoints
ledger_getVerifiedBatchProofsBySlotHeight
ledger_getVerifiedBatchProofsBySlotHeight
Description Returns verified ZK batch proof(s) for the specified DA slot height.
HTTP Request
curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"ledger_getVerifiedBatchProofsBySlotHeight","params":[85890],"id":1}' \
https://rpc.testnet.citrea.xyz
JSON-RPC Body
{
"jsonrpc": "2.0",
"method": "ledger_getVerifiedBatchProofsBySlotHeight",
"params": [85890],
"id": 1
}
Parameters
height
integer
Yes
DA slot height (L1)
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": [
{
"proof": "0x0300000000000000000000000000000081670c116a84c0351f18c3...", // ~2MB proof data
"proofOutput": {
"stateRoots": [
"0x5e2a5b8da99b65c5eba4b36f2368321dad95c08c641d698b09ca6756caac589e",
"0x182a9543bf64a90e78f7d810dedebdf4da3322752db5ee5533fae564e31033f7"
// ... additional state roots
],
"finalL2BlockHash": "0x8fe769cdb2d34f60b5a625caa8697ae1d1f213b558c9dc9e681059f18732e608",
"stateDiff": {
"0x412f612f0201edff3b3ee593dbef54e2fbdd421070db55e2de2aebe75f398bd85ac97ed364": "0xf4fd64e249e658fdb748f83190e47f0b1cd5e87fe30d005c257d7a94cca458e7167e690000000000"
// ... state differences (truncated for readability)
},
"lastL2Height": "0xae0e97",
"sequencerCommitmentIndexRange": ["0x92c", "0x92e"],
"sequencerCommitmentHashes": [
"0x8a9cd0b9fda255370073abff4176416665d14552d5f0d671998ca89523041b36"
// ... additional hashes
],
"lastL1HashOnBitcoinLightClientContract": "0xa1717b35aa14be01ce037d1a346c4c1714afcfa5e8a66a35af5ead0000000000",
"previousCommitmentIndex": "0x92b",
"previousCommitmentHash": "0xa37a45539d40448d22f6da7978ca58f5845b72a5043129941817099471198749"
}
}
]
}
Note: The actual proof data is approximately 2MB. This example shows truncated data for documentation purposes.
Response Fields
proof
string
ZK proof data (hex, ~2MB)
proofOutput.stateRoots
array
Array of state roots
proofOutput.finalL2BlockHash
string
Final L2 block hash in batch
proofOutput.stateDiff
object
State changes (key-value pairs)
proofOutput.lastL2Height
string
Last L2 height in proof (hex)
proofOutput.sequencerCommitmentIndexRange
array
Range of commitment indices
proofOutput.sequencerCommitmentHashes
array
Commitment hashes in range
ledger_getLastVerifiedBatchProof
ledger_getLastVerifiedBatchProof
Description Returns the most recent verified batch proof.
HTTP Request
curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"ledger_getLastVerifiedBatchProof","params":[],"id":1}' \
https://rpc.testnet.citrea.xyz
JSON-RPC Body
{
"jsonrpc": "2.0",
"method": "ledger_getLastVerifiedBatchProof",
"params": [],
"id": 1
}
Parameters
None
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
/* Same structure as ledger_getVerifiedBatchProofsBySlotHeight */
}
}
L1 Integration Endpoints
ledger_getLastScannedL1Height
ledger_getLastScannedL1Height
Description Returns the highest L1 block number the node has scanned so far.
HTTP Request
curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"ledger_getLastScannedL1Height","params":[],"id":1}' \
https://rpc.testnet.citrea.xyz
JSON-RPC Body
{
"jsonrpc": "2.0",
"method": "ledger_getLastScannedL1Height",
"params": [],
"id": 1
}
Parameters
None
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x15e53"
}
Response Fields
result
string
Last scanned L1 block height (hex)
Status Query Endpoints
citrea_getLastCommittedL2Height
citrea_getLastCommittedL2Height
Description Returns the latest L2 block height that has been committed to Bitcoin via sequencer commitment.
HTTP Request
curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"citrea_getLastCommittedL2Height","params":[],"id":1}' \
https://rpc.testnet.citrea.xyz
JSON-RPC Body
{
"jsonrpc": "2.0",
"method": "citrea_getLastCommittedL2Height",
"params": [],
"id": 1
}
Parameters
None
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"height": 12489007,
"commitment_index": 3444
}
}
Response Fields
height
number
Latest committed L2 block height
commitment_index
number
Sequencer commitment index
citrea_getLastProvenL2Height
citrea_getLastProvenL2Height
Description Returns the latest L2 block height that has been proven on Bitcoin with a validity proof.
HTTP Request
curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"citrea_getLastProvenL2Height","params":[],"id":1}' \
https://rpc.testnet.citrea.xyz
JSON-RPC Body
{
"jsonrpc": "2.0",
"method": "citrea_getLastProvenL2Height",
"params": [],
"id": 1
}
Parameters
None
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"height": 11457999,
"commitment_index": 2401
}
}
Response Fields
height
number
Latest proven L2 block height
commitment_index
number
Sequencer commitment index
citrea_getL2StatusHeightsByL1Height
citrea_getL2StatusHeightsByL1Height
Description Returns committed and proven L2 heights as of a given Bitcoin block.
HTTP Request
curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"citrea_getL2StatusHeightsByL1Height","params":[800000],"id":1}' \
https://rpc.testnet.citrea.xyz
JSON-RPC Body
{
"jsonrpc": "2.0",
"method": "citrea_getL2StatusHeightsByL1Height",
"params": [800000],
"id": 1
}
Parameters
l1_height
integer
Yes
Bitcoin block height to query
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"committed": {
"height": 12489007,
"commitment_index": 3444
},
"proven": {
"height": 11457999,
"commitment_index": 2401
}
}
}
Response Fields
committed
object
Latest committed L2 status
proven
object
Latest proven L2 status
Deposit Endpoints
citrea_sendRawDepositTransaction
citrea_sendRawDepositTransaction
Description Submits a raw deposit transaction to the Citrea sequencer. The node first simulates the deposit; if valid, it is queued for inclusion.
HTTP Request
curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"citrea_sendRawDepositTransaction","params":["0x01020304..."],"id":1}' \
http://0.0.0.0:8080
JSON-RPC Body
{
"jsonrpc": "2.0",
"method": "citrea_sendRawDepositTransaction",
"params": ["0x01020304..."],
"id": 1
}
Parameters
deposit
string
Yes
Raw serialized deposit tx data (hex)
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": null
}
Response Fields
result
null
Success returns null
eth_estimateDiffSize
eth_estimateDiffSize
Description Returns estimated diff size and gas consumption for a potential transaction.
HTTP Request
curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"eth_estimateDiffSize","params":[{"from":"0x0452663bfc46B86aC93d8220D9847cF5220D7642","to":"0x5fbdb2315678afecb367f032d93f642f64180aa3","value":"10000"}],"id":1}' \
https://rpc.testnet.citrea.xyz
JSON-RPC Body
{
"jsonrpc": "2.0",
"method": "eth_estimateDiffSize",
"params": [{
"from": "0x0452663bfc46B86aC93d8220D9847cF5220D7642",
"to": "0x5fbdb2315678afecb367f032d93f642f64180aa3",
"value": "10000"
}],
"id": 1
}
Parameters
Same as eth_estimateGas
.
Example Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"gas": "0x5208",
"l1DiffSize": "0x11"
}
}
Response Fields
gas
string
Estimated gas consumption (hex)
l1DiffSize
string
Estimated L1 diff size (hex)
Error Responses
All endpoints may return standard JSON-RPC error responses:
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32602,
"message": "Invalid params"
}
}
Common Error Codes
-32600
Invalid Request
The JSON sent is not a valid Request object
-32601
Method not found
The method does not exist / is not available
-32602
Invalid params
Invalid method parameter(s)
-32603
Internal error
Internal JSON-RPC error
Notes
All hex values should include the
0x
prefixBlock heights can be specified as integers or hex strings (block tags of Ethereum-spec also works)
Response data may be truncated in documentation for readability
Large responses (like proofs) may be several MB in size
Always check for error responses before processing results
Last updated
Was this helpful?