kybernetwork/pool-info

KyberSwap Pool Info Skill

Look up pool metadata (DEX, fee tier, tokens, TVL, volume, APR) using the KyberSwap Earn Service API. Supports both pool address lookup and token pair search across all indexed DEXes and chains.

Primary use cases:

1. Pool lookup — Get details for a specific pool address (or V4 pool ID)
2. Pool search — Find the best pools for a token pair by TVL, volume, or APR
3. DEX auto-detection — Identify which DEX a pool belongs to (used by zap skills)

API Endpoint

GET https://earn-service.kyberswap.com/api/v1/explorer/pools

Parameters

| Parameter | Required | Description | Example | |---|---|---|---| | chainIds | Yes | Chain ID(s), comma-separated | 42161, 1,42161,8453 | | q | No | Search query — pool address or token symbols | 0xc696..., ETH USDC | | protocol | No | DEX filter (matches exchange field in response) | uniswapv3, uniswap-v4, pancake-v3 | | page | No | Page number (default: 1) | 1 | | limit | No | Results per page (default: 10) | 10 | | interval | No | Stats interval (default: 24h) | 24h, 7d | | sortBy | No | Sort field | tvl, volume, apr, earnFee | | orderBy | No | Sort order | DESC, ASC | | userAddress | No | User wallet address (for position context) | 0xeF8A... |

Response Fields (per pool)

| Field | Type | Description | |---|---|---| | address | string | Pool address (20-byte) or pool ID (32-byte for V4) | | exchange | string | DEX identifier — e.g. uniswapv3, uniswap-v4, pancake-v3 | | feeTier | number | Fee tier as percentage (e.g. 0.05 = 0.05%) | | tvl | number | Total value locked in USD | | volume | number | Trading volume in USD (for the interval) | | apr | number | Total APR (percentage) | | lpApr | number | LP APR from trading fees only | | kemApr | number | KyberSwap Elastic Mining APR (external rewards) | | earnFee | number | Fees earned in USD (for the interval) | | tokens[] | array | Token objects: address, symbol, logoURI | | chain | object | Chain info: id, name, logoUrl |

Exchange to ZaaS DEX ID Mapping

The exchange field in the API response maps to the ZaaS API dex parameter:

| exchange value | ZaaS dex parameter | |---|---| | uniswapv3 | DEX_UNISWAPV3 | | uniswap-v4 | DEX_UNISWAP_V4 | | pancake-v3 | DEX_PANCAKESWAPV3 | | sushiswap-v3 | DEX_SUSHISWAPV3 | | aerodrome-cl | DEX_AERODROMECL | | camelot-v3 | DEX_CAMELOTV3 | | quickswap-v3-uni | DEX_QUICKSWAPV3UNI | | quickswap-v3-algebra | DEX_QUICKSWAPV3ALGEBRA | | metavault-v3 | DEX_METAVAULTV3 | | thruster-v3 | DEX_THRUSTERV3 |

General rule: Uppercase the exchange value, replace - with _, and prefix with DEX_. Special cases exist — when in doubt, cross-reference with ${CLAUDE_PLUGIN_ROOT}/references/dex-identifiers.md.

Input Parsing

The user will provide input like:

• pool info 0xc6962004f452be9203591991d15f6b388e09e8d0 on arbitrum
• find ETH/USDC pools on arbitrum
• best pool for WBTC/ETH on ethereum by TVL
• what DEX is pool 0xc696... on arbitrum
• top 5 uniswapv3 pools on base by volume
• pool APR for 0x7fcd... on arbitrum

Extract these fields:

• query — pool address/ID or token pair (e.g. ETH USDC)
• chain — the chain slug (default: ethereum)
• protocol — optional DEX filter (e.g. uniswapv3, uniswap-v4)
• sortBy — sort field (default: tvl)
• limit — number of results (default: 5 for search, 1 for address lookup)

Workflow

Step 1: Resolve Chain ID

Map the chain slug to chain ID using ${CLAUDE_PLUGIN_ROOT}/references/supported-chains.md.

Step 2: Query the API

Via WebFetch:

For pool address lookup:

GET https://earn-service.kyberswap.com/api/v1/explorer/pools?chainIds={chainId}&page=1&limit=1&interval=24h&q={poolAddress}

For token pair search:

GET https://earn-service.kyberswap.com/api/v1/explorer/pools?chainIds={chainId}&page=1&limit={limit}&interval=24h&sortBy={sortBy}&orderBy=DESC&q={token0}+{token1}

