Skip to main content
This page is the type-and-prop reference for @velora-dex/widget. For task-oriented walkthroughs, see Configure, Wallet management, Monetize, and Events & callbacks.

​
Public exports

Everything below can be imported from @velora-dex/widget:
ExportKindPurpose
WidgetcomponentThe main widget React component.
defaultsvalue{ tokenLists, chainIds, tradeModes } — defaults the widget uses when the corresponding config option is omitted.
WidgetPropstypeProps of <Widget />.
WidgetConfigtypeConfiguration object passed via the config prop.
WidgetThemetype"light" | "dark".
WidgetElementstypeKeys accepted by config.excludeUI.
EIP1193ProviderLaxtypeProvider shape accepted by the provider prop.
SupportedChainIdtypeUnion of supported chain IDs.
SwapModetype"market" | "delta" — used in event payloads.
TradeModetype"swap" | "limit" | "otc" | "twap".
FormInputPropstypeShape of the input prop.
MinTradeFlowTokentypeToken shape used in event payload tokenFrom / tokenTo.
WidgetState, AccountState, SettingsState, SwapFormState, LimitOrderFormState, OTCOrderFormState, TwapFormState, TokenFormStatetypePieces of widget state passed to every event callback as state.
WidgetEventCallbackstypeShape of the events prop.
OnConnectWallet, OnAllowToken, OnWrapETH, OnSwap, OnTwapOrder, OnLimitOrder, OnOTCOrder, OnSettingsChange, OnCancelOrder, OnCancelTx, OnFillOTCOrder, OnFormInputChange, OnPriceChangetypeIndividual event-callback types.
ApiConfig is not re-exported by name even though it’s the shape of the apiConfig prop. Infer it via WidgetProps["apiConfig"] if you need a named type.

​
<Widget /> props

interface WidgetProps {
  config?: WidgetConfig;
  apiConfig?: ApiConfig;
  provider?: EIP1193ProviderLax;
  events?: WidgetEventCallbacks;
  input?: FormInputProps;
}
PropTypeRequiredPurpose
configWidgetConfigNoWidget configuration.
apiConfigApiConfigNoAPI key and headers for backend requests.
providerEIP1193ProviderLaxNoEIP-1193 provider when using widgetMode: "dapp".
eventsWidgetEventCallbacksNoEvent callbacks.
inputFormInputPropsNoInitial form state (tokens, amounts, form type).
<Widget
  config={{ theme: "dark", widgetMode: "dapp" }}
  apiConfig={{ apiKey: "..." }}
  provider={window.ethereum}
  events={{ onSwap: ({ event }) => console.log(event.name) }}
  input={{ selectedForm: "swap", tokenFromAddress: "0x..." }}
/>

​
WidgetConfig

interface WidgetConfig {
  theme?: WidgetTheme;
  enableDelta?: boolean;
  enableCrossChain?: boolean;
  partnerConfig?: PartnerConfig;
  referrerConfig?: ReferrerConfig;
  privyAppId?: string;
  privyClientId?: string;
  debug?: boolean;
  widgetMode?: "dapp" | "standalone";
  enableDegenMode?: boolean;
  tokenLists?: string[];
  srcChains?: SupportedChainId[];
  destChains?: SupportedChainId[];
  tradeModes?: TradeMode[];
  excludeUI?: WidgetElements[];
}
Field-by-field documentation lives on Configure. Monetization fields are documented on Monetize. Wallet-related fields on Wallet management.

​
ApiConfig

interface ApiConfig {
  apiKey?: string;
  headers?: Record<string, string>;
}
Forwarded to the Velora SDK on every backend request (prices, swap construction, Delta order submission). Use when integrating against an authenticated tier or a partner-proxied endpoint.
FieldTypeDescription
apiKeystringAPI key sent with requests.
headersRecord<string, string>Extra HTTP headers (custom auth, metadata).
<Widget
  apiConfig={{
    apiKey: "your-api-key",
    headers: { "X-Custom-Header": "value" },
  }}
/>
This is client-side code. Don’t embed secrets you wouldn’t put in a public bundle.

