Kybernetwork Official Position Manager

---
name: position-manager
description: This skill should be used when the user asks to "check my positions", "show my liquidity positions", "list my LP positions", "view my pools", "position status", "show open positions", "show closed positions", "my DeFi positions", "portfolio positions", "position performance", "how are my positions doing", "unclaimed fees", "position APR", "position earnings", or wants to view, monitor, or analyze their DeFi liquidity positions. Queries the KyberSwap Earn Service API to display position details, APR, earnings, unclaimed fees, and portfolio summary across multiple chains and protocols.
metadata:
  tags:
    - defi
    - kyberswap
    - positions
    - liquidity
    - portfolio
    - evm
    - concentrated-liquidity
  provider: KyberSwap
  homepage: https://kyberswap.com
---

# KyberSwap Position Manager Skill

Query and display DeFi liquidity positions. View in-range, out-of-range, and closed positions with APR, earnings, unclaimed fees, and portfolio analytics.

## Input Parsing

The user will provide input like:
- `show my positions for 0xAbc123...`
- `check positions on ethereum for 0xAbc123...`
- `show open positions for 0xAbc123...`
- `show closed positions on arbitrum for 0xAbc123...`
- `how are my positions doing for 0xAbc123...`
- `show my unclaimed fees for 0xAbc123...`
- `position performance for 0xAbc123...`

Extract these fields:
- **wallet** (required) — the wallet address to query
- **chain** (optional) — filter by chain; if omitted, show all chains
- **status** (optional) — position status filter; default: in-range + out-of-range (active positions)
- **keyword** (optional) — filter by token symbol or pool address
- **sort** (optional) — sort order; default: `valueUsd:desc`
- **page** (optional) — page number; default: 1
- **pageSize** (optional) — results per page; default: 10

**If the wallet address is not provided, ask the user for it before proceeding.** Do not guess or use a placeholder address.

**Wallet address validation — reject or warn before proceeding:**
- **Must not be the zero address** (`0x0000000000000000000000000000000000000000`) — this is an invalid address and the query will return no results.
- **Must not be the native token sentinel** (`0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`) — this is a placeholder for native tokens, not a real account.
- **Must match the format** `^0x[a-fA-F0-9]{40}$` — reject malformed addresses.
- **Warn if it matches a known contract address** (e.g., a token address or a router address) — querying positions for a contract is unusual and likely a mistake. Ask the user to confirm.

## Supported Chains

All chains supported by the KyberSwap Earn Service. The API accepts any chain ID. Common ones:

| Chain | Chain ID |
|---|---|
| Ethereum | `1` |
| BNB Smart Chain | `56` |
| Arbitrum | `42161` |
| Polygon | `137` |
| Optimism | `10` |
| Base | `8453` |
| Avalanche | `43114` |
| Linea | `59144` |
| Scroll | `534352` |
| zkSync | `324` |
| Sonic | `146` |
| Berachain | `80094` |
| Ronin | `2020` |

When the user specifies a chain by name, map it to the corresponding chain ID. When viewing positions across all chains, leave the `chainIds` parameter as an empty string.

## Workflow

### Step 1: Build Query Parameters

Map user input to API query parameters:

| User says | API `statuses` value |
|---|---|
| "open positions" / "active positions" (or no filter specified) | `PositionStatusInRange,PositionStatusOutRange` |
| "in-range positions" | `PositionStatusInRange` |
| "out-of-range positions" | `PositionStatusOutRange` |
| "closed positions" | `PositionStatusClosed` |
| "all positions" | `PositionStatusInRange,PositionStatusOutRange,PositionStatusClosed` |

Additional parameter mappings:
- Specific chain → `chainIds={chainId}` (use chain ID number, not slug)
- All chains → `chainIds=` (empty)
- Token keyword → `keyword={symbol}`
- Sort → `sorts=valueUsd:desc` (default)
- Page → `page=1` (default, 1-indexed)
- Page size → `pageSize=10` (default)

### Step 2: Fetch Positions

Make the request using **WebFetch**:

```
URL: https://earn-service.kyberswap.com/api/v1/positions?wallet={wallet}&chainIds={chainIds}&protocols={protocols}&statuses={statuses}&keyword={keyword}&sorts={sorts}&page={page}&pageSize={pageSize}
Prompt: Return the full JSON response body exactly as received.
```

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

