Titan Builder

https://docs.titanbuilder.xyz
Admin
Titan Builder provides RPC endpoints and tools for blockchain builders, focusing on MEV share,...
Tokens:6,941
Snippets:37
Trust Score:6.1
Update:11 months ago
Show doc for...
Tokens:
Raw
### CURL Example for eth_sendBundle

Source: https://docs.titanbuilder.xyz/api/eth_sendbundle

Demonstrates how to send an eth_sendBundle request using cURL. This example includes sample signed transactions and a replacement UUID, showing the command structure and required headers for making the RPC call to the Titanbuilder endpoint.

```bash
curl -s --data '{"jsonrpc": "2.0","id": "1","method": "eth_sendBundle","params": [{"txs": ["0x12…ab","0x34..cd"], "blockNumber": "0x102286B","replacementUuid": "abcd1234"}]}' -H "Content-Type: application/json" -X POST https://rpc.titanbuilder.xyz
```

--------------------------------

### Response Example for eth_sendPrivateTransaction

Source: https://docs.titanbuilder.xyz/api/eth_sendprivatetransaction

This is an example of a successful response from the eth_sendPrivateTransaction method. It indicates that the transaction was processed, returning a result code and null for any errors.

```json
{"result":200,"error":null,"id":1}
```

--------------------------------

### Example titan_getBundleStats API Response (JSON)

Source: https://docs.titanbuilder.xyz/bundle-tracing

This is an example JSON response from the `titan_getBundleStats` API. It shows the structure of the data returned, including the JSON-RPC version, the result object, and the request ID. The 'result' object contains key information such as the bundle's 'status' (e.g., 'SimulationFail'), 'builderPayment', and an 'error' message if applicable.

```json
{
  "jsonrpc":"2.0",
  "result": {
    "status":"SimulationFail",
    "builderPayment":"0",
    "error":"BundleRevert. Reverting Hash: 0x…456"
  },
  "id":1
}
```

--------------------------------

### eth_sendBlobs cURL Request Example

Source: https://docs.titanbuilder.xyz/api/eth_sendblobs

Demonstrates how to send a request to the eth_sendBlobs endpoint using cURL. This example shows sending multiple blob transactions with different permutations of blobs to the RPC endpoint. It includes the necessary JSON payload with the 'txs' parameter containing various transaction strings.

```bash
curl -s --data '{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "eth_sendBlobs",
  "params": [{
    "txs": [
      "0x12...ab1",  // Transaction with 1 blob
      "0x34...cd2",  // Transaction with 2 blobs
      "0x56...ef3",  // Transaction with 3 blobs
      "0x78...gh4",  // Transaction with 4 blobs
      "0x9a...ij5",  // Transaction with 5 blobs
      "0xbc...kl6"   // Transaction with 6 blobs
    ]
  }]
}' -H "Content-Type: application/json" -X POST https://rpc.titanbuilder.xyz
```

--------------------------------

### Cancel Bundle with CURL

Source: https://docs.titanbuilder.xyz/api/eth_cancelbundle

Example demonstrating how to cancel a bundle using the CURL command-line tool. This sends a POST request to the specified RPC endpoint with the eth_cancelBundle method and the required replacementUuid.

```bash
curl -s --data '{"jsonrpc": "2.0","id": "1","method": "eth_cancelBundle", "params": [{"replacementUuid": "abcd1234"}]}' -H "Content-Type: application/json" -X POST https://rpc.titanbuilder.xyz
```

--------------------------------

### eth_sendBundle Response Example

Source: https://docs.titanbuilder.xyz/api/eth_sendbundle

Illustrates a successful response from the eth_sendBundle method. The response contains a bundleHash, which is a unique identifier for the submitted bundle, and a null error field indicating success.

```javascript
{"result":{"bundleHash":"0x164d7d41f24b7f333af3b4a70b690cf93f636227165ea2b699fbb7eed09c46c7"},"error":null,"id":1}
```

--------------------------------

### Get Bundle Statistics via titan_getBundleStats API (Bash)

Source: https://docs.titanbuilder.xyz/bundle-tracing

