Widget API Reference

Reference for exported components, props, and types in @deloraprotocol/widget.

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.

Prop	Type	Description
theme	"light" | "dark"	Built-in theme. Default: "light"
vars	Partial<MyWidgetVars>	Theme token overrides
className	string	Applied to the widget root element
style	React.CSSProperties	Inline 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.

Prop	Type	Description
config	TradeWidgetConfig	Required widget runtime config object
filters	TradeWidgetFilters	Optional sell-side and buy-side filtering rules
theme	"light" | "dark"	Built-in theme. Default: "dark"
vars	Partial<MyWidgetVars>	Theme token overrides
className	string	Applied to the widget root element
style	React.CSSProperties	Inline root styles applied after generated CSS variables
initialSellToken	TradeWidgetTokenSelection	Preselect sell token
initialBuyToken	TradeWidgetTokenSelection	Preselect buy token
initialSellNetworkId	number	Preselect sell network
initialBuyNetworkId	number	Preselect buy network
lockSellToken	boolean	Prevent changing the sell token
lockBuyToken	boolean	Prevent changing the buy token
lockSellNetwork	boolean	Prevent changing the sell network
lockBuyNetwork	boolean	Prevent changing the buy network
onQuote	(payload) => void	Quote resolved callback
onConnect	(payload) => void	Wallet connected callback
onApprove	(payload) => void	Approval transaction submitted callback
onSwap	(payload) => void	Swap transaction submitted callback
onTxSubmitted	(payload) => void	Generic transaction submitted callback
onTxConfirmed	(payload) => void	Generic transaction confirmed callback
onError	(payload) => void	Error callback

TradeWidgetConfig

Field	Type	Description
apiUrl	string	Delora API base
rpcUrls	TradeWidgetRpcUrlsByChainId	RPC override map by chain id
integrator	string	Quote request integrator id
apiKey	string	Optional Delora API key sent as x-api-key
fee	number	Quote fee value, range 0..0.1
slippage	number	Initial slippage, range 0..1
excludeBridges	string[]	Bridge denylist for quote requests
excludeExchanges	string[]	Exchange denylist for quote requests
assetBaseUrl	string	Base URL for relative image paths
termsUrl	string	Terms of Use link in the connect modal
privacyPolicyUrl	string	Privacy Policy link in the connect modal
walletConnectProjectId	string	WalletConnect 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.