Ethereum JSON-RPC API

JSON-RPC API methods for the eth_ namespace for ZKsync Era.

ZKsync Era supports the standard Ethereum JSON-RPC API.

Important Differences for Developers

When working with ZKsync, there are specific differences you should be aware of:

  1. Block Data Retrieval Methods:
    • Methods that return data about a block, such as eth_getBlockByHash, eth_getBlockByNumber, and Geth’s pubsub API eth_subscribe with the newHeads parameter, do not provide the actual receiptsRoot, transactionsRoot, and stateRoot values.
    • Instead, these fields contain zero values because ZKsync’s L2 blocks do not include the concept of a state root; only L1 batches have this concept.
  2. Unsupported Method:
    • The method eth_sendTransaction is intentionally not supported in ZKsync.

eth_chainId

Gets the current chain ID.

Parameters

None

Returns

QUANTITY - hexadecimal representation of the current blockchain network's chain ID.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "eth_chainId",
      "params": []
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "0x144",
  "id": 1
}

eth_call

Executes a new message call immediately without creating a transaction on the block chain.

Parameters

  1. CallRequest - object

  2. BlockIdVariant - Optional. See the default block parameters.

Returns

DATA - The data returned by the smart contract function, encoded in hexadecimal format.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "eth_call",
      "params": [
        {
          "to": "0xc94770007dda54cF92009BFF0dE90c06F603a09f"
        },
        "latest"
      ]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "0x",
  "id": 1
}

eth_estimateGas

Estimates the amount of gas needed to execute a call. The from field cannot be a smart contract that is not a SmartAccount if so an exception is hit.

Parameters

  1. CallRequest - object

  2. uint32 - Optional block number.

Returns

QUANTITY - The estimated amount of gas in hexadecimal format.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "eth_estimateGas",
      "params": [
        {
          "to": "0x...",
          "data": "0x..."
        }
      ]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x5cec"
}

eth_gasPrice

Retrieves the current average gas price in the network, expressed in gwei. This value provides an estimate of how much each unit of gas would cost for transactions on the network at the time of the query. It's particularly useful for dynamically adjusting transaction fees to current network conditions.

Parameters

None

Returns

QUANTITY - The current average gas price on the network, represented in gwei and encoded as a hexadecimal string.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "eth_gasPrice",
      "params": []
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "0x17d7840",
  "id": 1
}

eth_newFilter

Initiates a new filter for listening to specific events emitted by smart contracts or other blockchain actions. This feature enables applications to react to events and updates in real-time by setting criteria for the events they're interested in.

Parameters

  1. Filter - Object containing various fields to specify the criteria for filtering events

Returns

QUANTITY - unique identifier of the newly created filter, encoded as a hexadecimal string.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "eth_newFilter",
      "params": [
        {
          "topics": [
            "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
          ]
        }
      ]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "0xb415d4b0e6ca750802be8c84c99a68170deeb9ed09c4e2eb0dc5299ab715e978",
  "id": 1
}

eth_newBlockFilter

Creates a filter to notify when a new block arrives.

Parameters

None

Returns

QUANTITY - unique identifier of the newly created block filter, encoded as a hexadecimal string.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "eth_newBlockFilter",
      "params": []
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "0xb825a38f6350ff4d75d806e6f83a42a31d39fc7ef4fde02b404e8edeef6799b",
  "id": 1
}

eth_uninstallFilter

Removes a filter that was previously created using eth_newFilter, eth_newBlockFilter, or eth_newPendingTransactionFilter. This method is used to stop receiving updates for the specified filter and to clean up resources associated with it on the node.

Parameters

  1. QUANTITY, 32 bytes - unique identifier of the filter to be removed, originally returned by the filter creation method.

Returns

Boolean - true if the filter was successfully uninstalled; otherwise, false.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "eth_uninstallFilter",
      "params": ["0xb825a38f6350ff4d75d806e6f83a42a31d39fc7ef4fde02b404e8edeef6799b"]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": true,
  "id": 1
}

eth_newPendingTransactionFilter

Sets up a new filter to provide notifications for transactions that enter the pending state, which means they are broadcast to the network but not yet included in a block. This filter is useful for tracking transactions that are awaiting confirmation.

Parameters

None

Returns

QUANTITY, 32 bytes - unique identifier of the new filter for pending transactions, encoded as a hexadecimal string.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "eth_newPendingTransactionFilter",
      "params": []
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "0x9d844950bf3e368b43490ff4efdc0a009887365103f9fece0d8cc44adabf6a82",
  "id": 1
}

