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

# Configuration

> This page details your widget configuration options. Tweak it to fit your exact user experience needs!

> [!NOTE]
>
> **Visual Configuration Tool:** Want to see how your configuration options look before implementing them? Try [studio.skip.build](https://studio.skip.build) - our interactive widget builder that lets you customize themes, assets, routes, and more with a live preview.

# Component Props

The `Widget` component accepts the following props.

### `defaultRoute`

Customizes the initial route displayed on widget load. Query supported assets using the Skip Go API [/assets](https://docs.skip.build/go/api-reference/prod/fungible/get-v2fungibleassets) endpoint. Setting this triggers a route request on render.

```ts theme={null}
defaultRoute?: {
  amountIn?: number;
  amountOut?: number;
  srcChainId?: string;
  srcAssetDenom?: string;
  destChainId?: string;
  destAssetDenom?: string;
};
```

* `amountIn`: Preset input amount for exact amount in request.
* `amountOut`: Preset output amount for exact amount out request. If both specified, only `amountIn` is used.
* `srcChainId` : Source chain ID.
* `srcAssetDenom`: Source asset denomination.
* `destChainId`: Destination chain ID.
* `destAssetDenom`: Destination asset denomination.

### `routeConfig`

Customizes enabled route types.

```ts theme={null}
routeConfig?: {
  experimentalFeatures?: string[]; // e.g. ['stargate', 'eureka']
  allowMultiTx?: boolean;
  allowUnsafe?: boolean;
  bridges?: ('IBC' | 'AXELAR' | 'CCTP' | 'CCTP_V2' | 'HYPERLANE' | 'OPINIT' | 'GO_FAST' | 'STARGATE' | 'LAYER_ZERO' | 'EUREKA')[];
  swapVenues?: {
    name: string;
    chainId: string;
  }[];
  goFast?: boolean;
  smartSwapOptions?: SmartSwapOptions;
  timeoutSeconds?: string; // Number of seconds for the IBC transfer timeout, defaults to 5 minutes
};
```

* `allowMultiTx`: Allow multi-transaction routes. Default: true.
* `allowUnsafe`: Allow unsafe routes. Default: false. [More info](/go/advanced-swapping/allow_unsafe-preventing-handling-bad-execution.md).
* `bridges`: Restrict routing to specific bridges. Default: empty (all bridges).
* `swapVenues`: Restrict routing to specific swap venues. Default: empty (all venues).
* `goFast`: Enable Go Fast transfers. Default: false. [More info](/go/advanced-transfer/go-fast.md).
* `experimentalFeatures`: Array of experimental features to enable. Include `'eureka'` to enable routing with Eureka assets.
* `smartSwapOptions`: Advanced swapping features like EVM Swaps and split trade routes. [More info](/go/advanced-swapping/smart-swap-options.md).

### `batchSignTxs`

Controls whether all transactions in a multi-transaction route should be signed upfront or individually as they are executed.

```ts theme={null}
batchSignTxs?: boolean;
```

* **Default:** `true`
* When enabled, all transactions in the route will be requested for signature at the beginning of the execution. They will then be broadcast one by one in sequence.
* When disabled, each transaction will be signed individually just before it is broadcast.

**Example scenario with `batchSignTxs: true`:**
For a route: Solana → Noble → Cosmos (3 transactions requiring signatures)

* All 3 transactions will be prompted for signature upfront
* After signing, they will be broadcast sequentially: Solana first, then Noble, then Cosmos

> [!NOTE]
>
> **EVM Transaction Limitation:** If an EVM transaction appears as the second or later transaction in a route, batch signing cannot be performed upfront. In such cases, the EVM transaction and any subsequent transactions will need to be signed individually when they are ready to be executed.

### `filter`

Key value pair of chainIds or specific asset denoms allowed
on source and destination assets

```ts theme={null}
  filter?: {
    source?: Record<string, string[] | undefined>;
    destination?: Record<string, string[] | undefined>;
  };
```

Example:

```ts theme={null}
{
  source: {
    // only assets on this chainId is allowed
    'noble-1': undefined,
  },
  destination: {
    // these assets on this chainId are allowed
    'cosmoshub-4': ['uatom', 'ibc/2181AAB0218EAC24BC9F86BD1364FBBFA3E6E3FCC25E88E3E68C15DC6E752D86'],
    // these assets on this chainId are allowed
    'agoric-3': ['ibc/FE98AAD68F02F03565E9FA39A5E627946699B2B07115889ED812D8BA639576A9'],
    // any asset on this chainId are allowed
    'osmosis-1': undefined,
  }
}
```

### `filterOut`

Opposite of filter.
Key value pair of chainIds not allowed or specific asset denoms not allowed

```ts theme={null}
  filterOut?: {
    source?: Record<string, string[] | undefined>;
    destination?: Record<string, string[] | undefined>;
  };
```

Example:

```ts theme={null}
{
  source: {
    // only assets on this chainId is not allowed
    'noble-1': undefined,
  },
  destination: {
    // these assets on this chainId are not allowed
    'cosmoshub-4': ['uatom', 'ibc/2181AAB0218EAC24BC9F86BD1364FBBFA3E6E3FCC25E88E3E68C15DC6E752D86'],
  }
}
```

### `settings`

Sets defaults for user-customizable settings.

```ts theme={null}
settings?: {
  slippage?: number;
  useUnlimitedApproval?: boolean; // Set allowance amount to max if EVM transaction requires allowance approval
};
```

* `slippage`: Default slippage percentage (0-100) for CosmosSDK chain swaps. Default: `1`.
* `useUnlimitedApproval`: Set the EVM allowance to the max amount when an approval is required. Default: `false`.

### `onlyTestnet`

`onlyTestnet`: Boolean to show only testnet data. Default: false (mainnet data only).

### `endpointOptions`

Override default Skip proxied endpoints. Whitelisting required, reach out [here](https://discord.com/invite/interchain).

```ts theme={null}
endpointOptions?: {
    endpoints?: Record<string, EndpointOptions>;
    getRpcEndpointForChain?: (chainID: string) => Promise<string>;
    getRestEndpointForChain?: (chainID: string) => Promise<string>;
  };
```

### `apiUrl`

String to override default Skip Go API proxied endpoints. Whitelisting required, reach out [here](https://discord.com/invite/interchain).

### `brandColor`

Customizes the main highlight color of the widget

### `borderRadius`

Controls the corner roundness of cards and buttons in the widget. This is not a top-level prop — set it under [`theme`](#theme) via `theme.borderRadius`.

### `theme`

Advanced widget appearance customization options

```tsx theme={null}
  theme? = {
    brandColor: string;
    borderRadius: {
      main?: string | number;
      selectionButton?: string | number;
      ghostButton?: string | number;
      modalContainer?: string | number;
      rowItem?: string | number;
    };
    primary: {
      background: {
        normal: string;
      };
      text: {
        normal: string;
        lowContrast: string;
        ultraLowContrast: string;
      };
      ghostButtonHover: string;
    };
    secondary: {
      background: {
        normal: string;
        transparent: string;
        hover: string;
      };
    };
    success: {
      background: string;
      text: string;
    };
    warning: {
      background: string;
      text: string;
    };
    error: {
      background: string;
      text: string;
    };
  };
```

### `chainIdsToAffiliates`

Define fees per chain and recipient addresses.

> [!NOTE]
>
> Total basisPointsFee must be consistent across chains. Addresses must be valid for respective chains.

```ts theme={null}
chainIdsToAffiliates: {
  'noble-1': {
    affiliates: [{
      basisPointsFee: '100', // 1% fee
      address: 'noble..1', // address to receive fee
    },
    {
      basisPointsFee: '100', // 1% fee
      address: 'noble...2', // address to receive fee
    }]
  },
  'osmosis-1': {
    affiliates: [{
      basisPointsFee: '200', // 2% fee
      address: 'osmo...1', // address to receive fee
    },]
  }
}
```

### `enableSentrySessionReplays`

Enables sentry session replays on the widget to help with troubleshooting errors. Default: false.

### `enableAmplitudeAnalytics`

Enable Amplitude analytics for the widget to improve user experience. Default: false.

### `disableShadowDom`

Disables shadow dom, useful if there are issues with libraries not supporting shadow-dom or for enabling server side rendering
Default: false. (shadow dom is enabled by default to avoid styling conflicts/issues)

### `hideAssetsUnlessWalletTypeConnected`

Filters assets based on connected wallet types (currently only supports Sei Cosmos/EVM). Added in v3.7.3. Default: false.

### `assetSymbolsSortedToTop`

Prioritizes assets by recommended symbol when their pinning, search-match, and balance priorities are equal. Symbols are ordered as listed. To pin an asset above search matches and balances, use [`assetAnnotations`](#assetannotations) with `selector.pinToTop` instead.

```ts theme={null}
assetSymbolsSortedToTop?: string[];
```

### `assetAnnotations`

Render a per-asset annotation (badge / description / highlight / pin-to-top), keyed by recommended symbol.

```ts theme={null}
assetAnnotations?: Record<string, {
  variant?: "info" | "warning" | "error"; // color; defaults to "info"
  swapPage?: {
    label: string;                         // badge on the swap page asset rows
  };
  selector?: {
    description?: string;                   // detail line under the asset name in the token selector
    pinToTop?: boolean;                     // pin the asset to the top of the selector, above balances
  };
}>;
```

* `variant`: color of the badge / description / highlight. `info` uses the brand color, `warning` and `error` use the theme's warning/error colors.
* `swapPage.label`: renders a badge on the swap page (source and destination rows).
* `selector.description`: detail line under the asset name in the token selector.
* `selector.pinToTop`: pins the asset to the very top of the token selector (above balances, and above search matches).

Example:

```ts theme={null}
assetAnnotations={{
  "USDC.n": {
    variant: "info",
    swapPage: { label: "Migration required" },
    selector: {
      description: "Convert to USDC before support ends",
      pinToTop: true,
    },
  },
}}
```

### `filterOutUnlessUserHasBalance`

Like `filterOut`, but the assets/chains are only hidden unless the user holds a balance of them.

```ts theme={null}
filterOutUnlessUserHasBalance?: {
  source?: Record<string, string[] | undefined>;
  destination?: Record<string, string[] | undefined>;
};
```

### `walletConnect`

WalletConnect configuration used for wallet connections.

```ts theme={null}
walletConnect?: {
  options: {
    projectId?: string;
    name?: string;
  } | null;
  walletConnectModal?: {
    themeVariables?: Record<string, string>;
    themeMode?: "light" | "dark";
    privacyPolicyUrl?: string;
    termsOfServiceUrl?: string;
  } | null;
};
```

### `simulate`

Whether the widget simulates transactions before executing the route to validate gas and balances.

```ts theme={null}
simulate?: boolean;
```

* **Default:** `true`

### `rootId`

If specified, adds a `data-root-id` attribute to all root elements of the widget (including portals), useful for `document.querySelector` or scoped styling.

```ts theme={null}
rootId?: string;
```

### `modalZIndex`

Custom `z-index` for the widget's modals.

```ts theme={null}
modalZIndex?: number;
```

* **Default:** `10`

### `skipExplorerUrl`

Base URL of the Skip explorer that transaction history links point to.

```ts theme={null}
skipExplorerUrl?: string;
```

* **Default:** `https://explorer.skip.build`

### `callbacks`

Event handling functions.

```ts theme={null}
onWalletConnected?: (params: {
  walletName?: string;
  chainIdToAddressMap: Record<string, string>;
  address?: string;
}) => void;

onWalletDisconnected?: (params: {
  walletName?: string;
  chainType?: string;
}) => void;

onTransactionSignRequested?: (props: onTransactionSignRequestedProps) => void;

onTransactionBroadcasted?: (params: {
  chainId: string;
  signerAddress?: string;
  txIndex: number;
}) => void;

onTransactionComplete?: (params: {
  txHash: string;
  chainId: string;
  explorerLink?: string;
  sourceAddress: string;
  destinationAddress: string;
  sourceAssetDenom: string;
  sourceAssetChainID: string;
  destAssetDenom: string;
  destAssetChainID: string;
}) => void;

onTransactionFailed?: (params: { error: Error }) => void;

onRouteUpdated?: (props: {
  srcChainId?: string;
  srcAssetDenom?: string;
  destChainId?: string;
  destAssetDenom?: string;
  amountIn?: string;
  amountOut?: string;
  requiredChainAddresses?: string[];
}) => void;

onSourceAndDestinationSwapped?: (props: {
  srcChainId?: string;
  srcAssetDenom?: string;
  destChainId?: string;
  destAssetDenom?: string;
  amountIn?: string;
  amountOut?: string;
}) => void;

onSourceAssetUpdated?: (props: {
  chainId?: string;
  denom?: string;
}) => void;

onDestinationAssetUpdated?: (props: {
  chainId?: string;
  denom?: string;
}) => void;
```

* `onWalletConnected`: Called when a wallet is connected.
* `onWalletDisconnected`: Called when a wallet is disconnected.
* `onTransactionBroadcasted`: Called when a transaction is broadcasted. This is called multiple times for multi-transaction routes.
* `onTransactionComplete`: Triggered when a transaction is completed.
* `onTransactionFailed`: Triggered when a transaction fails.

### `connectedAddresses` & `signers`

If your application has already connected to a user's wallet (e.g., via MetaMask for EVM networks, Phantom for Solana, or Keplr for Cosmos), you **must provide both** the `connectedAddresses` and corresponding signer functions in order to enable the widget's injected wallet functionality.
See an implementation example [here](https://github.com/skip-mev/skip-go/tree/staging/examples/nextjs/src/app/injected/page.tsx).

`WalletClient` comes from the [`viem` package](https://viem.sh/docs/clients/wallet.html). `Adapter` comes from the [`@solana/wallet-adapter-base` package](https://solana.com/developers/cookbook/wallets/connect-wallet-react). And `OfflineSigner` comes from the [`@cosmjs` package](https://docs.keplr.app/api/cosmjs.html).

* **Type:** `Record<ChainId, Address>`

**Example:**

```typescript theme={null}
const connectedAddresses: Record<string, string> = {
  "1": "0x123...abc",          // Ethereum mainnet address
  "cosmoshub-4": "cosmos1...", // Cosmos Hub address
  "solana": "3n9...xyz",       // Solana address
  // ... add more chain IDs and addresses as needed
};
```

### Signer Functions

Each signer function below must be implemented to fully leverage the injected wallet capabilities:

* **`getCosmosSigner(): Promise<OfflineSigner>`**
  Returns a Cosmos-compatible signer.

* **`getEvmSigner(): Promise<WalletClient>`**
  Returns an EVM-compatible signer (e.g., from `viem`).

* **`getSvmSigner(): Promise<PhantomWalletAdapter>`**
  Returns a Solana-compatible signer, such as a `PhantomWalletAdapter`.

**Complete Example for injected wallet functionality:**

```jsx theme={null}
<Widget
  connectedAddresses={connectedAddresses}
  getCosmosSigner={getCosmosSigner}
  getEvmSigner={getEvmSigner}
  getSvmSigner={getSvmSigner}
/>
```


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