Skip to main content
All hooks are exported from 0xtrails. No provider wrapper is required.

Quotes

useQuote

Returns a real-time quote for a cross-chain transfer or swap. Pass human-readable decimal amounts; the hook converts to raw amounts using token decimals.
import { useQuote } from "0xtrails";

const { quote, loading, error } = useQuote({
  from: {
    chainId: 1,
    tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC on Ethereum
    amount: "100",
  },
  to: {
    chainId: 137,
    tokenAddress: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", // USDC on Polygon
    recipient: "0xYOUR_WALLET",
  },
});

if (quote) {
  await quote.send(); // execute the quoted route
}

useTrailsSendTransaction

Creates a button-driven transaction flow that opens the SDK modal. Accepts most useQuote parameters.
import { useTrailsSendTransaction } from "0xtrails";

const { sendTransaction, loading } = useTrailsSendTransaction({
  to: {
    chainId: 137,
    tokenAddress: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
    recipient: "0xYOUR_WALLET",
    amount: "50",
  },
});

return <button onClick={sendTransaction}>Fund</button>;

Tokens and balances

useTokenBalances

Returns token balances for an address, sorted by USD value, with price enrichment.
const { balances, loading } = useTokenBalances("0xUSER_ADDRESS");
Each balance includes symbol, name, decimals, contractAddress, chainId, balance, balanceFormatted, balanceDisplay, balanceUsd, and priceUsd.

useTokenList

Returns all tokens supported across all chains.

useSupportedTokens

Filters the token list by chain.
const { tokens } = useSupportedTokens({ chainId: 137 });

useTokenInfo

Returns ERC-20 metadata for a specific token.
const { token } = useTokenInfo({ address: "0xCONTRACT", chainId: 137 });

useAccountTotalBalanceUsd

Returns the aggregate USD value across all tokens for an address.
const { totalUsd } = useAccountTotalBalanceUsd("0xUSER_ADDRESS");

useHasSufficientBalanceToken

Checks whether an address holds enough of a specific token.

useHasSufficientBalanceUsd

Checks whether the total USD balance meets a threshold.

Chains

useSupportedChains

Returns all supported chains.
const { chains, loading } = useSupportedChains();

getChainInfo

Returns metadata for a specific chain by ID.

Intent state

useGetIntent

Fetches the current state of an intent by ID. Use this to display status in a custom UI.
const { intent, loading } = useGetIntent({ intentId: "INTENT_ID" });

useIntentRecover

Recovers funds from a stuck intent. Provides a single recover() call plus manual control.
const { recover } = useIntentRecover({
  intentId: "INTENT_ID",
  walletClient,
  refundToAddress: "0xUSER_ADDRESS",
});

useIntentRecoverWithAddress

For custodial or non-custodial wallet scenarios where you handle signing externally. Returns EIP-712 data via getDataToSign().

Earn markets

useEarnMarkets

Returns lending and vault markets, filterable by chain, provider, type, and sorted by various criteria.
const { markets } = useEarnMarkets({ chain: "polygon", sortBy: "apy" });

useEarnProviders

Returns all supported earn providers.

useEarnBalances

Returns current positions in earn markets for a wallet address.

Transaction history

useAccountTransactionHistory

Returns the transaction history for an address.

useIntentTransactionHistory

Returns history filtered to intent-related transactions.

Error handling

import {
  getIsUserRejectionError,
  getIsNoAvailableQuoteError,
  getIsInsufficientLiquidityError,
  getPrettifiedErrorMessage,
} from "0xtrails";

try {
  await quote.send();
} catch (error) {
  if (getIsUserRejectionError(error)) return; // user cancelled
  if (getIsNoAvailableQuoteError(error)) {
    showError("No route available for this transfer.");
    return;
  }
  showError(getPrettifiedErrorMessage(error));
}

Error detection utilities

UtilityReturns true when
getIsUserRejectionErrorUser rejected the transaction
getIsBalanceTooLowErrorInsufficient token balance
getIsApiErrorAPI returned an error
getIsRateLimitedErrorRate limit hit
getIsNoAvailableQuoteErrorNo route found
getIsInsufficientLiquidityErrorInsufficient liquidity on the route

getPrettifiedErrorMessage

Converts any SDK error into a user-facing string.

Utilities

ExportDescription
dynamic()Placeholder for amounts resolved at execution time, used in to.calldata args or composable actions. See Dynamic values
self()Placeholder for the intent wallet address at execution time
getERC20TransferData({ recipient, amount })Encodes an ERC-20 transfer as calldata
getTrailsClient(config)Initializes the underlying API client outside React
SDK_VERSIONCurrent SDK version string