eth_getLogs

Retrieves the logs matching a filter object.

Parameters

  1. Filter - Object containing various fields to specify the criteria for filtering events

Returns

Array of log objects that match the filter criteria. Each log object contains detailed information about a single log entry.

  • address: Data, 20 bytes - address of the contract that generated the log.
  • topics: Array of Data - Topics are indexed event parameters stored in the log.
  • data: DATA - The data contained in the log.
  • blockHash: DATA, 32 bytes - Hash of the block where this log was in.
  • blockNumber: QUANTITY - block number where this log was in.
  • transactionHash: DATA, 32 bytes - Hash of the transaction that generated this log.
  • transactionIndex: QUANTITY - Integer of the transaction's index position in the block.
  • logIndex: QUANTITY - Integer of the log's index position in the block.
  • transactionIndex: QUANTITY - Integer of the log's index position in the transaction.
  • logType: String - The type of log (can be null).
  • removed: Boolean - Indicates if the log was removed due to a chain reorganization.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "eth_getLogs",
      "params": [
        {
          "topics": [
            "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
          ],
          "fromBlock": "latest"
        }
      ]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": [
    {
      "address": "0x000000000000000000000000000000000000800a",
      "topics": [
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "0x00000000000000000000000091307ca99c2a9caac9d24259ae719a4a98453ba1",
        "0x0000000000000000000000000000000000000000000000000000000000008001"
      ],
      "data": "0x00000000000000000000000000000000000000000000000000007df3cbd10c80",
      "blockHash": "0xa0ddf35a0e35d03f533a2620d8c37fd4162d740cec3d3c635f43ca213f8a051f",
      "blockNumber": "0x1d2ba84",
      "transactionHash": "0xfdfcfdc6a0e2e3d09218749a752a2c2933f9eda5e9985c7fa3d861cb0112817d",
      "transactionIndex": "0x0",
      "logIndex": "0x0",
      "l1BatchNumber": null,
      "transactionLogIndex": "0x0",
      "logType": null,
      "removed": false
    },
    ...
  ],
  "id": 1
}

eth_getFilterLogs

Retrieves the logs for a filter created with eth_newFilter.

Parameters

  1. QUANTITY, 32 bytes - the filter id.

Returns

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "eth_getFilterLogs",
      "params": [
        "0xae2bfd759a98fd5e7a262f785b7706103a174391c5081dda92fea2cf6d9f94a6"
      ]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": [
    {...}
  ],
  "id": 1
}

eth_getFilterChanges

Retrieves the logs since the last poll for a filter created with eth_newFilter.

Parameters

  1. QUANTITY, 32 bytes - the filter id.

Returns

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "eth_getFilterChanges",
      "params": [
        "0x127e9eca4f7751fb4e5cb5291ad8b455"
      ]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": [
    {...}
  ],
  "id": 1
}

eth_getBalance

Gets the balance of an account at a specific block.

Parameters

  1. DATA, 20 bytes - address of the account whose balance is being queried.

  2. QUANTITY | TAG - integer block number, or the string "latest", "earliest", "pending", "safe" or "finalized", see the default block parameter

Returns

QUANTITY - The balance of the account at the specified block, encoded as a hexadecimal string representing the value in gwei.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "eth_getBalance",
      "params": [
        "0x103301a002a8AaDC8Fb83A2A70740FA6da7f83b8",
        "latest"
      ]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "id":1,
  "result": "0x12e54351196e564"
}

eth_getBlockByNumber

Retrieves a block by its number.

Parameters

  1. QUANTITY | TAG - integer block number, or the string "latest", "earliest", "pending", "safe" or "finalized", see the default block parameter

  2. Boolean - A boolean flag indicating whether to return full transaction objects (true) or just their hashes (false).

Returns

