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

# Swap Tokens (Uniswap)

Swap ERC20 tokens on Uniswap at the best available price on a single chain. Routes through the hosted Uniswap Trading API, which auto-selects across V2/V3/V4 pools, encodes the on-chain slippage floor, and uses Permit2 for approvals. Supports native ETH input and output. Returns the transaction hash and output amount. Ideal for: same-chain token swaps, native-ETH swaps, buying and selling ERC20s.

![Swap Tokens (Uniswap) logo](https://cdn.b3.fun/b3os-icons/uniswap.svg)
Catalog action EVM Onchain wallet Gas swap

Swap ERC20 tokens on Uniswap at the best available price on a single chain. Routes through the hosted Uniswap Trading API, which auto-selects across V2/V3/V4 pools, encodes the on-chain slippage floor, and uses Permit2 for approvals. Supports native ETH input and output. Returns the transaction hash and output amount. Ideal for: same-chain token swaps, native-ETH swaps, buying and selling ERC20s.

**Review wallet and value movement**

This action can require a wallet connector, gas, token movement, or an external side effect. Test with simulation or a controlled amount before using it in a live workflow.

## At a Glance

| Field | Value |
| --- | --- |
| Action ID | `uniswap-swap` |
| Category | EVM Onchain |
| Connector | `wallet` |
| Requires gas | Yes |
| Funds movement | `swap` |
| Tags | `blockchain`, `evm`, `dex`, `swap`, `sell`, `buy`, `token`, `erc20`, `trade`, `uniswap`, `defi` |

## Payload Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tokenIn` | `string` | Yes | Input token address to sell. Use 0x0000000000000000000000000000000000000000 for native ETH. |
| `tokenOut` | `string` | Yes | Output token address to receive. Use 0x0000000000000000000000000000000000000000 for native ETH. |
| `amountIn` | `string` | Yes | Exact input amount to sell, in the token's smallest unit \(wei\). |
| `chainId` | `number` | Yes | Chain to swap on. Uniswap Trading API routing is single-chain only. |
| `recipient` | `string` | No | Output tokens are always delivered to the swapping wallet — the Trading API has no separate destination parameter. If provided, this MUST equal the swapping wallet address; a different address is rejected. Leave empty to use the swapping wallet. |
| `slippageBps` | `number` | No | Slippage tolerance in basis points \(100 = 1%\). Default is 300 \(3%\). Max 8000 \(80%\). The executor converts this to the API's percent form \(slippageTolerance = slippageBps / 100\). |
| `maxPriceImpactBps` | `number` | No | Aborts the swap if the quote's price impact exceeds this many basis points \(1000 = 10%\). Default is 1000 \(10%\). Higher tolerates more impact. Read from the Trading API quote's own priceImpact; a quote that omits a numeric impact proceeds unchecked. |

## Result Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `transactionHash` | `string` | Yes | The Trading API swap transaction hash. |
| `amountOut` | `string` | Yes | Actual output amount received, in the token's smallest unit. Parsed from the transaction receipt's ERC20 Transfer logs for ERC20 output; falls back to the quoted amount for native-ETH output or when the receipt can't be reliably decoded. |
| `amountOutFormatted` | `string \| null` | No | Full-precision, human-readable output amount. Null when tokenOut's decimals could not be resolved. |
| `tokenOutDecimals` | `number \| null` | No | Decimal places of tokenOut, used to format amountOutFormatted. Null if on-chain lookup failed. |
| `tokenOutSymbol` | `string \| null` | No | Symbol of the output token \(e.g. 'USDC'\). Null if on-chain lookup failed. |
| `chainId` | `number` | Yes | Chain the swap executed on. |
| `wrappedTxHash` | `string \| null` | No | Transaction hash of the WETH.deposit\(\) wrap, present only when tokenIn was native and had no direct route — the action wrapped to WETH before swapping. Null on the normal \(no-wrap\) path. |

## Examples

**Workflow node**

```json
{
  "type": "uniswap-swap",
  "payload": {
    "tokenIn": "0x4200000000000000000000000000000000000006",
    "tokenOut": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amountIn": "1000000000000000000",
    "chainId": 8453
  },
  "children": [],
  "connector": {
    "type": "wallet",
    "id": "conn_wallet"
  }
}
```
  **Test with API**

```bash
curl -X POST "https://api.b3os.org/v1/actions/uniswap-swap/test" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "inputs": {
    "tokenIn": "0x4200000000000000000000000000000000000006",
    "tokenOut": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amountIn": "1000000000000000000",
    "chainId": 8453
  }
}'
```

**Use expressions for dynamic values**

Payload fields can use workflow expressions such as `{{$trigger.body.amount}}`, `{{$nodes.fetch.result.price}}`, and `{{$props.asset}}` when the value should come from a trigger, prior node, or reusable workflow prop.