React hooks

Hooks are exported from 0xtrails and require TrailsProvider inside a QueryClientProvider. See install.

Quote and execute

useQuote

Returns a live quote for a source and destination, and a send function that executes it. Amounts are human-readable decimal strings. Setting from.amount makes the quote exact input; setting to.amount makes it exact output.

import { useQuote } from "0xtrails";

const { quote, send, isLoadingQuote, quoteError, refetchQuote } = useQuote({
  walletClient,
  from: { token: "USDC", chain: "arbitrum", amount: "100" },
  to: { token: "USDC", chain: "polygon", recipient: recipientAddress },
  slippageTolerance: 0.005,
});

Param	Description
`walletClient`	viem wallet client that signs and sends. Its address owns the quote.
`walletAddress`	Quote owner when no wallet client is connected yet. Lets you preview quotes before connection.
`from`	`token`, `chain`, and optionally `amount`.
`to`	`token`, `chain`, and optionally `recipient`, `amount`, and `calldata`.
`slippageTolerance`	Maximum slippage as a fraction.
`onStatusUpdate`	Called with transaction states as the route runs.

Return	Description
`quote`	The quote, including `originAmountDisplay`, `destinationAmountDisplay`, `fees.totalFeeAmountUsdDisplay`, and `completionEstimateSeconds`.
`send`	Executes the quote. `null` until a quote and wallet are available.
`isLoadingQuote`, `quoteError`	Loading and error state. `quoteErrorPrettified` is a display-ready message.
`refetchQuote`	Requests a fresh quote. The hook does not poll, so call it when the customer returns to a quote they have been viewing.
`abort`	Cancels an in-flight quote.

useTrailsSendTransaction

Opens the widget modal for a destination you set in code, so the customer can pay for it from any token or chain. Pass the destination when you call sendTransaction.

import { useTrailsSendTransaction } from "0xtrails";

const { sendTransaction, isPending } = useTrailsSendTransaction({
  onSuccess: (result) => console.log("Done", result),
});

sendTransaction({
  to: { token: "USDC", chain: "polygon", recipient: merchantAddress, amount: "25" },
});

to takes the same fields as useQuote. Add from to preselect the source token, chain, and amount; omit it to let the customer choose in the modal.

Balances, chains, and tokens

Hook	Returns
`useTokenBalances(address)`	Token balances for an address across supported chains, with USD prices.
`useSupportedChains()`	Chains available for routing.
`useSupportedTokens({ chainId })`	Tokens available on a chain.

Card purchase limits

useMeldPurchaseLimits returns the smallest and largest amount a card or bank purchase accepts for a country, fiat currency, and destination token, before any quote is requested. Pass paymentMethodType to narrow the window to one payment method.

import { useMeldPurchaseLimits, isBelowMeldMinimum } from "0xtrails";

const { fiatLimits } = useMeldPurchaseLimits({
  countryCode: "US",
  fiatCurrency: "USD",
  destinationCurrencyCode: "USDC_POLYGON",
  paymentMethodType: "CREDIT_DEBIT_CARD",
});

if (isBelowMeldMinimum(amount, fiatLimits)) {
  showError(`Minimum purchase is ${fiatLimits.min} ${fiatLimits.currencyCode}`);
}

fiatLimits is null while loading or when no route offers the payment method; treat it as unknown and let the quote decide. The full response is returned as limits, and limitsForPaymentMethod(limits, method) narrows it to one method.

Earn

Hook	Returns
`useEarnMarkets({ chain, provider, type, sortBy, search })`	Earn markets. Sort with `rewardRateDesc` to show the highest rate first.
`useEarnProviders()`	Protocols that offer markets.
`useEarnBalances({ walletAddress, chain })`	A wallet’s positions. Pass `chains` instead of `chain` for several chains at once.

See earn for usage.

Track intents

Hook	Returns
`useGetIntent({ intentId })`	The intent and its status.
`useAccountTransactionHistory({ accountAddress, chainId })`	Past transactions for an address.
`useIntentTransactionHistory({ accountAddress })`	Past intents with their receipts.

Recover stuck funds

Some failed routes produce an automatic refund. Check refundTransaction on the intent receipt to confirm one was submitted. If funds remain at an intent address, useIntentRecover lets the owner sign and send a recovery transaction.

import { useIntentRecover } from "0xtrails";

const { hasIntentBalance, recover } = useIntentRecover({ intentId, walletClient });

if (hasIntentBalance) {
  const { txHash } = await recover();
}

Errors

getPrettifiedErrorMessage(error) turns any SDK error into a message you can show the customer. The getIs...Error helpers, such as getIsUserRejectionError and getIsBalanceTooLowError, identify specific failures.

Overview

Guides

SDK

API reference