Object representing the requested block, including various metadata fields and either a list of transaction hashes or full transaction objects, based on the full_transactions parameter.

  • hash: DATA, 32 bytes - hash of the block.
  • parentHash: DATA, 32 bytes - hash of the block's parent.
  • sha3Uncles: DATA, 32 bytes - SHA3 of the uncles data in the block.
  • miner: DATA, 20 bytes - address of the miner who mined the block.
  • stateRoot: DATA, 32 bytes - root of the final state trie of the block.
  • transactionsRoot: DATA, 32 bytes - root of the trie of the transactions in the block.
  • receiptsRoot: Data, 32 bytes - root of the receipts trie of the block.
  • number: QUANTITY - block number.
  • l1BatchNumber: QUANTITY - (Optional) The L1 batch number associated with the block.
  • gasUsed: QUANTITY - total gas used by all transactions in this block.
  • gasLimit: QUANTITY - gas limit of the block.
  • baseFeePerGas: QUANTITY - (Optional) base fee per gas in the block.
  • extraData: DATA - Extra data attached to the block.
  • logsBloom: DATA, 256 bytes - The bloom filter for the logs contained in the block.
  • timestamp: QUANTITY - timestamp for when the block was collated.
  • l1BatchTimestamp: QUANTITY - (Optional) L1 batch timestamp associated with the block.
  • difficulty: QUANTITY - difficulty of the block.
  • totalDifficulty: QUANTITY - total difficulty of the chain up to this block.
  • uncles: Array - An array of uncle hashes.
  • transactions: Array - An array of transaction hashes or transaction objects, depending on the full_transactions parameter.
  • size: QUANTITY - size of the block in bytes.
  • mixHash: DATA - mix hash of the block.
  • nonce: DATA, 8 bytes - nonce of the block.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_getBlockByNumber",
    "params": ["0x1d1551e", false]
  }'

Example Response

{
  "jsonrpc": "2.0",
  "result": {
    "hash": "0x5046bdc714b2a9b40e9fbfdfc5140371c1b03b40335d908de92a7686dcc067e9",
    "parentHash": "0x41f40b22c984aaf1c4cc98bfc8357156729f0a57ddc367fca8b38866b6b4a600",
    "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
    "miner": "0x0000000000000000000000000000000000000000",
    "stateRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "transactionsRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "receiptsRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "number": "0x1d1551e",
    "l1BatchNumber": "0x72ae1",
    "gasUsed": "0x1215d56",
    "gasLimit": "0xffffffff",
    "baseFeePerGas": "0x17d7840",
    "extraData": "0x",
    "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "timestamp": "0x660c1740",
    "l1BatchTimestamp": "0x660c16dc",
    "difficulty": "0x0",
    "totalDifficulty": "0x0",
    "sealFields": [],
    "uncles": [],
    "transactions": [
      "0xb2adc4d2b3203e186001dc37fdf02cc8e772518425d263adc6a17dbddff3bfda",
      "0xf200616da35820f5f407ffcc0a3fef84c8124638377eb2fdb4925888a90ff7da",
      "0x54ba07e65314ea38ececd0f7f623306f00103727865bf036a0117181b596c95b",
      "0x9453e01668129bc6e0bcece2a28a424fdde1624e5db03f83de51430ff3954b45",
      "0xac42bce47be22c4bd7891b476be7ff7a9c67442c8359da0e5c598fa2f9fe71ef",
      "0x1b1db6412cdf4ca8158b5efbeeada70d1d6e67a290b529e1fec145bab1e407da",
      "0x5fe0e3ee65f5c6be6975bccfd116d54dd5d8b3c83074165a5641087fe36d2ee3",
      "0x6ce2631af03a2d939a34d159ae01d025da4ea162ed5bf6769e18ace64cce29a9",
      "0x386d0fdb243f20e8b2d2683686baa315b16cc81f7b80ea58f69b628e4e047a32",
      "0x2c72143b520c4ad826972fc0725a8eeac590188b683cbb0cf103e5be60349607",
      "0x0f7d10d27357b2f69b63cc808b76faf4c3d3bbd6dae59a10930399f6a7ab476b"
    ],
    "size": "0x0",
    "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "nonce": "0x0000000000000000"
  },
  "id": 2
}

eth_getBlockByHash

Retrieves a block by its hash.

Parameters

  1. DATA, 32 bytes - hexadecimal string representing the hash of the block.
  2. Boolean - A boolean flag indicating whether to return full transaction objects (true) or just their hashes (false).

Returns

