KyberSwap Quote Skill

Fetch swap quotes from the KyberSwap Aggregator. Given a token pair and amount, retrieve the best route and present a clear summary including expected output, exchange rate, and gas cost.

Input Parsing

The user will provide input like:

1 ETH to USDC on ethereum
100 USDC to WBTC on arbitrum
0.5 WBTC to DAI on polygon
1000 USDT to ETH (default chain: ethereum)

Extract these fields:

amount — the human-readable amount to swap
tokenIn — the input token symbol
tokenOut — the output token symbol
chain — the chain slug (default: ethereum)

Workflow

Step 1: Resolve Token Addresses

Read the token registry at ${CLAUDE_PLUGIN_ROOT}/references/token-registry.md.

Look up tokenIn and tokenOut for the specified chain. Match case-insensitively. Note the decimals for each token.

Aliases to handle:

"ETH" on Ethereum/Arbitrum/Optimism/Base/Linea/Unichain → native token address
"MATIC" or "POL" on Polygon → native token address
"BNB" on BSC → native token address
"AVAX" on Avalanche → native token address
"MNT" on Mantle → native token address
"S" on Sonic → native token address
"BERA" on Berachain → native token address
"RON" on Ronin → native token address
"XTZ" on Etherlink → native token address
"MON" on Monad → native token address

If a token is not found in the registry: Use the fallback sequence described at the bottom of ${CLAUDE_PLUGIN_ROOT}/references/token-registry.md:

KyberSwap Token API (preferred) — search whitelisted tokens first: https://token-api.kyberswap.com/api/v1/public/tokens?chainIds={chainId}&name={symbol}&isWhitelisted=true via WebFetch. Pick the result whose symbol matches exactly with the highest marketCap. If no whitelisted match, retry without isWhitelisted (only trust verified or market-cap tokens). If still nothing, browse page=1&pageSize=100 (try up to 3 pages).
CoinGecko API (secondary fallback) — search CoinGecko for verified contract addresses if the Token API doesn't have it.
Ask user manually (final fallback) — if CoinGecko also fails, ask the user to provide the contract address. Never guess or fabricate addresses.

Step 2: Check Token Safety

For any token not in the built-in registry and not a native token, check the honeypot/FOT API. (Note: registry tokens are assumed safe, but a compromised proxy token could theoretically be updated. For high-value swaps involving proxy tokens, consider checking the safety API even for registry tokens.)

GET https://token-api.kyberswap.com/api/v1/public/tokens/honeypot-fot-info?chainId={chainId}&address={tokenAddress}

Via WebFetch, check both tokenIn and tokenOut:

If isHoneypot: true — warn the user that this token is flagged as a honeypot (cannot be sold after buying). Display the warning prominently.
If isFOT: true — warn the user that this token has a fee-on-transfer (tax: {tax}%). The actual received amount will be less than the quoted output. Display the adjusted estimate: adjustedAmount = quotedAmount * (1 - tax/100). Example: if the quote shows 100 USDC and tax is 5%, display "~95 USDC after tax".

Step 3: Convert Amount to Wei

amountInWei = amount * 10^(tokenIn decimals)

The result must be a plain integer string with no decimals, no scientific notation, and no separators.

For wei conversion, use a deterministic method instead of relying on AI mental math:

python3 -c "print(int(AMOUNT * 10**DECIMALS))"
# or
echo "AMOUNT * 10^DECIMALS" | bc

Verify known reference values: 1 ETH = 1000000000000000000 (18 decimals), 1 USDC = 1000000 (6 decimals)

Examples:

1 ETH (18 decimals) = 1000000000000000000
100 USDC (6 decimals) = 100000000
0.5 WBTC (8 decimals) = 50000000

Step 4: Call the Routes API (GET request)

Read the API reference at ${CLAUDE_PLUGIN_ROOT}/references/api-reference.md for the full specification.

Make the request using WebFetch:

URL: https://aggregator-api.kyberswap.com/{chain}/api/v1/routes?tokenIn={tokenInAddress}&tokenOut={tokenOutAddress}&amountIn={amountInWei}&source=ai-agent-skills
Prompt: Return the full JSON response body

Step 5: Handle Errors

Check the code field in the JSON response and handle common errors inline:

