# Solana Kolibrio OFA Searcher Connection

**GRPC Latest protofile:**

{% file src="/files/VGi8Ejf8OAmOia89qZpp" %}

**Current gRPC connection URL:** <https://searcher.kolibr.io> (requires *authorization* header in metadata)

**Current WS connection URL:**  wss\://solana.kolibr.io/ws (requires *x-api-key* header)

For the connection, a searcher requires an ApiKey that can be retrieved from the Kolibrio team<br>

***

**Glossary:**\
**OFA** - *order flow auction*\
**Originator** - *entity that produces a transaction*\
**Signal** - *originator’s transaction with metadata*\
**Jito** - <https://www.jito.wtf/>\
**Jito Backrun** *- transaction bundle that consists of 1 to 3 transactions and follows the following rules:*

* *Transaction order is guaranteed*
* *Every transaction in a bundle simulates on top of the previous one*
* *If one of the transactions reverts, the whole bundle will not be mined*

**Priority Backrun** - a set of transactions with a [priority fee](https://solana.com/developers/guides/advanced/how-to-use-priority-fees). Order is not guaranteed, but most likely they will be sorted by Fee. No revert protection. Faster inclusion

***

**Workflow:**\
After the connection establishment and stream subscription, searchers will start to receive signals\
Each signal consists of the following fields:

```
{
"id": string,
"revshare_address": string,
"message": []byte,
"priority_revshare_address": string,
}
```

| **id**                          | unique identification of the target transaction. The searcher should pass it back to bind backrun transactions to the target transaction.       |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **message**                     | bytes array that represents [Solana Transaction Message](https://github.com/anza-xyz/agave/blob/v2.1.13/sdk/program/src/message/legacy.rs#L131) |
| **revshare\_address**           | solana address where searcher should do transfer as bribe in jito backrun transaction                                                           |
| **priority\_revshare\_address** | solana address where searcher should do transfer as bribe in priority backrun transaction                                                       |

To submit a result, a searcher needs to send a message in a following format:

```
{
      "id": string,
      "jito_backrun": [][]byte,
      "priority_backrun": [][]byte,
      "expected_bid_lamports": int64,
}
```

| **id**                | unique identification of the target transaction. Refer to the id from the signal.                                                                                                                                                                                                    |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **jito\_backrun**     | <p>array of fully signed backrun transactions in bytes for Jito bundle and transfer to <strong>revshare\_address</strong><br><br><em>this transactios will be sent in jito bundle with target signal</em></p>                                                                        |
| **priority\_backrun** | <p>array of fully signed backrun transactions in bytes for sending with the fastest inclusion and transfer to <strong>priority\_revshare\_address</strong><br><br><em>this transactios will be sent in via fastest swqos & paladin connection.</em><br><em>learn more below</em></p> |

**⚠️NOTE: For a bid to be valid, the searcher transaction MUST include a separate transfer instruction to the revshare\_address or priority\_revshare\_address.**<br>

***

WS example:

```
  const conn = new WebSocket("wss://solana.kolibr.io/ws", {
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': apiKey, //ApiKey
    },
    perMessageDeflate: true,
  });

  conn.on('open', async (ws) => {
    console.log('connected')
  });

  conn.on('message', async (wsMsg) => {
    const signal = JSON.parse(wsMsg);
    const jitoBackrun = doSearcherMagic(signal);
    const priorityBackrun = doSearcherMagic(signal);
    const expectedBidLamports = doSearcherMagic(signal);
    
    const result = {
      id: opportunitySignal.id,
      jito_backrun: [[...jitoBackrun]],
      priority_backrun: [[...priorityBackrun]],
      expected_bid_lamports: expectedBidLamports
    }

    conn.send(JSON.stringify(result));
  })

  conn.on('ping', () => {
    conn.pong()
  })
```

GRPC example:

{% file src="/files/CPguLE08hOYvWFp70bPK" %}

***

**⚡ Priority Backruns**

Due to Solana’s high-throughput architecture and the varying broadcast requirements of different originators, there are edge cases where the **Kolibrio target signal** reaches the block leader *before* the full atomic Kolibrio bundle (i.e., the original transaction + arbitrage).

If this happens, and the signal gets included in a block *without* the associated arbitrage backrun, the arbitrage opportunity remains live on-chain. In such cases, the first random searcher to detect the transaction in the shred stream can still capture the value.

To handle these edge cases, Kolibrio introduces fallback auctions via Priority Backruns — a fast, parallel execution path for high-value recovery, which gives a clear **advantage to Kolibrio participants over regular shred-stream searchers**.

**🛠 How it Works**

* **Optional fallback**: In addition to the standard `jito_backrun`, searchers can include a `priority_backrun` — a high-speed backup arbitrage path.
* **Requirements** for a *priority\_backrun*:
  * Should include a **priority fee**.
  * Must send a tip to a **priority\_revshare\_address** defined by the originator.
* **Execution mechanics**:
  * Priority backruns are **broadcast via SWQoS and Paladin** low-latency channels with **\~2 ms artificial delays between each**, based on **Kolibrio Tip** — higher tips are sent earlier (resulting in \~5–10 index positions between broadcasts).
  * **Kolibrio will only broadcast priority\_backruns if**:
    * The target signal was created by a high-quality originator (e.g., trusted dApp, not a spam bot).
    * There is a credible probability that the signal will land *non-atomically* (i.e., without its associated arbitrage bundle).
* **Risk/Reward trade-off**:
  * priority\_backrun transactions may revert if the arbitrage is already handled in the original atomic bundle.
  * However, they give searchers a **chance to catch leftover MEV** faster than public shred-stream observers.

**📦 How to Land a Priority Backrun**

To land a priority backrun, your goal is to get as close as possible to the original signal in block position.

You need to balance:

* 🧾 **Priority Fee** — affects your on-chain placement.
* 💸 **Kolibrio Tip** — determines the **broadcast order** via SWQoS.

Kolibrio broadcasts selected backruns using **SWQoS + Paladin**, with \~2 ms artificial delays (resulting in \~5–10 index positions between each).

> ⚠️ A low priority fee can place you too far below the target, even if your Kolibrio Tip is high. Your goal is to land close — tune precisely for maximum impact.

***

**Multiregion:**

Kolibrio's main engine is located in Amsterdam, but there are also endpoints in other regions.

If a user transaction is created outside the EU, it will still be forwarded to the main server in Amsterdam — and if you're connected only to it, you'll receive it. However, a small percentage of transactions might appear slightly faster on another regional endpoint.

**Recommendation:** Use the Amsterdam main server for both listening to the stream and submitting transactions, but also monitor other regional endpoints to gain a small timing advantage.

| **Region**     | **GRPC URL**                       | **WS URL**                       |
| -------------- | ---------------------------------- | -------------------------------- |
| Amsterdam Main | <https://searcher.kolibr.io>       | wss\://solana.kolibr.io/ws       |
| Tokyo          | <https://tokyo-searcher.kolibr.io> | wss\://tokyo-solana.kolibr.io/ws |
| Salt Lake City | <https://slc-searcher.kolibr.io>   | wss\://slc-solana.kolibr.io/ws   |
| New York       | <https://ny-searcher.kolibr.io/>   | wss\://ny-solana.kolibr.io/ws    |
| Frankfurt      | <https://fra-searcher.kolibr.io/>  | wss\://fra-solana.kolibr.io/ws   |

***

### ⚠️ Main Rule: **NO FORM OF FRONTRUNNING IS ALLOWED.**

*Kolibrio system continuously monitors searchers behavior and runs analytics on top of target signal transactions. if any malicious behavior such as non atomic frontruns will be discovered - searcher will receive forever ban.*


---

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