Fund

Overview

Fund mode implements input-driven deposit flows where users select the amount they want to send. The widget routes funds from any supported chain and token to the destination automatically. Trade type: EXACT_INPUT — user specifies input amount, variable output after fees.

Quick start

Fund supports four payment methods: connected wallet, crypto transfer (QR/address), fiat on-ramp, and exchange (CEX). Set paymentMethod to open a specific flow, or omit it to let the user choose.

import { Fund } from '0xtrails/widget'

// Fiat on-ramp — user buys crypto with a card
<Fund
  apiKey="YOUR_API_KEY"
  paymentMethod="CREDIT_DEBIT_CARD"
  from={{ currency: "USD", amount: 100 }}
  to={{ recipient: "0xYourAddress", token: "USDC", chain: "base" }}
  onFundingSuccess={({ intentId }) => console.log("funded", intentId)}
/>

// CEX transfer — user sends from their exchange account
<Fund
  apiKey="YOUR_API_KEY"
  paymentMethod="EXCHANGE"
  from={{ exchange: "coinbase" }}
  to={{ recipient: "0xYourAddress", token: "USDC", chain: "base" }}
/>

The exchange (CEX) flow requires your app to be added to the allowlist. Contact us to get access.

// Connected wallet — user pays from their wallet (default)
<Fund
  apiKey="YOUR_API_KEY"
  paymentMethod="CONNECTED_WALLET"
  to={{ recipient: "0xYourAddress", token: "USDC", chain: "base" }}
/>

// Fully open — let the user pick their preferred method
<Fund apiKey="YOUR_API_KEY" />

See Source selection for all paymentMethod values and the from options each accepts.

Props

Required

Prop	Type	Description
`apiKey`	`string`	Trails API key

Destination (optional)

Prop	Type	Description
`to.recipient`	`string`	Wallet or contract address that receives the funds
`to.token`	`string`	Destination token — symbol or contract address
`to.chain`	`ChainIdentifier`	Destination chain — name, ID, or viem Chain
`to.defaultToken`	`string`	Default token — user can change
`to.defaultChain`	`ChainIdentifier`	Default chain — user can change
`to.calldata`	`string`	ABI-encoded calldata to execute after funds arrive
`to.supportedChains`	`ChainIdentifier[]`	Restrict destination chains the user can pick
`to.supportedTokensByChain`	`SupportedTokensByChainConfig[]`	Per-chain destination token allowlist

Source selection (optional)

Set paymentMethod to control how the user funds:

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

The from prop is fully typed based on the selected paymentMethod. TypeScript will narrow the allowed fields automatically, so only valid options for that method are accepted. When paymentMethod is set, the from object applies to that method:

// Fiat on-ramp with pre-selected currency and amount
<Fund
  apiKey="YOUR_API_KEY"
  paymentMethod="CREDIT_DEBIT_CARD"
  from={{ currency: "EUR", amount: 100 }}
  to={{ token: "USDC", chain: "base" }}
/>

// Exchange onramp from Coinbase
<Fund
  apiKey="YOUR_API_KEY"
  paymentMethod="EXCHANGE"
  from={{ exchange: "coinbase" }}
  to={{ token: "USDC", chain: "base" }}
/>

Fund method list (optional)

Control which funding methods are shown to the user:

Prop	Type	Description
`fundMethodsList`	`FundMethodListOption[]`	Ordered list: `"connected-wallet"`, `"crypto-transfer"`, `"cc-onramp"`, `"exchange"`
`hideUnlistedFundMethods`	`boolean`	Hide methods not in `fundMethodsList` (default: `false`)
`hideSwap`	`boolean`	Hide the swap tab in the fund UI (default: `false`)
`hideWallets`	`string[]`	Wallet addresses to exclude from the source wallet list
`defaultInputMode`	`"fiat" \| "token"`	Default amount input mode

Lifecycle callbacks

Callback	Signature	When it fires
`onFundingStart`	`({ sessionId }) => void`	User begins the funding flow. Fires before quoting, so no `intentId` yet
`onFundingSuccess`	`({ sessionId, intentId }) => void`	Funding completes successfully
`onFundingError`	`({ sessionId, intentId, error }) => void`	Funding encounters an error

intentId identifies the intent behind this flow and is what you pass to the Trails API or Trailscan to look it up. It is null for passthrough quotes. See Callback payloads.

Examples

Buy crypto with a credit card

import { Fund } from '0xtrails/widget'

<Fund
  apiKey="YOUR_API_KEY"
  paymentMethod="CREDIT_DEBIT_CARD"
  from={{ currency: "EUR", amount: 100 }}
  to={{ token: "USDC", chain: "base" }}
  onFundingSuccess={({ intentId }) => console.log("funded", intentId)}
/>

Transfer from a CEX

<Fund
  apiKey="YOUR_API_KEY"
  paymentMethod="EXCHANGE"
  from={{ token: "USDC", chain: "base", exchange: "coinbase" }}
  to={{ token: "KAT", chain: "katana" }}
/>

QR code / address deposit

<Fund
  apiKey="YOUR_API_KEY"
  paymentMethod="CRYPTO_TRANSFER"
  to={{
    recipient: "0x...",
    token: "USDC",
    chain: "base",
  }}
/>

Restrict to specific funding methods

Show only fiat and exchange onramps, hide the rest:

<Fund
  apiKey="YOUR_API_KEY"
  to={{ token: "USDC", chain: "base" }}
  fundMethodsList={["cc-onramp", "exchange"]}
  hideUnlistedFundMethods={true}
/>

Exchange onramp

