WIP-searcher-guide-refactor

Author: aditya520

pages/express-relay/errors.mdx

@@ -1,6 +1,6 @@
 # Error Codes
 
-The following table lists the error codes and their explanations for ExpressRelay and OpportunityAdapter contracts.
+The following table lists the error codes and their explanations for [`ExpressRelay`](https://github.com/pyth-network/per/blob/main/contracts/src/express-relay/ExpressRelay.sol) and [`OpportunityAdapter`](https://github.com/pyth-network/per/blob/main/contracts/src/opportunity-adapter/OpportunityAdapter.sol) contracts.
 They can be used to identify the cause of a failed transaction or bid.
 
 ## ExpressRelay

pages/express-relay/websocket-api-reference.mdx

@@ -1,14 +1,17 @@
-# Websocket API Reference
+import { Tabs } from "nextra/components";
 
-You can connect to the server via websocket in order to reduce latency and subscribe to various events. The websocket endpoint relies at `/v1/ws`(e.g `wss://pyth-express-relay-mainnet.asymmetric.re/v1/ws`)
+# 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:
+Each request sent to the server via WebSocket should be in the following JSON format:
 
-```json
+```json copy
 {
-	"id": "...", // used for uniquely identifying the responses to requests
+	"id": "...", // used for uniquely identifying the response to this request
 	"method": "...", // name of the server method to invoke
 	"params": {...} // parameters necessary for the method
 }
@@ -24,7 +27,7 @@ The server responds using the same `id` specified in the request:
 }
 ```
 
-In case of error, `status` field will be `error` and the error message will be available in the `result` field as a string:
+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
 {
@@ -36,7 +39,7 @@ In case of error, `status` field will be `error` and the error message will be a
 
 ## Subscribing to opportunities
 
-To subscribe to opportunities you can send a request with the `chain_ids` parameter which specifies the chains as an array.
+To subscribe to opportunities, you can send a request using the `chain_ids` parameter, which specifies the chains as an array.
 
 ```json
 {
@@ -48,7 +51,7 @@ To subscribe to opportunities you can send a request with the `chain_ids` parame
 }
 ```
 
-After a successful subscription you will receive the new opportunities for the selected chains via the websocket in the following format:
+After a successful subscription, you will receive new opportunities for the selected chains via the WebSocket in the following format:
 
 ```json
 {
@@ -57,11 +60,11 @@ After a successful subscription you will receive the new opportunities for the s
 }
 ```
 
-The schema for the opportunity is similar to what’s returned in the [http requests](https://pyth-express-relay-mainnet.asymmetric.re/docs/#/liquidation/get_opportunities)
+The schema for the opportunity is similar to what’s returned in the [HTTP requests](https://pyth-express-relay-mainnet.asymmetric.re/redoc#tag/opportunity/operation/get_opportunities)
 
-In order to unsubscribe from a list of chains you can send the following message:
+To unsubscribe from a list of chains, you can send the following message:
 
-```json
+```json copy
 {
   "id": "1",
   "method": "unsubscribe",
@@ -73,9 +76,10 @@ In order to unsubscribe from a list of chains you can send the following message
 
 ## 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
+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
+```json copy
 {
   "id": "1",
   "method": "post_bid",
@@ -85,30 +89,33 @@ In addition to the http methods, you can submit your bids via websocket in order
       "calldata": "0xdeadbeef",
       "chain_id": "sepolia",
       "contract": "0xcA11bde05977b3631167028862bE2a173976CA11",
-      "permission_key": "0xdeadbeefcafe"
+      "permission_key": "0xcafebabe"
     }
   }
 }
 ```
 
-A successful response to bid submission has the following schema:
+A successful response to a bid submission has the following schema:
 
 ```json
 {
-  "id": "1", // websocket request id
+  "id": "1", // WebSocket request id
   "status": "success",
   "result": {
-    "id": "beedbeed-b346-4fa1-8fab-2541a9e1872d", //bid id
+    "id": "beedbeed-b346-4fa1-8fab-2541a9e1872d", // bid id
     "status": "OK"
   }
 }
 ```
 
-From this point you will receive notifications about the bid status updates in JSON format. We share four examples below, one for each of the status options (”pending”, “submitted”, “lost”, “won”):
+After submitting your bid via WebSocket, you will receive notifications about the bid status updates in JSON format. 
+Refer to the four examples below, one for each of the status options (`pending`, `submitted`, `lost`, `won`):
 
+<Tabs items={[`pending`, `submitted`, `lost`, `won`]}>
+<Tabs.Tab>
 ```json
 // pending
-// The temporary state which means the auction for this bid is pending
+// The temporary state, which means the auction for this bid is pending
 {
 	"type": "bid_status_update",
 	"status": {
@@ -118,10 +125,13 @@ From this point you will receive notifications about the bid status updates in J
 		}
 	}
 }
-
+```
+</Tabs.Tab>
+<Tabs.Tab>
+```json
 // submitted
 // The bid is submitted to the chain, which is placed at the given index of the transaction with the given hash
-// This state is temporary and will be updated to either lost or won after conclusion of the auction
+// This state is temporary and will be updated to either lost or won after the conclusion of the auction
 {
 	"type": "bid_status_update",
 	"status": {
@@ -136,7 +146,10 @@ From this point you will receive notifications about the bid status updates in J
 		}
 	}
 }
-
+```
+</Tabs.Tab>
+<Tabs.Tab>
+```json
 // lost
 // The bid lost the auction, which is concluded with the transaction with the given hash and index
 // The result will be None if the auction was concluded off-chain and no auction was submitted to the chain
@@ -153,7 +166,10 @@ From this point you will receive notifications about the bid status updates in J
 		}
 	}
 }
-
+```
+</Tabs.Tab>
+<Tabs.Tab>
+```json
 // won
 // The bid won the auction, which is concluded with the transaction with the given hash and index
 {
@@ -171,9 +187,11 @@ From this point you will receive notifications about the bid status updates in J
 	}
 }
 ```
+</Tabs.Tab>
+</Tabs>
 
 ## Connection Persistence
 
-The websocket server responds to ping messages according to websocket standards.
+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.