### Step 3: Handle Errors

Check the response for errors before proceeding:

| Scenario | Quick Fix |
|---|---|
| No positions found | Wallet has no positions matching the specified filters. Try broadening filters (e.g., "all positions") or verify the wallet address. |
| Invalid wallet address | Validate format: `^0x[a-fA-F0-9]{40}$`. Ensure it is not the zero address or native token sentinel. |
| API error (500) | Retry. The Earn Service may be temporarily unavailable. |
| Rate limited (429) | Wait and retry with exponential backoff. |
| Empty response | The API returned no data. Verify the wallet address and try again. |

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

### Step 4: Parse and Calculate

Extract the following from the response:

**From top-level `data.stats`:**
- Total positions: `stats.totalItems`
- Total portfolio value: `stats.totalValueUsd`
- Total unclaimed fees: `stats.totalUnclaimedFeeUsd`
- Total earned fees: `stats.totalEarnedFeeUsd`
- Total claimed fees: `stats.totalClaimedFeeUsd`
- Total unclaimed rewards: `stats.totalUnclaimedRewardUsd`
- Total claimed rewards: `stats.totalClaimedRewardUsd`
- Total pending rewards: `stats.totalPendingRewardUsd`

**For each position in `data.positions[]`:**
- Token pair: `currentAmounts[0].token.symbol` / `currentAmounts[1].token.symbol`
- Position value: `valueInUSD`
- Current amounts: `currentAmounts[].amount.usdValue` and human amount (`amount / 10^decimals`)
- Provided amounts (initial deposit): `providedAmounts[].amount.usdValue`
- PnL: `sum(currentAmounts usdValue) + sum(unclaimed fee usdValue) - sum(providedAmounts usdValue)`
- Unclaimed fees: `stats.earning.fee.unclaimed[].amount.usdValue`
- APR: `stats.apr.all.30d` (use 30d as default display)
- LP APR: `stats.apr.lp.30d`
- Reward APR: `stats.apr.reward.lm` or `stats.apr.reward.eg` (30d values)
- Earnings: `stats.earning.totalUsd` (24h, 7d, 30d)
- Protocol: `pool.protocol.name`
- Pool address: `pool.address`
- Price range: `extra.priceRange.min` to `extra.priceRange.maxPrice`
- Current pool price: `pool.price`
- Chain: `chain.name` (chain ID: `chain.id`)
- Token ID: `tokenId`
- Token address (NFT manager): `tokenAddress`
- Status: `status`
- Created: `createdAtTime` (unix timestamp)
- Last updated: `lastUpdatedAt` (unix timestamp)

**Status mapping:**
- `PositionStatusInRange` → In Range
- `PositionStatusOutRange` → Out of Range
- `PositionStatusClosed` → Closed

### Step 5: Display Results

**Portfolio Summary (always show first):**

```
## Liquidity Position Portfolio for `{wallet}`

| Metric | Value |
|---|---|
| Total Positions | {totalItems} |
| Total Value | ${totalValueUsd} |
| Total Unclaimed Fees | ${totalUnclaimedFeeUsd} |
| Total Earned Fees | ${totalEarnedFeeUsd} |
```

**Positions Table:**

```
## Active Positions

| # | Chain | Pool | Protocol | Value | APR (30d) | Unclaimed Fees | Status |
|---|---|---|---|---|---|---|---|
| 1 | {chain} | {token0}/{token1} | {protocol} | ${value} | {apr}% | ${fees} | In Range |
| 2 | {chain} | {token0}/{token1} | {protocol} | ${value} | {apr}% | ${fees} | Out of Range |
```

**Detailed position view (when user asks about a specific position or wants details):**

