RPC Endpoint | TxBoost

# Interact directly with the Txboost RPC endpoint

searchers can interact with the RPC endpoint at one of URLs below.

# Bundle Relay URL

Network	URL
bsc	`https://relay-bsc.txboost.io`

The API provides JSON-RPC methods for interfacing with Txboost which are documented below:

# eth_sendBundle

eth_sendBundle can be used to send your bundles to the Txboost builder. The eth_sendBundle RPC has the following payload format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_sendBundle",
  "params": [
    {
      txs,               // Array[String], A list of signed transactions to execute in an atomic bundle
      blockNumber,       // String, a hex encoded block number for which this bundle is valid on
      minTimestamp,      // (Optional) Number, the minimum timestamp for which this bundle is valid, in seconds since the unix epoch
      maxTimestamp,      // (Optional) Number, the maximum timestamp for which this bundle is valid, in seconds since the unix epoch
      revertingTxHashes, // (Optional) Array[String], A list of tx hashes that are allowed to revert
    }
  ]
}

example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_sendBundle",
  "params": [
    {
      "txs": ["0x123abc...", "0x456def..."],
      "blockNumber": "0xb63dcd",
      "minTimestamp": 0,
      "maxTimestamp": 1615920932
    }
  ]
}

example response:

{
  "jsonrpc": "2.0",
  "id": "123",
  "result": {
    "bundleHash": "0x2228f5d8954ce31dc1601a8ba264dbd401bf1428388ce88238932815c5d6f23f"
  }
}

# eth_callBundle

Using https://simulation-bsc.txboost.io as the endpoint to call eth_callBundle.

eth_callBundle can be used to simulate a bundle against a specific block number, including simulating a bundle at the top of the next block. The eth_callBundle RPC has the following payload format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_callBundle",
  "params": [
    {
      txs,               // Array[String], A list of signed transactions to execute in an atomic bundle
      blockNumber,       // String, a hex encoded block number for which this bundle is valid on
      stateBlockNumber,  // String, either a hex encoded number or a block tag for which state to base this simulation on. Can use "latest"
      timestamp,         // (Optional) Number, the timestamp to use for this bundle simulation, in seconds since the unix epoch
    }
  ]
}

example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_callBundle",
  "params": [
    {
      "txs": ["0x123abc...", "0x456def..."],
      "blockNumber": "0xb63dcd",
      "stateBlockNumber": "latest",
      "timestamp": 1615920932
    }
  ]
}

example response:

{
  "jsonrpc": "2.0",
  "id": "123",
  "result": {
    "bundleGasPrice": "476190476193",
    "bundleHash": "0x73b1e258c7a42fd0230b2fd05529c5d4b6fcb66c227783f8bece8aeacdd1db2e",
    "coinbaseDiff": "20000000000126000",
    "ethSentToCoinbase": "20000000000000000",
    "gasFees": "126000",
    "results": [
      {
        "coinbaseDiff": "10000000000063000",
        "ethSentToCoinbase": "10000000000000000",
        "fromAddress": "0x02A727155aeF8609c9f7F2179b2a1f560B39F5A0",
        "gasFees": "63000",
        "gasPrice": "476190476193",
        "gasUsed": 21000,
        "toAddress": "0x73625f59CAdc5009Cb458B751b3E7b6b48C06f2C",
        "txHash": "0x669b4704a7d993a946cdd6e2f95233f308ce0c4649d2e04944e8299efcaa098a",
        "value": "0x"
      },
      {
        "coinbaseDiff": "10000000000063000",
        "ethSentToCoinbase": "10000000000000000",
        "fromAddress": "0x02A727155aeF8609c9f7F2179b2a1f560B39F5A0",
        "gasFees": "63000",
        "gasPrice": "476190476193",
        "gasUsed": 21000,
        "toAddress": "0x73625f59CAdc5009Cb458B751b3E7b6b48C06f2C",
        "txHash": "0xa839ee83465657cac01adc1d50d96c1b586ed498120a84a64749c0034b4f19fa",
        "value": "0x"
      }
    ],
    "stateBlockNumber": 5221585,
    "totalGasUsed": 42000
  }
}

# eth_sendPrivateTransaction

eth_sendPrivateTransaction is used to send a single transaction to Txboost.

This method has the following JSON-RPC format:

