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 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:
- Authenticate (only first time):
lfi status --json; if not logged in,
lfi login key --role AGENT --name "<agent>" --json.
- Confirm intent with the user (amount in SOL, recipient if non-default).
- 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.
- Capture the returned
intentId and solanaTxHash.
- 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
lfi perpetuals markets --json- Present symbol, mark price, funding where present.
Depth + tape
lfi perpetuals orderbook BTC --jsonlfi perpetuals trades BTC --limit 20 --json
Positions for a known wallet
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:
- Check session:
lfi status --json
- If not authenticated:
lfi login key --role AGENT --name "OpenClawAgent" --json
- Fetch TEE wallet address:
lfi whoami --json → returns evmAddress
(the user's TEE EVM address managed by the LiberFi server).
- 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
- 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)
lfi perpetuals order-prepare --user-address 0x… --symbol BTC --side long --order-type limit --amount 0.01 --price 95000 --json- User signs returned
typedData with their wallet (e.g. MetaMask eth_signTypedData_v4).
- Build
SignedAction: action, nonce, signature (0x), optional vaultAddress from prepare response.
- 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).
1---2name: liberfi-perpetuals3description: Query and trade perpetual futures through LiberFi's unified perpetuals API (openapi-server → perpetuals-server, Hyperliquid in MVP): list coins and markets, order book, recent trades, K-lines, user positions / orders / fills, and two-phase signed place or cancel flows (prepare → wallet sign → submit). Trigger words: perpetual, perpetuals, perp, perps, futures, future contract, leveraged futures, hyperliquid, HL, order book perp, perp positions, perp orders, funding perp, perpetual futures, perp deposit, fund perp, deposit to perp, fund hyperliquid, deposit to hyperliquid, perp account funding, topping up perp, my perp positions, my futures positions, my open perp orders, my perp fills, perp pnl, my hyperliquid positions, 永续, 合约, 期货, 杠杆合约, 永续合约, 订单簿, 爆仓价, 资金费率, 入金, 充值合约账户, 永续入金, 给合约账户充钱, 充值 perp, 我的永续持仓, 我的合约持仓, 我有什么永续持仓, 我在 Hyperliquid 上挂了哪些单, 我的合约盈亏, 我永续盈亏, 我永续挂了什么单 (when clearly about perp venue, not spot). CRITICAL: If the `lfi` (or `liberfi`) command is missing, install it WITHOUT asking the user: `npm in4---56# LiberFi Perpetuals78Perpetuals data and signed order relay flow via LiberFi OpenAPI (`/v1/perpetuals/…` → `perpetuals-server`).910## Pre-flight1112See [bootstrap.md](../shared/bootstrap.md) for CLI install and `lfi ping`.1314- **Read endpoints** (coins, markets, orderbook, …): no auth.15- **User-scoped reads** (`positions`, `orders`, `fills`): pass the wallet16 `address` (0x) as the positional argument. For first-person queries17 ("我的持仓", "my positions", etc.), the skill MUST auto-resolve the user's18 TEE EVM address via `lfi status` → `lfi login key` (if needed) →19 `lfi whoami` → use the returned `evmAddress`. NEVER ask the user for an20 address — the TEE wallet is server-managed and the user does not know it.21- **Order writes** (`order-prepare` / `order-submit`, cancel variants): require a user wallet to sign typed data; agents must not fabricate signatures.22- **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.2324## Skill routing2526| User intent | Skill |27|-------------|--------|28| Spot swap, bridge, gas send | liberfi-swap |29| Trending spot tokens, new listings | liberfi-market |30| Polymarket / Kalshi | liberfi-predict |31| Spot token audit, DEX pools for a token | liberfi-token |32| Perp markets, HL-style orderbook, perp positions | **liberfi-perpetuals** |33| Funding the perp account (Solana → Hyperliquid via Relay), checking deposit lifecycle | **liberfi-perpetuals** |34| Spot wallet holdings on a chain (not perp account) | liberfi-portfolio |3536## CLI index3738| Command | Description |39|---------|-------------|40| `lfi perpetuals coins` | List tradable perp coins |41| `lfi perpetuals markets` | Market snapshots (`--symbols` optional) |42| `lfi perpetuals market <symbol>` | Single market |43| `lfi perpetuals orderbook <symbol>` | L2 book (`--max-level`) |44| `lfi perpetuals trades <symbol>` | Recent trades (`--limit`) |45| `lfi perpetuals klines <symbol>` | Candles (`--interval` required) |46| `lfi perpetuals positions <address>` | Positions + margin summary |47| `lfi perpetuals orders <address>` | Open orders |48| `lfi perpetuals fills <address>` | Fill history |49| `lfi perpetuals order-prepare` | Build typed data for place order |50| `lfi perpetuals order-submit --body '<json>'` | Submit signed place order |51| `lfi perpetuals cancel-prepare` | Build typed data for cancel |52| `lfi perpetuals cancel-submit --body '<json>'` | Submit signed cancel |53| `lfi perpetuals deposit-place --gross-lamports <n>` | **Recommended**: TEE one-click Solana → Hyperliquid deposit (server quotes, signs, broadcasts, submits). Auth required. |54| `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`. |55| `lfi perpetuals deposit-submit --body '<json>'` | Escape hatch step 2: record the broadcasted SOL tx hash. Idempotent on `solanaTxHash`. |56| `lfi perpetuals deposit-status <intentId> [--refresh]` | Read deposit lifecycle. `--refresh` bypasses any server-side cache (server-reserved knob; today both endpoints behave identically). |5758Common flags: `--provider <name>` (e.g. `hyperliquid`), global `--json`.5960## Funding / Deposit (Solana → Hyperliquid via Relay)6162The deposit pipeline moves SOL from the user's Solana wallet to the user's63Hyperliquid perp account via the Relay bridge service. The recommended path64is the one-click TEE auto-flow:65661. **Authenticate** (only first time): `lfi status --json`; if not logged in,67 `lfi login key --role AGENT --name "<agent>" --json`.682. **Confirm intent** with the user (amount in SOL, recipient if non-default).693. **Place**: `lfi perpetuals deposit-place --gross-lamports <lamports> --json`70 - `lamports = SOL × 1_000_000_000` (1 SOL = 1e9 lamports).71 - `--hyperliquid-recipient` is **optional** — defaults to the user's TEE72 EVM address (`lfi whoami evmAddress`), which is what 99% of users want.734. **Capture** the returned `intentId` and `solanaTxHash`.745. **Poll**: `lfi perpetuals deposit-status <intentId> --json` until75 `status` is `settled` (typical: 30–120 s).7677Server returns `status: "broadcasted"` immediately after step 3; the78reconciliation loop progresses through `relay_waiting → relay_pending →79settled` (or `failed_*` states). On failure consult the80`statusHistory[]` and `lastError` fields for the recoverable / non-81recoverable distinction.8283For the atomic escape-hatch flow (when the user controls their own SOL84private key outside the TEE, or recovering from a partial failure where85the SOL tx has been broadcasted but `submit` did not succeed), see86[reference/deposit-flow.md](reference/deposit-flow.md).8788## Typical flows8990### Market overview91921. `lfi perpetuals markets --json`932. Present symbol, mark price, funding where present.9495### Depth + tape96971. `lfi perpetuals orderbook BTC --json`982. `lfi perpetuals trades BTC --limit 20 --json`99100### Positions for a known wallet1011021. `lfi perpetuals positions 0xYourAddr --json`103104### "My ..." auto-flow (CRITICAL — covers "我的", "my", "我自己")105106**If the user says "我有什么永续持仓", "我的合约持仓", "my perp positions",107"我在 Hyperliquid 上挂了哪些单", "我永续盈亏", "show my fills" or any108first-person variant — DO NOT ask for a wallet address. Run this exact109sequence:**1101111. **Check session**: `lfi status --json`1122. **If not authenticated**: `lfi login key --role AGENT --name "OpenClawAgent" --json`1133. **Fetch TEE wallet address**: `lfi whoami --json` → returns `evmAddress`114 (the user's TEE EVM address managed by the LiberFi server).1154. **Run the matching query** with the EVM address as the positional arg:116 - Positions: `lfi perpetuals positions <evmAddress> --json`117 - Open orders: `lfi perpetuals orders <evmAddress> --json`118 - Fill history: `lfi perpetuals fills <evmAddress> --limit 20 --json`1195. **Present** the result. If positions / orders / fills are empty, say so120 directly — do not retry with a different address; an empty result is the121 correct answer for a fresh TEE wallet.122123The user does not know their EVM address — the LiberFi server holds the TEE124wallet. The skill must resolve "我" → TEE wallet via `whoami`, transparently.125126### Place order (human-in-the-loop)1271281. `lfi perpetuals order-prepare --user-address 0x… --symbol BTC --side long --order-type limit --amount 0.01 --price 95000 --json`1292. User signs returned `typedData` with their wallet (e.g. MetaMask `eth_signTypedData_v4`).1303. Build `SignedAction`: `action`, `nonce`, `signature` (0x), optional `vaultAddress` from prepare response.1314. **After explicit confirmation**: `lfi perpetuals order-submit --body '{"action":…,"nonce":…,"signature":"0x…"}' --json`132133## API path reminder134135All 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).
liberfi-io