This snippet demonstrates how to call the `titan_getBundleStats` API endpoint using curl to retrieve the status of a specific bundle identified by its hash. It includes the necessary JSON-RPC payload and the target URL. The output is a JSON object containing the bundle's status, builder payment, and any associated error messages.

```bash
curl -X POST -H 'content-type: application/json' -d '{"method": "titan_getBundleStats", "params": [{"bundleHash": "0x...123"}], "jsonrpc": "2.0", "id": 1}' https://stats.titanbuilder.xyz
```

--------------------------------

### eth_cancelBundle Response Example

Source: https://docs.titanbuilder.xyz/api/eth_cancelbundle

Illustrates a successful response from the eth_cancelBundle RPC method. A 'result' of 200 indicates the cancellation request was processed. Note that cancellation is not guaranteed if submitted within 4 seconds of the final relay submission.

```json
{
  "result": 200,
  "error": null,
  "id": 1
}
```

--------------------------------

### Bundle Hash Algorithm

Source: https://docs.titanbuilder.xyz/api/eth_sendbundle

Details the Rust algorithm used to calculate the unique hash for a given bundle, ensuring integrity and identification.

```APIDOC
## Bundle Hash Calculation

### Description
This section details the algorithm for generating a bundle hash using Rust, which incorporates various properties of the `RawBundle` struct.

### Method
Internal Hashing Algorithm

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Code Example (Rust)
```rust
#[derive(Hash, Serialize, Deserialize)]
pub struct RawBundle {
   #[serde(default)]
    pub block_number: U64,
    #[serde(default)]
    pub txs: Vec<Bytes>,
    pub reverting_tx_hashes: Option<Vec<String>>,
    pub dropping_tx_hashes: Option<Vec<String>>,
    pub replacement_uuid: Option<String>,
    pub refund_percent: Option<u64>,
    pub refund_recipient: Option<Address>,
    pub refund_tx_hashes: Option<Vec<String>>,
}

pub fn bundle_hash(bundle: &RawBundle) -> B256 {
    let mut hasher = wyhash::WyHash::default();
    let mut bytes = [0u8; 32];
    for i in 0..4 {
        bundle.hash(&mut hasher);
        let hash = hasher.finish();
        bytes[(i * 8)..((i + 1) * 8)].copy_from_slice(&hash.to_be_bytes());
    }

    B256::from(bytes)
}
```
```

--------------------------------

### eth_cancelBundle Request Structure (JavaScript Object)

Source: https://docs.titanbuilder.xyz/api/eth_cancelbundle

Defines the JSON structure for the eth_cancelBundle RPC method request. It requires a 'replacementUuid' to identify the bundle to be canceled. The 'replacementUuid' must have been provided during the initial bundle submission.

```javascript
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_cancelBundle",
  "params": [
    {
      replacementUuid: "string"
    }
  ]
}
```

--------------------------------

### titan_getBundleStats

Source: https://docs.titanbuilder.xyz/bundle-tracing

Retrieves the status and tracing information for a specific MEV bundle.

```APIDOC
## POST /titan_getBundleStats

### Description
Retrieves the status and tracing information for a specific MEV bundle. This endpoint provides insights into why a bundle was or was not included in a block, including simulation results and potential reasons for exclusion.

### Method
POST

### Endpoint
`https://stats.titanbuilder.xyz`

### Parameters
#### Query Parameters
None

#### Request Body
- **method** (string) - Required - The name of the method to call, which is 'titan_getBundleStats'.
- **params** (array) - Required - An array containing the parameters for the method.
  - **bundleHash** (string) - Required - The unique hash of the bundle to retrieve statistics for.
- **jsonrpc** (string) - Required - The version of the JSON-RPC protocol, typically '2.0'.
- **id** (integer) - Required - A unique identifier for the request.

