Skip to main content

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.
The exchange (CEX) flow requires your app to be added to the allowlist. Contact us to get access.
See Source selection for all paymentMethod values and the from options each accepts.

Props

Required

Destination (optional)

Source selection (optional)

Set paymentMethod to control how the user funds: 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:

Fund method list (optional)

Control which funding methods are shown to the user:

Lifecycle callbacks

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

Transfer from a CEX

QR code / address deposit

Restrict to specific funding methods

Show only fiat and exchange onramps, hide the rest:

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:
To open the exchange flow directly instead of showing the funding method selector:
To restrict which exchanges appear, pass an exchanges array:
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:
  1. User selects an exchange from the list.
  2. An OAuth popup opens to the exchange’s login.
  3. After authentication, a transfer confirmation is shown with the amount, token, and destination.
  4. User confirms and the withdrawal is initiated from their exchange account.
  5. 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. Where the transfer lands: The exchange sends directly to the destination chain when it can: the destination has to be a stablecoin (USDC or USDT) the active exchanges list on that chain, at the contract Mesh reports delivering. The intent is then a same-chain relay. Anything else lands as USDC on Base and Trails bridges from there. The exchange’s holdings are listed on every chain it can send them to, not only Base. The transfer waits for a priced preview before it is offered, and a preview the linked account’s balance can’t cover is refused rather than started. useMeshLandingToken, resolveMeshLandingToken and MESH_FALLBACK_LANDING_TOKEN are exported from 0xtrails if you need the same resolution outside the widget. 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:
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.

Minimum purchase

Meld’s purchase window for the country, fiat currency, landing token and payment method is read before any quote is requested. An amount under the minimum is never quoted: the submit button is disabled and reads Minimum purchase is <min> <currency>. When the destination’s own landing has a minimum the amount can’t meet, the flow tries USDC on Base, whose window may be lower; that landing’s own window still applies. A window Meld doesn’t report leaves the decision to the quote. Stripe keeps its own fixed Minimum purchase is $1.00. To drive this outside the widget, use useMeldPurchaseLimits.

Onramp fees

Quote details show an Onramp (<provider>) row for card and exchange funding. When the provider reports the split, Network fee and Provider fee sub-rows appear under it; a component the provider reports as zero shows as $0.00 rather than hiding both.
  • Meld fees are in the user’s selected fiat currency.
  • Stripe shows the fee estimate on the checkout screen, then replaces it with the fees Stripe reports on the session once payment is under way, on the pending and receipt screens.
  • Mesh prices the transfer before the Link flow opens and shows it as the Onramp row; inside Link the previewed institution, network gas and client fees replace it.

Provider selector

Each provider row carries the provider’s logo beside its name, from the cached Meld service providers list, with a lettered placeholder when no logo is listed or the image fails to load. The destination-token figure sits under an Estimated amount caption: it is a projection of the provider’s payout, not the fiat the user spends. Rows compare like for like: providers you didn’t select are projected through the selected provider’s quote.

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.
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()).

See also