shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 数据与分析无需 API Key

Liberfi Swap

执行代币兑换并管理链上交易：列出支持的兑换链、浏览可用的兑换代币、获取价格/滑点/路径等兑换报价...

person作者: bombmodhubclawhub
open_in_new仓库download下载资源包

LiberFi Swap & Transaction

Execute token swaps and broadcast transactions using the LiberFi CLI.

Pre-flight Checks

See bootstrap.md for CLI installation and connectivity verification.

This skill's auth requirements:

| Command | Requires Auth | |---------|--------------| | lfi swap chains | No | | lfi swap tokens | No | | lfi swap quote | No | | lfi tx estimate | No | | lfi swap execute | Yes (JWT, uses TEE wallet) | | lfi tx send | Yes (JWT, uses TEE wallet) |

Authentication pre-flight for swap execute / tx send:

  1. Run lfi status --json
  2. If not authenticated:
    • Agent: lfi login key --role AGENT --json
    • Human: lfi login <email> --json → lfi verify <otpId> <code> --json
  3. Run lfi whoami --json to confirm wallet addresses

Additional pre-flight for swap operations:

  • Confirm the user knows the input/output token addresses (or help look them up via lfi swap tokens or lfi token search)
  • Note: --account is now optional for swap execute. If omitted, the server uses the authenticated user's TEE wallet address automatically.

Skill Routing

| If user asks about... | Route to | |-----------------------|----------| | Token search, price, details, security | liberfi-token | | Token K-line, candlestick chart | liberfi-token | | Token holders, smart money traders | liberfi-token | | Trending tokens, market rankings | liberfi-market | | Newly listed tokens | liberfi-market | | Wallet holdings, balance, PnL | liberfi-portfolio | | Wallet activity, transaction history | liberfi-portfolio |

CLI Command Index

Query Commands (read-only)

| Command | Description | Auth | |---------|-------------|------| | lfi swap chains | List all supported swap chains | No | | lfi swap tokens [--chain-id <id>] | List available swap tokens | No |

Mutating Commands (generate transactions)

| Command | Description | Auth | |---------|-------------|------| | lfi swap quote --in <addr> --out <addr> --amount <amt> --chain-family <fam> --chain-id <id> | Get a swap quote | No | | lfi swap execute --in <addr> --out <addr> --amount <amt> --chain-family <fam> --chain-id <id> | Execute swap via TEE wallet | Yes | | lfi swap sign-and-send --chain-family <fam> --chain-id <id> --quote-result '<json>' | Build, sign, and broadcast swap in one step via TEE wallet | Yes | | lfi tx estimate --chain-family <fam> --chain-id <id> --data '<json>' | Estimate transaction fee / gas | No | | lfi tx send --chain-family <fam> --chain-id <id> --signed-tx <data> | Broadcast a signed transaction | Yes |

Parameter Reference

Swap quote & execute (shared parameters):

  • --in <address> — Required. Input token address
  • --out <address> — Required. Output token address
  • --amount <amount> — Required. Input amount in smallest unit (lamports, wei, etc.)
  • --chain-family <family> — Required. evm or svm
  • --chain-id <id> — Required. Numeric chain ID (e.g. 0 for Solana mainnet, 1 for Ethereum)
  • --slippage-bps <bps> — Slippage tolerance in basis points (e.g. 100 = 1%)
  • --swap-mode <mode> — ExactIn (default) or ExactOut

Execute-only additional parameter:

  • --account <address> — Optional. Wallet address override. If omitted, the server uses the authenticated user's TEE wallet automatically. Requires authentication.
  • --quote-result <json> — Opaque quote result JSON from a prior swap quote call (pass through without modification)

Tx estimate parameters:

  • --chain-family <family> — Required. evm or svm
  • --chain-id <id> — Required. Numeric chain ID
  • --data <json> — Required. Transaction data as JSON string (structure depends on chain family)

Sign-and-send parameters:

  • --chain-family <family> — Required. evm or svm
  • --chain-id <id> — Required. Numeric chain ID
  • --quote-result <json> — Required. Full quote result JSON from a prior lfi swap quote call (pass through without modification)
  • --slippage-bps <bps> — Override slippage tolerance in basis points

Tx send parameters:

  • --chain-family <family> — Required. evm or svm
  • --chain-id <id> — Required. Numeric chain ID
  • --signed-tx <data> — Required. Signed transaction in base64 or hex encoding

Operation Flow

List Supported Chains

  1. Fetch chains: lfi swap chains --json
  2. Present: Show chain name, chain ID, chain family (evm/svm)
  3. Suggest next step: "Which chain do you want to trade on?"

