Skip to main content
This page summarizes the supported third-party integration API for @deloraprotocol/widget. Most integrations center on the trading widget surface:
  • TradeWidget
  • TradeWidgetWalletProvider
  • useTradeWidgetWalletManagement
The package also exports a smaller MyWidget demo component and shared theming props.

​
Main exports

Components and hooks:
  • MyWidget
  • TradeWidget
  • TradeWidgetWalletProvider
  • useTradeWidgetWalletManagement
Shared widget props and theme types:
  • MyWidgetProps
  • MyWidgetTheme
  • MyWidgetVars
Trade widget types:
  • TradeWidgetProps
  • TradeWidgetConfig
  • TradeWidgetRpcUrlsByChainId
  • WalletNamespace
  • TradeWidgetStatus
  • TradeWidgetFilters
  • TradeWidgetSideFilters
  • TradeWidgetTokenSelection
  • TradeWidgetQuotePayload
  • TradeWidgetActionPayload
  • TradeWidgetConnectPayload
  • TradeWidgetTransactionPayload
  • TradeWidgetErrorPayload
  • Token
  • Network
Wallet-management and provider types:
  • TradeWidgetManagedWallet
  • TradeWidgetManagedWalletConnectParams
  • TradeWidgetWalletManagement
  • TradeWidgetWalletProviderProps
  • Eip1193Provider
  • KnownWalletOptionId
  • SolanaInjectedProvider
  • SolanaProvider
  • WalletConnectionStatus
  • WalletOptionDescriptor
  • WalletOptionId
  • WalletOptionType
  • WalletVisualId
  • WalletStandardSolanaAccount
  • WalletStandardSolanaProvider

​
MyWidget and MyWidgetProps

MyWidget is a minimal example export that shares the same root theming surface as TradeWidget. If you are embedding the production trade experience, use TradeWidget. If you need the lightweight demo component that ships with the package, use MyWidget. MyWidgetProps extends normal root div props.
PropTypeDescription
theme"light" | "dark"Built-in theme. Default: "light"
varsPartial<MyWidgetVars>Theme token overrides
classNamestringApplied to the widget root element
styleReact.CSSPropertiesInline root styles applied after generated CSS variables

​
TradeWidgetProps

TradeWidgetProps extends normal root div props, except the DOM onError prop is replaced by the widget error callback.
PropTypeDescription
configTradeWidgetConfigRequired widget runtime config object
filtersTradeWidgetFiltersOptional sell-side and buy-side filtering rules
theme"light" | "dark"Built-in theme. Default: "dark"
varsPartial<MyWidgetVars>Theme token overrides
classNamestringApplied to the widget root element
styleReact.CSSPropertiesInline root styles applied after generated CSS variables
initialSellTokenTradeWidgetTokenSelectionPreselect sell token
initialBuyTokenTradeWidgetTokenSelectionPreselect buy token
initialSellNetworkIdnumberPreselect sell network
initialBuyNetworkIdnumberPreselect buy network
lockSellTokenbooleanPrevent changing the sell token
lockBuyTokenbooleanPrevent changing the buy token
lockSellNetworkbooleanPrevent changing the sell network
lockBuyNetworkbooleanPrevent changing the buy network
onQuote(payload) => voidQuote resolved callback
onConnect(payload) => voidWallet connected callback
onApprove(payload) => voidApproval transaction submitted callback
onSwap(payload) => voidSwap transaction submitted callback
onTxSubmitted(payload) => voidGeneric transaction submitted callback
onTxConfirmed(payload) => voidGeneric transaction confirmed callback
onError(payload) => voidError callback

​
TradeWidgetConfig

FieldTypeDescription
apiUrlstringDelora API base
rpcUrlsTradeWidgetRpcUrlsByChainIdRPC override map by chain id
integratorstringQuote request integrator id
apiKeystringOptional Delora API key sent as x-api-key
feenumberQuote fee value, range 0..0.1
slippagenumberInitial slippage, range 0..1
excludeBridgesstring[]Bridge denylist for quote requests
excludeExchangesstring[]Exchange denylist for quote requests
assetBaseUrlstringBase URL for relative image paths
termsUrlstringTerms of Use link in the connect modal
privacyPolicyUrlstringPrivacy Policy link in the connect modal
walletConnectProjectIdstringWalletConnect Cloud project id
apiKey is sent from the browser as an x-api-key header. Do not treat it as a secret. If termsUrl or privacyPolicyUrl is omitted, the connect modal falls back to:
  • ${window.location.origin}/documentation/termsofuse
  • ${window.location.origin}/documentation/privacypolicy
