Bundle Tracing

Bundle tracing allows searchers to understand bundle behavior after submission, and why bundles did or did not get included in blocks.

Bundle tracing will be delayed until at least 2 slots from the target block or maxTimestamp, and data will be available up to 24 hours after bundle submission.

When submitting a bundle, the response will include a bundle hash, which can be used to query your bundle status as follows. You must submit all bundle tracing queries to stats.quasar.win.

Request

curl -X POST https://stats.quasar.win \
  -H 'content-type: application/json' \
  -d '{
    "method": "quasar_getBundleStats",
    "params": [
      {
        "bundle_hash": "0x..123"
      }
    ],
    "jsonrpc": "2.0",
    "id": 1
  }'

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "status": "submitted",
    "builderPayment": "12934799399930",
    "error": null,
    "revertingHash": null,
    "receivedAt": 1753977388,
    "simulatedAt": 1753977388,
    "submittedAt": 1753977409,
    "blockNumber": 23040121,
    "targetBlock": 23040121,
    "minTimestamp": null,
    "maxTimestamp": null
  }
}

Bundle States

The flow of bundles through the system is as follows

Received
    |
    +---> Invalid
    |
    +---> SimulationFail
    |
    +---> SimulationPass
    |         |
    |         +---> ExcludedFromBlock
    |         |
    |         +---> IncludedInBlock
    |                   |
    |                   +---> Submitted
    |                             |
    |                             +---> Landed

---

• Received

  • Your bundle was received by the endpoint. If the bundle remains in this state, most likely the bundle was received too late into the block to be processed.

• Invalid

  • We were unable to parse your bundle. This indicates you need to troubleshoot your bundle formatting

• SimulationFail

  • If transactions revert that you have not listed in reverting or dropping hashes, the bundle will fail with this status. Another cause is when a bundle's value will not cover the refund payout. The response will list the specific error causing the simulation failure.

• SimulationPass

  • The bundle passed simulation, but was submitted too late to be considered for build inclusion.

• ExcludedFromBlock

  • Your bundle was successfully simulated, however, none of our block building algorithms chose it for inclusion in a block. This is typically because the value of the bundle, including priority fees wasn't enough to add to the block value.

• IncludedInBlock

  • Your bundle was included by at least one of our algorithms in a block it assembled, but it wasn't selected for submission to the relay. This is likely because another algorithm produced a more valuable block that excluded your bundle.

• Submitted

  • Your bundle was included in a block that was sent to relays, and may have landed on chain.

• Landed

  • Congratulations! Your bundle landed in the block on chain.