Building Actions

import {
  swap,
  lend,
  deposit,
  assertCondition,
  custom,
  dynamic,
  self,
} from '0xtrails'

Amounts are generally one of:

string — human-readable, e.g. "50" or "0.03". Scaled by the token’s decimals.
bigint — raw wei, used as-is.
dynamic() — “use the intent wallet’s runtime balance at execution time”, accepted only on fields that spend a balance. See Dynamic Values.

`swap` — on-chain token swap

Trade type is inferred from which amount you pass: amountIn → EXACT_INPUT, amountOut → EXACT_OUTPUT. Setting both (or neither) throws. dynamic() is allowed on amountIn for exact-input swaps and maxAmountIn for exact-output swaps. amountOut and minAmountOut must be concrete values because they are execution thresholds.

// EXACT_INPUT: spend 1 WETH, revert if output < 3000 USDC
swap({
  tokenIn: 'WETH',
  tokenOut: 'USDC',
  amountIn: '1',
  minAmountOut: '3000',
  fee: '0.05', // "0.01" | "0.05" | "0.3" (default) | "1"
})

// EXACT_OUTPUT: receive exactly 3000 USDC, spend at most 2 WETH
swap({
  tokenIn: 'WETH',
  tokenOut: 'USDC',
  amountOut: '3000',
  maxAmountIn: '2',
})

// Route through SushiSwap instead of Uniswap V3
swap({
  provider: 'SUSHISWAP_V3',
  tokenIn: 'USDC',
  tokenOut: 'WETH',
  amountIn: '100',
})

Defaults:

fee: "0.3" (0.3% pool).
provider: "UNISWAP_V3". If it isn’t deployed on the destination chain, the error tells you to try SushiSwap.
recipient: the intent wallet for the final action; for intermediate actions, output flows back so the next action can consume it. Override only if you want to send output to a third party.

Swap utilities

For anything that isn’t “build calldata for useQuote” — on-chain quoting, pool discovery, raw Call[] composition, address lookups — 0xtrails exports the underlying chain-scoped helpers behind swap. The same adapter shape is exported for both Uniswap V3 and SushiSwap V3: quoteSwap, getPool, swapExactInputSingle, and swapExactOutputSingle.

import { uniswapV3, sushiswapV3 } from '0xtrails'

Low-level helpers take raw bigint wei — use viem’s parseUnits to convert from human-readable amounts. Fee tiers take human strings: "0.01" / "0.05" / "0.3" / "1".

Typical use cases:

Pre-flight quoting — render expected output / price impact in the UI before the user commits, using quoteSwap.
Pool liquidity check — skip a pair or switch fee tier when getPool returns null.
Custom compositions — build Call[] directly and pass them through to.calls (useQuote) or calls (useTrailsSendTransaction) when you need something the typed swap doesn’t cover (e.g. multi-hop paths, permit2, …).

Chain-scoped adapter

uniswapV3.onChain(chain) (or sushiswapV3.onChain(chain)) returns an adapter bound to a specific chain (name or chain ID):

import { uniswapV3 } from '0xtrails'

const uni = uniswapV3.onChain('base')
// or: uniswapV3.onChain(8453)

`quoteSwap`

Query the provider’s V3 quoter — no signing, no broadcast. Use this to render expected output, gas estimate, and price movement before the user commits.

import { parseUnits } from 'viem'

const quote = await uni.quoteSwap({
  type: 'exactInputSingle',
  tokenIn: 'USDC',
  tokenOut: 'WETH',
  fee: '0.05',
  amountIn: parseUnits('100', 6), // 100 USDC
})

// quote.amountOut
// quote.gasEstimate
// quote.initializedTicksCrossed
// quote.sqrtPriceX96After

type can be "exactInputSingle" or "exactOutputSingle". Pass amountIn for exact input quotes. For exact output quotes, pass the desired output amount as amountOutMinimum:

const exactOutputQuote = await uni.quoteSwap({
  type: 'exactOutputSingle',
  tokenIn: 'USDC',
  tokenOut: 'WETH',
  fee: '0.05',
  amountIn: 0n, // ignored for exactOutputSingle
  amountOutMinimum: parseUnits('0.03', 18), // desired WETH output
})

`getPool`

Find the pool address for a pair and fee tier. Returns null when no pool exists — handy for switching fee tier or skipping the pair.

const pool = await uni.getPool({
  token0: 'USDC',
  token1: 'WETH',
  fee: '0.05',
})

if (!pool) {
  // Try a different fee tier or route
}

`swapExactInputSingle`

Build an approval + swap Call[] for an exact-input swap. Pass the calls through to.calls / calls to embed inside an intent, or send them directly from a wallet.

import { parseUnits } from 'viem'

const calls = uni.swapExactInputSingle({
  tokenIn: 'USDC',
  tokenOut: 'WETH',
  fee: '0.05',
  recipient: userEoa,
  amountIn: parseUnits('100', 6),           // 100 USDC
  amountOutMinimum: parseUnits('0.03', 18), // 0.03 WETH floor
})