Object containing detailed information about the block and its transactions.

  • hash: DATA, 32 bytes - hash of the block.
  • parentHash: DATA, 32 bytes - hash of the block's parent.
  • sha3Uncles: DATA, 32 bytes - SHA3 of the uncles data in the block.
  • miner: DATA, 20 bytes - address of the miner who mined the block.
  • stateRoot: DATA, 32 bytes - root of the final state trie of the block.
  • transactionsRoot: DATA, 32 bytes - root of the trie of the transactions in the block.
  • receiptsRoot: Data, 32 bytes - root of the receipts trie of the block.
  • number: QUANTITY - block number.
  • l1BatchNumber: QUANTITY - (Optional) The L1 batch number associated with the block.
  • gasUsed: QUANTITY - total gas used by all transactions in this block.
  • gasLimit: QUANTITY - gas limit of the block.
  • baseFeePerGas: QUANTITY - (Optional) base fee per gas in the block.
  • extraData: DATA - Extra data attached to the block.
  • logsBloom: DATA, 256 bytes - The bloom filter for the logs contained in the block.
  • timestamp: QUANTITY - timestamp for when the block was collated.
  • l1BatchTimestamp: QUANTITY - (Optional) L1 batch timestamp associated with the block.
  • difficulty: QUANTITY - difficulty of the block.
  • totalDifficulty: QUANTITY - total difficulty of the chain up to this block.
  • uncles: Array - An array of uncle hashes.
  • transactions: Array - An array of transaction hashes or transaction objects, depending on the full_transactions parameter.
  • size: QUANTITY - size of the block in bytes.
  • mixHash: DATA - mix hash of the block.
  • nonce: DATA, 8 bytes - nonce of the block.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "eth_getBlockByHash",
      "params": [
        "0x5046bdc714b2a9b40e9fbfdfc5140371c1b03b40335d908de92a7686dcc067e9",
        false
      ]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": {
    "hash": "0x5046bdc714b2a9b40e9fbfdfc5140371c1b03b40335d908de92a7686dcc067e9",
    "parentHash": "0x41f40b22c984aaf1c4cc98bfc8357156729f0a57ddc367fca8b38866b6b4a600",
    "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
    "miner": "0x0000000000000000000000000000000000000000",
    "stateRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "transactionsRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "receiptsRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "number": "0x1d1551e",
    "l1BatchNumber": "0x72ae1",
    "gasUsed": "0x1215d56",
    "gasLimit": "0xffffffff",
    "baseFeePerGas": "0x17d7840",
    "extraData": "0x",
    "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "timestamp": "0x660c1740",
    "l1BatchTimestamp": "0x660c16dc",
    "difficulty": "0x0",
    "totalDifficulty": "0x0",
    "sealFields": [],
    "uncles": [],
    "transactions": [
      "0xb2adc4d2b3203e186001dc37fdf02cc8e772518425d263adc6a17dbddff3bfda",
      "0xf200616da35820f5f407ffcc0a3fef84c8124638377eb2fdb4925888a90ff7da",
      "0x54ba07e65314ea38ececd0f7f623306f00103727865bf036a0117181b596c95b",
      "0x9453e01668129bc6e0bcece2a28a424fdde1624e5db03f83de51430ff3954b45",
      "0xac42bce47be22c4bd7891b476be7ff7a9c67442c8359da0e5c598fa2f9fe71ef",
      "0x1b1db6412cdf4ca8158b5efbeeada70d1d6e67a290b529e1fec145bab1e407da",
      "0x5fe0e3ee65f5c6be6975bccfd116d54dd5d8b3c83074165a5641087fe36d2ee3",
      "0x6ce2631af03a2d939a34d159ae01d025da4ea162ed5bf6769e18ace64cce29a9",
      "0x386d0fdb243f20e8b2d2683686baa315b16cc81f7b80ea58f69b628e4e047a32",
      "0x2c72143b520c4ad826972fc0725a8eeac590188b683cbb0cf103e5be60349607",
      "0x0f7d10d27357b2f69b63cc808b76faf4c3d3bbd6dae59a10930399f6a7ab476b"
    ],
    "size": "0x0",
    "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "nonce": "0x0000000000000000"
  },
  "id": 2
}

eth_getBlockTransactionCountByNumber

This method provides the total number of transactions included in a specific block, identified by its block number. It's a useful query for understanding the volume of transactions processed in a particular block.

Parameters

  1. QUANTITY | TAG - integer block number, or the string "latest", "earliest", "pending", "safe" or "finalized", see the default block parameter

Returns

QUANTITY - number of transactions in the specified block, encoded as a hexadecimal string.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "eth_getBlockTransactionCountByNumber",
      "params": ["0x1d1551e"]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "0xb",
  "id": 2
}

eth_getBlockReceipts

Fetches transaction receipts for all transactions in a specified block, offering comprehensive details such as the transaction status, gas used, and event logs.

Parameters

  1. QUANTITY | TAG - integer block number, or the string "latest", "earliest", "pending", "safe" or "finalized", see the default block parameter

Returns

