# 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`
* **Mainnet:** `https://rpc.mainnet.citrea.xyz`
* **Testnet:** `https://rpc.testnet.citrea.xyz`
* [**Alchemy**](https://alchemy.com)**:** [`https://citrea-mainnet.g.alchemy.com/v2/{apiKey}`](https://citrea-mainnet.g.alchemy.com/v2/%7BapiKey%7D)
  * You can also view/test RPC endpoints using [Alchemy's documentation / playground](https://www.alchemy.com/docs/node/citrea/citrea-api-endpoints/citrea-get-l-2-status-heights-by-l-1-height).

***

## Table of Contents

### 1. [Sync & Status Endpoints](#sync--status-endpoints)

* [`citrea_syncStatus`](#citrea_syncstatus)

### 2. [L2 Block Endpoints](#l2-block-endpoints)

* [`ledger_getL2BlockByNumber`](#ledger_getl2blockbynumber)
* [`ledger_getL2BlockByHash`](#ledger_getl2blockbyhash)
* [`ledger_getL2BlockRange`](#ledger_getl2blockrange)
* [`ledger_getHeadL2Block`](#ledger_getheadl2block)
* [`ledger_getHeadL2BlockHeight`](#ledger_getheadl2blockheight)

### 3. [Genesis & State Endpoints](#genesis--state-endpoints)

* [`ledger_getL2GenesisStateRoot`](#ledger_getl2genesisstateroot)

### 4. [Sequencer Commitment Endpoints](#sequencer-commitment-endpoints)

* [`ledger_getSequencerCommitmentsOnSlotByNumber`](#ledger_getsequencercommitmentsonslotbynumber)
* [`ledger_getSequencerCommitmentsOnSlotByHash`](#ledger_getsequencercommitmentsonslotbyhash)
* [`ledger_getSequencerCommitmentByIndex`](#ledger_getsequencercommitmentbyindex)

### 5. [Proof Endpoints](#proof-endpoints)

* [`ledger_getVerifiedBatchProofsBySlotHeight`](#ledger_getverifiedbatchproofsbyslotHeight)
* [`ledger_getLastVerifiedBatchProof`](#ledger_getlastverifiedbatchproof)

### 6. [L1 Integration Endpoints](#l1-integration-endpoints)

* [`ledger_getLastScannedL1Height`](#ledger_getlastscannedl1height)

### 7. [Status Query Endpoints](#status-query-endpoints)

* [`citrea_getLastCommittedL2Height`](#citrea_getlastcommittedl2height)
* [`citrea_getLastProvenL2Height`](#citrea_getlastprovenl2height)
* [`citrea_getL2StatusHeightsByL1Height`](#citrea_getl2statusheightsbyl1height)

### 8. [Deposit Endpoints](#deposit-endpoints)

* [`citrea_sendRawDepositTransaction`](#citrea_sendrawdeposittransaction)

### 9. [Diff Size Estimation Endpoint](#diff-size-estimation-endpoint)

* [`eth_estimateDiffSize`](#eth_estimatediffsize)

***

## Sync & Status Endpoints

### `citrea_syncStatus`

**Description**\
Returns the current synchronization status of the local Citrea node for both L1 (Bitcoin) and L2 (Citrea).

#### HTTP Request

```sh
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

```json
{
  "jsonrpc": "2.0",
  "method": "citrea_syncStatus",
  "params": [],
  "id": 1
}
```

#### Parameters

*None*

#### Example Response

**If fully synced:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "l1Status": { "Synced": 19224 },
    "l2Status": { "Synced": 2326433 }
  }
}
```

**If still syncing:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "l1Status": { "Synced": 19224 },
    "l2Status": {
      "Syncing": {
        "headBlockNumber": 264052,
        "syncedBlockNumber": 27050
      }
    }
  }
}
```

#### Response Fields

| Field                       | Type     | Description                         |
| --------------------------- | -------- | ----------------------------------- |
| `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`

**Description**\
Returns a complete L2 block by its block number.

#### HTTP Request

```sh
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

```json
{
  "jsonrpc": "2.0",
  "method": "ledger_getL2BlockByNumber",
  "params": [1000333],
  "id": 1
}
```

#### Parameters

| Name     | Type      | Required | Description              |
| -------- | --------- | -------- | ------------------------ |
| `number` | `integer` | **Yes**  | L2 block height to fetch |

#### Example Response

```json
{
  "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

| Field                   | Type     | Description                             |
| ----------------------- | -------- | --------------------------------------- |
| `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`

**Description**\
Returns a complete L2 block by its block hash.

#### HTTP Request

```sh
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

```json
{
  "jsonrpc": "2.0",
  "method": "ledger_getL2BlockByHash",
  "params": ["999528b4d08dc8d0b05cbace0f5e661f36d824cedde1ffa75dc0c197b355c111"],
  "id": 1
}
```

#### Parameters

| Name   | Type     | Required | Description                 |
| ------ | -------- | -------- | --------------------------- |
| `hash` | `string` | **Yes**  | 32-byte L2 block hash (hex) |

#### Example Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    /* Same structure as ledger_getL2BlockByNumber */
  }
}
```

***

### `ledger_getL2BlockRange`

**Description**\
Returns all L2 blocks in the inclusive range `[start, end]`.

#### HTTP Request

```sh
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

```json
{
  "jsonrpc": "2.0",
  "method": "ledger_getL2BlockRange",
  "params": [1000333, 1000335],
  "id": 1
}
```

#### Parameters

| Name    | Type      | Required | Description                 |
| ------- | --------- | -------- | --------------------------- |
| `start` | `integer` | **Yes**  | First block number in range |
| `end`   | `integer` | **Yes**  | Last block number in range  |

#### Example Response

```json
{
  "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`

**Description**\
Returns the latest (head) L2 block.

#### HTTP Request

```sh
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

```json
{
  "jsonrpc": "2.0",
  "method": "ledger_getHeadL2Block",
  "params": [],
  "id": 1
}
```

#### Parameters

*None*

#### Example Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    /* Same structure as ledger_getL2BlockByNumber */
  }
}
```

***

### `ledger_getHeadL2BlockHeight`

**Description**\
Returns the block number of the latest L2 block.

#### HTTP Request

```sh
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

```json
{
  "jsonrpc": "2.0",
  "method": "ledger_getHeadL2BlockHeight",
  "params": [],
  "id": 1
}
```

#### Parameters

*None*

#### Example Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xbed0d6"
}
```

#### Response Fields

| Field    | Type     | Description                          |
| -------- | -------- | ------------------------------------ |
| `result` | `string` | Latest L2 block height in hex format |

***

## Genesis & State Endpoints

### `ledger_getL2GenesisStateRoot`

**Description**\
Returns the 32-byte genesis state root for L2.

#### HTTP Request

```sh
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

```json
{
  "jsonrpc": "2.0",
  "method": "ledger_getL2GenesisStateRoot",
  "params": [],
  "id": 1
}
```

#### Parameters

*None*

#### Example Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x785c6d461111b5e9fdc515e0955d55baddfd8eb2dd2769342cc58060d6f5e0c5"
}
```

#### Response Fields

| Field    | Type     | Description                      |
| -------- | -------- | -------------------------------- |
| `result` | `string` | 32-byte genesis state root (hex) |

***

## Sequencer Commitment Endpoints

### `ledger_getSequencerCommitmentsOnSlotByNumber`

**Description**\
Returns sequencer commitment(s) found in the specified DA slot height.

#### HTTP Request

```sh
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

```json
{
  "jsonrpc": "2.0",
  "method": "ledger_getSequencerCommitmentsOnSlotByNumber",
  "params": [88001],
  "id": 1
}
```

#### Parameters

| Name     | Type      | Required | Description       |
| -------- | --------- | -------- | ----------------- |
| `height` | `integer` | **Yes**  | L1 DA slot height |

#### Example Response

**If commitments exist:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "merkleRoot": "0xd6dc3eb1a59be7bc1ece68318f82a60919f0f98d8c648337d588ce243a17f473",
      "index": "0xba5",
      "l2EndBlockNumber": "0xb7a20b"
    },
    {
      "merkleRoot": "0xf85a8f3f872fe8079fe778a2f6a8ebd92cf3d1a7c6324af025c8bffbb46d1811",
      "index": "0xba6",
      "l2EndBlockNumber": "0xb7a5f3"
    }
  ]
}
```

**If no commitments:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}
```

#### Response Fields

| Field              | Type     | Description                            |
| ------------------ | -------- | -------------------------------------- |
| `merkleRoot`       | `string` | Merkle root of sequencer commitment    |
| `index`            | `string` | Global commitment index (hex)          |
| `l2EndBlockNumber` | `string` | Last L2 block in this commitment (hex) |

***

### `ledger_getSequencerCommitmentsOnSlotByHash`

**Description**\
Returns sequencer commitment(s) found in the DA slot identified by its L1 block hash.

#### HTTP Request

```sh
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

```json
{
  "jsonrpc": "2.0",
  "method": "ledger_getSequencerCommitmentsOnSlotByHash",
  "params": ["788636f732f490c5072582c7dcde85e34d737c8a4d98e792a59c9d0100000000"],
  "id": 1
}
```

#### Parameters

| Name   | Type     | Required | Description                |
| ------ | -------- | -------- | -------------------------- |
| `hash` | `string` | **Yes**  | 32-byte DA slot hash (hex) |

#### Example Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "merkleRoot": "0xd6dc3eb1a59be7bc1ece68318f82a60919f0f98d8c648337d588ce243a17f473",
      "index": "0xba5",
      "l2EndBlockNumber": "0xb7a20b"
    }
  ]
}
```

***

### `ledger_getSequencerCommitmentByIndex`

**Description**\
Returns a sequencer commitment by its global index.

#### HTTP Request

```sh
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

```json
{
  "jsonrpc": "2.0",
  "method": "ledger_getSequencerCommitmentByIndex",
  "params": ["0xba5"],
  "id": 1
}
```

#### Parameters

| Name    | Type     | Required | Description            |
| ------- | -------- | -------- | ---------------------- |
| `index` | `string` | **Yes**  | Commitment index (hex) |

#### Example Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "merkleRoot": "0xd6dc3eb1a59be7bc1ece68318f82a60919f0f98d8c648337d588ce243a17f473",
    "index": "0xba5",
    "l2EndBlockNumber": "0xb7a20b"
  }
}
```

***

## Proof Endpoints

### `ledger_getVerifiedBatchProofsBySlotHeight`

**Description**\
Returns verified ZK batch proof(s) for the specified DA slot height.

#### HTTP Request

```sh
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

```json
{
  "jsonrpc": "2.0",
  "method": "ledger_getVerifiedBatchProofsBySlotHeight",
  "params": [85890],
  "id": 1
}
```

#### Parameters

| Name     | Type      | Required | Description         |
| -------- | --------- | -------- | ------------------- |
| `height` | `integer` | **Yes**  | DA slot height (L1) |

#### Example Response

```json
{
  "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

| Field                                       | Type     | Description                     |
| ------------------------------------------- | -------- | ------------------------------- |
| `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`

**Description**\
Returns the most recent verified batch proof.

#### HTTP Request

```sh
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

```json
{
  "jsonrpc": "2.0",
  "method": "ledger_getLastVerifiedBatchProof",
  "params": [],
  "id": 1
}
```

#### Parameters

*None*

#### Example Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    /* Same structure as ledger_getVerifiedBatchProofsBySlotHeight */
  }
}
```

***

## L1 Integration Endpoints

### `ledger_getLastScannedL1Height`

**Description**\
Returns the highest L1 block number the node has scanned so far.

#### HTTP Request

```sh
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

```json
{
  "jsonrpc": "2.0",
  "method": "ledger_getLastScannedL1Height",
  "params": [],
  "id": 1
}
```

#### Parameters

*None*

#### Example Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x15e53"
}
```

#### Response Fields

| Field    | Type     | Description                        |
| -------- | -------- | ---------------------------------- |
| `result` | `string` | Last scanned L1 block height (hex) |

***

## Status Query Endpoints

### `citrea_getLastCommittedL2Height`

**Description**\
Returns the latest L2 block height that has been committed to Bitcoin via sequencer commitment.

#### HTTP Request

```sh
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

```json
{
  "jsonrpc": "2.0",
  "method": "citrea_getLastCommittedL2Height",
  "params": [],
  "id": 1
}
```

#### Parameters

*None*

#### Example Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "height": 12489007,
    "commitment_index": 3444
  }
}
```

#### Response Fields

| Field              | Type     | Description                      |
| ------------------ | -------- | -------------------------------- |
| `height`           | `number` | Latest committed L2 block height |
| `commitment_index` | `number` | Sequencer commitment index       |

***

### `citrea_getLastProvenL2Height`

**Description**\
Returns the latest L2 block height that has been proven on Bitcoin with a validity proof.

#### HTTP Request

```sh
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

```json
{
  "jsonrpc": "2.0",
  "method": "citrea_getLastProvenL2Height",
  "params": [],
  "id": 1
}
```

#### Parameters

*None*

#### Example Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "height": 11457999,
    "commitment_index": 2401
  }
}
```

#### Response Fields

| Field              | Type     | Description                   |
| ------------------ | -------- | ----------------------------- |
| `height`           | `number` | Latest proven L2 block height |
| `commitment_index` | `number` | Sequencer commitment index    |

***

### `citrea_getL2StatusHeightsByL1Height`

**Description**\
Returns committed and proven L2 heights as of a given Bitcoin block.

#### HTTP Request

```sh
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

```json
{
  "jsonrpc": "2.0",
  "method": "citrea_getL2StatusHeightsByL1Height",
  "params": [800000],
  "id": 1
}
```

#### Parameters

| Name        | Type      | Required | Description                   |
| ----------- | --------- | -------- | ----------------------------- |
| `l1_height` | `integer` | **Yes**  | Bitcoin block height to query |

#### Example Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "committed": {
      "height": 12489007,
      "commitment_index": 3444
    },
    "proven": {
      "height": 11457999,
      "commitment_index": 2401
    }
  }
}
```

#### Response Fields

| Field       | Type     | Description                |
| ----------- | -------- | -------------------------- |
| `committed` | `object` | Latest committed L2 status |
| `proven`    | `object` | Latest proven L2 status    |

***

## Deposit Endpoints

### `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