### Request Example
```json
{
  "method": "titan_getBundleStats",
  "params": [{
    "bundleHash": "0x...123"
  }],
  "jsonrpc": "2.0",
  "id": 1
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - The JSON-RPC protocol version.
- **result** (object) - An object containing the bundle statistics.
  - **status** (string) - The current status of the bundle (e.g., 'SimulationFail', 'IncludedInBlock'). See 'Understanding Bundle Statuses' for details.
  - **builderPayment** (string) - The net builder payment for the bundle.
  - **error** (string) - Provides specific error details if the status indicates a failure.
- **id** (integer) - The identifier of the request.

#### Response Example
```json
{
  "jsonrpc":"2.0",
  "result": {
    "status":"SimulationFail",
    "builderPayment":"0",
    "error":"BundleRevert. Reverting Hash: 0x…456"
  },
  "id":1
}
```

### Understanding Bundle Statuses
- **Received**: Bundle received but too late for the pool.
- **Invalid**: Bundle is invalid (e.g., RLP, block number, nonce, Chain ID).
- **SimulationFail**: Bundle failed simulation due to transaction revert or insufficient builder payment.
- **SimulationPass**: Bundle passed simulation but was sent too late.
- **ExcludedFromBlock**: Bundle valid and passed simulation but not selected (insufficient bribe or late submission).
- **IncludedInBlock**: Bundle considered but not selected for relay submission (more valuable block existed).
- **Submitted**: Bundle included in a block submitted to a relay.
```

--------------------------------

### eth_sendBundle Method Parameters

Source: https://docs.titanbuilder.xyz/api/eth_sendbundle

Defines the structure and parameters for the eth_sendBundle JSON-RPC method. It includes fields for transactions, block number validity, reverting and dropping transaction hashes, replacement UUID, and refund configurations. The txs field is mandatory, while others are optional.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_sendBundle",
  "params": [
    {
      txs: [],               // Array[String], A list of signed transactions to execute in an atomic bundle, list can be empty for bundle cancellations
      blockNumber: "0x...",     // (Optional) String, a hex-encoded block number for which this bundle is valid. Default, current block number
      revertingTxHashes: [], // (Optional) Array[String], A list of tx hashes that are allowed to revert or be discarded
      droppingTxHashes: [],  // (Optional) Array[String], A list of tx hashes that are allowed to be discarded, but may not revert
      replacementUuid: "...",   // (Optional) String, any arbitrary string that can be used to replace or cancel this bundle
      refundPercent: 0,     // (Optional) Number, the percentage (from 0 to 99) of the  ETH reward of the last transaction, or the transaction specified by refundIndex, that should be refunded back to the ‘refundRecipient’
      refundTxHashes: [],    // (Optional) Array[String], Max length 1. An array of transaction hashes used to determine the refund. If not provided or left empty, the refund will be based on the final transaction in the bundle.
      refundRecipient: "0x...",   // (Optional) Address, the address that will receive the ETH refund. Default, sender of the first transaction in the bundle
    }
  ]
}
```

--------------------------------

### Bundle Hash Calculation Algorithm

Source: https://docs.titanbuilder.xyz/api/eth_sendbundle

Provides the Rust code for calculating the bundle hash. It defines the `RawBundle` struct and the `bundle_hash` function, which uses the `wyhash` algorithm to generate a `B256` hash from the bundle's serialized data.

```rust
#[derive(Hash, Serialize, Deserialize)]
pub struct RawBundle {
   #[serde(default)]
    pub block_number: U64,
    #[serde(default)]
    pub txs: Vec<Bytes>,
    pub reverting_tx_hashes: Option<Vec<String>>,
    pub dropping_tx_hashes: Option<Vec<String>>,
    pub replacement_uuid: Option<String>,
    pub refund_percent: Option<u64>,
    pub refund_recipient: Option<Address>,
    pub refund_tx_hashes: Option<Vec<String>>,
}

pub fn bundle_hash(bundle: &RawBundle) -> B256 {
    let mut hasher = wyhash::WyHash::default();
    let mut bytes = [0u8; 32];
    for i in 0..4 {
        bundle.hash(&mut hasher);
        let hash = hasher.finish();
        bytes[(i * 8)..((i + 1) * 8)].copy_from_slice(&hash.to_be_bytes());
    }

    B256::from(bytes)
}
```

--------------------------------

### eth_sendEndOfBlockBundle

Source: https://docs.titanbuilder.xyz/api/eth_sendendofblockbundle

Submits an end-of-block bundle of transactions for simulation and inclusion in the next block. Bundles are executed atomically and can target specific liquidity pools.

```APIDOC
## POST /eth_sendEndOfBlockBundle

