> ## Documentation Index
> Fetch the complete documentation index at: https://anypay-docs-widget-callback-intent-id.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Complete configuration reference for the Trails SDK

## Focused components

### Shared props

All focused components accept these optional props in addition to their mode-specific props.

#### Appearance

| Prop           | Type                               | Default  | Description                                   |
| -------------- | ---------------------------------- | -------- | --------------------------------------------- |
| `theme`        | `"light" \| "dark" \| "auto"`      | `"auto"` | Color theme; `auto` follows system preference |
| `customCss`    | `string \| Record<string, string>` | —        | Custom CSS to inject into the widget          |
| `disableCss`   | `boolean`                          | `false`  | Disable default CSS injection                 |
| `renderInline` | `boolean`                          | `false`  | Render inline instead of as a modal           |
| `buttonText`   | `string`                           | —        | Custom CTA button text                        |

#### App metadata

Used in wallet connection dialogs (WalletConnect, etc.):

```tsx theme={null}
appMetadata={{
  name: "My App",
  url: "https://myapp.com",
  imageUrl: "https://myapp.com/logo.png",
  description: "Short description",
}}
```

#### Wallet options

| Prop                     | Type                   | Description                                                                                                                                                                                                                                           |
| ------------------------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `walletConnectProjectId` | `string`               | WalletConnect project ID                                                                                                                                                                                                                              |
| `adapters`               | `TrailsAdapterEntry[]` | Explicit wallet runtime adapters. Use `wagmiAdapter` from [`@0xtrails/adapter-wagmi`](/sdk/adapters/wagmi) to share an existing wagmi session, or build your own with [`evmAdapter`](/sdk/adapters/eip-1193). See [Adapters](/sdk/adapters/overview). |
| `hideAddWallet`          | `boolean`              | Hide "Add wallet" option                                                                                                                                                                                                                              |
| `isSmartWallet`          | `boolean`              | Signal that the connected wallet is a smart wallet                                                                                                                                                                                                    |

<Note>
  The `wagmiConnectors` and `decoupleWagmi` props were removed in [`0xtrails@0.16.0`](/sdk/changelog/0xtrails-0.16.0). Wagmi is no longer required by default — pass adapters on the widget's `adapters` prop instead. See [Adapters](/sdk/adapters/overview).
</Note>

#### Route options

| Prop                             | Type                    | Description                                           |
| -------------------------------- | ----------------------- | ----------------------------------------------------- |
| `slippageTolerance`              | `number \| string`      | Slippage tolerance (e.g. `0.005` for 0.5%)            |
| `swapProvider`                   | `RouteProvider`         | Preferred same-chain swap provider                    |
| `swapProviderFallback`           | `boolean`               | Fall back if preferred swap provider is unavailable   |
| `bridgeProvider`                 | `RouteProvider`         | Preferred bridge provider                             |
| `bridgeProviderFallback`         | `boolean`               | Fall back if preferred bridge provider is unavailable |
| `priceImpactWarningThresholdBps` | `number`                | Basis points before showing a price impact warning    |
| `priceImpactWarningMessage`      | `string`                | Custom price impact warning message                   |
| `priceImpactFallbackBridgeUrl`   | `string`                | URL to redirect when price impact is too high         |
| `intentProtocolVersion`          | `IntentProtocolVersion` | Force a specific intent protocol version              |

#### Debug / dev

```tsx theme={null}
dev={{
  debug: true,
  sequenceIndexerUrl: "https://...",
  trailsApiUrl: "https://...",
}}
```

#### General callbacks

These callbacks are available on all focused components (in addition to mode-specific lifecycle callbacks):

