WebSocket API Reference

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://pyth-express-relay-mainnet.asymmetric.re/v1/ws).

General format

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

{
	"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:

{
  "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:

{
  "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.

{
  "id": "1",
  "method": "subscribe",
  "params": {
    "chain_ids": ["op_sepolia"]
  }
}

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

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

The schema for the opportunity is similar to what’s returned in the HTTP requests (opens in a new tab)

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

{
  "id": "1",
  "method": "unsubscribe",
  "params": {
    "chain_ids": ["op_sepolia"]
  }
}

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:

{
  "id": "1",
  "method": "post_bid",
  "params": {
    "bid": {
      "amount": "10",
      "calldata": "0xdeadbeef",
      "chain_id": "op_sepolia",
      "contract": "0xcA11bde05977b3631167028862bE2a173976CA11",
      "permission_key": "0xcafebabe"
    }
  }
}

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

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

After submitting your bid via WebSocket, you will receive notifications about the bid status updates in JSON format. Refer to the examples below, one for each of the status options in EVM and SVM:

// pending
// The temporary state, which means the auction for this bid is pending
{
	"type": "bid_status_update",
	"status": {
		"id": "beedbeed-0e42-400f-a8ef-d78aa5422252",
		"bid_status": {
			"type": "pending"
		}
	}
}

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.