Jump to

• Request
• Response

Invoke a Besu JSON-RPC Method

post

/v1/besu/proxy

Submits the request body to the selected Besu JSON-RPC endpoint and returns its status and response body. Use this endpoint for any JSON-RPC method, such as `eth_blockNumber` or `eth_getBalance`.

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

Additional Properties Allowed: true

JSON-RPC request submitted to a Besu node.

Show Source

• id(required): id
  Request identifier echoed in the response.
• jsonrpc(required): string
  JSON-RPC protocol version.
• method(required): string
  JSON-RPC method name.
• params(required): array params
  JSON-RPC parameters. The structure depends on the method.

{
    "type":"object",
    "description":"JSON-RPC request submitted to a Besu node.",
    "additionalProperties":true,
    "required":[
        "jsonrpc",
        "method",
        "params",
        "id"
    ],
    "properties":{
        "jsonrpc":{
            "type":"string",
            "description":"JSON-RPC protocol version.",
            "examples":[
                "2.0"
            ]
        },
        "method":{
            "type":"string",
            "description":"JSON-RPC method name.",
            "examples":[
                "eth_blockNumber"
            ]
        },
        "params":{
            "type":"array",
            "description":"JSON-RPC parameters. The structure depends on the method.",
            "items":{
                "oneOf":[
                    {
                        "type":"object",
                        "additionalProperties":true
                    },
                    {
                        "type":"array",
                        "items":{
                        }
                    },
                    {
                        "type":"string"
                    },
                    {
                        "type":"number"
                    },
                    {
                        "type":"integer"
                    },
                    {
                        "type":"boolean"
                    },
                    {
                        "type":"null"
                    }
                ]
            }
        },
        "id":{
            "oneOf":[
                {
                    "type":"string"
                },
                {
                    "type":"integer"
                }
            ],
            "description":"Request identifier echoed in the response.",
            "examples":[
                1
            ]
        }
    }
}

Nested Schema : id

Request identifier echoed in the response.

Match One Schema

Show Source

• string
• integer

{
    "oneOf":[
        {
            "type":"string"
        },
        {
            "type":"integer"
        }
    ],
    "description":"Request identifier echoed in the response.",
    "examples":[
        1
    ]
}

Nested Schema : params

Type: array

JSON-RPC parameters. The structure depends on the method.

Show Source

• Array of: items

{
    "type":"array",
    "description":"JSON-RPC parameters. The structure depends on the method.",
    "items":{
        "oneOf":[
            {
                "type":"object",
                "additionalProperties":true
            },
            {
                "type":"array",
                "items":{
                }
            },
            {
                "type":"string"
            },
            {
                "type":"number"
            },
            {
                "type":"integer"
            },
            {
                "type":"boolean"
            },
            {
                "type":"null"
            }
        ]
    }
}

Nested Schema : items

Match One Schema

Show Source

• object type
  Additional Properties Allowed: true
• array type
• string
• number
• integer
• boolean
• null

{
    "oneOf":[
        {
            "type":"object",
            "additionalProperties":true
        },
        {
            "type":"array",
            "items":{
            }
        },
        {
            "type":"string"
        },
        {
            "type":"number"
        },
        {
            "type":"integer"
        },
        {
            "type":"boolean"
        },
        {
            "type":"null"
        }
    ]
}

Nested Schema : type

Type: object

Additional Properties Allowed: true

Nested Schema : type

Type: array

Show Source

• Array of:

{
    "type":"array",
    "items":{
    }
}

Examples

Select an example eth_blockNumber eth_getBalance

Back to Top

Response

Supported Media Types

• application/json

200 Response

Returns the Besu JSON-RPC response.

Body ()

Root Schema : JsonRpcResponse

Type: object

Additional Properties Allowed: true

JSON-RPC response returned by a Besu node.

Show Source

• id: id
  Echoed request identifier.
• jsonrpc: string
  JSON-RPC protocol version.
• result:
  JSON-RPC result payload. The structure depends on the method.

{
    "type":"object",
    "description":"JSON-RPC response returned by a Besu node.",
    "additionalProperties":true,
    "properties":{
        "jsonrpc":{
            "type":"string",
            "description":"JSON-RPC protocol version.",
            "examples":[
                "2.0"
            ]
        },
        "id":{
            "oneOf":[
                {
                    "type":"string"
                },
                {
                    "type":"integer"
                }
            ],
            "description":"Echoed request identifier.",
            "examples":[
                1
            ]
        },
        "result":{
            "description":"JSON-RPC result payload. The structure depends on the method."
        }
    }
}

