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

CLI index

Common flags: --provider \x3Cname> (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 "\x3Cagent>" --json.
2. Confirm intent with the user (amount in SOL, recipient if non-default).
3. Place: lfi perpetuals deposit-place --gross-lamports \x3Clamports> --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 \x3CintentId> --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 \x3CevmAddress> --json
   • Open orders: lfi perpetuals orders \x3CevmAddress> --json
   • Fill history: lfi perpetuals fills \x3CevmAddress> --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).