> ## Documentation Index
> Fetch the complete documentation index at: https://docs.delora.build/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`
* `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](/widget/basic-setup/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

```ts theme={null}
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

```ts theme={null}
interface TradeWidgetFilters {
  sell?: TradeWidgetSideFilters;
  buy?: TradeWidgetSideFilters;
}

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

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

## `TradeWidgetStatus`

```ts theme={null}
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

```ts theme={null}
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

```ts theme={null}
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`.

```ts theme={null}
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.

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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

```ts theme={null}
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.