### Description
Submits an end-of-block bundle of transactions for simulation and inclusion in the next block. Bundles are executed atomically and can target specific liquidity pools. This method is used after a block has been built to simulate and potentially add end-of-block bundles.

### Method
POST

### Endpoint
/

### Parameters
#### Request Body
- **jsonrpc** (String) - Specifies the JSON-RPC protocol version, should be "2.0".
- **id** (Number) - The ID of the request.
- **method** (String) - The method name, should be "eth_sendEndOfBlockBundle".
- **params** (Array) - An array containing the parameters for the method.
  - **txs** (Array[String]) - A list of signed transactions to execute in an atomic bundle. This list can be empty for bundle cancellations.
  - **blockNumber** (String) - (Optional) A hex-encoded block number for which this bundle is valid. Defaults to the current block number.
  - **revertingTxHashes** (Array[String]) - (Optional) A list of transaction hashes that are allowed to revert or be discarded.
  - **targetPools** (Array[String]) - A list of pool addresses that this bundle is targeting.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_sendEndOfBlockBundle",
  "params": [
    {
      "txs": ["0x..."],
      "blockNumber": "0x12345",
      "revertingTxHashes": ["0x..."],
      "targetPools": ["0xpool1"]
    }
  ]
}
```

### Response
#### Success Response (200)
- **jsonrpc** (String) - The JSON-RPC protocol version.
- **id** (Number) - The ID of the request.
- **result** (Any) - The result of the method call. The specific structure depends on the implementation, but typically indicates success or failure of the bundle submission.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x..."
}
```
```

--------------------------------

### eth_sendBundle API

Source: https://docs.titanbuilder.xyz/api/eth_sendbundle

The eth_sendBundle method allows users to submit atomic bundles of transactions. It supports various optional parameters for customization, including block validity, reverting transactions, refund percentages, and replacement UUIDs.

```APIDOC
## POST /rpc.titanbuilder.xyz

### Description
Submits an atomic bundle of transactions for execution. This method is crucial for ensuring transaction atomicity and allows for complex transaction sequencing.

### Method
POST

### Endpoint
https://rpc.titanbuilder.xyz

### Parameters
#### Request Body
- **jsonrpc** (String) - Must be "2.0".
- **id** (Number/String) - Identifier for the request.
- **method** (String) - Must be "eth_sendBundle".
- **params** (Array) - An array containing the bundle parameters:
  - **txs** (Array[String]) - Required. A list of signed transactions to execute in an atomic bundle. Can be empty for cancellations.
  - **blockNumber** (String) - Optional. A hex-encoded block number for which this bundle is valid. Defaults to the current block number.
  - **revertingTxHashes** (Array[String]) - Optional. A list of transaction hashes that are allowed to revert or be discarded.
  - **droppingTxHashes** (Array[String]) - Optional. A list of transaction hashes that are allowed to be discarded, but may not revert.
  - **replacementUuid** (String) - Optional. An arbitrary string used to replace or cancel this bundle.
  - **refundPercent** (Number) - Optional. The percentage (0-99) of the ETH reward to be refunded. If set, a refund transaction is constructed automatically.
  - **refundTxHashes** (Array[String]) - Optional. Max length 1. Transaction hashes used to determine the refund. Defaults to the last transaction in the bundle.
  - **refundRecipient** (Address) - Optional. The address to receive the ETH refund. Defaults to the sender of the first transaction.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "eth_sendBundle",
  "params": [
    {
      "txs": [
        "0x12…ab",
        "0x34..cd"
      ],
      "blockNumber": "0x102286B",
      "replacementUuid": "abcd1234"
    }
  ]
}
```

### Response
#### Success Response (200)
- **result** (Object) - Contains the bundle hash.
  - **bundleHash** (String) - The hash of the submitted bundle.
- **error** (null) - Indicates no error occurred.
- **id** (Number/String) - The identifier for the request.

#### Response Example
```json
{
  "result": {
    "bundleHash": "0x164d7d41f24b7f333af3b4a70b690cf93f636227165ea2b699fbb7eed09c46c7"
  },
  "error": null,
  "id": 1
}
```

### Notes
- If `refundPercent` is set, the builder constructs a refund transaction. If the refund amount doesn't cover `gas_used * base_fee`, the bundle will be discarded.
- Sponsored bundles are supported. If a bundle fails with `LackOfFundForGasLimit`, the builder may sponsor the ETH required for gas fees, provided the bundle increases the builder's balance.
```

