Jump to

• Request
• Response

Execute a Read-Only Contract Query

post

/v1/besu/query

Executes a read-only smart contract call using the Ethereum JSON-RPC `eth_call` method. Supports encoding requests with `functionSignature` and `functionArgs`. A contract execution revert is a completed query and returns HTTP 200 with `executionStatus: REVERTED`. HTTP error responses are reserved for request validation failures and communication failures with the Besu node.

Request

Header Parameters

• X-Besu-Node: string
  Optional operator-defined Besu node identifier. Supported values include rpc-0, rpc-1, archive-0, validator-0, and bootnode-0.
• X-Request-Id: string
  Optional correlation ID. Echoed in the response when provided.

Supported Media Types

• application/json

Request Body - application/json ()

Root Schema : schema

Type: object

Defines a read-only contract query.

Show Source

• blockTag: string
  Block tag: `latest`, `pending`, `earliest`, or a hexadecimal or decimal block number.
• contractAbi: array contractAbi
  Optional ABI used to infer parameter types when `functionSignature` contains only a function name. If omitted, the ABI associated with `toAddress` is used when available.
• data: string
  Hexadecimal call data. If omitted and `functionSignature` is provided, call data is encoded automatically.
• decode: object QueryDecodeOptions
  Decode options. Each option defaults to `false` when omitted.
• ethValue: string
  Optional value in wei for `eth_call`.
• fromAddress(required): string
  Required call sender. Must belong to the authenticated caller.
• functionArgs: array functionArgs
  Function arguments as strings. Scalars use plain strings; arrays and tuples use JSON strings, such as '["1","2"]'.
• functionSignature: string
  Function signature for ABI encoding. Provide a fully specified signature, such as "balanceOf(address)", or a function name. For a function name, parameter types are inferred from `contractAbi` when provided or, when available, from the contract address.
• gasLimit: integer
  Optional gas limit for `eth_call` execution.
• toAddress(required): string
  Target contract address.

{
    "type":"object",
    "description":"Defines a read-only contract query.",
    "properties":{
        "toAddress":{
            "type":"string",
            "description":"Target contract address."
        },
        "data":{
            "type":"string",
            "description":"Hexadecimal call data. If omitted and `functionSignature` is provided, call data is encoded automatically."
        },
        "functionSignature":{
            "type":"string",
            "description":"Function signature for ABI encoding. Provide a fully specified signature, such as \"balanceOf(address)\", or a function name. For a function name, parameter types are inferred from `contractAbi` when provided or, when available, from the contract address.\n"
        },
        "functionArgs":{
            "type":"array",
            "items":{
                "type":"string"
            },
            "description":"Function arguments as strings. Scalars use plain strings; arrays and tuples use JSON strings, such as '[\"1\",\"2\"]'.\n"
        },
        "contractAbi":{
            "type":"array",
            "items":{
                "type":"object"
            },
            "description":"Optional ABI used to infer parameter types when `functionSignature` contains only a function name. If omitted, the ABI associated with `toAddress` is used when available.\n"
        },
        "fromAddress":{
            "type":"string",
            "description":"Required call sender. Must belong to the authenticated caller."
        },
        "gasLimit":{
            "type":"integer",
            "description":"Optional gas limit for `eth_call` execution."
        },
        "ethValue":{
            "type":"string",
            "description":"Optional value in wei for `eth_call`."
        },
        "blockTag":{
            "type":"string",
            "description":"Block tag: `latest`, `pending`, `earliest`, or a hexadecimal or decimal block number."
        },
        "decode":{
            "$ref":"#/components/schemas/QueryDecodeOptions",
            "description":"Decode controls for output data and revert error payloads."
        }
    },
    "required":[
        "toAddress",
        "fromAddress"
    ]
}

Nested Schema : contractAbi

Type: array

Optional ABI used to infer parameter types when `functionSignature` contains only a function name. If omitted, the ABI associated with `toAddress` is used when available.

Show Source

• Array of: object items

{
    "type":"array",
    "items":{
        "type":"object"
    },
    "description":"Optional ABI used to infer parameter types when `functionSignature` contains only a function name. If omitted, the ABI associated with `toAddress` is used when available.\n"
}

Nested Schema : QueryDecodeOptions

Type: object

Decode options. Each option defaults to `false` when omitted.

Show Source

• errors: boolean
  Decode revert reasons. Decoding occurs only when true and decodable revert bytes are present.
• outputs: boolean
  Decode `rawResult` into function outputs, including nested tuples and arrays when ABI is available. If some values cannot be decoded, the response includes structured `meta.issues` and `null` for affected fields without failing the request.

{
    "type":"object",
    "description":"Decode options. Each option defaults to `false` when omitted.",
    "properties":{
        "outputs":{
            "type":"boolean",
            "description":"Decode `rawResult` into function outputs, including nested tuples and arrays when ABI is available.\nIf some values cannot be decoded, the response includes structured `meta.issues` and `null` for affected fields without failing the request.\n"
        },
        "errors":{
            "type":"boolean",
            "description":"Decode revert reasons. Decoding occurs only when true and decodable revert bytes are present."
        }
    }
}

