State and account methods

These methods read account state at a given block, including balances, nonces, contract code, storage values, and Merkle proofs.

`eth_getBalance`

Returns the account balance of the specified address.

Parameters

address: string - 20-byte account address from which to retrieve the balance.
blockNumber or blockHash: string - (Optional) Hexadecimal integer representing a block number, block hash, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter. The default is latest.

note
pending returns the same value as latest.

Returns

Current balance, in wei, as a hexadecimal value.

Example

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": [
      "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73",
      "latest"
    ],
    "id": 53
  }'

{
  "jsonrpc": "2.0",
  "method": "eth_getBalance",
  "params": [
    "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73",
    "latest"
  ],
  "id": 53
}

{
  "jsonrpc": "2.0",
  "id": 53,
  "result": "0x1cfe56f3795885980000"
}

curl -X POST http://localhost:8547/graphql \
  -H "Content-Type: application/json" \
  --data '{
    "query": "{ account ( address: \"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\") { balance } }"
  }'

{
  account(address: "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73") {
    balance
  }
}

{
  "data": {
    "account": {
      "balance": "0x1ce96a1ffe7620d00000"
    }
  }
}

`eth_getCode`

Returns the code of the smart contract at the specified address. Besu stores compiled smart contract code as a hexadecimal value.

Parameters

address: string - 20-byte contract address.
blockNumber or blockHash: string - (Optional) Hexadecimal integer representing a block number, block hash, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter. The default is latest.

note
pending returns the same value as latest.

Returns

Code stored at the specified address.

Example

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getCode",
    "params": [
      "0xa50a51c09a5c451c52bb714527e1974b686d8e77",
      "latest"
    ],
    "id": 53
  }'

{
  "jsonrpc": "2.0",
  "method": "eth_getCode",
  "params": [
    "0xa50a51c09a5c451c52bb714527e1974b686d8e77",
    "latest"
  ],
  "id": 53
}

{
  "jsonrpc": "2.0",
  "id": 53,
  "result": "0x60806040526004361060485763ffffffff7c01000000000000000000000000000000000000000000000000000000006000350416633fa4f2458114604d57806355241077146071575b600080fd5b348015605857600080fd5b50605f6088565b60408051918252519081900360200190f35b348015607c57600080fd5b506086600435608e565b005b60005481565b60008190556040805182815290517f199cd93e851e4c78c437891155e2112093f8f15394aa89dab09e38d6ca0727879181900360200190a1505600a165627a7a723058209d8929142720a69bde2ab3bfa2da6217674b984899b62753979743c0470a2ea70029"
}

curl -X POST http://localhost:8547/graphql \
  -H "Content-Type: application/json" \
  --data '{
    "query": "{account(address: \"0xa50a51c09a5c451c52bb714527e1974b686d8e77\"){ code }}"
  }'

{
  account(address: "0xa50a51c09a5c451c52bb714527e1974b686d8e77") {
    code
  }
}

{
  "data": {
    "account": {
      "code": "0x60806040526004361060485763ffffffff7c01000000000000000000000000000000000000000000000000000000006000350416633fa4f2458114604d57806355241077146071575b600080fd5b348015605857600080fd5b50605f6088565b60408051918252519081900360200190f35b348015607c57600080fd5b506086600435608e565b005b60005481565b60008190556040805182815290517f199cd93e851e4c78c437891155e2112093f8f15394aa89dab09e38d6ca0727879181900360200190a1505600a165627a7a723058209d8929142720a69bde2ab3bfa2da6217674b984899b62753979743c0470a2ea70029"
    }
  }
}

`eth_getProof`

Returns the account and storage values of the specified account, including the Merkle proof.

The API allows IoT devices or mobile apps which are unable to run light clients to verify responses from untrusted sources, by using a trusted block hash.

Parameters

address: string - 20-byte address of the account or contract.
keys: array of strings - List of 32-byte storage keys to generate proofs for.
blockNumber or blockHash: string - (Optional) Hexadecimal integer representing a block number, block hash, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter. The default is latest.

note
pending returns the same value as latest.

Returns

Account details object.
- balance: string - Account balance.
- codeHash: string - 32-byte hash of the account code.
- nonce: string - Number of transactions sent from the account.
- storageHash: string - 32-byte SHA3 of the storageRoot.
- accountProof: array of strings - List of RLP-encoded Merkle tree nodes, starting with the stateRoot.
- storageProof: array of objects - List of storage entry objects.
  key: string - Storage key.
  
  value: string - Storage value.
  
  proof: array of strings - List of RLP-encoded Merkle tree nodes, starting with the storageHash.

Example

curl HTTP
wscat WS
JSON result

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getProof",
    "params": [
      "0a8156e7ee392d885d10eaa86afd0e323afdcd95",
      [
        "0x0000000000000000000000000000000000000000000000000000000000000347"
      ],
      "latest"
    ],
    "id": 1
  }'

