Add websocket support to sdk for real-time transaction status updates

demo/components/providers/RelayKitProviderWrapper.tsx

@@ -1,4 +1,9 @@
-import { LogLevel, RelayChain } from '@reservoir0x/relay-sdk'
+import {
+  createClient,
+  LogLevel,
+  MAINNET_RELAY_WS,
+  RelayChain
+} from '@reservoir0x/relay-sdk'
 import { RelayKitProvider } from '@reservoir0x/relay-kit-ui'
 import { useTheme } from 'next-themes'
 import { FC, ReactNode } from 'react'
@@ -9,6 +14,7 @@ export const RelayKitProviderWrapper: FC<{
   children: ReactNode
 }> = ({ relayApi, dynamicChains, children }) => {
   const { theme } = useTheme()
+
   return (
     <RelayKitProvider
       options={{
@@ -25,7 +31,11 @@ export const RelayKitProviderWrapper: FC<{
         useGasFeeEstimations: true,
         pollingInterval: 1000,
         confirmationPollingInterval: 1000,
-        themeScheme: theme === 'dark' ? 'dark' : 'light'
+        themeScheme: theme === 'dark' ? 'dark' : 'light',
+        websocket: {
+          enabled: true,
+          url: MAINNET_RELAY_WS
+        }
       }}
     >
       {children}

packages/sdk/src/actions/execute.test.ts

@@ -34,7 +34,7 @@ let executeStepsSpy = vi
       return Promise.resolve(clonedQuote)
     }
   )
-vi.mock('../utils/executeSteps.js', () => {
+vi.mock('../utils/executeSteps/index.js', () => {
   return {
     executeSteps: (...args: any[]) => {
       return executeStepsSpy(...args)

packages/sdk/src/client.ts

@@ -12,14 +12,25 @@ import type { RelayChain } from './types/index.js'
 import { LogLevel, log as logUtil } from './utils/logger.js'
 import * as actions from './actions/index.js'
 import * as utils from './utils/index.js'
-import { MAINNET_RELAY_API } from './constants/servers.js'
+import { MAINNET_RELAY_API, MAINNET_RELAY_WS } from './constants/servers.js'
 import { SDK_VERSION } from './version.js'
 
 /**
  * RelayClient Configuration Options
- * @param source Used to manually override the source domain used to attribute local orders
- * @param logLevel Log level from 0-4, the higher the more verbose.
- * @param maxPollingAttemptsBeforeTimeout The maximum number of attempts the synced api is polled before timing out. The api is polled every 5 secs (default is 30)
+ *
+ * @property {string} [baseApiUrl] - The base URL for the Relay API. Defaults to the mainnet API if not provided.
+ * @property {string} [source] - The source to associate your onchain activity with, should be a domain.
+ * @property {LogLevel} [logLevel] - Log level from 0-4, the higher the more verbose. Defaults to LogLevel.None.
+ * @property {number} [pollingInterval] - Interval (in ms) for polling the API for status updates.
+ * @property {number} [maxPollingAttemptsBeforeTimeout] - The maximum number of polling attempts before timing out. The API is polled every 5 seconds by default (default is 30 attempts).
+ * @property {RelayChain[]} [chains] - List of supported chains. If not provided, defaults to all mainnet/testnet chains based on the API URL.
+ * @property {boolean} [useGasFeeEstimations] - Whether to use gas fee estimations. Defaults to true.
+ * @property {string} [uiVersion] - Optional UI version string for analytics/debugging.
+ * @property {(message: Parameters<typeof logUtil>[0], level: LogLevel) => void} [logger] - Custom logger function. If not provided, uses the default logger.
+ * @property {number} [confirmationPollingInterval] - Interval (in ms) for polling transaction confirmations.
+ * @property {Object} [websocket] - Websocket configuration options.
+ * @property {boolean} [websocket.enabled] - Whether to enable websocket support. Defaults to false.
+ * @property {string} [websocket.url] - Custom websocket URL. If not provided, falls back to the default.
  */
 export type RelayClientOptions = {
   baseApiUrl?: string
@@ -32,6 +43,10 @@ export type RelayClientOptions = {
   uiVersion?: string
   logger?: (message: Parameters<typeof logUtil>['0'], level: LogLevel) => void
   confirmationPollingInterval?: number
+  websocket?: {
+    enabled?: boolean
+    url?: string
+  }
 }
 
 let _client: RelayClient
@@ -58,6 +73,8 @@ export class RelayClient {
   maxPollingAttemptsBeforeTimeout?: number
   useGasFeeEstimations: boolean
   chains: RelayChain[]
+  websocketEnabled: boolean
+  websocketUrl: string
   log(
     message: Parameters<typeof logUtil>['0'],
     level: LogLevel = LogLevel.Info
@@ -78,6 +95,8 @@ export class RelayClient {
     this.maxPollingAttemptsBeforeTimeout =
       options.maxPollingAttemptsBeforeTimeout
     this.useGasFeeEstimations = options.useGasFeeEstimations ?? true
+    this.websocketEnabled = options.websocket?.enabled ?? false
+    this.websocketUrl = options.websocket?.url ?? MAINNET_RELAY_WS
     if (options.chains) {
       this.chains = options.chains
     } else if (options.baseApiUrl?.includes('testnets')) {
@@ -121,6 +140,11 @@ export class RelayClient {
       options.useGasFeeEstimations !== undefined
         ? options.useGasFeeEstimations
         : this.useGasFeeEstimations
+    this.websocketEnabled =
+      options.websocket?.enabled !== undefined
+        ? options.websocket.enabled
+        : this.websocketEnabled
+    this.websocketUrl = options.websocket?.url || this.websocketUrl
 
     if (options.logger) {
       this.log = options.logger

packages/sdk/src/constants/servers.ts

@@ -1,3 +1,7 @@
 export const MAINNET_RELAY_API = 'https://api.relay.link'
 export const TESTNET_RELAY_API = 'https://api.testnets.relay.link'
 export const ASSETS_RELAY_API = 'https://assets.relay.link'
+
+// WebSocket endpoints
+export const MAINNET_RELAY_WS = 'wss://ws.relay.link'
+export const DEV_RELAY_WS = 'wss://ws.dev.relay.link'

packages/sdk/src/routes/index.ts

@@ -17,6 +17,7 @@ export const routes = [
   "/lives",
   "/intents/status",
   "/intents/status/v2",
+  "/intents/status/v3",
   "/intents/quote",
   "/intents/quote/v2",
   "/requests/{requestId}/signature",

packages/sdk/src/types/Execute.ts

@@ -57,6 +57,7 @@ export type Execute = {
         | 'waiting'
         | 'failure'
         | 'pending'
+        | 'submitted'
         | 'success'
         | 'unknown'
       progressState?: TransactionStepState | SignatureStepState

packages/sdk/src/types/SignatureStepItem.ts

@@ -2,7 +2,15 @@ import type { Execute } from './Execute.js'
 
 export type SignatureStepItem = Pick<
   NonNullable<Execute['steps'][0]['items']>[0],
-  'status' | 'orderIds' | 'orderIndexes' | 'orderData'
+  | 'status'
+  | 'orderIds'
+  | 'orderIndexes'
+  | 'orderData'
+  | 'progressState'
+  | 'txHashes'
+  | 'internalTxHashes'
+  | 'check'
+  | 'isValidatingSignature'
 > & {
   data?: {
     sign?: {

packages/sdk/src/types/TransactionStepItem.ts

@@ -2,9 +2,19 @@ import type { Execute } from './Execute.js'
 
 export type TransactionStepItem = Pick<
   NonNullable<Execute['steps'][0]['items']>[0],
-  'status' | 'orderIds' | 'orderIndexes' | 'orderData' | 'check'
+  | 'status'
+  | 'orderIds'
+  | 'orderIndexes'
+  | 'orderData'
+  | 'check'
+  | 'progressState'
+  | 'txHashes'
+  | 'internalTxHashes'
+  | 'receipt'
+  | 'checkStatus'
 > & {
   data: {
+    chainId?: number
     data: any
     from: `0x${string}`
     to: `0x${string}`

packages/sdk/src/types/api.ts

@@ -2428,6 +2428,11 @@ export interface paths {
              * @enum {string}
              */
             protocolVersion?: "v1" | "v2" | "preferV2";
+            /**
+             * @description Enable this to avoid direct transfers to the depository (only relevant for EVM and v2 protocol flow)
+             * @default true
+             */
+            explicitDeposit?: boolean;
             /** @description Enable this to use canonical+ bridging, trading speed for more liquidity */
             useExternalLiquidity?: boolean;
             /** @description Enable this for specific fallback routes */
@@ -2448,6 +2453,10 @@ export interface paths {
             gasLimitForDepositSpecifiedTxs?: number;
             /** @description Force executing swap requests via the solver (by default, same-chain swap requests are self-executed) */
             forceSolverExecution?: boolean;
+            /** @description If the sponsor should pay for the fees associated with the request. Includes gas topup amounts. */
+            subsidizeFees?: boolean;
+            /** @description The max subsidization amount in USD decimal format, e.g 100000 = $1. subsidizeFees must be enabled. This amount is the threshhold where if its surpassed the entire request will not be subsidized at all. */
+            maxSubsidizationAmount?: string;
             /** @description Swap sources to include for swap routing. */
             includedSwapSources?: string[];
             /** @description Swap sources to exclude for swap routing. */
@@ -3388,6 +3397,36 @@ export interface paths {
       };
     };
   };
+  "/intents/status/v3": {
+    get: {
+      parameters: {
+        query?: {
+          /** @description A unique id representing the execution in the Relay system. You can obtain this id from the requests api or the check object within the step items. */
+          requestId?: string;
+        };
+      };
+      responses: {
+        /** @description Default Response */
+        200: {
+          content: {
+            "application/json": {
+              /** @enum {string} */
+              status?: "refund" | "delayed" | "waiting" | "failure" | "pending" | "submitted" | "success";
+              details?: string;
+              /** @description Incoming transaction hashes */
+              inTxHashes?: string[];
+              /** @description Outgoing transaction hashes */
+              txHashes?: string[];
+              /** @description The last timestamp the data was updated */
+              updatedAt?: number;
+              originChainId?: number;
+              destinationChainId?: number;
+            };
+          };
+        };
+      };
+    };
+  };
   "/intents/quote": {
     post: {
       requestBody: {
@@ -4030,6 +4069,7 @@ export interface paths {
                     appFees?: {
                         recipient?: string;
                         amount?: string;
+                        amountUsd?: string;
                       }[];
                     metadata?: {
                       sender?: string;