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.

Catalog action EVM Onchain wallet Gas swap

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

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

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  }}'

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.

Was this page helpful?