EVM Searcher Integration

Subscribe to New Opportunities

Express Relay provides searchers with Typescript (opens in a new tab) and Python (opens in a new tab) SDKs to interact with Express Relay. Searchers can also directly fetch available opportunities via HTTP or subscribe to them via WebSocket.

Pyth provides a Typescript SDK, which allows searchers to subscribe to opportunities:

import { Client, Opportunity } from "@pythnetwork/express-relay-js";
 
const handleOpportunity = async (opportunity: Opportunity) => {
  // Implement your opportunity handler here
};
 
const client = new Client(
  { baseUrl: "https://pyth-express-relay-mainnet.asymmetric.re" },
  undefined, // Default WebSocket options
  handleOpportunity
);
await client.subscribeChains(["op_sepolia"]);

The server responds with opportunities in the following format:

{
  "target_calldata": "0xdeadbeef",                                      // Calldata to execute the opportunity
  "chain_id": "op_sepolia",
  "target_contract": "0xcA11bde05977b3631167028862bE2a173976CA11",      // Protocol contract address to call
  "permission_key": "0xcafebabe",                                       // Unique identifier for the opportunity
  "target_call_value": "1",                                             // Value (in Wei) to send to the protocol contract.
  "sell_tokens": [                                                      // Tokens the protocol expects to receive
    {
      "amount": "900",
      "token": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599"
    }
  ],
  "buy_tokens": [                                                       // Tokens the protocol will send in return
    {
      "amount": "1000",
      "token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
    }
  ],
  "version": "v1"                                                       // Opportunity format version
}

Construct the Bid

Searchers should construct a bid by evaluating the fetched opportunity. The SDKs provide an easy way to construct a bid using the OpportunityAdapter (opens in a new tab) contract. The OpportunityAdapter contract handles asset transfers and ensures the opportunity is executed correctly.

⚠️

Before constructing the bid, make sure your wallet has the required assets and has made the necessary approvals. Refer to the Prepare assets for Opportunity Adapter section for more details.

Here is an example of how to construct a bid object using OpportunityAdapter via the SDKs:

const handleOpportunity = async (opportunity: Opportunity) => {
    const nonce = BigInt(Math.floor(Math.random() * 2 ** 50));
    const privateKey = `0x0000`; // Private key of the searcher
    const bidAmount = BigInt(1000); // The bidAmount should be determined based on opportunity
    const deadline = BigInt(Math.round(Date.now() / 1000 + 60)) // Bid is valid for a minute
    const bid = await client.signBid(opportunity, {bidAmount, nonce, deadline}, privateKey)
}

If you prefer to use your custom contracts instead of the OpportunityAdapter, please refer to the custom contracts section.

Submit Bids on Opportunities to Express Relay

Searchers can submit the constructed bids to Express Relay via the SDKs, an HTTP POST request, or a WebSocket connection.

The code snippet below demonstrates how to submit a bid using the Typescript SDK:

const handleOpportunity = async (opportunity: Opportunity) => {
    ...
    const bid = await client.signBid(opportunity, {amount, nonce, deadline}, privateKey)
    await client.submitBid(bid)
}

Last updated on March 4, 2025