Nested Schema : id

Echoed request identifier.

Match One Schema

Show Source

• string
• integer

{
    "oneOf":[
        {
            "type":"string"
        },
        {
            "type":"integer"
        }
    ],
    "description":"Echoed request identifier.",
    "examples":[
        1
    ]
}

Examples

Select an example response_200_eth_block_number

4XX Response

Request error or Besu JSON-RPC error.

Body ()

Root Schema : JsonRpcErrorResponse

Type: object

JSON-RPC error response returned by a Besu node.

Show Source

• error: object JsonRpcErrorObject
  Error object returned in a JSON-RPC response.
• id: id
  Echoed request identifier, when available.
• jsonrpc: string
  JSON-RPC protocol version.

{
    "type":"object",
    "description":"JSON-RPC error response returned by a Besu node.",
    "properties":{
        "jsonrpc":{
            "type":"string",
            "description":"JSON-RPC protocol version.",
            "examples":[
                "2.0"
            ]
        },
        "id":{
            "oneOf":[
                {
                    "type":"string"
                },
                {
                    "type":"integer"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Echoed request identifier, when available."
        },
        "error":{
            "$ref":"#/components/schemas/JsonRpcErrorObject",
            "description":"JSON-RPC error payload containing code, message, and optional data."
        }
    }
}

Nested Schema : JsonRpcErrorObject

Type: object

Error object returned in a JSON-RPC response.

Show Source

• code: integer
  JSON-RPC error code returned by the Besu node.
• data:
  Error data returned by the Besu node. Its structure varies by method.
• message: string
  JSON-RPC error message returned by the Besu node.

{
    "type":"object",
    "description":"Error object returned in a JSON-RPC response.",
    "properties":{
        "code":{
            "type":"integer",
            "description":"JSON-RPC error code returned by the Besu node.",
            "examples":[
                -32603
            ]
        },
        "message":{
            "type":"string",
            "description":"JSON-RPC error message returned by the Besu node.",
            "examples":[
                "Internal error"
            ]
        },
        "data":{
            "description":"Error data returned by the Besu node. Its structure varies by method."
        }
    }
}

Nested Schema : id

Echoed request identifier, when available.

Match One Schema

Show Source

• string
• integer
• null

{
    "oneOf":[
        {
            "type":"string"
        },
        {
            "type":"integer"
        },
        {
            "type":"null"
        }
    ],
    "description":"Echoed request identifier, when available."
}

5XX Response

Unexpected service error or Besu JSON-RPC error.

Body ()

Root Schema : JsonRpcErrorResponse

Type: object

JSON-RPC error response returned by a Besu node.

Show Source

• error: object JsonRpcErrorObject
  Error object returned in a JSON-RPC response.
• id: id
  Echoed request identifier, when available.
• jsonrpc: string
  JSON-RPC protocol version.

{
    "type":"object",
    "description":"JSON-RPC error response returned by a Besu node.",
    "properties":{
        "jsonrpc":{
            "type":"string",
            "description":"JSON-RPC protocol version.",
            "examples":[
                "2.0"
            ]
        },
        "id":{
            "oneOf":[
                {
                    "type":"string"
                },
                {
                    "type":"integer"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Echoed request identifier, when available."
        },
        "error":{
            "$ref":"#/components/schemas/JsonRpcErrorObject",
            "description":"JSON-RPC error payload containing code, message, and optional data."
        }
    }
}

Nested Schema : JsonRpcErrorObject

Type: object

Error object returned in a JSON-RPC response.

Show Source

• code: integer
  JSON-RPC error code returned by the Besu node.
• data:
  Error data returned by the Besu node. Its structure varies by method.
• message: string
  JSON-RPC error message returned by the Besu node.

{
    "type":"object",
    "description":"Error object returned in a JSON-RPC response.",
    "properties":{
        "code":{
            "type":"integer",
            "description":"JSON-RPC error code returned by the Besu node.",
            "examples":[
                -32603
            ]
        },
        "message":{
            "type":"string",
            "description":"JSON-RPC error message returned by the Besu node.",
            "examples":[
                "Internal error"
            ]
        },
        "data":{
            "description":"Error data returned by the Besu node. Its structure varies by method."
        }
    }
}

Nested Schema : id

Echoed request identifier, when available.

Match One Schema

Show Source

• string
• integer
• null

{
    "oneOf":[
        {
            "type":"string"
        },
        {
            "type":"integer"
        },
        {
            "type":"null"
        }
    ],
    "description":"Echoed request identifier, when available."
}

Back to Top