Array of transaction receipt objects, each containing detailed information about a transaction included in the specified block.

  • transactionHash: DATA, 32 bytes - hash of the transaction.
  • transactionIndex: QUANTITY - index of the transaction in the block.
  • blockHash: DATA, 32 bytes - hash of the block containing the transaction.
  • blockNumber: QUANTITY - block number.
  • from: DATA, 20 bytes - address of the sender.
  • to: DATA, 20 bytes - address of the receiver. Can be null for contract creation transactions.
  • cumulativeGasUsed: QUANTITY - total amount of gas used when this transaction was executed in the block.
  • gasUsed: QUANTITY - amount of gas used by this specific transaction.
  • contractAddress: DATA, 20 bytes - contract address created, if the transaction was a contract creation, otherwise null.
  • logs: Array<Log> - An array of log objects generated by this transaction.
  • status: QUANTITY - status of the transaction, where "0x1" indicates success and "0x0" indicates failure.
  • logsBloom: DATA - bloom filter for the logs of the block.
  • type: QUANTITY - type of the transaction.
  • effectiveGasPrice: QUANTITY - effective gas price paid per unit of gas.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "eth_getBlockReceipts",
      "params": ["0x1d1551e"]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": [
    {
  "jsonrpc": "2.0",
  "result": [
    {
      "transactionHash": "0xb2adc4d2b3203e186001dc37fdf02cc8e772518425d263adc6a17dbddff3bfda",
      "transactionIndex": "0x0",
      "blockHash": "0x5046bdc714b2a9b40e9fbfdfc5140371c1b03b40335d908de92a7686dcc067e9",
      "blockNumber": "0x1d1551e",
      "l1BatchTxIndex": "0x469",
      "l1BatchNumber": "0x72ae1",
      "from": "0x1bc3366b3664c01b8687b1efcfc6478d9351a8a9",
      "to": "0x9b5def958d0f3b6955cbea4d5b7809b2fb26b059",
      "cumulativeGasUsed": "0x0",
      "gasUsed": "0x2b9bcb",
      "contractAddress": null,
      "logs": [
        {
          "address": "0x000000000000000000000000000000000000800a",
          "topics": [
            "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
            "0x0000000000000000000000001bc3366b3664c01b8687b1efcfc6478d9351a8a9",
            "0x0000000000000000000000000000000000000000000000000000000000008001"
          ],
          "data": "0x0000000000000000000000000000000000000000000000000001011c8f80b6c0",
          "blockHash": "0x5046bdc714b2a9b40e9fbfdfc5140371c1b03b40335d908de92a7686dcc067e9",
          "blockNumber": "0x1d1551e",
          "l1BatchNumber": "0x72ae1",
          "transactionHash": "0xb2adc4d2b3203e186001dc37fdf02cc8e772518425d263adc6a17dbddff3bfda",
          "transactionIndex": "0x0",
          "logIndex": "0x0",
          "transactionLogIndex": "0x0",
          "logType": null,
          "removed": false
        },
        {
          ...
        },
        ...
      ],
      "l2ToL1Logs": [],
      "status": "0x1",
      "root": "0x5046bdc714b2a9b40e9fbfdfc5140371c1b03b40335d908de92a7686dcc067e9",
      "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
      "type": "0x2",
      "effectiveGasPrice": "0x17d7840"
    },}
  ],
  "id": 2
}

eth_getBlockTransactionCountByHash

This method returns the number of transactions included in a block, identified by the block's hash. It's particularly useful for determining the transaction volume within a specific block without retrieving the transactions themselves.

Parameters

  1. DATA, 32 bytes - hash of the block for which the transaction count is requested. This should be provided as a hexadecimal string.

Returns

QUANTITY - number of transactions in the block, encoded as a hexadecimal string.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 2,
      "method": "eth_getBlockTransactionCountByHash",
      "params": ["0x5046bdc714b2a9b40e9fbfdfc5140371c1b03b40335d908de92a7686dcc067e9"]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "0xb",
  "id": 2
}

eth_getCode

Retrieves the code at a specific address at an optional block.

Parameters

  1. DATA, 20 bytes - The Ethereum address in hexadecimal format from which to retrieve the code.

  2. QUANTITY | TAG - integer block number, or the string "latest", "earliest", "pending", "safe" or "finalized", see the default block parameter

Returns

DATA - The code at the given address in the specified block, returned as a hexadecimal string. If the address is not a contract a 0x is returned.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 2,
      "method": "eth_getCode",
      "params": [
        "0x0cBE9d8a007ac5A090Ebdf044b688Fa8dfD862c3"
      ]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "0x00040000000000020000008003000039000000400030043f000000000301001900000060033002700000005d0330019700000001022001900000002a0000c13d000000040230008c0...",
  "id": 2
}

