# 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.


---

# 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.kolibrio.xyz/searchers/base-kolibrio-ofa-searcher-connection.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.