Widget API Reference

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. Components and hooks:

MyWidget
TradeWidget
TradeWidgetWalletProvider
useTradeWidgetWalletManagement

Shared widget props and theme types:

MyWidgetProps
MyWidgetTheme
MyWidgetVars

Trade widget types:

TradeWidgetProps
TradeWidgetConfig
TradeWidgetRpcUrlsByChainId
TradeWidgetWalletConfig
TradeWidgetWalletId
TradeWidgetPoweredByPosition
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`	Preferred endpoints, mapped from numeric chain IDs to ordered URL arrays
`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
`requireWalletConsent`	`boolean`	Require consent before wallet selection. Defaults to `true`; `false` hides the footer.
`walletConnectProjectId`	`string`	WalletConnect Cloud project id
`wallets`	`TradeWidgetWalletConfig`	Built-in wallet allowlist, denylist, and preferred order
`showPoweredByDelora`	`boolean`	Show the linked Powered by Delora label. Defaults to `true`.
`poweredByDeloraPosition`	`TradeWidgetPoweredByPosition`	Label alignment. Defaults to `"center"`.

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. When requireWalletConsent is false, the consent checkbox and both legal links are hidden, and wallet rows can be selected immediately.

Wallet and branding configuration types

type TradeWidgetWalletId =
  | "metamask"
  | "rabby-wallet"
  | "walletconnect"
  | "backpack"
  | "phantom"
  | "solflare"
  | "trust-wallet"
  | "okx-wallet"
  | "coinbase-wallet"
  | "magic-eden";

interface TradeWidgetWalletConfig {
  include?: TradeWidgetWalletId[];
  exclude?: TradeWidgetWalletId[];
  order?: TradeWidgetWalletId[];
}

type TradeWidgetPoweredByPosition = "left" | "center" | "right";

include, exclude, and order are independent. include is an allowlist, exclude is a denylist with precedence over include, and order only moves enabled wallets to the front without hiding unlisted wallets. These controls apply to widget-managed wallets, not host-provided walletOptions.

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. 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.

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.

Delora Widget

Basic Setup

Advanced Setup

Widget API Reference

`@deloraprotocol/widget` exports

`MyWidget` and `MyWidgetProps`

`TradeWidgetProps`

`TradeWidgetConfig`

Wallet and branding configuration types

Filters

`TradeWidgetStatus`

Event payloads

Wallet management types

`@deloraprotocol/widget-wallet-management` exports

`DeloraWalletManagementProvider`

`DeloraAutoWalletManagementProvider`

`useWagmiManagedWallet`

`useSolanaWalletAdapterManagedWallet`

`useCompositeManagedWallet`

​@deloraprotocol/widget exports

​MyWidget and MyWidgetProps

​TradeWidgetProps

​TradeWidgetConfig

​Wallet and branding configuration types

​Filters

​TradeWidgetStatus

​Event payloads

​Wallet management types

​@deloraprotocol/widget-wallet-management exports

​DeloraWalletManagementProvider

​DeloraAutoWalletManagementProvider

​useWagmiManagedWallet

​useSolanaWalletAdapterManagedWallet

​useCompositeManagedWallet

​Shared connect modal types

`@deloraprotocol/widget` exports

`MyWidget` and `MyWidgetProps`

`TradeWidgetProps`

`TradeWidgetConfig`

Wallet and branding configuration types

Filters

`TradeWidgetStatus`

Event payloads

Wallet management types

`@deloraprotocol/widget-wallet-management` exports

`DeloraWalletManagementProvider`

`DeloraAutoWalletManagementProvider`

`useWagmiManagedWallet`

`useSolanaWalletAdapterManagedWallet`

`useCompositeManagedWallet`

Shared connect modal types