```
## Position #{tokenId} -- {token0}/{token1} on {Chain}

| Detail | Value |
|---|---|
| Protocol | {protocol.name} |
| Pool | `{pool.address}` |
| Token ID | #{tokenId} |
| Status | {status} |
| Value | ${valueInUSD} |
| APR (30d) | {apr.all.30d}% (LP: {apr.lp.30d}% + Rewards: {apr.reward}%) |

### Current Amounts
| Token | Amount | USD Value | Price |
|---|---|---|---|
| {token0} | {amount0} | ${usdValue0} | ${priceUsd0} |
| {token1} | {amount1} | ${usdValue1} | ${priceUsd1} |

### Provided Amounts (Initial Deposit)
| Token | Amount | USD Value |
|---|---|---|
| {token0} | {provided0} | ${providedUsd0} |
| {token1} | {provided1} | ${providedUsd1} |

### Unclaimed Fees
| Token | Amount | USD Value |
|---|---|---|
| {token0} | {fee0} | ${feeUsd0} |
| {token1} | {fee1} | ${feeUsd1} |

### Price Range
| | Value |
|---|---|
| Current Price | {pool.price} |
| Min Range | {extra.priceRange.min} |
| Max Range | {extra.priceRange.maxPrice} |
| In Range | {yes/no} |

### Earnings (30d)
| Period | Earned |
|---|---|
| 24h | ${earning.24h} |
| 7d | ${earning.7d} |
| 30d | ${earning.30d} |
```

If more than 10 positions are returned, note pagination: *"Showing {count} of {total} positions. Use 'show positions page 2' for more."*

### Structured JSON Output

After the markdown tables, always include a JSON code block so other plugins or agents can consume the result programmatically:

````
```json
{
  "type": "kyberswap-position-manager",
  "wallet": "{wallet}",
  "summary": {
    "totalPositions": {totalItems},
    "totalValueUsd": {totalValueUsd},
    "totalUnclaimedFeeUsd": {totalUnclaimedFeeUsd},
    "totalEarnedFeeUsd": {totalEarnedFeeUsd}
  },
  "positions": [
    {
      "tokenId": {tokenId},
      "chain": "{chain}",
      "chainId": {chainId},
      "pool": "{poolAddress}",
      "protocol": "{protocolName}",
      "token0": "{token0Symbol}",
      "token1": "{token1Symbol}",
      "status": "{status}",
      "valueUsd": {valueInUSD},
      "apr30d": {apr},
      "unclaimedFeesUsd": {feeUsd},
      "priceRange": {
        "min": {min},
        "max": {max},
        "current": {currentPrice}
      }
    }
  ]
}
```
````

This JSON block enables downstream agents or plugins to parse the position data without scraping the markdown tables.

### Step 6: Actionable Suggestions

After displaying positions, suggest relevant actions based on position state:

**For out-of-range positions:**
> "Position #{tokenId} is out of range and not earning fees. Consider migrating to a new range: `/zap migrate position #{tokenId} ...`"

**For positions with significant unclaimed fees (> $1 USD):**
> "You have ${fees} in unclaimed fees on position #{tokenId}. Consider zapping out to collect: `/zap out position #{tokenId} on {chain} from {wallet}`"

**For adding more liquidity:**
> "To add more liquidity: `/zap 1 ETH into {pool} on {chain} from {wallet}`"

**For checking token prices:**
> "Check current prices with `/token-info {token0} {token1} on {chain}`"

## API Reference

### Endpoint

```
GET https://earn-service.kyberswap.com/api/v1/positions
```

### Query Parameters

| Parameter | Required | Description |
|---|---|---|
| `wallet` | Yes | Wallet address |
| `chainIds` | No | Comma-separated chain IDs (empty = all chains) |
| `protocols` | No | Filter by protocol |
| `statuses` | No | Comma-separated status values: `PositionStatusInRange`, `PositionStatusOutRange`, `PositionStatusClosed` |
| `keyword` | No | Search by token symbol or pool address |
| `sorts` | No | Sort order, e.g. `valueUsd:desc`, `valueUsd:asc` |
| `page` | No | Page number (1-indexed, default: 1) |
| `pageSize` | No | Results per page (default: 10) |

### Position Object Key Fields

