Merge pull request #3020 from pyth-network/add-express-relay-guides

feat(developer-hub): add how to guides for express relay

Author: nidhi-singh02

apps/developer-hub/content/docs/express-relay/how-to-guides/index.mdx

@@ -6,6 +6,13 @@ icon: Gavel
 full: true
 ---
 
+import { IntegrationCard } from "../../../src/components/IntegrationCard";
+import {
+  Files,
+  MagnifyingGlass,
+  Question,
+} from "@phosphor-icons/react/dist/ssr";
+
 # Introduction
 
 Express Relay is a priority auction which enables better orderflow mechanisms that eliminate [Maximal Extractable Value](https://www.ledger.com/academy/glossary/maximal-extractable-value-mev) (MEV).
@@ -25,23 +32,15 @@ To integrate with Express Relay, you can integrate as a protocol (to power token
     colorScheme="blue"
     title="Integrate as a Protocol"
     description="Power token swaps and recapture MEV with Express Relay integration"
-    icon={
-      <svg fill="none" stroke="currentColor" viewBox="0 0 24 24">
-        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" />
-      </svg>
-    }
+    icon={<Files size={16} />}
   />
 
   <IntegrationCard
     href="./integrate-as-searcher"
     colorScheme="green"
     title="Integrate as a Searcher"
     description="Access unified orderflow opportunities across DeFi protocols"
-    icon={
-      <svg fill="none" stroke="currentColor" viewBox="0 0 24 24">
-        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
-      </svg>
-    }
+    icon={<MagnifyingGlass size={16} />}
   />
 </div>
 
@@ -55,15 +54,6 @@ To learn more about Express Relay, refer to the following resources:
     colorScheme="purple"
     title="How Express Relay Works"
     description="Understand the mechanics behind Express Relay's priority auction system"
-    icon={
-      <svg fill="none" stroke="currentColor" viewBox="0 0 24 24">
-        <path
-          strokeLinecap="round"
-          strokeLinejoin="round"
-          strokeWidth={2}
-          d="M8.228 9c.549-1.165 2.03-2 3.772-2 2.21 0 4 1.343 4 3 0 1.4-1.278 2.575-3.006 2.907-.542.104-.994.54-.994 1.093m0 3h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"
-        />
-      </svg>
-    }
+    icon={<Question size={16} />}
   />
 </div>

apps/developer-hub/content/docs/express-relay/index.mdx

@@ -0,0 +1,83 @@
+---
+title: "Integrate as a Protocol"
+description: >-
+  Learn how frontends can integrate Express Relay to empower token swapping with better pricing and MEV recapture.
+---
+
+# How to Integrate Express Relay Swaps
+
+This guide will explain how frontends can integrate Express Relay to empower swapping.
+
+## Step 1: Install the Express Relay SDK
+
+Pyth provides a [Typescript SDK](https://www.npmjs.com/package/@pythnetwork/express-relay-js) to help developers integrate Express Relay into their frontends.
+
+You can install the SDK via npm or yarn. You can invoke the SDK client as below:
+
+```typescript
+import { Client } from "@pythnetwork/express-relay-js";
+
+const client = new Client(
+  { baseUrl: "https://per-mainnet.dourolabs.app" },
+  undefined, // Default WebSocket options
+);
+```
+
+## Step 2: Request a Quote
+
+You can request a quote by calling the [**getQuote**](https://github.com/pyth-network/per/blob/281de989db887aaf568fed39315a76acc16548fa/sdk/js/src/index.ts#L501-L506) SDK method.
+
+The example below shows how you can construct a quote request for a USDC → WSOL swap, with 100 USDC provided as input by the user:
+
+```typescript
+const userWallet = new PublicKey("<INPUT USER PUBKEY>");
+
+const quoteRequest = {
+  chainId: "solana",
+  inputTokenMint: new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"), // USDC mint
+  outputTokenMint: new PublicKey("So11111111111111111111111111111111111111112"), // WSOL mint
+  specifiedTokenAmount: {
+    side: "input",
+    amount: 100_000_000,
+  },
+  userWallet,
+};
+
+const quote = await client.getQuote(quoteRequest);
+```
+
+**quote** contains the full details, including the amount the searcher is quoting and the transaction that the user needs to sign. It also contains an **expirationTime**; after this time, the transaction will no longer succeed on chain, so you should request a new quote a few seconds before the **expirationTime**.
+
+## Step 3: Submit User Signature to the Express Relay Server
+
+Once you show the quote to the user, the user should sign the transaction if they wish to engage in the swap. The frontend can pass this signature along to the Express Relay server, which will handle aggregating all the required signatures for the transaction and submitting it to the RPC node.
+
+Below is an example showing how the frontend can submit the signed quote transaction to the server using the [**submitQuote**](https://github.com/pyth-network/per/blob/358eedc1f9072cdfc3418fba309697580f2474f9/sdk/js/src/index.ts#L537-L542) method. The response from the **getQuote** method includes a field called **referenceId**, which the frontend should use in its submission of the user signature.
+
+```typescript
+const submitQuote = {
+  chainId: "solana",
+  referenceId: quote.referenceId,
+  userSignature: signature,
+};
+
+const txSubmitted = await client.submitQuote(submitQuote);
+```
+
+**submitQuote** returns the fully signed transaction that the server submitted to the RPC node.
+
+## Additional Resources
+
+You may find these additional resources helpful for integrating Express Relay as a frontend.
+
+### Contract Addresses
+
+The [Contract Addresses](./contract-addresses) page lists the relevant addresses for Express Relay integration.
+
+### Error Codes
+
+The [Error Codes](./errors) page lists the error codes returned by Express Relay.
+
+### API Reference
+
+The [API Reference](https://per-mainnet.dourolabs.app/docs) provides detailed information on Express Relay APIs.

apps/developer-hub/content/docs/express-relay/integrate-as-protocol.mdx

@@ -0,0 +1,98 @@
+---
+title: "Integrate as a Searcher"
+description: >-
+  Integrate once and access all existing and future opportunities across integrated DeFi protocols through Express Relay's bidding system.
+---
+
+import { IntegrationCard } from "../../../../src/components/IntegrationCard";
+import { Code } from "@phosphor-icons/react/dist/ssr";
+
+# How to Integrate Express Relay as a Searcher
+
+Express Relay allows searchers to integrate once and access all existing and future opportunities across integrated DeFi protocols. Searchers **bid** on these opportunities exposed by Express Relay.
+
+Express Relay exposes different endpoints for interaction, which can be used directly via HTTP, WebSocket, or one of the SDKs for convenience.
+
+## What is a Searcher?
+
+Searchers are sophisticated actors who monitor blockchain networks for profitable opportunities such as arbitrage, liquidations, and MEV extraction. With Express Relay, searchers can:
+
+- **Access unified opportunities** across multiple integrated DeFi protocols
+- **Compete in fair auctions** for the right to fulfill user transactions
+- **Capture value** while providing better execution for users
+
+## Integration Methods
+
+Express Relay provides multiple ways for searchers to integrate:
+
+- **Direct API integration** using HTTP and WebSocket endpoints
+- **SDK integration** with [Typescript](https://github.com/pyth-network/per/tree/main/sdk/js) and [Python](https://github.com/pyth-network/per/tree/main/sdk/python) SDKs
+- **Real-time subscriptions** for opportunity monitoring
+
+## Integration Process
+
+Searchers can integrate with Express Relay in three key steps:
+
+### Step 1: Subscribe to New Opportunities
+
+Monitor opportunities across integrated DeFi protocols in real-time using Express Relay's WebSocket or HTTP endpoints. Opportunities include:
+
+- **Market orders** from integrated protocols requiring immediate execution
+- **Limit orders** on supported order book systems
+- **Liquidation opportunities** from lending and borrowing protocols
+- **Arbitrage opportunities** across different decentralized exchanges
+
+### Step 2: Construct and Submit Your Bid
+
+Analyze opportunities and construct competitive bids based on:
+
+- **Your execution strategy** and available capital
+- **Gas costs** and transaction efficiency considerations
+- **Expected profit margins** and risk assessment
+- **Competition** from other searchers in the auction
+
+Submit bids to Express Relay's auction system where the highest bidder wins the right to fulfill the opportunity.
+
+### Step 3: Execute Won Opportunities
+
+If your bid wins the auction, execute the opportunity by:
+
+- **Fulfilling the user's transaction** according to the opportunity parameters
+- **Capturing the bid amount** as compensation for providing the service
+- **Ensuring proper execution** to maintain reputation in the system
+
+## Supported Chains
+
+Searchers can currently integrate with Express Relay on **Solana Virtual Machine (SVM)** chains, with support for additional chains coming soon.
+
+## Getting Started
+
+Ready to integrate as a searcher? Start with our detailed integration guides:
+
+<div className="mt-8">
+  <IntegrationCard
+    href="./svm"
+    colorScheme="blue"
+    title="Integrate with Express Relay on SVM Chains"
+    description="Complete guide for integrating Express Relay on Solana Virtual Machine chains with code examples and best practices"
+    icon={<Code size={16} />}
+  />
+</div>
+
+## Additional Resources
+
+Explore these resources to enhance your searcher integration:
+
+### API Documentation
+
+- **[WebSocket API Reference](./websocket-api-reference)** - Real-time opportunity streaming
+- **[HTTP API Reference](./http-api-reference)** - REST endpoints for opportunities and bidding
+
+### Technical Resources
+
+- **[Contract Addresses](./contract-addresses)** - Smart contract addresses across supported chains
+- **[Error Codes](./errors)** - Complete list of error codes and troubleshooting guide
+
+### Understanding Express Relay
+
+- **[How Express Relay Works](./how-express-relay-works)** - Deep dive into the auction mechanism and architecture

apps/developer-hub/content/docs/express-relay/integrate-as-searcher/index.mdx

@@ -0,0 +1,4 @@
+{
+  "title": "Integrate as a Searcher",
+  "pages": ["svm"]
+}