> For the complete documentation index, see [llms.txt](https://docs.kolibrio.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kolibrio.xyz/searchers/base-kolibrio-ofa-searcher-connection.md).

# Base Kolibrio OFA Searcher Connection

##

**Summary:** The interface is fully compatible with MEV Blocker. Connect to the WebSocket, include the `X-Bev-Signature` header, subscribe to partial pending transactions, and receive notifications via JSON-RPC. Construct your backrun bundle from the incoming signals and submit it using `eth_sendBundle`.

### Important behavioral difference vs ETH stream

BASE’s stream not only hides the transaction signature, it also *masks the gas fields in the transaction payload* (fakes gas-related values). When a searcher wins a bid, they will receive the same transaction notification again — but with the **real** gas values.

This means you must treat duplicate notifications for the same transaction hash as *authoritative updates*, and you must update/correct your gas-price estimates for any pending bids based on the later message that contains the real gas info. Failing to do so will cause your bundle bids to be priced incorrectly.

**BASE Auction Time:** 250ms

### Endpoint

`wss://bev-relay.kolibr.io/base`

**Required HTTP header** when establishing the WebSocket session:

`X-Bev-Signature: <signature>`

> The X-Bev-Signature header is used for authentication/authorization. The signature format and keys are provided by the Kolibrio team.

***

### Subscription

After a successful connection, send the following JSON‑RPC request to subscribe:

```jsx
{"method": "eth_subscribe","params": ["mevblocker_partialPendingTransactions"]}
```

**Expected response:**

```jsx
{"jsonrpc": "2.0", "id": 1, "result": "0xd58bbbc0f5190962eff01b6f0ec17724"}
```

After this, you’ll start receiving `eth_subscription` notifications when new relevant transactions appear.

***

### Incoming Signal Format

Example notification:

```jsx
{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x6e...",
    "result": {
      "hash": "0xb3406...",
      "chainId": "0x2105",
      "type": "0x2",
      "from": "0x192...",
      "to": "0x4...
      "value": "0x5af3107a4000",
      "data": "0xffff",
      "nonce": "0x0",
      "gas": "0x5208",
      "maxPriorityFeePerGas": "0xf4240",
      "maxFeePerGas": "0x26643aa",
      "accessList": []
    },
    "revshareAddress": "0x90000...."
  }
}
```

**Note:** The bacrkun bid should be sent to in WETH or ETH to revshareAddress\
**Note:** All numeric fields are hex‑encoded.

***

## 🧩 Two-Phase Gas Revelation

Kolibrio implements a **two-phase gas revelation** mechanism to ensure fair bidding behavior across searchers.

When a transaction first appears in the Kolibrio stream, its gas parameters are intentionally **masked**.\
Only after a valid bid is submitted - the **real gas values** be revealed.

This process happens in two distinct phases:

### Phase 1 — Initial Signal *(Fake Gas)*

You’ll receive an early notification containing **placeholder (fake)** gas values.

**Example:**

```json
{
  "hash": "0xabc...",
  "maxFeePerGas": "0x5f5e100",  // FAKE (e.g. 100 gwei)
  "maxPriorityFeePerGas": "0x3b9aca00",
  "revshareAddress": "0x90000...."
}
```

At this stage:

* Treat the message as a *signal*.
* Submit your **initial bundle** using the placeholder gas with WETH  or ETH transfer to *revshareAddress* from signal
* Record the transaction hash for later update.

### Phase 2 — Real Gas *(After Valid Bid)*

If your initial bid is **valid and wins the action**, Kolibrio will resend the **same transaction hash**.\
This time, the payload will include the **real gas parameters**.

**Example:**

```json
{
  "hash": "0xabc...",
  "maxFeePerGas": "0x26643aa",  // REAL (e.g. 40 gwei)
  "maxPriorityFeePerGas": "0x1dcd6500", 
  "revshareAddress": "0x90000...."
}
```

At this stage:

* Replace the placeholder gas data with the real one.
* Resubmit a **final bundle** with correctly priced gas.

***

### Sending a Bundle

Once you’ve built your signed backrun transaction, send it as a bundle via the same WebSocket or simple HTTP POST request:

```jsx
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_sendBundle",
  "params": [
    {
      "txs": [
        "0x02abcd...", // target transaction hash (32 bytes)
        "0x02abcd..." // your signed bacrkun raw transaction
        ...
      ]
    }
  ]
}
```

***

### Best Practices & Constraints

* Send your bid/payment to the provided revshareAddress
* Treat the target transaction `hash` as a 32‑byte hex string (with `0x` prefix).
* Both transaction hashes and raw signed transactions are accepted in `txs`.
* The order of `txs` matters: target transaction first, followed by your backrun txs.

***

### Example Flow

1. Open WS connection → `wss://bev-relay.kolibr.io/base` with `X-Bev-Signature`.
2. Send `eth_subscribe` to `mevblocker_partialPendingTransactions`.
3. Receive `eth_subscription` messages with `result` with fake gas
4. Process and build your backrun transaction with WETH  or ETH transfer to `revshareAddress`. Send `eth_sendBundle` containing the target hash and your signed transaction.
5. In 0-250ms - Receive `eth_subscription` messages with `result` with real gas
6. Process and build your backrun transaction with WETH  or ETH transfer to `revshareAddress`. Send `eth_sendBundle` containing the target hash and your signed transaction.

***

### Security Notes

* Keep your signing keys and `X-Bev-Signature` secrets secure.