Users can transfer directly from a CEX account (Coinbase, Binance, Robinhood, and others) without leaving your app. The OAuth connection and transfer are handled automatically — Trails receives the funds and routes them to the destination. No separate account or additional API keys are required. Pass the onramp prop to enable the exchange flow. At minimum, set environment:

<Fund
  apiKey="YOUR_API_KEY"
  onramp={{
    mesh: {
      environment: 'production',
    },
  }}
/>

To open the exchange flow directly instead of showing the funding method selector:

<Fund
  apiKey="YOUR_API_KEY"
  paymentMethod="EXCHANGE"
  onramp={{
    mesh: {
      environment: 'production',
    },
  }}
  to={{ recipient: "0xYourAddress", token: "USDC", chain: "base" }}
  onFundingSuccess={({ intentId }) => console.log("funded", intentId)}
/>

To restrict which exchanges appear, pass an exchanges array:

<Fund
  apiKey="YOUR_API_KEY"
  onramp={{
    mesh: {
      environment: 'production',
      exchanges: ['coinbase', 'robinhood'],
    },
  }}
/>

Each entry names an exchange brand, not a single Mesh integration: 'robinhood' keeps every Robinhood integration Mesh offers, and 'binanceUs' is a separate brand from 'binance'. Matching ignores case, spaces, hyphens and underscores. An entry that is not a known brand matches a Mesh integration key or integration id exactly. The picker lists exchanges in allowlist order, and an empty or omitted list keeps every exchange. Brand names are the keys of MESH_EXCHANGE_ALIASES, exported from 0xtrails. For development and testing, use environment: 'sandbox'. A yellow banner is shown inside the widget when sandbox is active. How the auth flow works:

User selects an exchange from the list.
An OAuth popup opens to the exchange’s login.
After authentication, a transfer confirmation is shown with the amount, token, and destination.
User confirms and the withdrawal is initiated from their exchange account.
Once detected on-chain, Trails routes the funds to the destination.

The widget shows a pending state while the exchange processes the withdrawal. Session tokens are stored locally for 5 minutes so the user does not have to re-authenticate if they retry. Troubleshooting:

Exchange list is empty — confirm apiKey is valid; the exchange list fetch requires a valid API key.
Popup blocked — trigger the flow from a user gesture (button click) rather than programmatically, and encourage users to allow popups for your domain.
Session expired — the exchange session is valid for 5 minutes; a “Refresh Session” button appears if it expires.

Card onramp

The Credit or debit card funding method opens a provider picker titled “Pay by card”: Stripe, Meld, or a country-based automatic pick when only one is available. From [email protected] card purchases land on the destination chain’s token when the provider supports it, falling back to USDC on Base. To restrict which card providers appear, pass cardProviders on the onramp prop:

<Fund
  apiKey="YOUR_API_KEY"
  onramp={{
    cardProviders: ['stripe', 'meld'],
  }}
/>

cardProviders accepts "stripe" and "meld". Omit it to offer every provider the deployment advertises; unknown values are ignored, and a list with no known value behaves like no list. See Stripe Onramp.

Protocol deposit with dynamic calldata

For ERC-4626 vaults and staking contracts where the deposit amount is a function parameter, use TRAILS_HYDRATE_PLACEHOLDER_AMOUNT. Trails replaces it with the actual bridged/swapped output at execution time.

import { Fund } from '0xtrails/widget'
import { TRAILS_HYDRATE_PLACEHOLDER_AMOUNT } from '0xtrails'
import { encodeFunctionData } from 'viem'

const depositCalldata = encodeFunctionData({
  abi: [{
    name: 'deposit',
    type: 'function',
    stateMutability: 'nonpayable',
    inputs: [
      { name: 'amount', type: 'uint256' },
      { name: 'receiver', type: 'address' },
    ],
    outputs: [{ name: 'shares', type: 'uint256' }],
  }],
  functionName: 'deposit',
  args: [TRAILS_HYDRATE_PLACEHOLDER_AMOUNT, '0xReceiverAddress'],
})

<Fund
  apiKey="YOUR_API_KEY"
  to={{
    recipient: "0xYearnVault",
    token: "USDC",
    chain: "katana",
    calldata: depositCalldata,
  }}
  onFundingSuccess={({ intentId }) => console.log("deposited", intentId)}
/>

Use TRAILS_HYDRATE_PLACEHOLDER_AMOUNT when the deposit amount is a function parameter and the user selects the amount. Do not use it for functions that read balance internally (e.g. depositAll()).

SDK Documentation

Overview

Quick start

Props

Required

Destination (optional)

Source selection (optional)

Fund method list (optional)

Lifecycle callbacks

Examples

Buy crypto with a credit card

Transfer from a CEX

QR code / address deposit

Restrict to specific funding methods

Exchange onramp

Card onramp

Protocol deposit with dynamic calldata

See also

​Overview

​Quick start

​Props

​Required

​Destination (optional)

​Source selection (optional)

​Fund method list (optional)

​Lifecycle callbacks

​Examples

​Buy crypto with a credit card

​Transfer from a CEX

​QR code / address deposit

​Restrict to specific funding methods

​Exchange onramp

​Card onramp

​Protocol deposit with dynamic calldata

​See also

Overview

Quick start

Props

Required

Destination (optional)

Source selection (optional)

Fund method list (optional)

Lifecycle callbacks

Examples

Buy crypto with a credit card

Transfer from a CEX

QR code / address deposit

Restrict to specific funding methods

Exchange onramp

Card onramp

Protocol deposit with dynamic calldata

See also