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 (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 "" --json.

1. Confirm intent with the user (amount in SOL, recipient if non-default).
2. Place: lfi perpetuals deposit-place --gross-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.

1. Capture the returned intentId and solanaTxHash.
2. Poll: lfi perpetuals deposit-status --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).

1. Run the matching query with the EVM address as the positional arg:
• Positions: lfi perpetuals positions --json
• Open orders: lfi perpetuals orders --json
• Fill history: lfi perpetuals fills --limit 20 --json
2. 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).