{
  "jsonrpc": "2.0",
  "method": "eth_getProof",
  "params": [
    "0a8156e7ee392d885d10eaa86afd0e323afdcd95",
    [
      "0x0000000000000000000000000000000000000000000000000000000000000347"
    ],
    "latest"
  ],
  "id": 1
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "accountProof": [
      "0xf90211a0...608d898380",
      "0xf90211a0...ec33f19580",
      "0xf901d1a0...9e55584480",
      "0xf8718080...18e5777142"
    ],
    "address": "0x0a8156e7ee392d885d10eaa86afd0e323afdcd95",
    "balance": "0x0",
    "codeHash": "0x2b6975dcaf69f9bb9a3b30bb6a37b305ce440250bf0dd2f23338cb18e5777142",
    "nonce": "0x5f",
    "storageHash": "0x917688de43091589aa58c1dfd315105bc9de4478b9ba7471616a4d8a43d46203",
    "storageProof": [
      {
        "key": "0x0000000000000000000000000000000000000000000000000000000000000347",
        "value": "0x0",
        "proof": [
          "0xf90211a0...5176779280",
          "0xf901f1a0...c208d86580",
          "0xf8d180a0...1ce6808080"
        ]
      }
    ]
  }
}

`eth_getStorageAt`

Returns the value of a storage position at a specified address.

Parameters

address: string - 20-byte storage address.
index: string - Integer index of the storage position.
blockNumber or blockHash: string - (Optional) Hexadecimal integer representing a block number, block hash, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter. The default is latest.

note
pending returns the same value as latest.

Returns

Value at the specified storage position.

Example

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getStorageAt",
    "params": [
      "0x‭3B3F3E‬",
      "0x0",
      "latest"
    ],
    "id": 53
  }'

{
  "jsonrpc": "2.0",
  "method": "eth_getStorageAt",
  "params": [
    "0x‭3B3F3E‬",
    "0x0",
    "latest"
  ],
  "id": 53
}

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

curl -X POST http://localhost:8547/graphql \
  -H "Content-Type: application/json" \
  --data '{
    "query": "{account(address: \"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\") {storage(slot: \"0x04\")}}"
  }'

{
  account(address: "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73") {
    storage(slot: "0x04")
  }
}

{
  "data": {
    "account": {
      "storage": "0x0000000000000000000000000000000000000000000000000000000000000000"
    }
  }
}

`eth_getStorageValues`

Returns storage values for multiple slots across one or more accounts in a single call. This is a batched version of eth_getStorageAt.

Parameters

storageRequest: object - Each key is a 20-byte account address and each value is an array of storage slot keys (as 32-byte hex strings). The maximum total number of storage slots across all addresses is 1024.
blockNumber or blockHash: string - (Optional) Hexadecimal integer representing a block number, block hash, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter. The default is latest.

note
pending returns the same value as latest.

Returns

Each key is an account address and each value is an array of hex-encoded storage values in the same order as the requested slot keys. Unknown accounts return zero values for all requested slots. Key order in the response object is not guaranteed to match the request.

Example

curl HTTP
wscat WS
JSON result

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getStorageValues",
    "params": [
      {
        "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73": [
          "0x0",
          "0x1"
        ],
        "0x627306090abaB3A6e1400e9345bC60c78a8BEf57": [
          "0x0"
        ]
      },
      "latest"
    ],
    "id": 1
  }'

{
  "jsonrpc": "2.0",
  "method": "eth_getStorageValues",
  "params": [
    {
      "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73": [
        "0x0",
        "0x1"
      ],
      "0x627306090abaB3A6e1400e9345bC60c78a8BEf57": [
        "0x0"
      ]
    },
    "latest"
  ],
  "id": 1
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "0x627306090abab3a6e1400e9345bc60c78a8bef57": [
      "0x0000000000000000000000000000000000000000000000000000000000000000"
    ],
    "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73": [
      "0x0000000000000000000000000000000000000000000000000000000000000000",
      "0x0000000000000000000000000000000000000000000000000000000000000000"
    ]
  }
}

`eth_getTransactionCount`

Returns the number of transactions sent from a specified address. Use the pending tag to get the next account nonce not used by any pending transactions.

Parameters

address: string - 20-byte account address.
blockNumber or blockHash: string - (Optional) Hexadecimal integer representing a block number, block hash, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter. The default is latest.

Returns

Integer representing the number of transactions sent from the specified address.

Example

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getTransactionCount",
    "params": [
      "0xc94770007dda54cF92009BFF0dE90c06F603a09f",
      "latest"
    ],
    "id": 1
  }'

{
  "jsonrpc": "2.0",
  "method": "eth_getTransactionCount",
  "params": [
    "0xc94770007dda54cF92009BFF0dE90c06F603a09f",
    "latest"
  ],
  "id": 1
}

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

curl -X POST http://localhost:8547/graphql \
  -H "Content-Type: application/json" \
  --data '{
    "query": "{ account (address:\"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73\"){transactionCount}}"
  }'

{
  account(address: "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73") {
    transactionCount
  }
}

{
  "data": {
    "account": {
      "transactionCount": 5
    }
  }
}

eth_getBalance​

Parameters​

Returns​

Example​

eth_getCode​

Parameters​

Returns​

Example​

eth_getProof​

Parameters​

Returns​

Example​

eth_getStorageAt​

Parameters​

Returns​

Example​

eth_getStorageValues​

Parameters​

Returns​

Example​

eth_getTransactionCount​

Parameters​

Returns​

Example​

`eth_getBalance`

Parameters

Returns

Example

`eth_getCode`

Parameters

Returns

Example

`eth_getProof`

Parameters

Returns

Example

`eth_getStorageAt`

Parameters

Returns

Example

`eth_getStorageValues`

Parameters

Returns

Example

`eth_getTransactionCount`

Parameters

Returns

Example