```sh
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

```json
{
  "jsonrpc": "2.0",
  "method": "citrea_sendRawDepositTransaction",
  "params": ["0x01020304..."],
  "id": 1
}
```

#### Parameters

| Name      | Type     | Required | Description                          |
| --------- | -------- | -------- | ------------------------------------ |
| `deposit` | `string` | **Yes**  | Raw serialized deposit tx data (hex) |

#### Example Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}
```

#### Response Fields

| Field    | Type   | Description          |
| -------- | ------ | -------------------- |
| `result` | `null` | Success returns null |

***

### `eth_estimateDiffSize`

**Description**\
Returns estimated diff size and gas consumption for a potential transaction.

#### HTTP Request

```sh
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

```json
{
  "jsonrpc": "2.0",
  "method": "eth_estimateDiffSize",
  "params": [{
    "from": "0x0452663bfc46B86aC93d8220D9847cF5220D7642",
    "to": "0x5fbdb2315678afecb367f032d93f642f64180aa3",
    "value": "10000"
  }],
  "id": 1
}
```

#### Parameters

Same as [`eth_estimateGas`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_estimategas).

#### Example Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "gas": "0x5208",
    "l1DiffSize": "0x11"
  }
}
```

#### Response Fields

| Field        | Type     | Description                     |
| ------------ | -------- | ------------------------------- |
| `gas`        | `string` | Estimated gas consumption (hex) |
| `l1DiffSize` | `string` | Estimated L1 diff size (hex)    |

***

## Error Responses

All endpoints may return standard JSON-RPC error responses:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params"
  }
}
```

### Common Error Codes

| Code     | Message          | Description                                  |
| -------- | ---------------- | -------------------------------------------- |
| `-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` prefix
* Block heights can be specified as integers or hex strings (block tags of Ethereum-spec also work)
* 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.citrea.xyz/developer-documentation/rpc-documentation/citrea-rpc-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.