LiberFi Perpetuals#

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 (0x) as the positional argument. For first-person queries ("我的持仓", "my positions", etc.), the skill MUST auto-resolve the user's TEE EVM address via lfi status → lfi login key (if needed) → lfi whoami → use the returned evmAddress. NEVER ask the user for an address — the TEE wallet is server-managed and the user does not know it.
• 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 intentSkillSpot swap, bridge, gas sendliberfi-swapTrending spot tokens, new listingsliberfi-marketPolymarket / Kalshiliberfi-predictSpot token audit, DEX pools for a tokenliberfi-tokenPerp markets, HL-style orderbook, perp positionsliberfi-perpetualsFunding the perp account (Solana → Hyperliquid via Relay), checking deposit lifecycleliberfi-perpetualsSpot wallet holdings on a chain (not perp account)liberfi-portfolio

CLI index#

CommandDescriptionlfi perpetuals coinsList tradable perp coinslfi perpetuals marketsMarket snapshots ( --symbols optional)lfi perpetuals market <symbol>Single marketlfi 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 summarylfi perpetuals orders <address>Open orderslfi perpetuals fills <address>Fill historylfi perpetuals order-prepareBuild typed data for place orderlfi perpetuals order-submit --body '<json>'Submit signed place orderlfi perpetuals cancel-prepareBuild typed data for cancellfi perpetuals cancel-submit --body '<json>'Submit signed cancellfi 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

"My ..." auto-flow (CRITICAL — covers "我的", "my", "我自己")#

If the user says "我有什么永续持仓", "我的合约持仓", "my perp positions", "我在 Hyperliquid 上挂了哪些单", "我永续盈亏", "show my fills" or any first-person variant — DO NOT ask for a wallet address. Run this exact sequence:

1. Check session: lfi status --json

2. If not authenticated: lfi login key --role AGENT --name "OpenClawAgent" --json

3. Fetch TEE wallet address: lfi whoami --json → returns evmAddress (the user's TEE EVM address managed by the LiberFi server).

4. Run the matching query with the EVM address as the positional arg:

   • Positions: lfi perpetuals positions <evmAddress> --json
   • Open orders: lfi perpetuals orders <evmAddress> --json
   • Fill history: lfi perpetuals fills <evmAddress> --limit 20 --json

5. Present the result. If positions / orders / fills are empty, say so directly — do not retry with a different address; an empty result is the correct answer for a fresh TEE wallet.

The user does not know their EVM address — the LiberFi server holds the TEE wallet. The skill must resolve "我" → TEE wallet via whoami, transparently.

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).