Uniswap Pool Lookup
Discover Uniswap V3 and V4 pools for a token pair on a chain, ranked by USD TVL when known (falling back to in-range liquidity L when TVL is unknown). Returns each pool's address/poolId, fee tier, tick spacing, and (for V4) a hash-verified PoolKey ready for v4-add-liquidity. Also returns a top-level `tokens` block with each currency's on-chain decimals + symbol (token0/token1, sorted) so an LP consumer can size raw amounts without a separate decimals lookup. Ideal for: resolving which V4 fee tier or V3 pool to use before adding liquidity.
Catalog action EVM Onchain
Discover Uniswap V3 and V4 pools for a token pair on a chain, ranked by USD TVL when known (falling back to in-range liquidity L when TVL is unknown). Returns each pool's address/poolId, fee tier, tick spacing, and (for V4) a hash-verified PoolKey ready for v4-add-liquidity. Also returns a top-level tokens block with each currency's on-chain decimals + symbol (token0/token1, sorted) so an LP consumer can size raw amounts without a separate decimals lookup. Ideal for: resolving which V4 fee tier or V3 pool to use before adding liquidity.
At a Glance
| Field | Value |
|---|---|
| Action ID | pool-lookup |
| Category | EVM Onchain |
| Connector | Not required |
| Requires gas | No |
| Funds movement | None declared |
| Tags | blockchain, evm, dex, pool, liquidity, read |
Payload Schema
| Field | Type | Required | Description |
|---|---|---|---|
chainId | number | Yes | Chain |
tokenA | string | Yes | First token of the pair. Order does not matter; currencies are sorted internally. |
tokenB | string | Yes | Second token of the pair. |
versions | array | No | Which Uniswap versions to search. Default: both. |
limit | number | No | Max pools to return. Default: 10. |
includeEmpty | boolean | No | Include pools with zero in-range liquidity. Default: true — a pool with no in-range liquidity is still a valid (often the best) liquidity-add target, since you'd be the first LP in range. Callers doing swap-routing, where an empty pool is unusable, should pass false. |
Result Schema
| Field | Type | Required | Description |
|---|---|---|---|
pools | array | Yes | Pools ranked by USD TVL when known, falling back to in-range liquidity L, descending. |
best | object | null | No | The deepest pool, or null when none were found. |
tokens | object | Yes | The pair's two currencies in sorted (token0/token1) order — the same order as a V4 poolKey's currency0/currency1 — each with on-chain decimals + symbol so an LP consumer can size raw amounts without a separate decimals lookup. Populated even when 'pools' is empty. |
degraded | boolean | Yes | True when coverage may be incomplete. |
degradedReason | string | null | No | - |
Examples
json{ "type": "pool-lookup", "payload": { "chainId": 4663, "tokenA": "0xd0601CE157Db5bdC3162BbaC2a2C8aF5320D9EEC", "tokenB": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168" }, "children": []}
bashcurl -X POST "https://api.b3os.org/v1/actions/pool-lookup/test" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "inputs": { "chainId": 4663, "tokenA": "0xd0601CE157Db5bdC3162BbaC2a2C8aF5320D9EEC", "tokenB": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168" }}'
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.