Widget API Reference

Reference for exported components, props, and types in the Delora widget packages.

This page summarizes the supported third-party integration API for @deloraprotocol/widget and the optional @deloraprotocol/widget-wallet-management adapter package.

Most integrations center on the trading widget surface:

• TradeWidget
• TradeWidgetWalletProvider
• useTradeWidgetWalletManagement

The core package also exports a smaller MyWidget demo component and shared theming props.

@deloraprotocol/widget 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

Common MyWidgetVars fields include:

• radius for shared surface radius
• actionButtonRadius for the main CTA radius
• fontFamily, fontSize, lineHeight, and letterSpacing for typography
• color and surface tokens such as bg, fg, border, surface, and surfaceAlt

See Customize Widget for the full theme-token surface and examples.

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	Optional Delora API base. If omitted, the widget uses https://api.delora.build. You can point this to your own backend proxy.
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. Recommended only for trusted environments.
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

For browser-rendered widgets, prefer not to pass apiKey directly from the client. Keep it on your backend and proxy /v1/chains, /v1/tokens, /v1/tools, and /v1/quotes through config.apiUrl.

If your proxy does not serve Delora-relative image assets, set assetBaseUrl explicitly or proxy those asset paths as well.

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;
  managedNamespaces?: Array<"EVM" | "SVM">;
  walletsByNamespace?: Partial<Record<"EVM" | "SVM", TradeWidgetManagedWallet | 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.

@deloraprotocol/widget-wallet-management exports

This package is optional. Install it when you want Delora to reuse wallet state from common host wallet libraries instead of writing a TradeWidgetManagedWallet object by hand.

Subpath exports:

Import	Exports
@deloraprotocol/widget-wallet-management/provider	DeloraWalletManagementProvider, DeloraWalletManagementProviderProps
@deloraprotocol/widget-wallet-management/auto	DeloraAutoWalletManagementProvider, DeloraAutoWalletManagementProviderProps
@deloraprotocol/widget-wallet-management/wagmi	useWagmiManagedWallet, UseWagmiManagedWalletOptions
@deloraprotocol/widget-wallet-management/solana	useSolanaWalletAdapterManagedWallet, UseSolanaWalletAdapterManagedWalletOptions
@deloraprotocol/widget-wallet-management/composite	useCompositeManagedWallet, UseCompositeManagedWalletOptions

The root package also re-exports every adapter and shared type. Prefer subpath imports when your app only installs one optional peer wallet stack.

Shared types exported from the root package:

• DeloraOpenConnectModal
• DeloraOpenConnectModalParams
• ManagedWallet

DeloraWalletManagementProvider

DeloraWalletManagementProvider is a convenience wrapper around TradeWidgetWalletProvider.

interface DeloraWalletManagementProviderProps {
  wallet?: TradeWidgetManagedWallet | null;
  origin?: TradeWidgetManagedWallet | null;
  destination?: TradeWidgetManagedWallet | null;
  children?: React.ReactNode;
}

If origin or destination is omitted, that side receives wallet. Pass explicit origin and destination when sell-side and receiver-side wallet ownership should differ.

DeloraAutoWalletManagementProvider

DeloraAutoWalletManagementProvider detects host Wagmi and Solana Wallet Adapter contexts and wires them into the widget.

interface DeloraAutoWalletManagementProviderProps {
  evm?: UseWagmiManagedWalletOptions | false;
  solana?: UseSolanaWalletAdapterManagedWalletOptions | false;
  wallet?: TradeWidgetManagedWallet | null;
  origin?: TradeWidgetManagedWallet | null;
  destination?: TradeWidgetManagedWallet | null;
  usePartialWalletManagement?: boolean;
  forceInternalWalletManagement?: boolean;
  children?: React.ReactNode;
}

Defaults:

• usePartialWalletManagement: true
• forceInternalWalletManagement: false

Set evm={false} or solana={false} to opt out of one namespace. Set forceInternalWalletManagement to ignore all detected host contexts.

useWagmiManagedWallet

interface UseWagmiManagedWalletOptions {
  walletOptions?: WalletOptionDescriptor[];
  walletOptionIds?: WalletOptionId[];
  includeUnknownWalletOptions?: boolean;
  openConnectModal?: DeloraOpenConnectModal;
  connectTimeoutMs?: number;
  preferredConnectorId?: string;
  chainId?: number;
  walletName?: string;
  walletIconUrl?: string | null;
}

The hook returns TradeWidgetManagedWallet for the EVM namespace. It reads account state from Wagmi, resolves an EIP-1193 provider from the active connector, and delegates connect and disconnect actions to Wagmi.

useSolanaWalletAdapterManagedWallet

interface UseSolanaWalletAdapterManagedWalletOptions {
  walletOptions?: WalletOptionDescriptor[];
  includeUndetectedWallets?: boolean;
  openConnectModal?: DeloraOpenConnectModal;
  connectTimeoutMs?: number;
  walletName?: string;
  walletIconUrl?: string | null;
}

The hook returns TradeWidgetManagedWallet for the SVM namespace. It reads account state from Solana Wallet Adapter and exposes a Solana provider wrapper for transaction signing.

useCompositeManagedWallet

interface UseCompositeManagedWalletOptions {
  evm?: TradeWidgetManagedWallet | null;
  solana?: TradeWidgetManagedWallet | null;
  preferredNamespace?: "EVM" | "SVM" | null;
}

The hook combines separate EVM and Solana managed wallets into one TradeWidgetManagedWallet. It sets managedNamespaces, fills walletsByNamespace, merges wallet options, and routes connect/provider calls to the namespace-specific adapter.

Shared connect modal types

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

type DeloraOpenConnectModal = (
  params: DeloraOpenConnectModalParams
) => Promise<void> | void;

Use openConnectModal when the Delora connect button should open a host wallet modal, such as RainbowKit or Solana Wallet Adapter UI.