--------------------------------

### eth_sendBlobs

Source: https://docs.titanbuilder.xyz/api/eth_sendblobs

This endpoint allows you to send multiple permutations of blob transactions from a single sender. It addresses the challenge of external blob originators by supporting a custom blob pool that allows multiple transactions with the same nonce, ensuring optimal blob combinations are selected.

```APIDOC
## POST /eth_sendBlobs

### Description
Allows sending all permutations of blob transactions from a single sender. It utilizes a custom blob pool that permits multiple transactions with the same nonce, enabling the selection of optimal blob combinations.

### Method
POST

### Endpoint
/eth_sendBlobs

### Parameters
#### Request Body
- **jsonrpc** (String) - Required - Specifies the JSON-RPC version, usually "2.0".
- **id** (String) - Required - An identifier for the request.
- **method** (String) - Required - The name of the method to be invoked, must be "eth_sendBlobs".
- **params** (Array) - Required - An array containing the method parameters.
  - **txs** (Array[String]) - Required - A list of blob transactions. One transaction per blob permutation.
  - **maxBlockNumber** (String) - Optional - A hex-encoded string representing the block number of the last block in which the transactions should be included.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "eth_sendBlobs",
  "params": [
    {
      "txs": [
        "0x12...ab1", 
        "0x34...cd2", 
        "0x56...ef3", 
        "0x78...gh4", 
        "0x9a...ij5", 
        "0xbc...kl6"
      ],
      "maxBlockNumber": "0x12345"
    }
  ]
}
```

### Response
#### Success Response (200)
- **result** (Integer) - The result of the operation, typically 200 for success.
- **error** (Object | null) - An error object if the operation failed, otherwise null.
- **id** (String) - The identifier for the response, matching the request id.

#### Response Example
```json
{
  "result": 200,
  "error": null,
  "id": 1
}
```
```

--------------------------------

### Send Private Transaction (JavaScript)

Source: https://docs.titanbuilder.xyz/api/eth_sendprivatetransaction

This JavaScript snippet demonstrates how to send a private transaction using the eth_sendPrivateTransaction method. It requires a signed raw transaction hex string as a parameter. The output is a JSON-RPC response indicating success or failure.

```javascript
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "eth_sendPrivateTransaction",
  "params": [
    {
      tx               // Signed raw tx hex
    }
  ]
}
```

--------------------------------

### eth_sendEndOfBlockBundle JSON-RPC Request Structure

Source: https://docs.titanbuilder.xyz/api/eth_sendendofblockbundle

Defines the structure for the eth_sendEndOfBlockBundle JSON-RPC request. It includes parameters for signed transactions, optional block number, optional reverting transaction hashes, and target pools. This method is used to process atomic bundles at the end of a block.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_sendEndOfBlockBundle",
  "params": [
    {
      "txs": [],               // Array[String], A list of signed transactions to execute in an atomic bundle, list can be empty for bundle cancellations
      "blockNumber": "",       // (Optional) String, a hex-encoded block number for which this bundle is valid. Default, current block number
      "revertingTxHashes": [], // (Optional) Array[String], A list of tx hashes that are allowed to revert or be discarded     
      "targetPools": []        // Array[String], A list of pool addresses that this bundle is targeting
    }
  ]
}
```

