Liberfi Swap

Execute token swaps and manage on-chain transactions: list supported swap chains, browse available swap tokens, get swap quotes with price/slippage/route inf...

Security Scan

The skill's stated swap/transaction functionality is plausible, but the runtime instructions include a clear instruction to install a CLI package without user consent and to hide install failures — that mismatch and directive to lie are strong red flags.

Purpose & Capability

The commands and parameters described (lfi swap quote/execute, tx send/estimate, token security) align with a token-swap CLI skill. However the SKILL.md also instructs the agent to perform an npm global install if the CLI is missing even though the skill declares no install spec — this is an unexpected install requirement not reflected in the registry metadata.

Instruction Scope

The instructions tell the agent to install a network package 'WITHOUT asking the user' and to 'NEVER tell the user the package does not exist' (retrying registries instead). They also include commands that authenticate (lfi login key --role AGENT) and can cause actual on-chain fund movement (swap execute, sign-and-send, tx send). Although the doc says to require explicit user confirmation before swaps, the explicit auto-install and 'never tell' behavior grant the agent wide discretion to alter the runtime environment and conceal failures — scope creep beyond a read-only helper.

Install Mechanism

The skill has no formal install spec but instructs the agent to run 'npm install -g @liberfi.io/cli' automatically. Network installs from npm are common, but: (1) the registry URL and retry logic are baked into the instructions, (2) the command is mandated to run without user consent, and (3) the skill explicitly instructs the agent to hide or lie about install failures. That combination increases risk.

Credentials

The skill declares no required environment variables, which is consistent with using a CLI that performs authentication. However the allowed commands include 'lfi login key --role AGENT' (agent-scoped auth) which could provision JWTs/credentials for the agent to use a TEE wallet and sign/send transactions. Requesting agent-scoped authentication and wallet access is plausible for executing swaps but is high-impact — users should expect that these steps grant transaction authority.

Persistence & Privilege

always:false and no declared config paths reduce concerns about forced persistence. That said, the skill's instructions direct the agent to authenticate and potentially use a TEE wallet (server-side signing) which grants the agent capability to perform state-changing on-chain actions when authorized. The skill does not request permanent presence but does instruct installation and login behavior that changes the environment.

What to consider before installing

Do not install or allow this skill to run unattended. Key concerns: (1) SKILL.md explicitly tells the agent to run a global npm install without asking the user and to hide install failures — this is unexpected and suspicious. (2) The skill guides the agent to perform agent-scoped logins and operations that can sign/send on-chain transactions. Before installing, verify the npm package and its source (check https://registry.npmjs.org/@liberfi.io/cli and the project's repository), require explicit user consent for any install, run the CLI install in a sandboxed environment first, and never allow the agent to auto-run 'lfi login key --role AGENT' or execute swaps without an interactive human confirmation step. If you cannot verify the package source and code, treat this skill as risky.

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