1. Web3 Transactions and Besu Instance APIs
  2. Tasks
  3. Transactions

Sign and Submit a Transaction

post

/v1/besu/transaction

Signs and submits transactions to the configured Besu network for transfers, contract calls, and contract deployments.

Request

Header Parameters
  • Optional idempotency key for transaction tracking. Reusing a key with the same request returns the existing operation; reusing it with a different request returns HTTP 409.
  • Optional operator-defined Besu node identifier. Supported values include rpc-0, rpc-1, archive-0, validator-0, and bootnode-0.
  • Optional correlation ID. Echoed in the response when provided.
Supported Media Types
Request Body - application/json ()
Root Schema : schema
Type: object
Defines a transaction signing and submission request.
Show Source
  • abi
    Contract ABI. Required when `constructorArgs` is provided.
  • Contract bytecode in 0x-prefixed hexadecimal format. Required for deployment.
  • constructorArgs
    Optional constructor arguments, represented as strings.
  • contextTrailer
    Additional Properties Allowed: true
    Optional context object appended to contract-call calldata using the version 1 context format. If omitted or null, no context information is included. If provided, the value must be a non-empty JSON object.
  • contractAbi
    Optional ABI used to infer parameter types when `functionSignature` contains only a function name. For overloaded functions, the matching parameter count is used. If omitted, the ABI associated with `toAddress` is used when available.
  • 98701215921085330000000000000000000000000000000000000000000000000
  • SignDecodeOptions
    Decode options. Each option defaults to `false` when omitted.
  • Transfer amount in wei, represented as a decimal string, such as "10000000000000000".
  • Sender address for signing. Supply exactly one of walletId or fromAddress for wallet-backed requests. The address must be available to the authenticated caller.
  • functionArgs
    Function arguments as strings aligned with the parameter order. Scalars: address, bool, string, int/uint (any width), bytes/bytesN (1..32). Arrays (1-D) and tuples are supported by passing JSON strings: - Dynamic/fixed arrays, such as '["0xabc...", "0xdef..."]' or '["1","2","3"]' - Tuples and nested tuples, such as '["0xabc...", "42"]' - Empty tuple-array fields are valid, such as '[..., [], ...]' for tuple params containing '(...)[]' For a function name without types, `contractAbi` is used to infer parameter types. For overloaded functions, the matching parameter count is used.
  • Function selector for ABI encoding when data is absent. You may provide: - Fully specified signature, such as "approve(address,uint256)", or - Function name only, such as "approve"; parameter types are inferred from the provided ABI. For overloaded functions, the matching parameter count is used. If contractAbi is not supplied, the ABI associated with `toAddress is used when available.
  • EIP-1559 maximum fee per gas.
  • Gas limit. Required for contract deployment and optional otherwise.
  • Gas price for legacy transactions. If omitted, the value is obtained through `eth_gasPrice`.
  • EIP-1559 priority fee per gas.
  • TransactionLifecycleCallbackOptions
    Callback delivery options for a tracked transaction operation. Defines the callback target for a transaction operation. Callback credentials are never returned in API responses, support views, metrics, audit logs, or delivery records.
  • Optional user-facing contract metadata stored when this request deploys a contract. Rejected for non-deployment transactions.
  • Transaction nonce. If omitted, the pending nonce is obtained through `eth_getTransactionCount`.
  • Allowed Values: [ "NORMAL", "ENCODE_ONLY", "SIGN_ONLY", "ENCODE_AND_SIGN", "SIGN_AND_SEND" ]
    Operation mode for transaction submission. NORMAL signs and submits the transaction. ENCODE_ONLY returns encoded transaction fields. SIGN_ONLY signs pre-encoded request data without function, ABI, or deployment encoding. ENCODE_AND_SIGN encodes and signs the transaction without submitting it. SIGN_AND_SEND signs pre-encoded request data and submits the signed transaction. For modes other than NORMAL, decode.inputs, decode.events, decode.errors, receipt, and txByHash are unavailable.
  • TransactionPreflightOptions
    Controls for preflight simulation before transaction signing and submission.
  • Default Value: 60
    Maximum number of receipt checks. Default: `60`.
  • Default Value: 1500
    Interval, in milliseconds, between receipt checks. Default: `1500`.
  • storageLayout
    Optional Solidity compiler storage-layout JSON.
  • Recipient address. Omit for a contract deployment.
  • Default Value: false
    When `true` for `NORMAL` submissions, creates a transaction operation and returns `operationId` and `statusUrl`. Other operation modes reject this option.
  • Default Value: false
    When `true`, includes the `eth_getTransactionByHash` result in the response.
  • Default Value: 2
    Allowed Values: [ 0, 2 ]
    Transaction type: `0` for legacy or `2` for EIP-1559.
  • Default Value: true
    When `true`, waits for a transaction receipt before responding. Default: `true`.
  • Wallet identifier for signing. Supply exactly one of walletId or fromAddress for wallet-backed requests.
Nested Schema : abi
Type: array
Contract ABI. Required when `constructorArgs` is provided.
Show Source
Nested Schema : constructorArgs
Type: array
Optional constructor arguments, represented as strings.
Show Source
Nested Schema : contextTrailer
Type: object
Additional Properties Allowed: true
Optional context object appended to contract-call calldata using the version 1 context format. If omitted or null, no context information is included. If provided, the value must be a non-empty JSON object.
Nested Schema : contractAbi
Type: array
Optional ABI used to infer parameter types when `functionSignature` contains only a function name. For overloaded functions, the matching parameter count is used. If omitted, the ABI associated with `toAddress` is used when available.
Show Source
Nested Schema : SignDecodeOptions
Type: object
Decode options. Each option defaults to `false` when omitted.
Show Source
Nested Schema : functionArgs
Type: array
Function arguments as strings aligned with the parameter order. Scalars: address, bool, string, int/uint (any width), bytes/bytesN (1..32). Arrays (1-D) and tuples are supported by passing JSON strings: - Dynamic/fixed arrays, such as '["0xabc...", "0xdef..."]' or '["1","2","3"]' - Tuples and nested tuples, such as '["0xabc...", "42"]' - Empty tuple-array fields are valid, such as '[..., [], ...]' for tuple params containing '(...)[]' For a function name without types, `contractAbi` is used to infer parameter types. For overloaded functions, the matching parameter count is used.
Show Source
Nested Schema : TransactionLifecycleCallbackOptions
Type: object
Callback delivery options for a tracked transaction operation. Defines the callback target for a transaction operation. Callback credentials are never returned in API responses, support views, metrics, audit logs, or delivery records.
Show Source
Nested Schema : TransactionPreflightOptions
Type: object
Controls for preflight simulation before transaction signing and submission.
Show Source
  • Default Value: pending
    Block tag used for simulation. Supports `pending`, `latest`, `earliest`, or a block number.
  • Default Value: true
    Includes the gas estimate or configured gas limit in the preflight result when available.
  • Default Value: false
    Prevents signing and submission if simulation reverts or is unavailable.
  • Default Value: false
    Runs `eth_call` before signing and submission. Enabled automatically when `requireSuccess=true`.
Nested Schema : storageLayout
Type: object
Optional Solidity compiler storage-layout JSON.
Nested Schema : items
Type: object
Nested Schema : items
Type: object
Nested Schema : events
Type: array
Optional event allowlist. When omitted or empty, callbacks default to confirmed and failed only.
Show Source
  • Allowed Values: [ "submitted_to_node", "accepted_by_node", "mined", "confirmed", "failed", "receipt_reorged", "remediation_denied" ]
Nested Schema : EventSubscriptionOAuthConfig
Type: object
OAuth 2.0 configuration for callback authentication.
Show Source
  • Default Value: true
    Controls OAuth token request client-auth placement. When true, sends `clientId:clientSecret` in an HTTP Basic Authorization header to the token endpoint. When false, sends client_id and client_secret form fields in the token request body.
  • OAuth 2.0 client identifier registered for the callback endpoint.
  • OAuth 2.0 client secret used for token acquisition.
  • Default Value: client_credentials
    Allowed Values: [ "client_credentials", "refresh_token" ]
    OAuth 2.0 token grant used for callback access-token acquisition. client_credentials obtains an access token with the configured client credentials. refresh_token uses the supplied refreshToken and retains any replacement refresh token returned by the identity provider.
  • Required when grantType=refresh_token; pre-provisioned OAuth refresh token used to mint callback access tokens.
  • Space-delimited OAuth scopes requested during token exchange.
  • EventSubscriptionTlsConfig
    TLS or mTLS configuration for callback delivery. If mTLS is used, both clientCert and clientKey must be provided together.
  • EventSubscriptionTlsConfig
    TLS or mTLS configuration for callback delivery. If mTLS is used, both clientCert and clientKey must be provided together.
  • OAuth 2.0 token endpoint used to obtain access tokens for callbacks.
Match All
OAuth 2.0 configuration for callback authentication.
Show Source
Nested Schema : EventSubscriptionTlsConfig
Type: object
TLS or mTLS configuration for callback delivery. If mTLS is used, both clientCert and clientKey must be provided together.
Show Source
Examples

Back to Top

Response

Supported Media Types

200 Response

Returns the transaction result.
Body ()
Root Schema : TransactionSubmitResponse
Type: object
Result of a transaction submission, encoding, or signing request.
Show Source
Nested Schema : transactionByHash
Type: object
Additional Properties Allowed: true
Transaction details returned by the Ethereum JSON-RPC `eth_getTransactionByHash` method when requested and available.
Examples

400 Response

Validation failed.
Body ()
Root Schema : ErrorResponse
Type: object
Error response returned by the service.
Show Source
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

409 Response

Request conflicts with an existing idempotency record or transaction state.
Body ()
Root Schema : ErrorResponse
Type: object
Error response returned by the service.
Show Source
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

422 Response

Transaction submission succeeded and a synchronously observed receipt reports EVM execution reverted. The response body remains a TransactionSubmitResponse, including the transaction hash and receipt.
Body ()
Root Schema : TransactionSubmitResponse
Type: object
Result of a transaction submission, encoding, or signing request.
Show Source
Nested Schema : transactionByHash
Type: object
Additional Properties Allowed: true
Transaction details returned by the Ethereum JSON-RPC `eth_getTransactionByHash` method when requested and available.

500 Response

Unexpected service error.
Body ()
Root Schema : ErrorResponse
Type: object
Error response returned by the service.
Show Source
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.
Body ()
Root Schema : ErrorResponse
Type: object
Error response returned by the service.
Show Source
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.

503 Response

Transaction lifecycle service is unavailable for an idempotent tracked submission.
Body ()
Root Schema : ErrorResponse
Type: object
Error response returned by the service.
Show Source
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

Back to Top