For DEX-filtered search:

GET https://earn-service.kyberswap.com/api/v1/explorer/pools?chainIds={chainId}&page=1&limit={limit}&interval=24h&sortBy={sortBy}&orderBy=DESC&protocol={protocol}&q={searchQuery}

Add the X-Client-Id: ai-agent-skills header.

Step 3: Handle Empty Results

If the API returns 0 results:

• For address lookup: "Pool {address} not found on {chain}. It may not be indexed by KyberSwap, or the chain may be wrong."
• For token pair search: "No pools found for {token0}/{token1} on {chain}. Try a different chain or check token symbols."
• Suggest the user try without the protocol filter if one was applied.

Step 4: Format the Output

Single pool (address lookup):

## Pool Info — {token0}/{token1} on {Chain}

| Detail | Value |
|---|---|
| Pool Address | `{address}` |
| DEX | {exchange} |
| Fee Tier | {feeTier}% |
| Token 0 | {token0.symbol} (`{token0.address}`) |
| Token 1 | {token1.symbol} (`{token1.address}`) |
| TVL | ${tvl} |
| 24h Volume | ${volume} |
| APR | {apr}% |
| LP APR | {lpApr}% |
| 24h Fees Earned | ${earnFee} |

Multiple pools (search):

## {token0}/{token1} Pools on {Chain} (sorted by {sortBy})

| # | DEX | Fee | TVL | 24h Volume | APR | Pool Address |
|---|---|---|---|---|---|---|
| 1 | {exchange} | {feeTier}% | ${tvl} | ${volume} | {apr}% | `{address}` |
| 2 | ... | ... | ... | ... | ... | ... |

Structured JSON Output

After the markdown table, include a JSON block:

```json
{
  "type": "kyberswap-pool-info",
  "chain": "{chain}",
  "chainId": {chainId},
  "query": "{query}",
  "pools": [
    {
      "address": "{address}",
      "exchange": "{exchange}",
      "dex": "{DEX_IDENTIFIER}",
      "feeTier": {feeTier},
      "token0": {"symbol": "{symbol}", "address": "{address}"},
      "token1": {"symbol": "{symbol}", "address": "{address}"},
      "tvl": {tvl},
      "volume": {volume},
      "apr": {apr},
      "lpApr": {lpApr},
      "earnFee": {earnFee}
    }
  ]
}
```

DEX Auto-Detection (for zap skills)

When a zap skill receives a pool address without a DEX identifier, use this API to detect the DEX:

GET https://earn-service.kyberswap.com/api/v1/explorer/pools?chainIds={chainId}&page=1&limit=1&interval=24h&q={poolAddress}

Extract the exchange field and map it to the ZaaS dex parameter using the Exchange to ZaaS DEX ID Mapping table above.

If the pool is not indexed (0 results), fall back to asking the user to specify the DEX.

Error Handling

HTTP Error Codes

| Code | Meaning | Action | |---|---|---| | 400 | Bad request | Check query parameters: chainIds, q, protocol. | | 404 | Not found | Check endpoint URL and chain ID. | | 429 | Rate limited | Wait and retry with exponential backoff. | | 500 | Internal server error | Retry after a brief delay. If persistent, the service may be down. |

For any error not listed here, refer to ${CLAUDE_PLUGIN_ROOT}/skills/error-handling/SKILL.md.

Important Notes

• This skill is read-only — no transactions are built or submitted.
• The API indexes pools across many DEXes. Not all pools are indexed — very new or low-liquidity pools may be missing.
• V4 pools use 32-byte pool IDs as the address field (e.g. 0x864a...03a8).
• The feeTier is a percentage (e.g. 0.05 means 0.05%), not basis points.
• APR values are annualized from the selected interval — 24h APR can be volatile.
• Use sortBy=tvl for the most liquid pools, sortBy=apr for highest yield, sortBy=volume for most active.

Troubleshooting

| Issue | Resolution | |---|---| | Pool not found | Pool may not be indexed. Try without chain filter or verify the address on a block explorer. | | Wrong DEX returned | The exchange field is authoritative. If it doesn't match expectations, the pool may have been deployed by a different DEX. | | Stale data | APR and volume are based on the interval parameter. Use 7d for more stable averages. | | V4 pool not found by ID | V4 pool indexing may lag. Try searching by token pair with protocol=uniswap-v4 instead. |