--------------------------------

### Send Private Transaction (CURL)

Source: https://docs.titanbuilder.xyz/api/eth_sendprivatetransaction

This CURL command shows how to send a private transaction using the eth_sendPrivateTransaction method via an HTTP POST request. It includes the JSON-RPC payload with the signed raw transaction hex. The expected response is a JSON object indicating the transaction result.

```bash
curl -s --data '{"jsonrpc": "2.0","id": "1","method": "eth_sendPrivateTransaction","params": [{"tx": "0x12…ab"}]}' -H "Content-Type: application/json" -X POST https://rpc.titanbuilder.xyz
```

--------------------------------

### eth_cancelBundle

Source: https://docs.titanbuilder.xyz/api/eth_cancelbundle

Cancels a previously submitted Ethereum bundle using its replacement UUID. Note that cancellation may not be guaranteed if submitted too close to the final relay submission.

```APIDOC
## POST /rpc

### Description
Cancels a previously submitted Ethereum bundle using its replacement UUID. Note that cancellation may not be guaranteed if submitted too close to the final relay submission.

### Method
POST

### Endpoint
/rpc

### Parameters
#### Query Parameters
None

#### Request Body
- **jsonrpc** (string) - Required - The JSON-RPC protocol version, must be "2.0".
- **id** (integer) - Required - The ID of the request.
- **method** (string) - Required - The method name, must be "eth_cancelBundle".
- **params** (array) - Required - An array containing the parameters for the method.
  - **replacementUuid** (string) - Required - The unique identifier for the bundle to be canceled. This UUID must have been set during the bundle submission.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_cancelBundle",
  "params": [
    {
      "replacementUuid": "abcd1234"
    }
  ]
}
```

### Response
#### Success Response (200)
- **result** (integer) - The result of the operation, typically 200 on success.
- **error** (null) - Should be null on success.
- **id** (integer) - The ID of the request.

#### Response Example
```json
{
  "result": 200,
  "error": null,
  "id": 1
}
```
```

--------------------------------

### eth_sendBlobs JSON-RPC Request Structure

Source: https://docs.titanbuilder.xyz/api/eth_sendblobs

Defines the JSON-RPC request structure for the eth_sendBlobs method. It includes the method name, a unique ID, and parameters for sending blob transactions. The 'txs' parameter is an array of strings representing blob transactions, and 'maxBlockNumber' is an optional hex-encoded string for the maximum block number.

```javascript
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "eth_sendBlobs",
  "params": [
    {
      txs: ["String"],            // Array[String], A list of blob transactions. One transaction per blob permutation.
      maxBlockNumber: "String", // (Optional) String, a hex-encoded string representing the block number of the last block in which the transactions should be included.
    }
  ]
}
```

--------------------------------

### eth_sendPrivateTransaction

Source: https://docs.titanbuilder.xyz/api/eth_sendprivatetransaction

Sends a private transaction to the network. This method allows for private transaction submission without broadcasting to the public mempool.

```APIDOC
## POST /rpc

### Description
Sends a private transaction to the network. This method allows for private transaction submission without broadcasting to the public mempool.

### Method
POST

### Endpoint
/rpc

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - Specifies the JSON-RPC protocol version, must be "2.0".
- **id** (integer) - Required - An identifier for the request.
- **method** (string) - Required - The name of the method to be invoked, must be "eth_sendPrivateTransaction".
- **params** (array) - Required - An array containing the parameters for the method.
  - **tx** (string) - Required - The signed raw transaction in hexadecimal format.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "eth_sendPrivateTransaction",
  "params": [
    {
      "tx": "0x12…ab"
    }
  ]
}
```

### Response
#### Success Response (200)
- **result** (integer) - The result of the operation, typically a transaction identifier or status code.
- **error** (object) - An error object if the request failed, otherwise null.
- **id** (integer) - The identifier for the response, matching the request id.

#### Response Example
```json
{
  "result": 200,
  "error": null,
  "id": 1
}
```

### Notes
- The `maxBlockNumber` parameter is not supported for this method.
```
Tokens:
Raw