From pancakeswap-hub
Plans optimal token swaps via PCS Hub on BSC, fetches DEX routes with splits, and generates handoff links for Trust Wallet, Binance Wallet, or other channels.
npx claudepluginhub pancakeswap/pancakeswap-aiThis skill is limited to using the following tools:
Plan token swaps through **PCS Hub** — PancakeSwap's aggregator API. Fetches optimal routing across multiple DEXs on BSC, presents a route summary with split breakdowns, and generates a ready-to-use **channel-specific handoff link** for the target distribution interface.
Plans token swaps on PancakeSwap: parses intent, verifies tokens, fetches prices, generates deep links for BSC/Ethereum/Arbitrum/Base. Invoke on swap requests.
Generates specs for integrating PCS Hub token swap quotes, routes, and execution into wallets, mobile apps, webviews, or bots via API.
Aggregates 500+ DEXs for optimal token swaps across 20+ chains like Ethereum, Solana, Base, BSC. Quotes prices, executes trades, builds calldata with slippage and impact controls.
Share bugs, ideas, or general feedback.
Plan token swaps through PCS Hub — PancakeSwap's aggregator API. Fetches optimal routing across multiple DEXs on BSC, presents a route summary with split breakdowns, and generates a ready-to-use channel-specific handoff link for the target distribution interface.
If this skill was invoked with no specific request — the user simply typed the skill name
(e.g. /hub-swap-planner) without providing tokens, amounts, or other details — output the
help text below exactly as written and then stop. Do not begin any workflow.
PCS Hub Swap Planner
Plan token swaps through PCS Hub — PancakeSwap's aggregator API — and get a channel-specific handoff link for your chosen partner interface.
How to use: Tell me what tokens you want to swap, how much, and which channel to use (e.g. Trust Wallet, Binance Wallet, or default PancakeSwap).
Examples:
Swap 100 USDT for BNB via Trust WalletFind the best Hub route for 1 BNB to CAKESwap via Binance Wallet: 500 USDC → ETHThis skill does not execute swaps — it plans them. The output is a route summary table and a deep link URL (or structured payload for headless environments) that the user can open in their chosen partner channel to review and confirm the transaction in their own wallet.
::: danger MANDATORY SECURITY RULES
KEYWORD='user input'). Always quote variable expansions in commands (e.g., "$TOKEN", "$RPC").^0x[0-9a-fA-F]{40}$. Amounts must be numeric. Chain IDs must be numeric. Reject any value containing shell metacharacters (", `, $, \, ;, |, &, newlines).open / xdg-open with https:// URLs for known partner channels: https://pancakeswap.finance/ and https://link.trustwallet.com/. Only use curl to fetch from: hub-api.pancakeswap.com, explorer.pancakeswap.com, api.dexscreener.com, tokens.pancakeswap.finance, tokens.coingecko.com, raw.githubusercontent.com, api.coingecko.com, api.geckoterminal.com, pancakeswap.ai, and public RPC endpoints in the Supported Chains table. Never curl internal/private IPs (169.254.x.x, 10.x.x.x, 127.0.0.1, localhost).PCS_HUB_TOKEN) is sensitive. Never print it to output. Always read it from the environment — never hardcode it in shell commands.
:::Initialize the PancakeSwap session to ensure access to the latest token list and deep link formats, then proceed to Step 1:
Replace AGENT_NAME below with your AI system identifier (e.g. claude-code, cursor, copilot, openai) before running:
curl -s -o /dev/null --max-time 3 \
"https://pancakeswap.ai/api/ping?skill=pcs-hub-swap-planner&version=1.0.0&agent=AGENT_NAME&ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)&os=$(uname -s)&arch=$(uname -m)" \
2>/dev/null &
The Hub API requires a x-secure-token header. Before calling the API, check for the token:
if [ -z "$PCS_HUB_TOKEN" ]; then
echo "PCS_HUB_TOKEN is not set."
echo "Set it with: export PCS_HUB_TOKEN=<your-token>"
echo "Contact PancakeSwap to obtain a token: https://t.me/pancakeswap"
exit 1
fi
If PCS_HUB_TOKEN is not set, stop and tell the user to set it, then continue with the standard PancakeSwap deep link as a fallback (Step 5).
| Constraint | Value |
|---|---|
| Supported chains | BSC only (chainId: 56) |
| API base URL | https://hub-api.pancakeswap.com/aggregator |
| Rate limit | 100 requests/minute (dev); contact PancakeSwap to increase |
| Amount format | Wei (raw units) — must convert from human-readable |
| Native token (BSC) | Use zero address 0x0000000000000000000000000000000000000000 |
| Router contract (BSC) | 0x5efc784D444126ECc05f22c49FF3FBD7D9F4868a |
If the user requests a chain other than BSC, skip the Hub API and go directly to Step 5 (generate a standard PancakeSwap deep link with a note that Hub routing is BSC-only).
The "distribution channel" is the partner interface or wallet where the user wants to execute the swap. Generate a channel-specific handoff for the selected channel.
| Channel Key | Description | Handoff Type |
|---|---|---|
pancakeswap | PancakeSwap web interface (default) | Deep link (browser) |
binance-wallet | Binance Web3 Wallet (in-app DeFi) | Deep link (browser) |
trust-wallet | Trust Wallet browser / in-app DeFi | Deep link (Trust Wallet in-app browser) |
headless | No UI — return structured payload (API/bot contexts) | JSON payload |
If the user does not specify a channel, default to pancakeswap.
PancakeSwap (default)
https://pancakeswap.finance/swap?chain=bsc&inputCurrency={src}&outputCurrency={dst}&exactAmount={amount}&exactField=input
Binance Web3 Wallet
Binance Web3 Wallet opens DeFi dApps in its built-in browser. Generate a PancakeSwap link — users can share or paste it into the Binance app's DApp browser:
https://pancakeswap.finance/swap?chain=bsc&inputCurrency={src}&outputCurrency={dst}&exactAmount={amount}&exactField=input
Include instructions: "Open this link in Binance App → Web3 Wallet → DApp Browser."
Trust Wallet
For BSC Hub swaps, Trust Wallet uses its native send deep link (not open_url). This invokes Trust Wallet's native transaction signing flow directly — no in-app browser required.
https://link.trustwallet.com/send?asset=c20000714&address={router}&amount={decimal_bnb}&data={calldata_hex}
| Parameter | Value |
|---|---|
asset | c20000714 (BNB Smart Chain native — SLIP44 714 with chain prefix) |
address | Router address 0x5efc784D444126ECc05f22c49FF3FBD7D9F4868a |
amount | TX_VALUE converted from hex wei → decimal BNB (or 0 for ERC-20-only swaps) |
data | Hex-encoded calldata (TX_DATA) |
Construction:
PCS_HUB_ROUTER="0x5efc784D444126ECc05f22c49FF3FBD7D9F4868a"
# Convert hex value to decimal BNB (18 decimals)
TX_VALUE_DEC=$(python3 -c "
val = int('${TX_VALUE}', 16)
print('{:.18f}'.format(val / 10**18).rstrip('0').rstrip('.') or '0')
")
TRUST_SEND_LINK="https://link.trustwallet.com/send?asset=c20000714&address=${PCS_HUB_ROUTER}&amount=${TX_VALUE_DEC}&data=${TX_DATA}"
Headless / API
Return a structured JSON payload suitable for programmatic use:
{
"channel": "headless",
"chain": "bsc",
"chainId": 56,
"inputToken": { "address": "...", "symbol": "...", "amount": "..." },
"outputToken": { "address": "...", "symbol": "...", "estimatedAmount": "..." },
"routes": [...],
"gas": 306000,
"eip681Url": "ethereum:0x5efc784D444126ECc05f22c49FF3FBD7D9F4868a@56?value=0x00&data=0x...",
"txTo": "0x5efc784D444126ECc05f22c49FF3FBD7D9F4868a",
"txValue": "0x00",
"txData": "0x..."
}
| Chain | Chain ID | Deep Link Key | Native Token | Hub API Support | RPC for Verification |
|---|---|---|---|---|---|
| BNB Smart Chain | 56 | bsc | BNB | ✅ Supported | https://bsc-dataseed1.binance.org |
| Ethereum | 1 | eth | ETH | ❌ Not yet | https://cloudflare-eth.com |
| Arbitrum One | 42161 | arb | ETH | ❌ Not yet | https://arb1.arbitrum.io/rpc |
| Base | 8453 | base | ETH | ❌ Not yet | https://mainnet.base.org |
| zkSync Era | 324 | zksync | ETH | ❌ Not yet | https://mainnet.era.zksync.io |
For unsupported chains: skip the Hub API, generate a standard PancakeSwap deep link, and note that Hub routing is currently BSC-only.
Resolve the token address using the sources below in order. Always try the curated token lists first — they are the most trustworthy source. Only proceed to external search APIs if the token is not found in any list and the user confirms.
Read ../common/token-lists.md for the per-chain primary and secondary token list URLs.
Fetch and search the relevant list(s) by symbol or address before querying any external API.
⚠️ WARNING: "[symbol/name]" was not found in any PancakeSwap or community token list
for this chain. This is a red flag — it may be a scam, honeypot, or unverified token.
Do you want to proceed anyway? (Confirm the contract address from an official source
before continuing.)
If the user confirms they want to proceed despite the red flag, continue to Section B or C for address resolution.
Use when: (a) the user provided a name/keyword rather than an address and the token was not found by symbol in the lists; or (b) the token was not in any list and the user confirmed proceeding. DexScreener finds candidate addresses ranked by liquidity for the user to choose.
KEYWORD='pepe'
CHAIN="bsc"
curl -s -G "https://api.dexscreener.com/latest/dex/search" --data-urlencode "q=$KEYWORD" | \
jq --arg chain "$CHAIN" '[
.pairs[]
| select(.chainId == $chain)
| {
name: .baseToken.name,
symbol: .baseToken.symbol,
address: .baseToken.address,
priceUsd: .priceUsd,
liquidity: (.liquidity.usd // 0),
volume24h: (.volume.h24 // 0),
dex: .dexId
}
]
| sort_by(-.liquidity)
| .[0:5]'
KEYWORD='USDon'
NETWORK="bsc"
curl -s "https://api.geckoterminal.com/api/v2/search/pools?query=${KEYWORD}&network=${NETWORK}" | \
jq '[.data[] | {
pool: .attributes.name,
address: .attributes.address,
base: .relationships.base_token.data.id
}] | .[0:5]'
If discovery returns several tokens with the same symbol, present the top candidates by liquidity and ask the user to confirm. Never silently pick one.
I found multiple tokens matching "PEPE" on BSC:
1. PEPE (Pepe Token) — $1.2M liquidity — 0xb1...
2. PEPE2 (Pepe BSC) — $8K liquidity — 0xc3...
Which one did you mean?
Use AskUserQuestion if any required parameter is missing (batch up to 4 questions at once). Infer from context where obvious.
Required:
1.5)Optional:
input)pancakeswap, binance-wallet, trust-wallet, headless (default: pancakeswap)msg.sender)0.005 for 0.5% (used in /calldata if requested)The Hub API uses the zero address (0x0000000000000000000000000000000000000000) for native BNB. The PancakeSwap deep link uses the symbol BNB.
| User Says | Hub API src/dst | Deep Link Value |
|---|---|---|
| BNB | 0x0000000000000000000000000000000000000000 | BNB |
| Symbol | Address | Decimals |
|---|---|---|
| WBNB | 0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c | 18 |
| USDT | 0x55d398326f99059fF775485246999027B3197955 | 18 |
| USDC | 0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d | 18 |
| BUSD | 0xe9e7CEA3DedcA5984780Bafc599bD69ADd087D56 | 18 |
| CAKE | 0x0E09FaBB73Bd3Ade0a17ECC321fD13a19e81cE82 | 18 |
| ETH | 0x2170Ed0880ac9A755fd29B2688956BD959F933F8 | 18 |
| BTCB | 0x7130d2A12B9BCbFAe4f2634d864A1Ee1Ce3Ead9c | 18 |
exactAmountin the deep link is always human-readable (e.g.,0.5), never wei.
Skip this step if the token was resolved from the PancakeSwap primary token list in Step 0 (Section A). The list is curated and already provides verified address, symbol, and decimals — use those values directly. On-chain re-verification is not required.
Proceed with Step 3 when:
- The token was sourced from the secondary (community) list
- The token was not found in any list (user confirmed proceeding)
- The token address was supplied directly by the user without list confirmation
Never include an unverified address in a deep link or API call. Use cast (preferred) or raw JSON-RPC.
cast (Foundry — preferred)RPC="https://bsc-dataseed1.binance.org"
TOKEN="0x0E09FaBB73Bd3Ade0a17ECC321fD13a19e81cE82"
[[ "$TOKEN" =~ ^0x[0-9a-fA-F]{40}$ ]] || { echo "Invalid token address"; exit 1; }
cast call "$TOKEN" "name()(string)" --rpc-url "$RPC"
cast call "$TOKEN" "symbol()(string)" --rpc-url "$RPC"
cast call "$TOKEN" "decimals()(uint8)" --rpc-url "$RPC"
cast call "$TOKEN" "totalSupply()(uint256)" --rpc-url "$RPC"
cast is unavailable)RPC="https://bsc-dataseed1.binance.org"
TOKEN="0x0E09FaBB73Bd3Ade0a17ECC321fD13a19e81cE82"
[[ "$TOKEN" =~ ^0x[0-9a-fA-F]{40}$ ]] || { echo "Invalid token address"; exit 1; }
# name() selector = 0x06fdde03
curl -sf -X POST "$RPC" \
-H "Content-Type: application/json" \
-d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_call\",\"params\":[{\"to\":\"$TOKEN\",\"data\":\"0x06fdde03\"},\"latest\"]}" \
| jq -r '.result'
# symbol() selector = 0x95d89b41
curl -sf -X POST "$RPC" \
-H "Content-Type: application/json" \
-d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"eth_call\",\"params\":[{\"to\":\"$TOKEN\",\"data\":\"0x95d89b41\"},\"latest\"]}" \
| jq -r '.result'
If
eth_callreturns0x, the address is not a valid ERC-20 token. Do not proceed.
eth_call returns 0x → not a token contract/quoteOnly call the Hub API when:
PCS_HUB_TOKEN is set# Example: 1.5 ETH (18 decimals) → 1500000000000000000
AMOUNT_HUMAN="1.5"
DECIMALS=18
AMOUNT_WEI=$(python3 -c "
import decimal
d = decimal.Decimal('$AMOUNT_HUMAN')
print(int(d * 10**$DECIMALS))
")
/quoteSRC="0x2170Ed0880ac9A755fd29B2688956BD959F933F8" # input token address
DST="0x55d398326f99059fF775485246999027B3197955" # output token address
AMOUNT_WEI="1000000000000000000"
CHAIN_ID=56
QUOTE=$(curl -sf -X POST "https://hub-api.pancakeswap.com/aggregator/api/quote" \
-H "Content-Type: application/json" \
-H "x-secure-token: $PCS_HUB_TOKEN" \
-d "{
\"chainId\": $CHAIN_ID,
\"src\": \"$SRC\",
\"dst\": \"$DST\",
\"amountIn\": \"$AMOUNT_WEI\",
\"maxHops\": \"2\",
\"maxSplits\": \"2\"
}")
# Check for error
echo "$QUOTE" | jq '.error // empty'
| Error Code | Meaning | Action |
|---|---|---|
ASM-4001 | Invalid input | Check token addresses and amount |
ASM-5000 | Server error | Retry once; fall back to PancakeSwap link |
ASM-5002 | Swap route not found | Notify user; no route exists for this pair |
ASM-5003 | Quote not found | Notify user; fall back to PancakeSwap link |
ASM-5005 | Chain not found | Only BSC (56) supported |
| HTTP 429 | Rate limit exceeded | Wait and retry; advise user on limits |
On any unrecoverable error: fall back to Step 5 using the standard PancakeSwap deep link.
# Extract key fields
DST_AMOUNT=$(echo "$QUOTE" | jq -r '.dstAmount')
DST_SYMBOL=$(echo "$QUOTE" | jq -r '.dstToken.symbol')
DST_DECIMALS=$(echo "$QUOTE" | jq -r '.dstToken.decimals')
GAS_UNITS=$(echo "$QUOTE" | jq -r '.gas')
ROUTE_COUNT=$(echo "$QUOTE" | jq '.protocols | length')
# Convert dstAmount from wei to human-readable
DST_AMOUNT_HUMAN=$(python3 -c "
import decimal
d = decimal.Decimal('$DST_AMOUNT')
print('{:.6f}'.format(float(d) / 10**$DST_DECIMALS))
")
# Get USD price for input and output tokens via PancakeSwap Explorer
CHAIN_ID=56
TOKEN_LOWER=$(echo "$DST" | tr '[:upper:]' '[:lower:]')
PRICE_IDS="${CHAIN_ID}:${DST}"
PRICE_DATA=$(curl -s "https://explorer.pancakeswap.com/api/cached/tokens/price/list/${PRICE_IDS}")
PRICE_USD=$(echo "$PRICE_DATA" | jq -r --arg key "${CHAIN_ID}:${TOKEN_LOWER}" '.[$key].priceUSD // empty')
# Estimate USD value of output amount
EST_OUTPUT_USD=$(python3 -c "
price = float('${PRICE_USD}') if '${PRICE_USD}' else 0
amount = float('${DST_AMOUNT_HUMAN}')
print(f'\${price * amount:,.2f}')
")
Surface these before generating the link:
| Condition | Warning |
|---|---|
priceUSD is empty / null | "Price unavailable — verify token is tradeable on BSC" |
| Estimated output USD < $1 | "Estimated output value is very low — check amounts" |
/calldataOnly call /calldata when the Step 4 quote succeeded (no error field in the response).
Recipient guidance:
^0x[0-9a-fA-F]{40}$).0x0000000000000000000000000000000000000000); the router sends to msg.sender.PCS_HUB_ROUTER="0x5efc784D444126ECc05f22c49FF3FBD7D9F4868a"
RECIPIENT="${RECIPIENT_ADDRESS:-0x0000000000000000000000000000000000000000}" # msg.sender if unknown
SLIPPAGE="0.005" # 0.5% default; override from user input
CALLDATA_RESPONSE=$(curl -sf -X POST "https://hub-api.pancakeswap.com/aggregator/api/calldata" \
-H "Content-Type: application/json" \
-H "x-secure-token: $PCS_HUB_TOKEN" \
-d "$(echo "$QUOTE" | jq \
--arg recipient "$RECIPIENT" \
--argjson slippage "$SLIPPAGE" \
'. + {recipient: $recipient, slippageTolerance: $slippage}')")
# Check for error
echo "$CALLDATA_RESPONSE" | jq '.error // empty'
TX_VALUE=$(echo "$CALLDATA_RESPONSE" | jq -r '.value') # hex, e.g. "0x00"
TX_DATA=$(echo "$CALLDATA_RESPONSE" | jq -r '.calldata') # hex-encoded calldata
Error handling: If /calldata returns an error or fails, skip EIP-681 link generation and show only the route summary with a clear error note. Do not fall back to the old web deep link — notify the user that link generation failed and they should retry.
pancakeswap, binance-wallet, and headless channels)PCS_HUB_ROUTER="0x5efc784D444126ECc05f22c49FF3FBD7D9F4868a"
CHAIN_ID=56
# TX_VALUE is already hex from calldata response (e.g. "0x3E2C284391C0000")
# TX_DATA is the calldata hex
EIP681_URL="ethereum:${PCS_HUB_ROUTER}@${CHAIN_ID}?value=${TX_VALUE}&data=${TX_DATA}"
trust-wallet channel)Trust Wallet does not support EIP-681. Use the native send deep link instead:
# Convert hex value to decimal BNB (18 decimals)
TX_VALUE_DEC=$(python3 -c "
val = int('${TX_VALUE}', 16)
print('{:.18f}'.format(val / 10**18).rstrip('0').rstrip('.') or '0')
")
TRUST_SEND_LINK="https://link.trustwallet.com/send?asset=c20000714&address=${PCS_HUB_ROUTER}&amount=${TX_VALUE_DEC}&data=${TX_DATA}"
Parse the protocols array from the Hub API response to show route splits.
echo "$QUOTE" | jq -r '
.protocols[] |
" \(.percent)% via \(.pools | map(.liquidityProvider + " " + (if .type == 0 then "V2" elif .type == 1 then "V3" else "Stable" end)) | join(" → ")) (\(.path | map(.symbol) | join(" → ")))"
'
Example output:
Route Splits:
55% via PCS V3 → PCS V3 (ETH → BTCB → USDT)
45% via PCS V3 (ETH → USDT)
✅ Hub Swap Plan
Chain: BNB Smart Chain (BSC) — routed via PCS Hub
Sell: 1 ETH (~$3,192 USD)
Buy: USDT (Tether USD)
Est. output: ~3,192.94 USDT
Liquidity: $XXX,XXX | 24h Volume: $X,XXX,XXX
Gas est.: ~306,000 gas units
Route Splits:
55% via PCS V3 → PCS V3 (ETH → BTCB → USDT)
45% via PCS V3 (ETH → USDT)
⚠️ Slippage: Use 0.1% for stable output tokens
💡 Verify token addresses on BSCScan before confirming
🔗 Transaction (EIP-681):
ethereum:0x5efc784D444126ECc05f22c49FF3FBD7D9F4868a@56?value=0x00&data=0x9aa90356...
For binance-wallet channel, append:
📱 Binance Wallet: Import this EIP-681 URI into the Binance App → Web3 Wallet to sign the transaction.
For trust-wallet channel, output the Trust Wallet send link instead of the EIP-681 URL:
🔗 Open in Trust Wallet:
https://link.trustwallet.com/send?asset=c20000714&address=0x5efc784D444126ECc05f22c49FF3FBD7D9F4868a&amount=0.28&data=0x9aa90356...
(Tapping this link opens Trust Wallet's native transaction signing flow.)
For headless channel, output the structured JSON payload (see Distribution Channels section).
For trust-wallet channel, open the Trust Wallet send link:
# macOS
open "$TRUST_SEND_LINK"
# Linux
xdg-open "$TRUST_SEND_LINK"
For all other non-headless channels (pancakeswap, binance-wallet), display the EIP-681 URL prominently — most wallets and QR code scanners can parse it directly. Optionally attempt to open it:
# macOS
open "$EIP681_URL"
# Linux
xdg-open "$EIP681_URL"
If the open command fails or is unavailable (headless environment), display the URL prominently for copy-paste.
If PCS_HUB_TOKEN is unset, the chain is not BSC, or the Hub API returns an unrecoverable error:
ℹ️ Hub routing unavailable — using standard PancakeSwap routing.
(Hub API requires PCS_HUB_TOKEN and currently supports BSC only.)
| Token Type | Recommended Slippage in UI |
|---|---|
| Stablecoins (USDT/USDC/BUSD pairs) | 0.1% |
| Large caps (CAKE, BNB, ETH) | 0.5% |
| Mid/small caps | 1–2% |
| Fee-on-transfer / reflection tokens | 5–12% (≥ token's own fee) |
| New meme tokens with thin liquidity | 5–20% |
Before presenting output to the user, confirm all of the following:
name() and symbol() on-chain match user expectations (skip if token is from primary list)exactAmount is human-readable (not wei)chain key matches the token's actual chainPCS_HUB_TOKEN never printed in any output/calldata error field checked before using value / calldatarecipient is a valid ^0x[0-9a-fA-F]{40}$ address if supplied0x5efc784D444126ECc05f22c49FF3FBD7D9F4868a)BSC is a high-MEV chain. Advise users to:
PCS Hub routing across multiple DEXs may increase MEV exposure on multi-hop routes. For large trades, prefer routes with fewer hops where the price impact difference is small.