# Bundle Tracing

### Introduction

This feature aims to provide MEV searchers with in-depth insights into why their bundles were or were not included in blocks. This is an early version of the feature, and we welcome your feedback on additional data points you'd find useful.

> **Note**: The bundle trace will be ready approximately 5 minutes after your bundle has been sent. 
>
> Rate limit: 50 requests/sec.

### Using `titan_getBundleStats` Endpoint

To get the status of your bundle, use the `titan_getBundleStats` API endpoint. Below is an example request and response:

#### Example Request

```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
```

#### Example Response

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

### Understanding Bundle Statuses

The `status` field in the response can have multiple values, each of which provides specific information about the bundle:

1. **Received**: Your bundle was received by the RPC endpoint but arrived too late to be added to the pool.
2. **Invalid**: Your bundle could be invalid for various reasons. For example, invalid RLP encoding, incorrect block number, already mined nonces, incorrect Chain ID, etc... To troubleshoot, ensure that the transactions within the bundle can be simulated using an `estimateGas` call to your node, and that the block number is either greater than the current block or set to 0 (we will default it to the current block if set to 0).
3. **SimulationFail**: This status arises from one of two scenarios, both evaluated during top-of-block simulation:
   1. Transaction revert: One or more transactions, not listed in the reverting transaction hashes, reverted.
   2. Builder payment: The net builder payment, computed as the difference between the builder's balance post-bundle and pre-bundle, is less than or equal to zero.
4. **SimulationPass:** Your bundle passed top-of-block simulation but was not selected for inclusion. This could be due to:
   1. Bundle was sent too late to be considered for inclusion.
   2. Insufficient bribe: While our algorithms don't solely sort by bribe, they do aim to maximise total block value. In 95% of cases, increasing your bribe should solve the issue.
   3. Late submission: This is less likely but possible if the bundle is sent very late into the slot, e.g., around `prev_slot + 12s`.
5. **IncludedInBlock**: Your bundle was considered by at least one of our sorting algorithms but wasn't selected for submission to the relay. This is likely because another algorithm produced a more valuable block that excluded your bundle. `builderPaymentWhenIncluded` reflects the builder payment of your bundle inside the block it was included in.
6. **Submitted**: Your bundle was included in at least one block submitted to a relay. It's important to note here that this does not mean your bundle was submitted in the winning block, just that it was submitted at least once.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.titanbuilder.xyz/bundle-tracing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.