Configure Widget

Use TradeWidget props to control the widget’s runtime behavior, preselected assets, and available networks or tokens.

Runtime configuration

All runtime options live under the required config prop.

<TradeWidget
  config={{
    apiKey: "your-api-key",
    apiUrl: "https://your-app.com/api/delora",
    rpcUrls: {
      1: [
        "https://your-primary-ethereum-rpc.example",
        "https://your-fallback-ethereum-rpc.example",
      ],
      1000000001: [
        "https://your-primary-solana-rpc.example",
        "https://your-fallback-solana-rpc.example",
      ],
    },
    integrator: "my-dapp",
    fee: 0.01,
    slippage: 0.005,
    walletConnectProjectId: "your-walletconnect-project-id",
    termsUrl: "/legal/terms",
    privacyPolicyUrl: "/legal/privacy",
    requireWalletConsent: true,
    wallets: {
      order: ["walletconnect", "metamask"],
      exclude: ["rabby-wallet"],
    },
    showPoweredByDelora: true,
    poweredByDeloraPosition: "center",
  }}
/>

By default, the widget uses https://api.delora.build. Set apiUrl when you want a custom upstream, such as your own backend proxy:

<TradeWidget
  config={{
    apiUrl: "https://your-app.com/api/delora",
    integrator: "my-dapp",
    fee: 0.01,
  }}
/>

Use rpcUrls to provide preferred endpoints for a supported chain. Map each numeric chain ID to an ordered URL array; the widget tries those URLs first and keeps its default endpoints as fallbacks. For supported chain IDs, see Connected chains.

Field	Type	Description
`apiUrl`	`string`	Optional Delora API base used for `/v1/chains`, `/v1/tokens`, `/v1/tools`, and `/v1/quotes`
`apiKey`	`string`	Optional `x-api-key` header for Delora API requests. Avoid using this directly in browser-rendered widgets.
`rpcUrls`	`TradeWidgetRpcUrlsByChainId`	Preferred per-chain RPC endpoints used for on-chain reads and execution helpers
`integrator`	`string`	Forwarded to quote requests
`fee`	`number`	Forwarded to quote requests. Valid range: `0..0.1`
`slippage`	`number`	Initial slippage value. Valid range: `0..1`
`excludeBridges`	`string[]`	Quote denylist for bridges
`excludeExchanges`	`string[]`	Quote denylist for exchanges
`assetBaseUrl`	`string`	Base URL for resolving relative token and network image paths
`termsUrl`	`string`	URL used in the wallet consent footer
`privacyPolicyUrl`	`string`	URL used in the wallet consent footer
`requireWalletConsent`	`boolean`	Require acceptance before choosing a wallet. Defaults to `true`; `false` hides the consent footer.
`walletConnectProjectId`	`string`	WalletConnect Cloud project id for the EVM QR flow
`wallets`	`TradeWidgetWalletConfig`	Allowlist, denylist, and display order for widget-managed wallets
`showPoweredByDelora`	`boolean`	Show the linked Powered by Delora label. Defaults to `true`.
`poweredByDeloraPosition`	`"left" \| "center" \| "right"`	Horizontal label position. Defaults to `"center"`.

If assetBaseUrl is not set, it falls back to config.apiUrl and then to https://api.delora.build. For browser-based widget integrations, prefer not to pass apiKey directly from the client. Instead:

keep your Delora API key on your backend
expose a proxy that forwards /v1/chains, /v1/tokens, /v1/tools, and /v1/quotes to https://api.delora.build
point config.apiUrl to that proxy
if your proxy does not also serve Delora relative image assets, set assetBaseUrl: "https://api.delora.build" or proxy those asset paths as well

TradeWidget already supports this pattern because all Delora API reads go through config.apiUrl. 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 URLs explicitly. The consent footer is enabled by default. To remove the checkbox, links, and acceptance requirement from the connect modal, set:

<TradeWidget
  config={{
    requireWalletConsent: false,
  }}
/>

When requireWalletConsent is false, termsUrl and privacyPolicyUrl are not rendered because the entire consent footer is hidden.

Configure built-in wallets

Use config.wallets to control the widget-managed wallet picker. These three fields have independent purposes:

include is an allowlist. When present, only listed wallets are eligible.
exclude is a denylist. It removes listed wallets and takes precedence over include.
order moves listed, enabled wallets to the front in the specified order. It does not hide unlisted wallets.

For example, offer only WalletConnect:

<TradeWidget
  config={{
    wallets: {
      include: ["walletconnect"],
    },
  }}
/>