Nested Schema : functionArgs

Type: array

Function arguments as strings. Scalars use plain strings; arrays and tuples use JSON strings, such as '["1","2"]'.

Show Source

• Array of: string

{
    "type":"array",
    "items":{
        "type":"string"
    },
    "description":"Function arguments as strings. Scalars use plain strings; arrays and tuples use JSON strings, such as '[\"1\",\"2\"]'.\n"
}

Nested Schema : items

Type: object

Examples

Select an example ERC20 balanceOf via fully-specified signature name-only signature with contractAbi to infer types Provide pre-encoded calldata directly Decode outputs for balanceOf Name-only signature without contractAbi

Back to Top

Response

Supported Media Types

• application/json

200 Response

Returns the read-only contract query result.

Body ()

Root Schema : QueryResponse

Type: object

Result of a read-only contract query.

Show Source

• blockTag(required): string
  Block parameter used for the call: `latest`, `pending`, `earliest`, or a block number.
• data(required): string
  Calldata used for the call, in 0x-prefixed hexadecimal format.
• decoded:
  Decoded result for enabled decode options. `rawResult` contains the complete return value. For successful queries, incomplete or invalid ABI data can return `null` for affected fields and include structured `meta.issues` without failing the request. Output decoding applies to successful queries. Revert decoding is exposed through `decodedError`.
• decodedError:
  Decoded revert payload when `decode.errors=true` and sufficient information is available. Its absence does not change a reverted query into an HTTP error.
• executionStatus(required): string
  Allowed Values: [ "SUCCESS", "REVERTED" ]

  `SUCCESS` when `eth_call` returns normally, or `REVERTED` when Besu completes `eth_call` and the EVM reverts. A reverted execution is returned with HTTP 200.
• from(required): string
  Sender address used to execute `eth_call`.
• rawResult: string
  Return data from a successful `eth_call`, in 0x-prefixed hexadecimal format. Absent when `executionStatus` is `REVERTED`.
• requestId: [ "string", "null" ]
  Client-provided correlation ID echoed for reverted queries.
• to(required): string
  Target contract address for the call.
• upstreamCode: [ "integer", "null" ]
  Besu JSON-RPC error code when `executionStatus` is `REVERTED`.
• upstreamData: [ "string", "null" ]
  Besu revert payload or error data when `executionStatus` is `REVERTED`.
• upstreamError: [ "object", "null" ] upstreamError
  Additional Properties Allowed: true

  Complete Besu error object for a reverted execution, including revert information.

{
    "type":"object",
    "description":"Result of a read-only contract query.",
    "required":[
        "executionStatus",
        "to",
        "from",
        "data",
        "blockTag"
    ],
    "properties":{
        "executionStatus":{
            "type":"string",
            "enum":[
                "SUCCESS",
                "REVERTED"
            ],
            "description":"`SUCCESS` when `eth_call` returns normally, or `REVERTED` when Besu completes\n`eth_call` and the EVM reverts. A reverted execution is returned with HTTP 200.\n"
        },
        "to":{
            "type":"string",
            "description":"Target contract address for the call."
        },
        "from":{
            "type":"string",
            "description":"Sender address used to execute `eth_call`."
        },
        "data":{
            "type":"string",
            "description":"Calldata used for the call, in 0x-prefixed hexadecimal format."
        },
        "blockTag":{
            "type":"string",
            "description":"Block parameter used for the call: `latest`, `pending`, `earliest`, or a block number."
        },
        "rawResult":{
            "type":"string",
            "description":"Return data from a successful `eth_call`, in 0x-prefixed hexadecimal format. Absent when `executionStatus` is `REVERTED`."
        },
        "decoded":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/DecodedResult"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Decoded result for enabled decode options.\n`rawResult` contains the complete return value.\nFor successful queries, incomplete or invalid ABI data can return `null` for affected fields and include structured `meta.issues` without failing the request.\nOutput decoding applies to successful queries. Revert decoding is exposed through `decodedError`.\n"
        },
        "upstreamCode":{
            "type":[
                "integer",
                "null"
            ],
            "description":"Besu JSON-RPC error code when `executionStatus` is `REVERTED`."
        },
        "upstreamData":{
            "type":[
                "string",
                "null"
            ],
            "description":"Besu revert payload or error data when `executionStatus` is `REVERTED`."
        },
        "upstreamError":{
            "type":[
                "object",
                "null"
            ],
            "additionalProperties":true,
            "description":"Complete Besu error object for a reverted execution, including revert information."
        },
        "decodedError":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/DecodedError"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Decoded revert payload when `decode.errors=true` and sufficient information is available. Its absence does not change a reverted query into an HTTP error."
        },
        "requestId":{
            "type":[
                "string",
                "null"
            ],
            "description":"Client-provided correlation ID echoed for reverted queries."
        }
    }
}

Nested Schema : upstreamError

Type: object

Additional Properties Allowed: true

Complete Besu error object for a reverted execution, including revert information.

Examples

