---
title: "WebSocket API Reference"
description: >-
  Searchers can connect to the server via WebSocket to reduce latency and subscribe to various events.
---

The WebSocket endpoint lives at `/v1/ws` (e.g wss://per-mainnet.dourolabs.app/v1/ws).

## General Format

Each request sent to the server via WebSocket should be in the following JSON format:

```json
{
  "id": "...", // used for uniquely identifying the response to this request
  "method": "...", // name of the server method to invoke
  "params": {...} // parameters necessary for the method
}
```

The server responds using the same **id** specified in the request:

```json
{
  "id": "...",
  "status": "success",
  "result": {}
}
```

In case of error, the **status** field will be **error**, and the error message will be available in the **result** field as a string:

```json
{
  "id": "...",
  "status": "error",
  "result": "..."
}
```

## Subscribing to Opportunities

To subscribe to opportunities, you can send a request using the **chain_ids** parameter, which specifies the chains as an array.

```json
{
  "id": "1",
  "method": "subscribe",
  "params": {
    "chain_ids": ["development-solana"]
  }
}
```

After a successful subscription, you will receive new opportunities for the selected chains via the WebSocket in the following format:

```json
{
  "type": "new_opportunity",
  "opportunity": {...}
}
```

The schema for the opportunity is similar to what's returned in the [HTTP requests](https://per-mainnet.dourolabs.app/docs#tag/opportunity/operation/get_opportunities).

To unsubscribe from a list of chains, you can send the following message:

```json
{
  "id": "1",
  "method": "unsubscribe",
  "params": {
    "chain_ids": ["development-solana"]
  }
}
```

## Submitting Bids

In addition to the HTTP methods, you can submit your bids via WebSocket in order to avoid additional network round trips and get notified about changes to your bid status.
Here is an example JSON payload for submitting a new bid:

```json
{
  "id": "1",
  "method": "post_bid",
  "params": {
    "bid": {
      "chain_id": "development-solana",
      "transaction": "SGVsbG8sIFdvcmxkIQ=="
    }
  }
}
```

A successful response to a bid submission has the following schema:

```json
{
  "id": "1", // WebSocket request id
  "status": "success",
  "result": {
    "id": "beedbeed-b346-4fa1-8fab-2541a9e1872d", // bid id
    "status": "OK"
  }
}
```

## Bid Status Updates

After submitting your bid via WebSocket, you will receive notifications about the bid status updates in JSON format.

<Tabs items={['pending', 'submitted', 'lost', 'won', 'failed', 'expired']}>
<Tab value="pending">

```json
// The temporary state which means the auction for this bid is pending.
// It will be updated to Lost or Submitted after the auction takes place.
{
  "type": "bid_status_update",
  "status": {
    "id": "beedbeed-0e42-400f-a8ef-d78aa5422252",
    "bid_status": {
      "type": "pending"
    }
  }
}
```

</Tab>
<Tab value="submitted">

```json
// The bid won the auction and was submitted to the chain, with the signature
// of the corresponding transaction provided in the result field.
// This state is temporary and will be updated to either Won or Failed after
// the transaction is included in a block, or Expired if the transaction expires.
{
  "type": "bid_status_update",
  "status": {
    "id": "beedbeed-0e42-400f-a8ef-d78aa5422252",
    "bid_status": {
      "type": "submitted",
      "result": "Jb2urXPyEh4xiBgzYvwEFe4q1iMxG1DNxWGGQg94AmKgqFTwLAiTiHrYiYxwHUB4DV8u5ahNEVtMMDm3sNSRdTg"
    }
  }
}
```

</Tab>
<Tab value="lost">

```json
// The bid did not win the auction and therefore was not submitted.
{
  "type": "bid_status_update",
  "status": {
    "id": "beedbeed-0e42-400f-a8ef-d78aa5422252",
    "bid_status": {
      "type": "lost"
    }
  }
}
```

</Tab>
<Tab value="won">
```json
// The final state which means the bid was submitted to the chain and successfully executed.
{
  "type": "bid_status_update",
  "status": {
    "id": "beedbeed-0e42-400f-a8ef-d78aa5422252",
    "bid_status": {
      "type": "won",
      "result": "Jb2urXPyEh4xiBgzYvwEFe4q1iMxG1DNxWGGQg94AmKgqFTwLAiTiHrYiYxwHUB4DV8u5ahNEVtMMDm3sNSRdTg"
    }
  }
}
```

</Tab>
<Tab value="failed">

```json
// The final state which means the bid was submitted to the chain but failed to execute.
{
  "type": "bid_status_update",
  "status": {
    "id": "beedbeed-0e42-400f-a8ef-d78aa5422252",
    "bid_status": {
      "type": "failed",
      "result": "Jb2urXPyEh4xiBgzYvwEFe4q1iMxG1DNxWGGQg94AmKgqFTwLAiTiHrYiYxwHUB4DV8u5ahNEVtMMDm3sNSRdTg"
    }
  }
}
```

</Tab>
<Tab value="expired">

```json
// The final state which means the bid was submitted to the chain but expired before execution.
{
  "type": "bid_status_update",
  "status": {
    "id": "beedbeed-0e42-400f-a8ef-d78aa5422252",
    "bid_status": {
      "type": "expired",
      "result": "Jb2urXPyEh4xiBgzYvwEFe4q1iMxG1DNxWGGQg94AmKgqFTwLAiTiHrYiYxwHUB4DV8u5ahNEVtMMDm3sNSRdTg"
    }
  }
}
```

</Tab>
</Tabs>

## Connection Persistence

The WebSocket server responds to ping messages according to WebSocket standards.

Additionally, the server periodically sends a ping message to the client to ensure the connection is still active and expects a pong in return.