| Field | Type | Description |
|---|---|---|
| `chain` | `{ name, logo, id }` | Chain information |
| `tokenId` | number | NFT token ID |
| `tokenAddress` | string | NFT manager contract address |
| `positionId` | string | Position identifier |
| `wallet` | string | Owner wallet address |
| `liquidity` | string | Liquidity amount |
| `status` | string | `PositionStatusInRange`, `PositionStatusOutRange`, or `PositionStatusClosed` |
| `valueInUSD` | number | Position value in USD |
| `createdAtTime` | number | Unix timestamp of creation |
| `createAtBlock` | number | Block number at creation |
| `lastUpdatedAt` | number | Unix timestamp of last update |
| `stats.apr.all` | `{ 24h, 7d, 30d }` | Combined APR |
| `stats.apr.lp` | `{ 24h, 7d, 30d }` | LP fee APR |
| `stats.apr.reward.lm` | `{ 24h, 7d, 30d }` | Liquidity mining reward APR |
| `stats.apr.reward.eg` | `{ 24h, 7d, 30d }` | Elastic reward APR |
| `stats.earning.totalUsd` | `{ 24h, 7d, 30d }` | Total earnings in USD |
| `stats.earning.fee.unclaimed[]` | array | Unclaimed fee tokens with `{ amount: { usdValue, priceUsd, amount }, token: { logo, symbol, name, decimals, address } }` |
| `stats.earning.fee.claimed[]` | array | Claimed fee tokens (same structure) |
| `currentAmounts[]` | array | Current token amounts in the position |
| `providedAmounts[]` | array | Initial deposit amounts |
| `pool` | object | Pool details: `{ id, address, price, tokenAmounts[], fees[], tickSpacing, protocol: { type, logo, name }, category, hooks }` |
| `extra.priceRange` | `{ min, maxPrice }` | Position price range |
| `id` | number | Internal position ID |

### Response Stats (Top-Level)

| Field | Description |
|---|---|
| `data.stats.totalItems` | Total number of matching positions |
| `data.stats.totalValueUsd` | Sum of all position values |
| `data.stats.totalEarnedFeeUsd` | Total fees earned (all time) |
| `data.stats.totalClaimedFeeUsd` | Total fees claimed |
| `data.stats.totalUnclaimedFeeUsd` | Total unclaimed fees |
| `data.stats.totalClaimedRewardUsd` | Total claimed rewards |
| `data.stats.totalUnclaimedRewardUsd` | Total unclaimed rewards |
| `data.stats.totalPendingRewardUsd` | Total pending rewards |

## Important Notes

- This is a **read-only skill** -- no transactions are built or submitted.
- To add liquidity, use the **zap** skill (`${CLAUDE_PLUGIN_ROOT}/skills/zap/SKILL.md`).
- To remove liquidity, use the **zap** skill's zap-out workflow.
- To migrate positions, use the **zap** skill's migrate workflow.
- Position values and APRs are estimates provided by the KyberSwap Earn Service and may differ slightly from on-chain values.
- Unclaimed fees must be collected via a zap-out or collect transaction.
- Default to showing active (in-range + out-of-range) positions sorted by value if no filter is specified.
- When viewing positions across all chains, the `chainIds` parameter should be an empty string.
- If the user doesn't specify a chain, query all chains.
- Never guess wallet addresses. Always ask the user if not provided.

## Additional Resources

### Reference Files

- **`${CLAUDE_PLUGIN_ROOT}/references/token-registry.md`** -- Token addresses and decimals by chain
- **`${CLAUDE_PLUGIN_ROOT}/references/api-reference.md`** -- Full API specification, error codes, rate limiting

### Related Skills

- **`${CLAUDE_PLUGIN_ROOT}/skills/zap/SKILL.md`** -- Zap in, zap out, and migrate positions
- **`${CLAUDE_PLUGIN_ROOT}/skills/token-info/SKILL.md`** -- Token price and information lookup

### External Documentation

- **KyberSwap Earn:** https://kyberswap.com/earn

## Troubleshooting

| Issue | Resolution |
|---|---|
| No positions found | Verify the wallet address owns liquidity positions. Try "all positions" to include closed ones. Check the wallet on the KyberSwap Earn UI. |
| Missing APR data | Some positions (especially newly created or low-liquidity ones) may not have APR data yet. The Earn Service calculates APR periodically. |
| Stale position data | Position data is indexed periodically. Recent on-chain changes (deposits, withdrawals) may take a few minutes to appear. |
| Chain not showing positions | Verify the chain ID is correct. Try querying all chains (omit `chainIds`) to see if positions exist on a different chain. |
| Rate limited | The Earn Service may rate-limit requests. Wait and retry. |

For error codes not covered above, or for advanced debugging, refer to **`${CLAUDE_PLUGIN_ROOT}/skills/error-handling/SKILL.md`**.