Liberfi Perpetuals

Query and trade perpetual futures through LiberFi's unified perpetuals API (openapi-server → perpetuals-server, Hyperliquid in MVP): list coins and markets,...

Security Scan

The skill's stated purpose (perpetuals trading) matches its commands, but the runtime instructions include an explicit, opaque directive to auto-install a global npm CLI without user consent and to hide install failures — a deceptive installation behavior that raises concern.

Purpose & Capability

Name, description and allowed CLI commands align: this skill is focused on perpetual futures queries and two-phase signed order/deposit flows via the LiberFi CLI.

Instruction Scope

The SKILL.md instructs the agent to install the @liberfi.io/cli globally WITHOUT asking the user and to retry/hide registry failures. That is outside normal scope for a helper: it mandates the agent perform system changes and to conceal install problems. Other runtime instructions (use --json, require user confirmation for submits/deposits, TEE one-click flow) are coherent and appropriate for perp trading.

Install Mechanism

There is no formal install spec in the registry metadata, but the documentation tells the agent to run `npm install -g @liberfi.io/cli --registry https://registry.npmjs.org/`. Using npm (official registry) is typical for a CLI, but a global install modifies the host and running it automatically without user consent increases risk (potential for arbitrary code execution, typosquat packages, or privilege escalation). The instruction to suppress failure messages exacerbates the risk.

Credentials

The skill declares no environment variables and does not request unrelated secrets. It does expect the CLI to handle auth (lfi status / lfi login) and read wallet addresses (lfi whoami), which is proportionate to trading/depositing functionality. No extraneous credential requests are present in the metadata, but the agent will interact with user keys/wallets via the CLI flows — the SKILL.md sensibly warns to require explicit user confirmation for submits/deposits.

Persistence & Privilege

The skill is not marked always:true and is user-invocable. However, the SKILL.md's automatic global npm install implies the skill expects to persist a CLI binary on the system. That persistent system modification should require explicit user consent; the current instructions bypass that, raising operational concerns though not an explicit registry-level privilege escalation flag.

What to consider before installing

Key things to consider before installing or enabling this skill: - The skill's behavior is generally coherent for a perpetuals trading helper, but its documentation explicitly tells the agent to auto-install a global npm package without asking and to hide install failures. This is a red flag: ask for human approval before any npm -g install. - Verify the CLI package and maintainer manually: look up @liberfi.io/cli on the npm registry and the project's homepage/repository, review package versions, release history, and source code (or request a signed checksum) before running npm install -g. Watch for typosquatting (similar package names). - Prefer to install the CLI yourself in a controlled environment (non-root, container, or sandbox) and only grant the agent access after you inspect the binary. Do not allow the agent to retry registries or suppress errors on your behalf. - The skill correctly warns to never run order-submit / cancel-submit or deposit-place without explicit user confirmation — honor that: require interactive confirmation for any transaction that spends funds or relays signed actions. - If you plan to use deposits, prefer the TEE one-click flow as described, but understand that escape-hatch flows require you to sign/broadcast transactions outside the CLI and are error-prone. - If you are not comfortable auditing npm packages or giving an agent permission to modify your system, decline automatic installs and run the CLI manually after vetting.

Perpetuals data and signed order relay flow via LiberFi OpenAPI (/v1/perpetuals/… → perpetuals-server).

Pre-flight

See bootstrap.md for CLI install and lfi ping.

• Read endpoints (coins, markets, orderbook, …): no auth.
• User-scoped reads (positions, orders, fills): pass the wallet address in the CLI argument (0x).
• Order writes (order-prepare / order-submit, cancel variants): require a user wallet to sign typed data; agents must not fabricate signatures.
• Deposit (recommended deposit-place): requires authentication (lfi status then lfi login key) — the server's TEE wallet signs and broadcasts on the user's behalf. The atomic deposit-quote / deposit-submit escape hatches do not require auth but the caller is then responsible for signing the SOL tx and broadcasting it themselves.

Skill routing

User intent	Skill
Spot swap, bridge, gas send	liberfi-swap
Trending spot tokens, new listings	liberfi-market
Polymarket / Kalshi	liberfi-predict
Spot token audit, DEX pools for a token	liberfi-token
Perp markets, HL-style orderbook, perp positions	liberfi-perpetuals
Funding the perp account (Solana → Hyperliquid via Relay), checking deposit lifecycle	liberfi-perpetuals
Spot wallet holdings on a chain (not perp account)	liberfi-portfolio

