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:

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 --json → lfi verify --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

CLI Command Index

Query Commands (read-only)

Mutating Commands (generate transactions)

Parameter Reference

Swap quote & execute (shared parameters):

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

Execute-only additional parameter:

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

Tx estimate parameters:

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

Sign-and-send parameters:

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

Tx send parameters:

• --chain-family — Required. evm or svm
• --chain-id — Required. Numeric chain ID
• --signed-tx — 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 --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 --json
3. Review security result — warn user if any risk flags
4. Get quote: lfi swap quote --in --out --amount --chain-family --chain-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 --json
3. If security flags found → warn user, recommend NOT proceeding
4. Get quote first: lfi swap quote --in --out --amount --chain-family --chain-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 --out --amount --chain-family --chain-id --quote-result '' --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 --chain-id --quote-result '' --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 --chain-id --data '' --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 --chain-id --signed-tx --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 --json — Security check (mandatory)
5. swap → lfi swap quote --in So11111111111111111111111111111111111111112 --out --amount --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
   --json — Mandatory security check
5. swap → lfi swap quote --in --out
   --amount --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 --json — Get holdings
4. Identify largest holding, calculate half amount in smallest unit
5. token → lfi token security sol --json — Security check
6. swap → lfi swap quote --in --out --amount --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

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

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