Skip to main content
All builders are exported from 0xtrails. Amount fields accept human-readable decimal strings (e.g., "0.5" for 0.5 USDC), raw bigint values, or dynamic() for runtime resolution.

​
swap

Executes a token exchange via Uniswap V3 or SushiSwap V3. Trade type is inferred from which amount field you provide: amountIn produces EXACT_INPUT; amountOut produces EXACT_OUTPUT. 
import { swap } from "0xtrails";

swap({
  tokenIn: "USDC",
  tokenOut: "WETH",
  amountIn: "100",       // EXACT_INPUT: spend exactly 100 USDC
  // amountOut: "0.05",  // EXACT_OUTPUT: receive exactly 0.05 WETH
  feeTier: 3000,         // optional; default 0.3%
  slippage: 0.005,       // optional; default from provider config
})
ParameterTypeDescription
tokenInstringInput token symbol or address
tokenOutstringOutput token symbol or address
amountInstring | bigint | dynamicAmount to spend (use for EXACT_INPUT)
amountOutstring | bigint | dynamicAmount to receive (use for EXACT_OUTPUT)
feeTiernumberPool fee tier in basis points; default 3000 (0.3%)
slippagenumberSlippage tolerance; overrides provider default
providerstringForce a specific swap provider ("uniswap" or "sushiswap")

​
Low-level swap utilities

For advanced use cases that need pre-flight pricing or manual call construction:
UtilityDescription
quoteSwap({ tokenIn, tokenOut, amountIn, chainId })Returns a price quote without signing
getPool({ tokenA, tokenB, feeTier, chainId })Returns the pool address for a token pair
swapExactInputSingle(params)Builds an approval + swap call array for exact input
swapExactOutputSingle(params)Builds an approval + swap call array for exact output

​
lend

Supplies tokens to a lending market. Use useEarnMarkets to discover available marketId values. 
import { lend } from "0xtrails";

lend({
  marketId: "aave-v3-usdc-polygon",
  token: "USDC",
  amount: dynamic(), // consume whatever arrived from the previous step
})
ParameterTypeDescription
marketIdstringMarket identifier from useEarnMarkets
tokenstringToken symbol or address to supply
amountstring | bigint | dynamicAmount to lend

​
deposit

Contributes funds to a vault-shaped market: ERC-4626, Morpho, or Yearn vaults. 
import { deposit } from "0xtrails";

deposit({
  marketId: "morpho-usdc-vault",
  token: "USDC",
  amount: "500",
})
ParameterTypeDescription
marketIdstringVault identifier from useEarnMarkets
tokenstringToken symbol or address
amountstring | bigint | dynamicAmount to deposit

​
assertCondition

An onchain guard. If the condition evaluates to false at execution time, the entire batch reverts. Use this to validate state before continuing (minimum balance, deadline, allowance). 
import { assertCondition } from "0xtrails";

assertCondition({
  type: "balance",
  token: "USDC",
  minAmount: "90", // revert if less than 90 USDC arrived
})
assertCondition does not accept dynamic() values, it evaluates concrete conditions against live chain state.
ParameterTypeDescription
type"balance" | "deadline" | "allowance"Condition type
tokenstringToken to check (for balance/allowance conditions)
minAmountstring | bigintMinimum acceptable amount
deadlinenumberUnix timestamp (for deadline conditions)

​
custom

An escape hatch for arbitrary contract calls. Use encodeFunctionData from viem to build the calldata. 
import { custom } from "0xtrails";
import { encodeFunctionData } from "viem";

custom({
  target: "0xCONTRACT_ADDRESS",
  calldata: encodeFunctionData({
    abi: MY_ABI,
    functionName: "myFunction",
    args: [arg1, arg2],
  }),
  value: 0n, // optional ETH value
})
ParameterTypeDescription
targetstringContract address to call
calldatastringABI-encoded function call
valuebigintETH value to send with the call; default 0n

​
ERC-20 helpers

Utilities for constructing standard ERC-20 calls and looking up token metadata.

​
Token registry

import { erc20Utils } from "0xtrails";

// Canonical USDC address and decimals on Base
const { address, decimals } = erc20Utils.USDC.onChain("base");

// Generic symbol lookup
const weth = erc20Utils.token("WETH").onChain(137);

​
Calldata builders

import { approve, transfer, buildApproveAndCall } from "0xtrails";

// Generate approve calldata (raw bigint amount)
const approveTx = approve({ spender: "0xSPENDER", amount: 1000000n });

// Bundle an approve + downstream call
const [approveTx, callTx] = buildApproveAndCall({
  token: "0xUSDC",
  spender: "0xSPENDER",
  call: { target: "0xCONTRACT", calldata: "0x..." },
  // amount defaults to maxUint256 if omitted
});

​
Slippage calculator

import { getAmountWithSlippage } from "0xtrails";

// Apply 50 bps slippage to a minimum output amount
const minOut = getAmountWithSlippage({ amount: 1000000n, slippageBps: 50 });