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

# V4 DEX Add Liquidity

Add concentrated liquidity to Uniswap V4 pools by minting a position NFT. Supports native ETH (no WETH wrapping), custom price ranges, and hook contracts. Uses Permit2 for approvals. Returns position NFT token ID. Ideal for: V4 liquidity provision, native ETH pools, hook-enabled pools, advanced LP strategies.

![V4 DEX Add Liquidity logo](https://cdn.b3.fun/b3os-icons/uniswap.svg)
Catalog action EVM Onchain wallet Gas send

Add concentrated liquidity to Uniswap V4 pools by minting a position NFT. Supports native ETH (no WETH wrapping), custom price ranges, and hook contracts. Uses Permit2 for approvals. Returns position NFT token ID. Ideal for: V4 liquidity provision, native ETH pools, hook-enabled pools, advanced LP strategies.

**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 | `v4-add-liquidity` |
| Category | EVM Onchain |
| Connector | `wallet` |
| Requires gas | Yes |
| Funds movement | `send` |
| Tags | `blockchain`, `evm`, `dex`, `liquidity`, `lp`, `amm`, `defi`, `v4`, `uniswap`, `nft` |

## Payload Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `chainId` | `number` | Yes | Chain |
| `currency0` | `string` | Yes | First currency address. Use 0x0000000000000000000000000000000000000000 for native ETH. Will be sorted with currency1 to determine actual order. |
| `amount0Desired` | `string` | No | Desired amount of currency0 to add \(in wei/smallest unit\). At least one of amount0Desired or amount1Desired must be provided. |
| `currency1` | `string` | Yes | Second currency address. Use 0x0000000000000000000000000000000000000000 for native ETH. Will be sorted with currency0 to determine actual order. |
| `amount1Desired` | `string` | No | Desired amount of currency1 to add \(in wei/smallest unit\). At least one of amount0Desired or amount1Desired must be provided. |
| `fee` | `number` | Yes | Pool fee in hundredths of a bip, from the pool's PoolKey. Any integer 0-1000000, or 8388608 for a dynamic-fee pool. Common tiers: 100 \(0.01%\), 500 \(0.05%\), 3000 \(0.3%\), 10000 \(1%\). Use pool-lookup to obtain the exact value — it must match the pool's PoolKey or the transaction reverts. |
| `tickSpacing` | `number` | No | Tick spacing for the pool. Optional only for the canonical fee tiers \(100, 500, 3000, 10000\), which have a known default. Required for any other fee — use pool-lookup's returned best.poolKey.tickSpacing, which is meant to feed directly into this field. |
| `hooks` | `string` | No | Hook contract address. Default: 0x0000000000000000000000000000000000000000 \(no hooks / vanilla pool\) |
| `tickLower` | `number` | No | Lower tick of the position. If not provided, uses full range. Must be a multiple of tick spacing. |
| `tickUpper` | `number` | No | Upper tick of the position. If not provided, uses full range. Must be a multiple of tick spacing. |
| `slippageBps` | `number` | No | Slippage tolerance in basis points \(100 = 1%\). Default: 50 \(0.5%\) |
| `deadlineMinutes` | `number` | No | Transaction deadline in minutes from now. Default: 20 |
| `positionManagerAddress` | `string` | No | Optional custom PositionManager address. If not provided, uses default for the chain. |

## Result Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `string` | Yes | - |
| `transactionHash` | `string` | Yes | The transaction hash |
| `tokenId` | `string` | No | NFT position token ID |
| `liquidity` | `string` | No | Amount of liquidity minted |
| `tickLower` | `number` | No | Lower tick of the position |
| `tickUpper` | `number` | No | Upper tick of the position |

## Examples

**Workflow node**

```json
{
  "type": "v4-add-liquidity",
  "payload": {
    "currency0": "0x0000000000000000000000000000000000000000",
    "currency1": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "fee": 3000,
    "chainId": 8453
  },
  "children": [],
  "connector": {
    "type": "wallet",
    "id": "conn_wallet"
  }
}
```
  **Test with API**

```bash
curl -X POST "https://api.b3os.org/v1/actions/v4-add-liquidity/test" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "inputs": {
    "currency0": "0x0000000000000000000000000000000000000000",
    "currency1": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "fee": 3000,
    "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.