eth_getStorageAt

Retrieves the value from a storage position at a given address.

Parameters

  1. DATA, 20 bytes - address
  2. QUANTITY - index position of the storage slot in hexadecimal format, starting from 0x0.

  3. QUANTITY | TAG - integer block number, or the string "latest", "earliest", "pending", "safe" or "finalized", see the default block parameter

Returns

DATA - the value at this storage position.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 2,
      "method": "eth_getStorageAt",
      "params": ["0x0cBE9d8a007ac5A090Ebdf044b688Fa8dfD862c3", "0x0", "latest"]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "id": 2
}

eth_getTransactionCount

Gets the number of transactions sent from an address.

Parameters

  1. DATA, 20 bytes - address

  2. QUANTITY | TAG - integer block number, or the string "latest", "earliest", "pending", "safe" or "finalized", see the default block parameter

Returns

QUANTITY - integer of the number of transactions sent from this address.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 2,
      "method": "eth_getTransactionCount",
      "params": [
        "0x0f54f47bf9b8e317b214ccd6a7c3e38b893cd7f0",
        "latest"
      ]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "0x0",
  "id": 2
}

eth_getTransactionByHash

Retrieves a transaction by its hash.

Parameters

  1. DATA, 32 bytes - hash of a transaction.

Returns

Object - A transaction object, or null when no transaction was found:

  • blockHash: DATA, 32 Bytes - hash of the block where this transaction was in. null when its pending.
  • blockNumber: QUANTITY - block number where this transaction was in. null when its pending.
  • from: DATA, 20 Bytes - address of the sender.
  • gas: QUANTITY - gas provided by the sender.
  • gasPrice: QUANTITY - gas price provided by the sender in Wei.
  • hash: DATA, 32 Bytes - hash of the transaction.
  • input: DATA - the data send along with the transaction.
  • nonce: QUANTITY - the number of transactions made by the sender prior to this one.
  • to: DATA, 20 Bytes - address of the receiver. null when its a contract creation transaction.
  • transactionIndex: QUANTITY - integer of the transactions index position in the block. null when its pending. value: QUANTITY - value transferred in Wei.
  • v: QUANTITY - ECDSA recovery id
  • r: QUANTITY - ECDSA signature r
  • s: QUANTITY - ECDSA signature s

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 2,
      "method": "eth_getTransactionByHash",
      "params": [
        "0xb2adc4d2b3203e186001dc37fdf02cc8e772518425d263adc6a17dbddff3bfda"
      ]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": {
    "hash": "0xb2adc4d2b3203e186001dc37fdf02cc8e772518425d263adc6a17dbddff3bfda",
    "nonce": "0x14c",
    "blockHash": "0x5046bdc714b2a9b40e9fbfdfc5140371c1b03b40335d908de92a7686dcc067e9",
    "blockNumber": "0x1d1551e",
    "transactionIndex": "0x0",
    "from": "0x1bc3366b3664c01b8687b1efcfc6478d9351a8a9",
    "to": "0x9b5def958d0f3b6955cbea4d5b7809b2fb26b059",
    "value": "0x398dd06d5c8000",
    "gasPrice": "0x17d7840",
    "gas": "0x7fcf94",
    "input": "0xd7570e450000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000b49cfac038353ecd00000000000000000000000000000000000000000000000000000000660c4618000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000398dd06d5c800000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000020000000000000000000000000ae1146c4b2aecd980451a67717c33050680e085b00000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000120000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000600000000000000000000000005aea5775959fbc2557cc8789bc1bf90a239d9a910000000000000000000000001bc3366b3664c01b8687b1efcfc6478d9351a8a900000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000",
    "v": "0x0",
    "r": "0x5502a500c68407013cc2fbfeac220afdcb4ad1d997ba7c85d47d5622598d65d8",
    "s": "0x5573ac964036b6ac7aab5bf0024134763cb86decbfcfeb2fca7becb9dab96355",
    "type": "0x2",
    "maxFeePerGas": "0x202fbf0",
    "maxPriorityFeePerGas": "0x0",
    "chainId": "0x144",
    "l1BatchNumber": "0x72ae1",
    "l1BatchTxIndex": "0x469"
  },
  "id": 2
}

eth_getTransactionByBlockHashAndIndex

Retrieves a transaction by block hash and transaction index position.

Parameters

  1. DATA, 32 bytes - hash of a block.
  2. QUANTITY - integer of the transaction index position, starting from 0x0.

Returns