​
EIP1193ProviderLax

Many wallets don’t satisfy viem’s strict EIP1193Provider signature, so the widget accepts a looser shape: 
type EIP1193ProviderLax = {
  request: (args: { method: any; params?: any }) => Promise<any>;
  on: (event: any, callback: (arg: unknown) => void) => void;
  removeListener: (event: any, callback: (arg: unknown) => void) => void;
};
Used with widgetMode: "dapp". See Wallet management.

​
FormInputProps

Pre-populate the form on mount, useful for deep links and programmatic control. 
interface FormInputProps {
  selectedForm?: "swap" | "limit" | "otc" | "twap";
  tokenFromAddress?: Address;
  srcChainId?: SupportedChainId;
  tokenToAddress?: Address;
  destChainId?: SupportedChainId;
  sendAmount?: string;
  receiveAmount?: string;
  side?: "BUY" | "SELL";
  orderDeadline?: string;
}

​
selectedForm

"swap" | "limit" | "otc" | "twap" — defaults to "swap". Corresponds to tradeMode in events.

​
tokenFromAddress

Address — the source-token address to pre-select. Pair with srcChainId.

​
srcChainId

SupportedChainId — chain for the source token. Required when tokenFromAddress is provided.

​
tokenToAddress

Address — the destination-token address to pre-select. Pair with destChainId (or omit for same-chain).

​
destChainId

SupportedChainId — chain for the destination token. Only functional when selectedForm is "swap" (crosschain). For limit and OTC, it’s forced to match srcChainId.

​
sendAmount

string — initial amount to send, in token units (not wei). Must parse as a number.

​
receiveAmount

string — initial amount to receive, in token units. Mutually exclusive with sendAmount for the same trade-side.

​
side

"BUY" | "SELL" — only for selectedForm: "swap" or "twap". If omitted, defaults to "SELL" when sendAmount is set and "BUY" when receiveAmount is set. If both or neither amounts are present, the user’s UI selection wins.

​
orderDeadline

string — Unix timestamp (seconds), as a numeric string. Only functional when selectedForm is "limit" or "otc". For Delta Limit Orders, the minimum recommended expiry is now + 10 minutes. For OTC, "0" means no expiry. The widget doesn’t reject invalid values at prop time — they surface in the trade flow. 
<Widget
  input={{
    selectedForm: "swap",
    tokenFromAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
    tokenToAddress: "0xdAC17F958D2ee523a2206206994597C13D831ec7",   // USDT
    srcChainId: 1,
    destChainId: 1,
    sendAmount: "1000",
  }}
/>
For native ETH, pass the special address "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE".

​
WidgetEventCallbacks

interface WidgetEventCallbacks {
  onConnectWallet?: OnConnectWallet;
  onConnectWalletClick?: OnConnectWallet;
  onAllowToken?: OnAllowToken;
  onWrapETH?: OnWrapETH;
  onSwap?: OnSwap;
  onTwapOrder?: OnTwapOrder;
  onCancelTx?: OnCancelTx;
  onLimitOrder?: OnLimitOrder;
  onOTCOrder?: OnOTCOrder;
  onSettingsChange?: OnSettingsChange;
  onCancelOrder?: OnCancelOrder;
  onFillOTCOrder?: OnFillOTCOrder;
  onFormInputChange?: OnFormInputChange;
  onPriceChange?: OnPriceChange;
}
Each callback receives { event, state } where event is a discriminated union on event.name and state is a snapshot of the full widget state. Detailed sub-event names, params, and lifecycle ordering live on Events & callbacks.

​
defaults

import { defaults } from "@velora-dex/widget";

defaults.chainIds;    // SupportedChainId[]
defaults.tokenLists;  // string[]
defaults.tradeModes;  // TradeMode[]
Use to compose custom values that include or exclude defaults: 
const srcChains = defaults.chainIds.filter((id) => id !== 1); // all except Ethereum
const tokenLists = [...defaults.tokenLists, "https://example.com/my-tokens.json"];
Last modified on June 14, 2026