> For the complete documentation index, see [llms.txt](https://docs.lighter.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lighter.xyz/evm/json-rpc-api.md).

# JSON-RPC API

## Standard Ethereum RPC

Standard Ethereum JSON-RPC methods are supported on Lighter EVM. The following namespaces are available:

* `eth` — standard Ethereum methods (`eth_blockNumber`, `eth_getBalance`, `eth_sendRawTransaction`, etc.)
* `net` — network info (`net_version`, `net_listening`, etc.)
* `web3` — utility methods (`web3_clientVersion`, `web3_sha3`)
* `debug` — debug methods (`debug_traceTransaction`, `debug_traceCall`, etc.)
* `trace` — trace methods (`trace_transaction`, `trace_block`, etc.)

These methods are available on your configured Lighter EVM RPC endpoint.

### L1 data fee fields

`eth_getTransactionReceipt` responses include three additional fields reporting the transaction's [L1 data fee](/evm/differences-from-l1-evm/l1-data-fee.md):

* `l1GasUsed` — pubdata bytes metered for the transaction.
* `l1GasPrice` — price per pubdata byte, in wei.
* `l1Fee` — `l1GasUsed * l1GasPrice`, in wei.

Fee-exempt exogenous transactions report their metered bytes in `l1GasUsed` with `l1GasPrice = 0` and `l1Fee = 0`.

## Lighter RPC

Lighter EVM additionally exposes a `lighter` JSON-RPC namespace with Lighter-specific RPC methods.

### `lighter_syncStatus`

Returns the current sync status of the sequencer.

**Response:**

```json
{
  "headL1":      { "number": 0, "hash": "0x…", "parentHash": "0x…", "timestamp": 0 },
  "safeL1":      { "number": 0, "hash": "0x…", "parentHash": "0x…", "timestamp": 0 },
  "finalizedL1": { "number": 0, "hash": "0x…", "parentHash": "0x…", "timestamp": 0 },
  "unsafeL2":    { "number": 0, "hash": "0x…", "parentHash": "0x…", "timestamp": 0, "parentCoreBlock": 0 },
  "safeL2":      { "number": 0, "hash": "0x…", "parentHash": "0x…", "timestamp": 0, "parentCoreBlock": 0 },
  "finalizedL2": { "number": 0, "hash": "0x…", "parentHash": "0x…", "timestamp": 0, "parentCoreBlock": 0 },
  "latestCommittedBatch": { "batchNumber": 0, "upToL2BlockNumber": 0, "l1CommitBlockNumber": 0 },
  "latestVerifiedBatch":  { "batchNumber": 0, "upToL2BlockNumber": 0, "l1VerificationBlockNumber": 0 },
  "latestExecutedBatch":  { "batchNumber": 0, "upToL2BlockNumber": 0, "l1BatchExecutionBlockNumber": 0 }
}
```

All fields are nullable — they return `null` until the sequencer has observed the corresponding state. L2 block references include a `parentCoreBlock` field indicating the Core block height that the EVM block's state is derived from.

### `lighter_getWithdrawalProof`

Returns the Merkle proof and the claim arguments for a withdrawal initiated on Lighter EVM, once the batch containing it has been executed on L1. See [L1 and EVM](/evm/interop/message-passing/l1-and-evm.md#obtaining-the-proof) for the full flow.

**Parameters:**

1. `txHash` — hash of the Lighter EVM transaction that emitted the `WithdrawalInitiated` event.
2. `index` — zero-based position of the `WithdrawalInitiated` event among those emitted by the transaction (`0` for a transaction with a single withdrawal).

**Response:**

```json
{
  "batchNumber": 1287,
  "proof": ["0x…", "0x…"],
  "isLeft": "0x2",
  "l1CallHash": "0x…",
  "root": "0x…",
  "l2Sender": "0x…",
  "to": "0x…",
  "value": "0x2386f26fc10000",
  "msgNonce": "0x1c",
  "data": "0x"
}
```

**Errors:**

The method returns a JSON-RPC error with code `-32000` and a descriptive message when:

* The batch containing the transaction has not yet finalized on L1.
* The transaction is unknown to the node, for example because a follower node has not imported its block yet.
* `index` is greater than or equal to the number of `WithdrawalInitiated` events the transaction emitted.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.lighter.xyz/evm/json-rpc-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.