liberfi-swap

Original：🇺🇸 English
Translated

Execute token swaps and manage on-chain transactions: list supported swap chains, browse available swap tokens, get swap quotes with price/slippage/route info, build signable swap transactions, estimate gas/transaction fees, and broadcast signed transactions to the blockchain. Trigger words: swap, trade, exchange, buy token, sell token, convert, swap tokens, trade tokens, exchange tokens, buy crypto, sell crypto, get a quote, swap quote, price quote, how much will I get, swap rate, exchange rate, slippage, swap route, best price, execute swap, confirm swap, make a trade, place a trade, transaction, send transaction, broadcast, submit transaction, tx, send tx, gas fee, transaction fee, fee estimate, gas estimate, how much gas, supported chains, swap chains, which chains, available tokens, swap tokens, chain list, token list, build transaction, sign transaction. Chinese: 兑换, 交易, 买入, 卖出, 换币, 代币兑换, 报价, 兑换报价, 价格, 能换多少, 滑点, 路由, 最优价格, 执行交易, 确认交易, 发送交易, 广播交易, 手续费, Gas费, 费用估算, 支持的链, 可用代币, 构建交易, 签名交易. CRITICAL: Always use `--json` flag for structured output. CRITICAL: Swap amounts are in **smallest unit** (e.g. lamports for SOL, wei for ETH). CRITICAL: ALWAYS run `lfi token security` on the target token BEFORE executing a swap. CRITICAL: NEVER execute swap or send transaction without explicit user confirmation. Do NOT use this skill for: - Token search, info, security audit, K-line → use liberfi-token - Trending tokens or new token rankings → use liberfi-market - Wallet holdings, activity, or PnL stats → use liberfi-portfolio - Token holder or trader analysis → use liberfi-token Do NOT activate on vague inputs like "trade" or "buy" without specifying tokens or amounts.

4installs
Sourceliberfi-io/liberfi-skills
Added on

NPX Install

npx skill4agent add liberfi-io/liberfi-skills liberfi-swap

Tags

Translated version includes tags in frontmatter
crypto-swaponchain-transactionliberfi-clitoken-exchangegas-estimation

SKILL.md Content

View Translation Comparison →

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:
CommandRequires 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, securityliberfi-token
Token K-line, candlestick chartliberfi-token
Token holders, smart money tradersliberfi-token
Trending tokens, market rankingsliberfi-market
Newly listed tokensliberfi-market
Wallet holdings, balance, PnLliberfi-portfolio
Wallet activity, transaction historyliberfi-portfolio

CLI Command Index

Query Commands (read-only)

CommandDescriptionAuth
lfi swap chains
List all supported swap chainsNo
lfi swap tokens [--chain-id <id>]
List available swap tokensNo

Mutating Commands (generate transactions)

CommandDescriptionAuth
lfi swap quote --in <addr> --out <addr> --amount <amt> --chain-family <fam> --chain-id <id>
Get a swap quoteNo
lfi swap execute --in <addr> --out <addr> --amount <amt> --chain-family <fam> --chain-id <id>
Execute swap via TEE walletYes
lfi swap sign-and-send --chain-family <fam> --chain-id <id> --quote-result '<json>'
Build, sign, and broadcast swap in one step via TEE walletYes
lfi tx estimate --chain-family <fam> --chain-id <id> --data '<json>'
Estimate transaction fee / gasNo
lfi tx send --chain-family <fam> --chain-id <id> --signed-tx <data>
Broadcast a signed transactionYes

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):
bash
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):
bash
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 completedSuggest 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

PitfallCorrect 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 swapALWAYS run 
lfi token security
on the output token first
Executing swap without user confirmationALWAYS show quote summary and wait for explicit "yes"
Passing modified quote_result to execute / sign-and-sendPass 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 checkingCall 
lfi whoami --json
to get the confirmed evmAddress / solAddress
Retrying failed tx send without checkingThe 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