For third-party embeds, it is usually better to set both links explicitly.

​
Filters

interface TradeWidgetFilters {
  sell?: TradeWidgetSideFilters;
  buy?: TradeWidgetSideFilters;
}

interface TradeWidgetSideFilters {
  includeNetworkIds?: number[];
  excludeNetworkIds?: number[];
  includeTokens?: TradeWidgetTokenSelection[];
  excludeTokens?: TradeWidgetTokenSelection[];
}

interface TradeWidgetTokenSelection {
  chainId: number;
  address: string;
}

​
TradeWidgetStatus

type TradeWidgetStatus =
  | "idle"
  | "connecting-wallet"
  | "loading-metadata"
  | "finding-quote"
  | "checking-allowance"
  | "awaiting-approve-signature"
  | "approve-pending"
  | "awaiting-swap-signature"
  | "swap-pending"
  | "success"
  | "error";

​
Event payloads

interface TradeWidgetQuotePayload {
  namespace: "EVM" | "SVM";
  senderAddress: string;
  receiverAddress: string;
  sellNetwork: Network;
  buyNetwork: Network;
  sellToken: Token;
  buyToken: Token;
  sellAmount: string;
  buyAmount: string;
  slippage: number;
  quote: QuoteResponse;
}

interface TradeWidgetActionPayload {
  action: "approve" | "swap";
  namespace: "EVM" | "SVM";
  walletAddress: string;
  receiverAddress: string;
  sellNetwork: Network;
  buyNetwork: Network;
  sellToken: Token;
  buyToken: Token;
  sellAmount: string;
  buyAmount: string;
  slippage: number;
  quote: QuoteResponse | null;
  txData: {
    to?: string;
    data?: string;
    value?: string;
  } | null;
  price: number;
  gasCostUSD: string | null;
  txHash?: string;
  receipt?: unknown;
}

interface TradeWidgetTransactionPayload extends TradeWidgetActionPayload {}

interface TradeWidgetConnectPayload {
  namespace: "EVM" | "SVM";
  address: string;
  walletName?: string;
}

interface TradeWidgetErrorPayload {
  source:
    | "metadata"
    | "configuration"
    | "quote"
    | "selection"
    | "wallet"
    | "balances"
    | "execution"
    | "unsupported";
  message: string;
  status?: number;
  statusCode?: number;
  error?: unknown;
}

​
Wallet management types

interface TradeWidgetWalletManagement {
  origin?: TradeWidgetManagedWallet | null;
  destination?: TradeWidgetManagedWallet | null;
}

interface TradeWidgetManagedWalletConnectParams {
  namespace?: "EVM" | "SVM" | null;
  walletId?: WalletOptionId;
}

interface TradeWidgetManagedWallet {
  status?: WalletConnectionStatus;
  namespace: "EVM" | "SVM" | null;
  address: string | null;
  walletName?: string;
  connectedWalletId?: WalletOptionId | null;
  connectedWalletVisualId?: WalletVisualId | null;
  connectedWalletIconUrl?: string | null;
  errorMessage?: string;
  walletOptions?: WalletOptionDescriptor[];
  evmProvider?: Eip1193Provider | null;
  evmBrowserProvider?: BrowserProvider;
  solanaProvider?: SolanaProvider | null;
  walletStandardSolanaAccount?: WalletStandardSolanaAccount | null;
  connect?: (params?) => Promise<boolean | void> | boolean | void;
  connectPreferred?: (namespace?) => Promise<boolean | void> | boolean | void;
  connectWalletOption?: (walletId, namespace?) => Promise<boolean | void> | boolean | void;
  disconnect?: () => Promise<void> | void;
  clearError?: () => void;
  peekLastConnectionError?: () => string | undefined;
  getEvmProvider?: () => Eip1193Provider;
  getEvmBrowserProvider?: () => Promise<BrowserProvider>;
  getSolanaProvider?: () => SolanaProvider;
  getConnectedWalletStandardSolanaAccount?: () => WalletStandardSolanaAccount | null;
}
If you pass an origin or destination object into TradeWidgetWalletProvider, that side is treated as externally managed. To keep the built-in wallet flow for a side, omit that side from the provider value entirely. useTradeWidgetWalletManagement is a thin helper hook for reading the same wallet-management context that powers TradeWidgetWalletProvider.