Select an example response_200_query_raw_result Returns decoded output when requested Completed eth_call whose EVM execution reverted Decoded dynamic uint256[] output Decoded tuple output containing nested dynamic array Best-effort decode with partial nulls and structured issues

400 Response

Validation failed.

Body ()

Root Schema : ErrorResponse

Type: object

Error response returned by the service.

Show Source

• decodedError:
  Returned only when `decode.errors=true` and decodable revert bytes are present.
• error: string
  Short error summary suitable for display.
• hint: [ "string", "null" ]
  Optional guidance for resolving the error.
• message: [ "string", "null" ]
  Additional error details, when available.
• policy:
  Present for policy warnings or denials such as preflight failure.
• preflight:
  Present for preflight-gated transaction submission errors.
• requestId: [ "string", "null" ]
  Client-provided correlation ID echoed in the response.
• upstreamCode: [ "integer", "null" ]
  Besu node error code, when provided by the RPC endpoint.
• upstreamData: [ "string", "null" ]
  Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available.
• upstreamError: [ "object", "null" ] upstreamError
  Additional Properties Allowed: true

  Complete error object returned by the Besu node, including code, message, and data fields, when available.

{
    "type":"object",
    "description":"Error response returned by the service.",
    "properties":{
        "error":{
            "type":"string",
            "description":"Short error summary suitable for display."
        },
        "message":{
            "type":[
                "string",
                "null"
            ],
            "description":"Additional error details, when available."
        },
        "hint":{
            "type":[
                "string",
                "null"
            ],
            "description":"Optional guidance for resolving the error."
        },
        "upstreamCode":{
            "type":[
                "integer",
                "null"
            ],
            "description":"Besu node error code, when provided by the RPC endpoint."
        },
        "upstreamData":{
            "type":[
                "string",
                "null"
            ],
            "description":"Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available."
        },
        "upstreamError":{
            "type":[
                "object",
                "null"
            ],
            "additionalProperties":true,
            "description":"Complete error object returned by the Besu node, including code, message, and data fields, when available."
        },
        "decodedError":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/DecodedError"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Returned only when `decode.errors=true` and decodable revert bytes are present."
        },
        "preflight":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPreflightResult"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for preflight-gated transaction submission errors."
        },
        "policy":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPolicyDecision"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for policy warnings or denials such as preflight failure."
        },
        "requestId":{
            "type":[
                "string",
                "null"
            ],
            "description":"Client-provided correlation ID echoed in the response."
        }
    }
}

Nested Schema : upstreamError

Type: object

Additional Properties Allowed: true

Complete error object returned by the Besu node, including code, message, and data fields, when available.

502 Response

Communication failure with the Besu node; EVM reverts return HTTP 200.

Body ()

Root Schema : ErrorResponse

Type: object

Error response returned by the service.

Show Source

• decodedError:
  Returned only when `decode.errors=true` and decodable revert bytes are present.
• error: string
  Short error summary suitable for display.
• hint: [ "string", "null" ]
  Optional guidance for resolving the error.
• message: [ "string", "null" ]
  Additional error details, when available.
• policy:
  Present for policy warnings or denials such as preflight failure.
• preflight:
  Present for preflight-gated transaction submission errors.
• requestId: [ "string", "null" ]
  Client-provided correlation ID echoed in the response.
• upstreamCode: [ "integer", "null" ]
  Besu node error code, when provided by the RPC endpoint.
• upstreamData: [ "string", "null" ]
  Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available.
• upstreamError: [ "object", "null" ] upstreamError
  Additional Properties Allowed: true

  Complete error object returned by the Besu node, including code, message, and data fields, when available.

{
    "type":"object",
    "description":"Error response returned by the service.",
    "properties":{
        "error":{
            "type":"string",
            "description":"Short error summary suitable for display."
        },
        "message":{
            "type":[
                "string",
                "null"
            ],
            "description":"Additional error details, when available."
        },
        "hint":{
            "type":[
                "string",
                "null"
            ],
            "description":"Optional guidance for resolving the error."
        },
        "upstreamCode":{
            "type":[
                "integer",
                "null"
            ],
            "description":"Besu node error code, when provided by the RPC endpoint."
        },
        "upstreamData":{
            "type":[
                "string",
                "null"
            ],
            "description":"Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available."
        },
        "upstreamError":{
            "type":[
                "object",
                "null"
            ],
            "additionalProperties":true,
            "description":"Complete error object returned by the Besu node, including code, message, and data fields, when available."
        },
        "decodedError":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/DecodedError"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Returned only when `decode.errors=true` and decodable revert bytes are present."
        },
        "preflight":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPreflightResult"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for preflight-gated transaction submission errors."
        },
        "policy":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPolicyDecision"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for policy warnings or denials such as preflight failure."
        },
        "requestId":{
            "type":[
                "string",
                "null"
            ],
            "description":"Client-provided correlation ID echoed in the response."
        }
    }
}

Nested Schema : upstreamError

Type: object

Additional Properties Allowed: true

Complete error object returned by the Besu node, including code, message, and data fields, when available.

Examples

Select an example Upstream transport failure

Back to Top