| Callback                    | Payload                                      | When it fires                           |
| --------------------------- | -------------------------------------------- | --------------------------------------- |
| `onOpen`                    | —                                            | Widget modal opens                      |
| `onClose`                   | —                                            | Widget modal closes                     |
| `onQuote`                   | `{ sessionId, intentId, quote }`             | Quote is received                       |
| `onSignRequest`             | `{ sessionId, intentId }`                    | Wallet signature requested              |
| `onSign`                    | `{ sessionId, intentId }`                    | Wallet signature obtained               |
| `onSignReject`              | `{ sessionId, intentId, error }`             | User rejected the signature             |
| `onApproveRequest`          | `{ sessionId, intentId }`                    | ERC-20 approval requested               |
| `onApprove`                 | `{ sessionId, intentId, transactionHash }`   | ERC-20 approval confirmed               |
| `onApproveReject`           | `{ sessionId, intentId, error }`             | User rejected the approval              |
| `onStatus`                  | `{ sessionId, intentId, transactionStates }` | Transaction status update               |
| `onOriginConfirmation`      | `{ sessionId, intentId, txHash, chainId }`   | Origin-chain transaction confirmed      |
| `onDestinationConfirmation` | `{ sessionId, intentId, txHash, chainId }`   | Destination-chain transaction confirmed |

#### Callback payloads

Every callback that fires after a quote exists carries two identifiers:

| Field       | Type             | Description                                                                                                                                                                                                                             |
| ----------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sessionId` | `string`         | Analytics session id for the current widget session. Stable across every callback in one session, but not known to the Trails API.                                                                                                      |
| `intentId`  | `string \| null` | Id of the intent created for the active quote. Use it to look the payment up server-side (`GetIntentReceipt`, `GetIntentStatus`) or on Trailscan. `null` for passthrough quotes (same-chain, same-token transfers that need no intent). |

The `*Start` callbacks (`onPaymentStart`, `onFundingStart`, …) fire before quoting, so they carry only `sessionId`. `onOpen` and `onClose` have
no payload.

```tsx theme={null}
<Pay
  apiKey="YOUR_API_KEY"
  to={{ recipient: "0xMerchant", currency: "USDC", chain: "base", amount: "25" }}
  onQuote={({ intentId }) => console.log("intent created", intentId)}
  onPaymentSuccess={({ intentId }) => {
    // Verify server-side with the Trails API before fulfilling
    fetch("/api/verify-payment", { method: "POST", body: JSON.stringify({ intentId }) })
  }}
>
  <button>Pay $25</button>
</Pay>
```

The payload types are exported as `CheckoutEventBase` (`{ sessionId, intentId }`) and `TransactionConfirmationEvent` from `0xtrails`.

### ChainIdentifier

All `chain` fields accept a `ChainIdentifier`, which can be:

* A chain name string: `"base"`, `"ethereum"`, `"polygon"`, `"arbitrum"`, `"optimism"`, `"avalanche"`, `"bsc"`, `"katana"`, etc.
* A numeric chain ID: `8453`, `1`, `137`, etc.
* A viem `Chain` object

### PaymentMethod

The `paymentMethod` prop on focused components accepts:

| Value                 | Method                                  |
| --------------------- | --------------------------------------- |
| `"CONNECTED_WALLET"`  | Connected wallet (default when omitted) |
| `"CRYPTO_TRANSFER"`   | QR code / address deposit               |
| `"CREDIT_DEBIT_CARD"` | Fiat on-ramp (credit/debit card)        |
| `"EXCHANGE"`          | CEX transfer (Coinbase, Binance, etc.)  |

### Mode-specific props

See the individual mode pages for full prop details:

* [Pay](/sdk/modes/pay) — `to.recipient`, `to.currency`, `to.chain`, `to.amount`, `payMessage`, `onPaymentStart/Success/Error`
* [Fund](/sdk/modes/fund) — `to`, `fundMethodsList`, `hideUnlistedFundMethods`, `hideSwap`, `onFundingStart/Success/Error`
* [Swap](/sdk/modes/swap) — `from`, `to`, `onSwapStart/Success/Error`
* [Withdraw](/sdk/modes/withdraw) — `from`, `to`, `onWithdrawStart/Success/Error`
* [Earn](/sdk/modes/earn) — `to` with `calldata`, `onEarnStart/Success/Error`