Find Available Tokens

  1. Fetch tokens: lfi swap tokens --chain-id <id> --json
  2. Present: Show token name, symbol, address
  3. Suggest next step: "Which tokens do you want to swap?"

Get a Swap Quote

  1. Collect inputs: Input token, output token, amount, chain family, chain ID
  2. (mandatory) Run security check: lfi token security <chain> <outputTokenAddress> --json
  3. Review security result — warn user if any risk flags
  4. Get quote: lfi swap quote --in <in> --out <out> --amount <amt> --chain-family <fam> --chain-id <id> --json
  5. Present: Show input amount, expected output amount, price impact, slippage, route
  6. Suggest next step: "Want to execute this swap?"

Execute a Swap (Full Flow)

Authentication pre-flight (do this first):

lfi status --json   # check session
# If not authenticated:
lfi login key --role AGENT --json   # agent
# or: lfi login <email> --json → lfi verify <otpId> <code> --json
lfi whoami --json   # confirm evmAddress / solAddress
  1. Collect inputs: Input/output tokens, amount, chain
  2. (mandatory) Security check: lfi token security <chain> <outputTokenAddress> --json
  3. If security flags found → warn user, recommend NOT proceeding
  4. Get quote first: lfi swap quote --in <in> --out <out> --amount <amt> --chain-family <fam> --chain-id <id> --json
  5. Present swap summary to user:
    • Input: X amount of TokenA
    • Output: ~Y amount of TokenB
    • Slippage: Z%
    • Estimated fees (if available)
  6. (mandatory) Wait for explicit user confirmation
  7. Execute swap: lfi swap execute --in <in> --out <out> --amount <amt> --chain-family <fam> --chain-id <id> --quote-result '<quoteJson>' --json
    • The server signs the transaction using the authenticated user's TEE wallet.
    • No manual signing step required — the response contains the result or signed tx hash.
  8. Suggest next step: "Swap submitted! You can track it on the block explorer."

Execute Swap in One Step (sign-and-send)

Use this when you already have a quote result and want to build, sign, and broadcast in a single call — no separate swap execute needed.

Authentication pre-flight (do this first):

lfi status --json   # check session
# If not authenticated:
lfi login key --role AGENT --json   # agent
# or: lfi login <email> --json → lfi verify <otpId> <code> --json
  1. Collect inputs: Chain family, chain ID, and the quote result JSON from a prior swap quote call
  2. (mandatory) Security check already performed during the quote step — do not skip
  3. Present swap summary and wait for explicit user confirmation
  4. Execute: lfi swap sign-and-send --chain-family <fam> --chain-id <id> --quote-result '<quoteJson>' --json
    • The server builds the transaction, signs it via the authenticated user's TEE wallet, and broadcasts it in one step.
  5. Suggest next step: "Swap submitted! You can track it on the block explorer."

When to use sign-and-send vs execute:

  • Use sign-and-send when you already have a quote_result and want a single atomic call.
  • Use execute when you want to specify input/output tokens and amount directly (it internally fetches a quote).

Estimate Transaction Fee

  1. Estimate: lfi tx estimate --chain-family <fam> --chain-id <id> --data '<txJson>' --json
  2. Present: Show estimated gas/fee in native token and USD equivalent
  3. Suggest next step: "Ready to send?"

Broadcast Signed Transaction (when using external wallet)

When the user has signed the transaction externally (not using TEE wallet):

  1. (mandatory) Ensure authenticated: lfi status --json
  2. (mandatory) Final confirmation: "Are you sure you want to broadcast this transaction? This is irreversible."
  3. Send: lfi tx send --chain-family <fam> --chain-id <id> --signed-tx <signedData> --json
  4. Present: Show transaction hash
  5. Suggest next step: "Transaction submitted! You can track it on the block explorer."

Cross-Skill Workflows

"I want to swap SOL for USDC"

Full flow: auth → token → swap

  1. auth → lfi status --json — Check session; if not authed → lfi login key --json
  2. auth → lfi whoami --json — Confirm solAddress
  3. token → lfi token search --q "USDC" --chains sol --json — Find USDC address on Solana
  4. token → lfi token security sol <usdcAddress> --json — Security check (mandatory)
  5. swap → lfi swap quote --in So11111111111111111111111111111111111111112 --out <usdcAddress> --amount <amt> --chain-family svm --chain-id 0 --json — Get quote
  6. Present quote summary, wait for user confirmation
  7. swap → lfi swap execute --in ... --out ... --amount ... --chain-family svm --chain-id 0 --json — Server signs via TEE wallet

"What's the best price to buy this trending token?"