{
  jsonrpc: "2.0",
  id: string | number,
  method: "eth_sendPrivateTransaction",
  params: [{
    tx,               // String, raw signed transaction
    maxBlockNumber,   // Hex-encoded number string, optional. Highest block number in which the transaction should be included.
    preferences?: {
      fast: boolean,  // Deprecated; required until this is removed from the API. Value has no effect.
      privacy?: {     //  options; optional
        hints?: Array< // data about tx to share w/ searchers on mev-share
            "contract_address" |
            "function_selector" |
            "calldata" |
            "logs" |
            "hash"
        >,
        builders?: Array< //  builders to exclusively receive bundles; optional
            "default" |
            "Txboost"
        >,
      },
      validity?: {
        refund?: Array<{address, percent}>
      }
    }
  }]
}

example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_sendPrivateTransaction",
  "params": [
    {
      "tx": "0x123abc...",
      "maxBlockNumber": "0xcd23a0",
      "preferences": {
        "fast": true, // left for backwards compatibility; may be removed in a future version
        "privacy": {
          "hints": ["calldata", "transaction_hash"],
          "builders": ["default"]
        },
        "validity": {
          "refund": [{ "address": "0xadd123", "percent": 50 }]
        }
      }
    }
  ]
}

example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x45df1bc3de765927b053ec029fc9d15d6321945b23cac0614eb0b5e61f3a2f2a" // tx hash
}

# `privacy`

By default, transactions are sent to the Txboost MEV-Share Node with the default Stable configuration. The privacy parameter allows you to specify your own privacy parameters.

Param	Type Info	Description
`hint`	Array of strings	Each hint specifies which data about the transaction will be shared with searchers on mev-share.
`builders`	Array of strings	Builders to grant permission to include the transaction in a block.

hint

builders

Txboost currently supports sending orderflow to the following block builders. This is subject to change over time.

# `validity`

Validity is used to specify the address and percentage to pay refund from the backrun of this transaction.

By default, the refund is paid to the signer of the transaction and 90% of the backrun value is sent to the user by default.

If multiple refund addresses are specified, then the backrun value is split between them according to the percentage specified. For example, if refund is [{address: addr1, percent: 10}, {address: addr1, percent: 20}] then 10% of the backrun value is sent to addr1 and 20% is sent to addr2 and 70% of the backrun value is left to the builder.

Param	Type Info	Description
`refund`	Array of objects	Each entry in the array specifies address that should receive refund from backrun and percent of the backrun value.
`refund[].address`	Address	Address that should receive refund.
`refund[].percent`	Number	Percentage of the total backrun value that this address should receive.

# eth_sendPrivateRawTransaction

eth_sendPrivateRawTransactionis used to send a single transaction to Txboost. Flashbots will attempt to build a block including the transaction for the next blocks This method has the following JSON-RPC format:

{
  jsonrpc: "2.0",
  id: string | number,
  method: "eth_sendPrivateRawTransaction",
  params: [
    tx,               // String, raw signed transaction
    preferences?      // Optional, see eth_sendPrivateTransaction
  ]
}

example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_sendPrivateRawTransaction",
  "params": ["0x123abc..."]
}

example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x45df1bc3de765927b053ec029fc9d15d6321945b23cac0614eb0b5e61f3a2f2a" // tx hash
}

Param	Type Info	Description
`params[0]`	String	Raw signed transaction
`params[1]`	Object	Optional private tx preferences, see `preferences` in eth_sendPrivateTransaction.

# eth_cancelPrivateTransaction

The eth_cancelPrivateTransaction method stops private transactions from being submitted for future blocks. A transaction can only be cancelled if the request is signed by the same key as the eth_sendPrivateTransaction call submitting the transaction in first place.

This method has the following JSON-RPC format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_cancelPrivateTransaction",
  "params": [{
    txHash,   // String, transaction hash of private tx to be cancelled
  }]
}

example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_cancelPrivateTransaction",
  "params": [
    {
      "txHash": "0x45df1bc3de765927b053ec029fc9d15d6321945b23cac0614eb0b5e61f3a2f2a"
    }
  ]
}

example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true // true if tx successfully cancelled, false if not
}

# API Response

All method supports JSON-RPC standards for success response and not supported for error response.

# Authentication

To authenticate your request, please set the "Authorization" HTTP header in the RPC request.

Please refer to the example.

# Interact directly with the Txboost RPC endpoint

# Bundle Relay URL

# eth_sendBundle

# eth_callBundle

# eth_sendPrivateTransaction

# privacy

# validity

# eth_sendPrivateRawTransaction

# eth_cancelPrivateTransaction

# API Response

# Authentication

# `privacy`

# `validity`