Pre-General Availability: 2026-02-23

Jump to

• Request
• Response

Generic Passthrough for Besu JSON-RPC

post

/v1/besu/proxy

Forwards the request body as-is to the configured Besu RPC node, and returns the upstream status and body.

Use this for any JSON-RPC method, such as eth_blockNumber or eth_getBalance.

Request

Header Parameters

• X-Besu-Url: string
  Optional upstream JSON-RPC URL override. When provided, the request is forwarded to this URL.
• X-Request-Id: string
  Optional request correlation identifier. Echoed in responses when provided.

Supported Media Types

• application/json

Request Body - application/json ()

Root Schema : schema

Type: object

Additional Properties Allowed: true

Show Source

• id(required): id
  Client-supplied identifier echoed in the response
• jsonrpc(required): string
  JSON-RPC protocol version

  Example: 2.0
• method(required): string
  JSON-RPC method name

  Example: eth_blockNumber
• params(required): array params
  JSON-RPC params array; structure depends on the method

{
    "type":"object",
    "additionalProperties":true,
    "required":[
        "jsonrpc",
        "method",
        "params",
        "id"
    ],
    "properties":{
        "jsonrpc":{
            "type":"string",
            "description":"JSON-RPC protocol version",
            "example":"2.0"
        },
        "method":{
            "type":"string",
            "description":"JSON-RPC method name",
            "example":"eth_blockNumber"
        },
        "params":{
            "type":"array",
            "description":"JSON-RPC params array; structure depends on the method",
            "items":{
                "type":"object"
            }
        },
        "id":{
            "oneOf":[
                {
                    "type":"string"
                },
                {
                    "type":"integer"
                }
            ],
            "description":"Client-supplied identifier echoed in the response",
            "example":1
        }
    }
}

Nested Schema : id

Client-supplied identifier echoed in the response

Match One Schema

Show Source

• string
• integer

{
    "oneOf":[
        {
            "type":"string"
        },
        {
            "type":"integer"
        }
    ],
    "description":"Client-supplied identifier echoed in the response",
    "example":1
}

Example:

1

Nested Schema : params

Type: array

JSON-RPC params array; structure depends on the method

Show Source

• Array of: object items

{
    "type":"array",
    "description":"JSON-RPC params array; structure depends on the method",
    "items":{
        "type":"object"
    }
}

Nested Schema : items

Type: object

Examples

Select an example eth_blockNumber eth_getBalance

Back to Top

Response

Supported Media Types

• application/json

200 Response

Successful upstream response

Body ()

Root Schema : JsonRpcResponse

Type: object

Additional Properties Allowed: true

Show Source

• id: id
  Echoed request identifier
• jsonrpc: string
  JSON-RPC protocol version

  Example: 2.0
• result:
  RPC result payload (varies by method)

{
    "type":"object",
    "additionalProperties":true,
    "properties":{
        "jsonrpc":{
            "type":"string",
            "description":"JSON-RPC protocol version",
            "example":"2.0"
        },
        "id":{
            "oneOf":[
                {
                    "type":"string"
                },
                {
                    "type":"integer"
                }
            ],
            "description":"Echoed request identifier",
            "example":1
        },
        "result":{
            "nullable":true,
            "description":"RPC result payload (varies by method)"
        }
    }
}

Nested Schema : id

Echoed request identifier

Match One Schema

Show Source

• string
• integer

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

Example:

1

Examples

Select an example ethBlockNumber

4XX Response

Upstream or request error

Body ()

Root Schema : JsonRpcErrorResponse

Type: object

Show Source

• error: object JsonRpcErrorObject
• id: id
  Echoed request identifier when available
• jsonrpc: string
  JSON-RPC protocol version

  Example: 2.0

{
    "type":"object",
    "properties":{
        "jsonrpc":{
            "type":"string",
            "description":"JSON-RPC protocol version",
            "example":"2.0"
        },
        "id":{
            "nullable":true,
            "oneOf":[
                {
                    "type":"string"
                },
                {
                    "type":"integer"
                }
            ],
            "description":"Echoed request identifier when available"
        },
        "error":{
            "$ref":"#/components/schemas/JsonRpcErrorObject"
        }
    }
}

Nested Schema : JsonRpcErrorObject

Type: object

Show Source

• code: integer
  Example: -32603
• data:
  Upstream-supplied error data payload (type varies by method)
• message: string
  Example: Internal error

{
    "type":"object",
    "properties":{
        "code":{
            "type":"integer",
            "example":-32603
        },
        "message":{
            "type":"string",
            "example":"Internal error"
        },
        "data":{
            "nullable":true,
            "description":"Upstream-supplied error data payload (type varies by method)"
        }
    }
}

Nested Schema : id

Echoed request identifier when available

Match One Schema

Show Source

• string
• integer

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

5XX Response

Upstream or proxy error

Body ()

Root Schema : JsonRpcErrorResponse

Type: object

Show Source

• error: object JsonRpcErrorObject
• id: id
  Echoed request identifier when available
• jsonrpc: string
  JSON-RPC protocol version

  Example: 2.0

{
    "type":"object",
    "properties":{
        "jsonrpc":{
            "type":"string",
            "description":"JSON-RPC protocol version",
            "example":"2.0"
        },
        "id":{
            "nullable":true,
            "oneOf":[
                {
                    "type":"string"
                },
                {
                    "type":"integer"
                }
            ],
            "description":"Echoed request identifier when available"
        },
        "error":{
            "$ref":"#/components/schemas/JsonRpcErrorObject"
        }
    }
}

Nested Schema : JsonRpcErrorObject

Type: object

Show Source

• code: integer
  Example: -32603
• data:
  Upstream-supplied error data payload (type varies by method)
• message: string
  Example: Internal error

{
    "type":"object",
    "properties":{
        "code":{
            "type":"integer",
            "example":-32603
        },
        "message":{
            "type":"string",
            "example":"Internal error"
        },
        "data":{
            "nullable":true,
            "description":"Upstream-supplied error data payload (type varies by method)"
        }
    }
}

Nested Schema : id

Echoed request identifier when available

Match One Schema

Show Source

• string
• integer

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

Back to Top