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:

lfi swap chains

lfi swap tokens

lfi swap quote

lfi tx estimate

lfi swap execute

lfi tx send

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

CLI Command Index

Query Commands (read-only)

lfi swap chains

lfi swap tokens [--chain-id <id>]

Mutating Commands (generate transactions)

lfi swap quote --in <addr> --out <addr> --amount <amt> --chain-family <fam> --chain-id <id>

lfi swap execute --in <addr> --out <addr> --amount <amt> --chain-family <fam> --chain-id <id>

lfi swap sign-and-send --chain-family <fam> --chain-id <id> --quote-result '<json>'

lfi tx estimate --chain-family <fam> --chain-id <id> --data '<json>'

lfi tx send --chain-family <fam> --chain-id <id> --signed-tx <data>

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

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

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

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

lfi token security

swap execute

swap sign-and-send

lfi status --json

lfi whoami --json

sign-and-send

swap quote

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