Skip to main content

Besu JSON-RPC API

POST 
/ledger/v4/blockchains/besu

Hyperledger Besu Ethereum Enterprise Client JSON-RPC API.

This endpoint does not proxy arbitrary Besu JSON-RPC methods. Only the following read-only methods are forwarded to Besu without any authorisation check: eth_blockNumber, eth_call, eth_chainId, eth_estimateGas, eth_getBlockByHash, eth_getBlockByNumber, eth_getBlockReceipts, eth_getBlockTransactionCountByHash, eth_getBlockTransactionCountByNumber, eth_getCode, eth_getLogs, eth_getTransactionByBlockHashAndIndex, eth_getTransactionByBlockNumberAndIndex, eth_getTransactionByHash, eth_getTransactionCount, eth_getTransactionReceipt, eth_getUncleByBlockHashAndIndex, eth_getUncleByBlockNumberAndIndex, eth_getUncleCountByBlockHash, eth_getUncleCountByBlockNumber, net_version.

eth_sendRawTransaction is also accepted, but is subject to an authorisation check (see below). Any other method returns a -32601 (Method not found) JSON-RPC error.

Authorisation for eth_sendRawTransaction:

  • The raw transaction must decode to a transaction with both a from and a to address.
  • If to is the EBSI proxy factory contract address, the sender (from) must hold the TCR:deployProxy policy in the Trusted Policies Registry — no access token is required in this case.
  • Otherwise (a regular contract call), the request must carry an Authorization: Bearer <access_token> header with a valid access token issued by Authorisation API v4 for the openid ledger_invoke scope. The token's authorization_details.addresses must include the transaction's to address, and the token's sub (a did:key or did:ebsi) must control the transaction's from address.

Batching: a JSON array of request objects is processed as a JSON-RPC batch. Batches are capped at 1024 requests; larger batches are rejected with a -32005 error.

Notifications: a request object with no id is treated as a JSON-RPC notification and is never given a response. For a single (non-batch) notification, this endpoint returns an empty 200 body.

Error handling: all JSON-RPC-level errors (invalid request, method not found, internal errors while querying Besu, etc.) are returned with HTTP status 200, wrapped in a JSON-RPC error object, per the JSON-RPC 2.0 convention of using the transport layer only for transport-level failures. The only condition returned with a non-200 HTTP status is a request body that isn't valid JSON (400).

Request​

Responses​

JSON-RPC Response. Returned both for successful calls and for JSON-RPC-level errors (invalid request, method not found, batch too large, internal errors while querying Besu, etc.) — see the endpoint description. A single-request notification (no id in the request) returns an empty body.

Last updated on