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

# Velora Widget props and types

> Props, exports, and TypeScript types for @velora-dex/widget.

This page is the type-and-prop reference for `@velora-dex/widget`. For task-oriented walkthroughs, see [Configure](/docs/widget/configure), [Wallet management](/docs/widget/wallet-management), [Monetize](/docs/widget/monetize), and [Events & callbacks](/docs/widget/events-and-callbacks).

## Public exports

Everything below can be imported from `@velora-dex/widget`:

| Export | Kind | Purpose |
| - | - | - |
| `Widget` | component | The main widget React component. |
| `defaults` | value | `{ tokenLists, chainIds, tradeModes }` — defaults the widget uses when the corresponding config option is omitted. |
| `WidgetProps` | type | Props of `<Widget />`. |
| `WidgetConfig` | type | Configuration object passed via the `config` prop. |
| `WidgetTheme` | type | `"light" \| "dark"`. |
| `WidgetElements` | type | Keys accepted by `config.excludeUI`. |
| `EIP1193ProviderLax` | type | Provider shape accepted by the `provider` prop. |
| `SupportedChainId` | type | Union of supported chain IDs. |
| `SwapMode` | type | `"market" \| "delta"` — used in event payloads. |
| `TradeMode` | type | `"swap" \| "limit" \| "otc" \| "twap"`. |
| `FormInputProps` | type | Shape of the `input` prop. |
| `MinTradeFlowToken` | type | Token shape used in event payload `tokenFrom` / `tokenTo`. |
| `WidgetState`, `AccountState`, `SettingsState`, `SwapFormState`, `LimitOrderFormState`, `OTCOrderFormState`, `TwapFormState`, `TokenFormState` | type | Pieces of widget state passed to every event callback as `state`. |
| `WidgetEventCallbacks` | type | Shape of the `events` prop. |
| `OnConnectWallet`, `OnAllowToken`, `OnWrapETH`, `OnSwap`, `OnTwapOrder`, `OnLimitOrder`, `OnOTCOrder`, `OnSettingsChange`, `OnCancelOrder`, `OnCancelTx`, `OnFillOTCOrder`, `OnFormInputChange`, `OnPriceChange` | type | Individual event-callback types. |

<Note>
  `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.
</Note>

## `<Widget />` props

```ts theme={null}
interface WidgetProps {
  config?: WidgetConfig;
  apiConfig?: ApiConfig;
  provider?: EIP1193ProviderLax;
  events?: WidgetEventCallbacks;
  input?: FormInputProps;
}
```

| Prop | Type | Required | Purpose |
| - | - | - | - |
| `config` | `WidgetConfig` | No | Widget configuration. |
| `apiConfig` | `ApiConfig` | No | API key and headers for backend requests. |
| `provider` | `EIP1193ProviderLax` | No | EIP-1193 provider when using `widgetMode: "dapp"`. |
| `events` | `WidgetEventCallbacks` | No | Event callbacks. |
| `input` | `FormInputProps` | No | Initial form state (tokens, amounts, form type). |

```tsx theme={null}
<Widget
  config={{ theme: "dark", widgetMode: "dapp" }}
  apiConfig={{ apiKey: "..." }}
  provider={window.ethereum}
  events={{ onSwap: ({ event }) => console.log(event.name) }}
  input={{ selectedForm: "swap", tokenFromAddress: "0x..." }}
/>
```

## `WidgetConfig`

```ts theme={null}
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](/docs/widget/configure). Monetization fields are documented on [Monetize](/docs/widget/monetize). Wallet-related fields on [Wallet management](/docs/widget/wallet-management).

## `ApiConfig`

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

| Field | Type | Description |
| - | - | - |
| `apiKey` | `string` | API key sent with requests. |
| `headers` | `Record<string, string>` | Extra HTTP headers (custom auth, metadata). |

```tsx theme={null}
<Widget
  apiConfig={{
    apiKey: "your-api-key",
    headers: { "X-Custom-Header": "value" },
  }}
/>
```

<Warning>
  This is client-side code. Don't embed secrets you wouldn't put in a public bundle.
</Warning>

## `EIP1193ProviderLax`

Many wallets don't satisfy viem's strict `EIP1193Provider` signature, so the widget accepts a looser shape:

```ts theme={null}
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](/docs/widget/wallet-management).

## `FormInputProps`

Pre-populate the form on mount, useful for deep links and programmatic control.

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

```tsx theme={null}
<Widget
  input={{
    selectedForm: "swap",
    tokenFromAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
    tokenToAddress: "0xdAC17F958D2ee523a2206206994597C13D831ec7",   // USDT
    srcChainId: 1,
    destChainId: 1,
    sendAmount: "1000",
  }}
/>
```

<Note>
  For native ETH, pass the special address `"0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"`.
</Note>

## `WidgetEventCallbacks`

```ts theme={null}
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](/docs/widget/events-and-callbacks).

## `defaults`

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

```tsx theme={null}
const srcChains = defaults.chainIds.filter((id) => id !== 1); // all except Ethereum
const tokenLists = [...defaults.tokenLists, "https://example.com/my-tokens.json"];
```

## Related pages

* [Configure](/docs/widget/configure) — `WidgetConfig` field walkthroughs.
* [Wallet management](/docs/widget/wallet-management) — `widgetMode`, `provider`, optional Privy connector.
* [Monetize](/docs/widget/monetize) — `partnerConfig`, `referrerConfig`.
* [Events & callbacks](/docs/widget/events-and-callbacks) — per-callback sub-events and params.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.