The response contains detailed information about the transaction, see eth_getTransactionByHash.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 2,
      "method": "eth_getTransactionByBlockHashAndIndex",
      "params": [
        "0x5046bdc714b2a9b40e9fbfdfc5140371c1b03b40335d908de92a7686dcc067e9",
        "0x0"
      ]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": {
    "hash": "0xb2adc4d2b3203e186001dc37fdf02cc8e772518425d263adc6a17dbddff3bfda",
    "nonce": "0x14c",
    "blockHash": "0x5046bdc714b2a9b40e9fbfdfc5140371c1b03b40335d908de92a7686dcc067e9",
    "blockNumber": "0x1d1551e",
    "transactionIndex": "0x0",
    "from": "0x1bc3366b3664c01b8687b1efcfc6478d9351a8a9",
    "to": "0x9b5def958d0f3b6955cbea4d5b7809b2fb26b059",
    "value": "0x398dd06d5c8000",
    "gasPrice": "0x17d7840",
    "gas": "0x7fcf94",
    "input": "0xd7570e450000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000b49cfac038353ecd00000000000000000000000000000000000000000000000000000000660c4618000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000398dd06d5c800000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000020000000000000000000000000ae1146c4b2aecd980451a67717c33050680e085b00000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000120000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000600000000000000000000000005aea5775959fbc2557cc8789bc1bf90a239d9a910000000000000000000000001bc3366b3664c01b8687b1efcfc6478d9351a8a900000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000",
    "v": "0x0",
    "r": "0x5502a500c68407013cc2fbfeac220afdcb4ad1d997ba7c85d47d5622598d65d8",
    "s": "0x5573ac964036b6ac7aab5bf0024134763cb86decbfcfeb2fca7becb9dab96355",
    "type": "0x2",
    "maxFeePerGas": "0x202fbf0",
    "maxPriorityFeePerGas": "0x0",
    "chainId": "0x144",
    "l1BatchNumber": "0x72ae1",
    "l1BatchTxIndex": "0x469"
  },
  "id": 2
}

eth_getTransactionReceipt

Retrieves the receipt of a transaction by transaction hash.

Parameters

  1. DATA, 32 bytes - unique hash of the transaction.

Returns

Object - A transaction receipt object, or null when no receipt was found:

  • transactionHash : DATA, 32 Bytes - hash of the transaction.
  • transactionIndex: QUANTITY - integer of the transactions index position in the block.
  • blockHash: DATA, 32 Bytes - hash of the block where this transaction was in.
  • blockNumber: QUANTITY - block number where this transaction was in.
  • from: DATA, 20 Bytes - address of the sender.
  • to: DATA, 20 Bytes - address of the receiver. null when its a contract creation transaction.
  • cumulativeGasUsed : QUANTITY - The total amount of gas used when this transaction was executed in the block.
  • effectiveGasPrice : QUANTITY - The sum of the base fee and tip paid per unit of gas.
  • gasUsed : QUANTITY - The amount of gas used by this specific transaction alone. contractAddress : DATA, 20 Bytes - The contract address created, if the transaction was a contract creation, otherwise null.
  • logs: Array - Array of log objects, which this transaction generated.
  • logsBloom: DATA, 256 Bytes - Bloom filter for light clients to quickly retrieve related logs.
  • type: QUANTITY - integer of the transaction type, 0x0 for legacy transactions, 0x1 for access list types, 0x2 for dynamic fees.

It also returns either:

  • root: DATA 32 - bytes of post-transaction stateroot (pre Byzantium)
  • status: QUANTITY - either 0x1 (success) or 0x0 (failure)

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 2,
      "method": "eth_getTransactionReceipt",
      "params": ["0xb2adc4d2b3203e186001dc37fdf02cc8e772518425d263adc6a17dbddff3bfda"]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": {
    "transactionHash": "0xb2adc4d2b3203e186001dc37fdf02cc8e772518425d263adc6a17dbddff3bfda",
    "transactionIndex": "0x0",
    "blockHash": "0x5046bdc714b2a9b40e9fbfdfc5140371c1b03b40335d908de92a7686dcc067e9",
    "blockNumber": "0x1d1551e",
    "l1BatchTxIndex": "0x469",
    "l1BatchNumber": "0x72ae1",
    "from": "0x1bc3366b3664c01b8687b1efcfc6478d9351a8a9",
    "to": "0x9b5def958d0f3b6955cbea4d5b7809b2fb26b059",
    "cumulativeGasUsed": "0x0",
    "gasUsed": "0x2b9bcb",
    "contractAddress": null,
    "logs": [
      {
        "address": "0x000000000000000000000000000000000000800a",
        "topics": [
          "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
          "0x0000000000000000000000001bc3366b3664c01b8687b1efcfc6478d9351a8a9",
          "0x0000000000000000000000000000000000000000000000000000000000008001"
        ],
        "data": "0x0000000000000000000000000000000000000000000000000001011c8f80b6c0",
        "blockHash": "0x5046bdc714b2a9b40e9fbfdfc5140371c1b03b40335d908de92a7686dcc067e9",
        "blockNumber": "0x1d1551e",
        "l1BatchNumber": "0x72ae1",
        "transactionHash": "0xb2adc4d2b3203e186001dc37fdf02cc8e772518425d263adc6a17dbddff3bfda",
        "transactionIndex": "0x0",
        "logIndex": "0x0",
        "transactionLogIndex": "0x0",
        "logType": null,
        "removed": false
      },
      ...
    ],
    "l2ToL1Logs": [],
    "status": "0x1",
    "root": "0x5046bdc714b2a9b40e9fbfdfc5140371c1b03b40335d908de92a7686dcc067e9",
    "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "type": "0x2",
    "effectiveGasPrice": "0x17d7840"
  },
  "id": 2
}