Or prioritize WalletConnect, MetaMask, and Solflare while keeping all other wallets except Rabby available:

<TradeWidget
  config={{
    wallets: {
      order: ["walletconnect", "metamask", "solflare"],
      exclude: ["rabby-wallet"],
    },
  }}
/>

Supported wallet ids are:

metamask
rabby-wallet
walletconnect
backpack
phantom
solflare
trust-wallet
okx-wallet
coinbase-wallet
magic-eden

Wallet filtering also applies to persisted built-in sessions, so an excluded or non-included wallet is not restored automatically. Namespace compatibility still applies after configuration; for example, WalletConnect is available for EVM and Solflare is available for Solana. config.wallets controls only built-in wallet management. When the host supplies walletOptions through external wallet management, that host-provided array remains the source of truth.

Initial selections

You can preselect both networks and tokens.

<TradeWidget
  config={{}}
  initialSellNetworkId={1}
  initialBuyNetworkId={1000000001}
  initialSellToken={{
    chainId: 1,
    address: "0x0000000000000000000000000000000000000000",
  }}
  initialBuyToken={{
    chainId: 1000000001,
    address: "11111111111111111111111111111111",
  }}
/>

If an initial network or token is not available in loaded metadata, the widget reports it through onError. The same happens when a host-provided initial selection becomes invalid after filters are applied.

Lock tokens or networks

Use lock props when you want the host app to keep part of the form fixed.

<TradeWidget
  config={{}}
  initialBuyToken={{ chainId: 1, address: "0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }}
  lockBuyToken
/>

Supported lock props:

lockSellToken
lockBuyToken
lockSellNetwork
lockBuyNetwork

Behavior:

Locking a token also locks its network, because the token already implies a chain
Locking a network still allows token changes inside that network
Any lock disables the center “swap sides” button to avoid breaking host-provided constraints

Filter available networks and tokens

Use filters to restrict the sell and buy sides independently.

<TradeWidget
  config={{}}
  filters={{
    sell: {
      includeNetworkIds: [1, 8453],
      excludeTokens: [
        {
          chainId: 1,
          address: "0x0000000000000000000000000000000000000000",
        },
      ],
    },
    buy: {
      includeTokens: [
        {
          chainId: 1000000001,
          address: "11111111111111111111111111111111",
        },
      ],
    },
  }}
/>

Each side supports:

includeNetworkIds
excludeNetworkIds
includeTokens
excludeTokens

Important filter behavior:

Filters are applied per side, so sell and buy restrictions can be different
Networks that end up with no available tokens are removed automatically
Conflicting filters produce onError events with source: "configuration"
If no networks remain on a side after filtering, the widget enters a configuration error state

Custom token lookup

When a side does not use includeTokens, the token selector can import a token by contract or mint address if the address is valid for the active network. Imported tokens become part of the current browser session and can also be restored from persisted selection state. When includeTokens is set for a side, custom token import is disabled on that side.

Persistence

The widget stores the latest selected sell and buy networks and tokens in browser localStorage, so the next mount can restore the previous selection when the host app does not explicitly override it. Slippage and internal wallet choices are also persisted separately.

Quote lifecycle and refresh behavior

The widget does not request a quote on every keystroke. Quote loading has a small client-side lifecycle:

sell input is debounced by about 1 second before a quote request is sent
successful quotes auto-refresh every 60 seconds while the current selection stays stable
auto-refresh stops after 5 consecutive refresh cycles until the user changes the selection or amount
the quote countdown ring in the UI can also be clicked to request a manual refresh immediately

The widget also applies a local cooldown around quote refreshes to avoid excessive request loops:

more than 15 quote requests within 5 seconds starts a local cooldown
the cooldown lasts 5 seconds
during that window, the widget can emit onError({ source: "quote", statusCode: 429 }) even if the backend did not return 429

If you build analytics or retry logic around quote errors, treat this as widget-side throttling as well as possible API-side rate limiting.

Delora Widget

Basic Setup

Advanced Setup

Configure Widget

Runtime configuration

Configure built-in wallets

Initial selections

Lock tokens or networks

Filter available networks and tokens

Custom token lookup

Persistence

Quote lifecycle and refresh behavior

​Runtime configuration

​Configure built-in wallets

​Initial selections

​Lock tokens or networks

​Filter available networks and tokens

​Custom token lookup

​Persistence

​Quote lifecycle and refresh behavior

Runtime configuration

Configure built-in wallets

Initial selections

Lock tokens or networks

Filter available networks and tokens

Custom token lookup

Persistence

Quote lifecycle and refresh behavior