> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polygon.technology/llms.txt
> Use this file to discover all available pages before exploring further.

# Building actions

> Reference for all composable action builders: swap, lend, deposit, assertCondition, and custom.

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`.

```tsx theme={null}
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
})
```

| Parameter   | Type                        | Description                                                   |
| ----------- | --------------------------- | ------------------------------------------------------------- |
| `tokenIn`   | string                      | Input token symbol or address                                 |
| `tokenOut`  | string                      | Output token symbol or address                                |
| `amountIn`  | string \| bigint \| dynamic | Amount to spend (use for EXACT\_INPUT)                        |
| `amountOut` | string \| bigint \| dynamic | Amount to receive (use for EXACT\_OUTPUT)                     |
| `feeTier`   | number                      | Pool fee tier in basis points; default `3000` (0.3%)          |
| `slippage`  | number                      | Slippage tolerance; overrides provider default                |
| `provider`  | string                      | Force a specific swap provider (`"uniswap"` or `"sushiswap"`) |

### Low-level swap utilities

For advanced use cases that need pre-flight pricing or manual call construction:

| Utility                                               | Description                                           |
| ----------------------------------------------------- | ----------------------------------------------------- |
| `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.

```tsx theme={null}
import { lend } from "0xtrails";

lend({
  marketId: "aave-v3-usdc-polygon",
  token: "USDC",
  amount: dynamic(), // consume whatever arrived from the previous step
})
```

| Parameter  | Type                        | Description                             |
| ---------- | --------------------------- | --------------------------------------- |
| `marketId` | string                      | Market identifier from `useEarnMarkets` |
| `token`    | string                      | Token symbol or address to supply       |
| `amount`   | string \| bigint \| dynamic | Amount to lend                          |

## deposit

Contributes funds to a vault-shaped market: ERC-4626, Morpho, or Yearn vaults.

```tsx theme={null}
import { deposit } from "0xtrails";

deposit({
  marketId: "morpho-usdc-vault",
  token: "USDC",
  amount: "500",
})
```

| Parameter  | Type                        | Description                            |
| ---------- | --------------------------- | -------------------------------------- |
| `marketId` | string                      | Vault identifier from `useEarnMarkets` |
| `token`    | string                      | Token symbol or address                |
| `amount`   | string \| bigint \| dynamic | Amount 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).

```tsx theme={null}
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.

| Parameter   | Type                                         | Description                                       |
| ----------- | -------------------------------------------- | ------------------------------------------------- |
| `type`      | `"balance"` \| `"deadline"` \| `"allowance"` | Condition type                                    |
| `token`     | string                                       | Token to check (for balance/allowance conditions) |
| `minAmount` | string \| bigint                             | Minimum acceptable amount                         |
| `deadline`  | number                                       | Unix timestamp (for deadline conditions)          |

## custom

An escape hatch for arbitrary contract calls. Use `encodeFunctionData` from viem to build the calldata.

```tsx theme={null}
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
})
```

| Parameter  | Type   | Description                                   |
| ---------- | ------ | --------------------------------------------- |
| `target`   | string | Contract address to call                      |
| `calldata` | string | ABI-encoded function call                     |
| `value`    | bigint | ETH 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

```tsx theme={null}
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

```tsx theme={null}
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

```tsx theme={null}
import { getAmountWithSlippage } from "0xtrails";

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