eth_protocolVersion

Returns the current Ethereum protocol version.

Parameters

None

Returns

String - A single string indicating the protocol version. The version is prefixed with an identifier (e.g. "zks" for ZKsync) followed by a version number.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 2,
      "method": "eth_protocolVersion",
      "params": []
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "zks/1",
  "id": 2
}

eth_sendRawTransaction

Submits a pre-signed transaction for broadcast to the network.

Parameters

  1. DATA - The complete, signed transaction data.

Returns

DATA, 32 bytes - A single string that is the hash of the transaction if it has been successfully submitted to the network. This hash can be used to track the transaction's inclusion in a block and subsequent execution status.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 2,
      "method": "eth_sendRawTransaction",
      "params": ["0xf86c808504a817c80082520894095e7baea6a6c7c4c2dfeb977efac326af552d870a868e8..."]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "0x2f5d6a8af654c249bc487e7c7b926a3f3f165b575a6485a487f12c7a9e3c8e45",
  "id": 2
}

eth_accounts

Returns a list of addresses owned by the client.

Parameters

None

Returns

Array of DATA, 20 bytes - An array of account addresses owned by the client.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 2,
      "method": "eth_accounts",
      "params": []
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": [],
  "id": 2
}

eth_feeHistory

Retrieves the fee history for the requested blocks.

Parameters

  1. uint64 - the number of the blocks to check.
  2. QUANTITY - the latest block number.
  3. Array of float32 - The percentiles of transaction fees to return.

Returns

Object containing the following fields:

  • oldestBlock: QUANTITY - block number in hex of the oldest block queried.
  • baseFeePerGas: Array of QUANTITY - An array of base fees per gas, represented in hex, for each block.
  • gasUsedRatio: Array of Float - An array of ratios of gas used by each block, represented as floats.
  • reward: Array of Array<QUANTITY> - An array of arrays containing the transaction fee rewards at specified percentiles, each represented in hex.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "eth_feeHistory",
      "params": [
          "10",
          "0x3039",
          [25.0, 50.0, 75.0]
      ]
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": {
    "oldestBlock": "0x302a",
    "baseFeePerGas": [
      "0xee6b280",
      "0xee6b280",
      "0xee6b280",
    ],
    "gasUsedRatio": [
      0.0,
      0.0,
      0.0,
    ],
    "reward": [
      ["0x0", "0x0", "0x0"],
      ["0x0", "0x0", "0x0"],
      ["0x0", "0x0", "0x0"],
    ]
  },
  "id": 1
}

web3_clientVersion

Note: The sha3 method is intentionally omitted from the main server implementation, as it can be readily implemented on the client side if necessary.

Retrieves the version of the client software.

Parameters

None

Returns

String - The client version supported by the node. The version is prefixed with an identifier (e.g. "ZKsync" for ZKsync) followed by a version number.

Example Request

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
      "id": 1,
      "jsonrpc": "2.0",
      "method": "web3_clientVersion",
      "params": []
    }'

Example Response

{
  "jsonrpc": "2.0",
  "result": "ZKsync/v2.0",
  "id": 1
}

Debug JSON-RPC API

Methods useful for debugging purposes with ZKsync Era.

PubSub JSON-RPC API

Methods to subscribe/unsubscribe to events and receive notifications on ZKsync Era.

Made with ❤️ by the ZKsync Community