SushiSwap V3 uses the same fields plus a required deadline:

import { sushiswapV3 } from '0xtrails'
import { parseUnits } from 'viem'

const sushi = sushiswapV3.onChain('base')
const deadline = BigInt(Math.floor(Date.now() / 1000) + 20 * 60)

const calls = sushi.swapExactInputSingle({
  tokenIn: 'USDC',
  tokenOut: 'WETH',
  fee: '0.05',
  recipient: userEoa,
  deadline,
  amountIn: parseUnits('100', 6),
  amountOutMinimum: parseUnits('0.03', 18),
})

`swapExactOutputSingle`

Build an approval + swap Call[] for an exact-output swap.

import { parseUnits } from 'viem'

const calls = uni.swapExactOutputSingle({
  tokenIn: 'USDC',
  tokenOut: 'WETH',
  fee: '0.05',
  recipient: userEoa,
  amountOut: parseUnits('0.03', 18),     // 0.03 WETH exactly
  amountInMaximum: parseUnits('100', 6), // 100 USDC ceiling
})

For SushiSwap V3 exact-output calls, include deadline as well.

Address lookups

Top-level helpers return contract addresses per chain:

uniswapV3.swapRouterAddressOn('base')
uniswapV3.factoryAddressOn('base')

sushiswapV3.swapRouterAddressOn('base')
sushiswapV3.factoryAddressOn('base')

Capability checks

Not every chain has both providers deployed. isSupportedOn returns false instead of throwing — useful for falling back between providers or warning the user.

import { uniswapV3, sushiswapV3 } from '0xtrails'

const adapter = uniswapV3.isSupportedOn('base')
  ? uniswapV3.onChain('base')
  : sushiswapV3.isSupportedOn('base')
    ? sushiswapV3.onChain('base')
    : null

if (!adapter) {
  // Neither provider is deployed on this chain — surface a friendly error.
}

`lend` — supply into a money-market

Use for supported lending markets such as Aave. Use useEarnMarkets to fetch the marketId.

lend({
  marketId: 'base-usdc-aave-v3-lending',
  amount: '50',
})

Optional: receiverAddress defaults to the connected user wallet, so aTokens / fTokens / cTokens land on the user’s EOA automatically. Only override when you want the position to belong to a different owner.

`deposit` — deposit into a vault

Use for vault-shaped markets (ERC-4626, Morpho, Yearn, SummerFi, Sky, …).

deposit({
  marketId: 'base-usdc-pusdc-0x1401d1271c47648ac70cbcdfa3776d4a87ce006b-4626-vault',
  amount: '100',
})

Optional params:

receiverAddress — defaults to the connected user wallet so vault shares land on the user’s EOA.

`assertCondition` — on-chain guard

If the condition is false at execution time the entire batch reverts.

// Ensure the swap really produced >= 2400 USDC
assertCondition({ erc20Balance: { token: 'USDC', gte: '2400' } })

// Native balance check
assertCondition({ nativeBalance: { gte: '0.5' } })

// Deadline (unix timestamp)
assertCondition({ notExpired: { deadline: 1712600000 } })

// Allowance check
assertCondition({
  erc20Allowance: { token: 'USDC', spender: '0x…', gte: '1000' },
})

assertCondition is the only builder that does not accept dynamic() — its values must be known at quote time.

`custom` — arbitrary contract call (escape hatch)

Use when nothing above fits. Pair with buildCall and erc20Utils for ergonomic calldata — see ERC-20 Helpers.

import { custom, erc20Utils } from '0xtrails'
import { encodeFunctionData, parseUnits } from 'viem'

const MY_CONTRACT = '0x0000000000000000000000000000000000001234'
const usdc = erc20Utils.USDC.addressOn('base')

const actions = [
  custom({
    ...erc20Utils.approve({
      tokenAddress: usdc,
      spender: MY_CONTRACT,
      amount: parseUnits('100', 6),
    }),
  }),
  custom({
    to: MY_CONTRACT,
    data: encodeFunctionData({
      abi: stakingAbi,
      functionName: 'stake',
      args: [parseUnits('100', 6)],
    }),
  }),
]

If custom calldata contains a dynamic() amount, pass dynamicAmountToken so the encoder knows which ERC-20 balance to hydrate at execution time. The only exception is a bare ERC-20 approve(spender, dynamic()), where the token is inferred from the call target.

​swap — on-chain token swap

​Swap utilities

​Chain-scoped adapter

​quoteSwap

​getPool

​swapExactInputSingle

​swapExactOutputSingle

​Address lookups

​Capability checks

​lend — supply into a money-market

​deposit — deposit into a vault

​assertCondition — on-chain guard

​custom — arbitrary contract call (escape hatch)

`swap` — on-chain token swap

Swap utilities

Chain-scoped adapter

`quoteSwap`

`getPool`

`swapExactInputSingle`

`swapExactOutputSingle`

Address lookups

Capability checks

`lend` — supply into a money-market

`deposit` — deposit into a vault

`assertCondition` — on-chain guard

`custom` — arbitrary contract call (escape hatch)