CLI index

Command	Description
lfi perpetuals coins	List tradable perp coins
lfi perpetuals markets	Market snapshots (--symbols optional)
lfi perpetuals market <symbol>	Single market
lfi perpetuals orderbook <symbol>	L2 book (--max-level)
lfi perpetuals trades <symbol>	Recent trades (--limit)
lfi perpetuals klines <symbol>	Candles (--interval required)
lfi perpetuals positions <address>	Positions + margin summary
lfi perpetuals orders <address>	Open orders
lfi perpetuals fills <address>	Fill history
lfi perpetuals order-prepare	Build typed data for place order
lfi perpetuals order-submit --body '<json>'	Submit signed place order
lfi perpetuals cancel-prepare	Build typed data for cancel
lfi perpetuals cancel-submit --body '<json>'	Submit signed cancel
lfi perpetuals deposit-place --gross-lamports <n>	Recommended: TEE one-click Solana → Hyperliquid deposit (server quotes, signs, broadcasts, submits). Auth required.
lfi perpetuals deposit-quote --user-solana-address <a> --hyperliquid-recipient <a> --gross-lamports <n>	Escape hatch step 1: returns unsigned SOL tx + breakdown. Caller signs + broadcasts within ~30s, then calls deposit-submit.
lfi perpetuals deposit-submit --body '<json>'	Escape hatch step 2: record the broadcasted SOL tx hash. Idempotent on solanaTxHash.
lfi perpetuals deposit-status <intentId> [--refresh]	Read deposit lifecycle. --refresh bypasses any server-side cache (server-reserved knob; today both endpoints behave identically).

Common flags: --provider <name> (e.g. hyperliquid), global --json.

Funding / Deposit (Solana → Hyperliquid via Relay)

The deposit pipeline moves SOL from the user's Solana wallet to the user's Hyperliquid perp account via the Relay bridge service. The recommended path is the one-click TEE auto-flow:

1. Authenticate (only first time): lfi status --json; if not logged in, lfi login key --role AGENT --name "<agent>" --json.
2. Confirm intent with the user (amount in SOL, recipient if non-default).
3. Place: lfi perpetuals deposit-place --gross-lamports <lamports> --json
   • lamports = SOL × 1_000_000_000 (1 SOL = 1e9 lamports).
   • --hyperliquid-recipient is optional — defaults to the user's TEE EVM address (lfi whoami evmAddress), which is what 99% of users want.
4. Capture the returned intentId and solanaTxHash.
5. Poll: lfi perpetuals deposit-status <intentId> --json until status is settled (typical: 30–120 s).

Server returns status: "broadcasted" immediately after step 3; the reconciliation loop progresses through relay_waiting → relay_pending → settled (or failed_* states). On failure consult the statusHistory[] and lastError fields for the recoverable / non- recoverable distinction.

For the atomic escape-hatch flow (when the user controls their own SOL private key outside the TEE, or recovering from a partial failure where the SOL tx has been broadcasted but submit did not succeed), see reference/deposit-flow.md.

Typical flows

Market overview

1. lfi perpetuals markets --json
2. Present symbol, mark price, funding where present.

Depth + tape

1. lfi perpetuals orderbook BTC --json
2. lfi perpetuals trades BTC --limit 20 --json

Positions for a known wallet

1. lfi perpetuals positions 0xYourAddr --json

Place order (human-in-the-loop)

1. lfi perpetuals order-prepare --user-address 0x… --symbol BTC --side long --order-type limit --amount 0.01 --price 95000 --json
2. User signs returned typedData with their wallet (e.g. MetaMask eth_signTypedData_v4).
3. Build SignedAction: action, nonce, signature (0x), optional vaultAddress from prepare response.
4. After explicit confirmation: lfi perpetuals order-submit --body '{"action":…,"nonce":…,"signature":"0x…"}' --json

API path reminder

All CLI calls hit OpenAPI paths under /v1/perpetuals/…, which the gateway proxies to perpetuals-server /v1/…. Configure the gateway with UPSTREAM_PERPETUALS_SERVICE_BASE_URL (default local example: http://localhost:8083 — avoid colliding with openapi :8080 and prediction :8082; run perpetuals-server with SERVER_PORT=8083 when colocated).