| Code | Message | Quick Fix | |------|---------|-----------| | 4008 | Route not found | No liquidity for this pair/amount. Remove source filters (includedSources/excludedSources), try a smaller amount, or retry after a few seconds. | | 4011 | Token not found | Verify the token address is correct for this chain. Use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for native tokens. Check spelling and 0x prefix. | | 4000 | Bad request | Read the fieldViolations array in the response. Common issues: amountIn must be a plain integer string in wei (no decimals, no scientific notation), addresses must be 42-char hex with lowercase 0x. | | 4010 / 40011 | No eligible pools / Filtered sources (observed behavior, not in public API docs) | Remove includedSources/excludedSources filters. The pair may have liquidity only on specific DEXs. | | 404 | Chain not found | Check chain slug spelling. Supported: ethereum, bsc, polygon, arbitrum, optimism, avalanche, base, linea, mantle, sonic, berachain, ronin, unichain, hyperevm, plasma, etherlink, monad, megaeth. | | 4990 | Request canceled | Retry the request. Likely a timeout or network issue. | | 500 | Internal server error | Verify all addresses are valid hex. Retry — may be transient. |

For any error code not listed above, or for deeper troubleshooting, refer to ${CLAUDE_PLUGIN_ROOT}/skills/error-handling/SKILL.md for the comprehensive error reference.

Step 5b: Dust Amount Warning

After getting a successful route, check the USD values from the response:

If amountInUsd < $0.10 — warn the user: "This swap amount is extremely small (~$X). Gas fees (~$Y) will far exceed the swap value. Consider using a larger amount."
If gasUsd > amountInUsd — warn the user: "Gas cost (~$Y) exceeds the swap value (~$X). This trade is uneconomical."

Still show the quote, but include the warning prominently before the results table.

Step 6: Format the Output

Present the results in this format:

## KyberSwap Quote

**{amount} {tokenIn} → {amountOut} {tokenOut}** on {Chain}

| Detail | Value |
|---|---|
| Input | {amount} {tokenIn} (~${amountInUsd}) |
| Output | {amountOut} {tokenOut} (~${amountOutUsd}) |
| Rate | 1 {tokenIn} = {rate} {tokenOut} |
| Gas estimate | {gas} units (~${gasUsd}) |
| L1 fee (L2 only) | ~${l1FeeUsd} *(omit this row on L1 chains or if `l1FeeUsd` is `"0"`)* |
| Router | `{routerAddress}` |

### Route
{For each split in the route, show: tokenIn → tokenOut via [exchange name]}

Calculating the output amount: Convert amountOut from wei back to human-readable using tokenOut's decimals:

humanAmount = amountOut / 10^(tokenOut decimals)

Calculating the rate:

rate = humanAmountOut / humanAmountIn

Display rates with appropriate precision (up to 6 significant digits).

Structured JSON Output

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

```json
{
  "type": "kyberswap-quote",
  "chain": "{chain}",
  "tokenIn": {
    "symbol": "{tokenIn}",
    "address": "{tokenInAddress}",
    "decimals": {tokenInDecimals},
    "amount": "{amount}",
    "amountWei": "{amountInWei}",
    "amountUsd": "{amountInUsd}"
  },
  "tokenOut": {
    "symbol": "{tokenOut}",
    "address": "{tokenOutAddress}",
    "decimals": {tokenOutDecimals},
    "amount": "{amountOut}",
    "amountWei": "{amountOutWei}",
    "amountUsd": "{amountOutUsd}"
  },
  "rate": "{rate}",
  "gas": "{gas}",
  "gasUsd": "{gasUsd}",
  "routerAddress": "{routerAddress}"
}
```

This JSON block enables downstream agents or plugins to parse the quote result without scraping the markdown table.

Important Notes

Always read both ${CLAUDE_PLUGIN_ROOT}/references/token-registry.md and ${CLAUDE_PLUGIN_ROOT}/references/api-reference.md before making API calls.
Never guess token addresses. Always verify from the registry or via the Token API / search.
If the user doesn't specify a chain, default to ethereum.
If the user specifies a chain not listed in references/api-reference.md, query https://common-service.kyberswap.com/api/v1/aggregator/supported-chains via WebFetch to check if the chain is supported. Look for a matching chainName with state: "active" or state: "new". Use the chainName value as the path slug.
The quote is informational only — no transaction is built or submitted.

Additional Resources

Reference Files

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

Example Files

Working examples in ${CLAUDE_PLUGIN_ROOT}/skills/quote/references/:

basic-quote.md — Simple ETH to USDC quote on Ethereum
multi-chain-quote.md — Quote on L2 chain with L1 fee

Troubleshooting

For error codes not covered in Step 5, or for advanced debugging (PMM/RFQ errors, edge cases), refer to ${CLAUDE_PLUGIN_ROOT}/skills/error-handling/SKILL.md.