Searchers

Searchers receive live orderflow over WebSocket and submit bundles over the same connection or HTTP.

To request a searcher account, contact us at [e-mail].

Transport	Endpoint
WebSocket	wss://searcher.orderflow.ethgas.com/v1/{API_KEY}
HTTP	https://searcher.orderflow.ethgas.com/v1/{API_KEY}

Receive orderflow

Opening the WebSocket subscribes the session automatically. A client may also send the idempotent subscription request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_subscribe",
  "params": ["ethgas_partialPendingBundles"]
}

The params can also be mevblocker_partialPendingBundles or blink_partialPendingBundles for compatibility to other protocols.

Notifications contain an ordered array of decoded unsigned transactions. This abridged example omits some type-specific fee fields:

{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x...",
    "result": [{
      "chainId": "0x1",
      "to": "0x...",
      "value": "0x0",
      "data": "0x...",
      "nonce": "0x1",
      "gas": "0x5208",
      "type": "0x2",
      "hash": "0x...",
      "from": "0x..."
    }]
  }
}

Fanout is live-only: open the WebSocket before the originator submits. Missed notifications are not replayed.

If the result array contains only 1 object, it is a transaction only. If it contains more than 1 object, that is a bundle. You only need to reference the hash of the last transaction in your backrun bundle.

eth_unsubscribe is not supported. To stop receiving orderflow, close the WebSocket connection.

Submit a backrun

Use the last transaction hash from the notification as the first txs entry, followed by your signed transaction(s):

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "eth_sendBundle",
  "params": [{
    "txs": ["0x<ORIGINATOR_REFERENCE_HASH>", "0x<SIGNED_BACKRUN>"],
    "blockNumber": "0x12abcde",
    "replacementUuid": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
    "revertingTxHashes": [],
    "droppingTxHashes": []
  }]
}

The response returns a local bundleHash. The engine expands a valid originator reference server-side and adds the applicable refund fields before builder submission.

txs accepts 0–100 entries. An empty txs array is a cancellation by replacementUuid and behaves identically to eth_cancelBundle; in this case replacementUuid is required and no other field is permitted.

replacementUuid is optional for submission. When used, increase either replacementSeqNumber or its alias replacementNonce; do not send both.

minTimestamp is an optional unsigned Unix timestamp in seconds. It must not be later than the bundle's intake time; future values are rejected rather than queued.

Cancel replacements

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "eth_cancelBundle",
  "params": [{
    "replacementUuid": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee"
  }]
}

A successful intake response is 200; it confirms cancellation admission, not builder completion. An empty txs bundle with only replacementUuid is also a cancellation.

Connection behavior

Respond to pings promptly. Sessions close after 24 hours and should reconnect. Authorization changes close the connection, and slow readers may be disconnected when their outbound queue fills.