Full flow: auth → market → token → swap

  1. auth → lfi status --json — Check session; if not authed → lfi login key --json
  2. market → lfi ranking trending sol 1h --limit 5 --json — Get trending tokens
  3. User picks a token
  4. token → lfi token security sol <address> --json — Mandatory security check
  5. swap → lfi swap quote --in <baseToken> --out <address> --amount <amt> --chain-family svm --chain-id 0 --json
  6. Present quote with price impact analysis, wait for confirmation
  7. swap → lfi swap execute --in ... --out ... --json — Server signs via TEE wallet

"Check my wallet, then sell half of my biggest holding"

Full flow: auth → portfolio → token → swap

  1. auth → lfi status --json — Check session; if not authed → lfi login key --json
  2. auth → lfi whoami --json — Get solAddress / evmAddress
  3. portfolio → lfi wallet holdings sol <solAddress> --json — Get holdings
  4. Identify largest holding, calculate half amount in smallest unit
  5. token → lfi token security sol <tokenAddress> --json — Security check
  6. swap → lfi swap quote --in <tokenAddress> --out <baseToken> --amount <halfAmt> --chain-family svm --chain-id 0 --json
  7. Present quote, wait for confirmation
  8. swap → lfi swap execute --in ... --out ... --json — Server signs via TEE wallet

Suggest Next Steps

| Just completed | Suggest to user | |----------------|-----------------| | Chain list | "Which chain do you want to trade on?" / "想在哪条链上交易？" | | Token list | "Which tokens do you want to swap?" / "想兑换哪些代币？" | | Swap quote | "Want to execute this swap?" / "要执行这笔兑换吗？" | | Swap execute (TEE) | "Swap submitted via your LiberFi TEE wallet!" / "已通过LiberFi TEE钱包提交兑换！" | | Swap sign-and-send | "Swap built, signed, and broadcast in one step!" / "兑换已一步完成构建、签名并广播！" | | Fee estimate | "Ready to send?" / "准备好发送了吗？" | | Tx send | "Transaction submitted! Track it on the block explorer." / "交易已提交！可在区块浏览器上查看。" | | Not authenticated | "Please log in first: lfi login key --json" / "请先登录：lfi login key --json" |

Edge Cases

  • Insufficient balance: If the swap execute fails with an insufficient balance error, inform the user and suggest checking their holdings via lfi wallet holdings
  • Slippage exceeded: If the quote shows high price impact (>5%), warn the user and suggest reducing the amount or increasing slippage tolerance
  • Invalid token address: Validate format before calling the API; ask user to verify the address
  • Unknown chain family: Only evm and svm are supported; if user mentions a chain, map it to the correct family (e.g. Solana → svm, Ethereum/BSC/Base → evm)
  • Amount format error: Remind user that amounts must be in smallest unit (lamports for SOL = amount * 10^9, wei for ETH = amount * 10^18)
  • Transaction already submitted: If tx send fails, warn that the transaction may have already been broadcast; check status before retrying
  • Quote expired: Quotes have a limited validity window; if too much time passes, get a new quote before executing
  • Network timeout: Retry once after 3 seconds; if still fails, suggest checking connectivity

Common Pitfalls

| Pitfall | Correct Approach | |---------|-----------------| | Using human-readable amounts (e.g. "1 SOL") | Convert to smallest unit first: 1 SOL = 1,000,000,000 lamports | | Skipping security check before swap | ALWAYS run lfi token security on the output token first | | Executing swap without user confirmation | ALWAYS show quote summary and wait for explicit "yes" | | Passing modified quote_result to execute / sign-and-send | Pass the quote_result JSON through WITHOUT any modification | | Calling swap execute or swap sign-and-send without authentication | Check lfi status --json first; re-authenticate if needed | | Assuming a wallet address without checking | Call lfi whoami --json to get the confirmed evmAddress / solAddress | | Retrying failed tx send without checking | The tx may have been submitted; check on-chain status first | | Using sign-and-send when you don't yet have a quote | Call swap quote first to get the quote result, then pass it to sign-and-send |

Security Notes

See security-policy.md for global security rules.

Skill-specific rules:

  • Swap and transaction operations are HIGH RISK — they can move funds irreversibly
  • NEVER execute swap execute or tx send without explicit user confirmation
  • ALWAYS run token security on the output token before presenting a swap quote
  • If the security audit reveals honeypot or high tax flags, strongly recommend the user NOT proceed
  • The quote_result field is opaque — pass it through as-is; do not interpret, modify, or display its raw content
  • Transaction amounts in smallest unit are easy to get wrong — always double-check with the user: "You want to swap X SOL (= Y lamports), correct?"
  • After broadcasting, provide the transaction hash so the user can independently verify on a block explorer