liberfi-perpetuals

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

LiberFi Perpetuals

Perpetuals data and signed order relay flow via LiberFi OpenAPI (

/v1/perpetuals/…

→

perpetuals-server

通过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.

CLI安装及

lfi ping

操作请参考bootstrap.md。

只读端点（币种、市场、订单簿等）：无需认证。
用户范围只读操作（
```
positions
```
、
```
orders
```
、
```
fills
```
）：需传入钱包
```
address
```
（0x开头）作为位置参数。对于第一人称查询（如“我的持仓”、“my positions”等），技能必须通过
```
lfi status
```
→
```
lfi login key
```
（如需） →
```
lfi whoami
```
自动解析用户的TEE EVM地址，并使用返回的
```
evmAddress
```
。绝对不要向用户索要地址——TEE钱包由服务器管理，用户并不知晓该地址。
订单写入操作（
```
order-prepare
```
/
```
order-submit
```
及撤单变体）：需要用户钱包对类型数据进行签名；代理不得伪造签名。
入金（推荐使用
deposit-place
）：需要认证（
```
lfi status
```
后执行
```
lfi login key
```
）——服务器的TEE钱包代表用户签名并广播交易。原子化的
```
deposit-quote
```
/
```
deposit-submit
```
备选方案无需认证，但调用者需自行签署SOL交易并广播。

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

用户意图	技能
现货兑换、跨链桥、Gas转账	liberfi-swap
热门现货代币、新上线代币	liberfi-market
Polymarket/Kalshi预测市场	liberfi-predict
现货代币审计、代币的DEX资金池	liberfi-token
永续合约市场、HL风格订单簿、永续持仓	liberfi-perpetuals
永续合约账户入金（Solana → Hyperliquid via Relay）、查询入金生命周期	liberfi-perpetuals
链上现货钱包持仓（非永续合约账户）	liberfi-portfolio

CLI index

CLI命令索引

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

命令	描述
`lfi perpetuals coins`	列出可交易的永续合约币种
`lfi perpetuals markets`	市场快照（可选 `--symbols` 参数）
`lfi perpetuals market <symbol>`	单个市场详情
`lfi perpetuals orderbook <symbol>`	L2订单簿（可选 `--max-level` 参数）
`lfi perpetuals trades <symbol>`	近期成交记录（可选 `--limit` 参数）
`lfi perpetuals klines <symbol>`	K线数据（必填 `--interval` 参数）
`lfi perpetuals positions <address>`	持仓及保证金汇总
`lfi perpetuals orders <address>`	当前挂单
`lfi perpetuals fills <address>`	成交历史
`lfi perpetuals order-prepare`	构建下单所需的类型数据
`lfi perpetuals order-submit --body '<json>'`	提交已签名的下单请求
`lfi perpetuals cancel-prepare`	构建撤单所需的类型数据
`lfi perpetuals cancel-submit --body '<json>'`	提交已签名的撤单请求
`lfi perpetuals deposit-place --gross-lamports <n>`	推荐：TEE一键式Solana → Hyperliquid入金（服务器报价、签名、广播、提交）。需要认证。
`lfi perpetuals deposit-quote --user-solana-address <a> --hyperliquid-recipient <a> --gross-lamports <n>`	备选方案步骤1：返回未签名的SOL交易及明细。调用者需在约30秒内签名并广播，然后执行 `deposit-submit` 。
`lfi perpetuals deposit-submit --body '<json>'`	备选方案步骤2：记录已广播的SOL交易哈希。基于 `solanaTxHash` 实现幂等性。
`lfi perpetuals deposit-status <intentId> [--refresh]`	查询入金生命周期。 `--refresh` 参数绕过服务器端缓存（服务器保留参数；目前两个端点行为一致）。

通用参数：

--provider <name>

（例如

hyperliquid

），全局参数

--json

。

Funding / Deposit (Solana → Hyperliquid via Relay)

入金流程（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

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.

入金管道通过Relay桥接服务将SOL从用户的Solana钱包转移至用户的Hyperliquid永续合约账户。推荐使用一键式TEE自动流程：

认证（仅首次需要）：

lfi status --json

；若未登录，执行

lfi login key --role AGENT --name "<agent>" --json

。

与用户确认意图（SOL金额，非默认接收方需确认）。
发起入金：
```
lfi perpetuals deposit-place --gross-lamports <lamports> --json
```
- ```
lamports = SOL × 1_000_000_000
```
  （1 SOL = 1e9 lamports）。
- ```
--hyperliquid-recipient
```
  为可选参数——默认值为用户的TEE EVM地址（
```
lfi whoami evmAddress
```
  ），99%的用户使用默认值即可。
记录返回的
```
intentId
```
和
```
solanaTxHash
```
。
轮询状态：
```
lfi perpetuals deposit-status <intentId> --json
```
，直到
```
status
```
变为
```
settled
```
（通常耗时30–120秒）。

步骤3执行后，服务器立即返回

status: "broadcasted"

；对账流程会依次经历

relay_waiting → relay_pending → settled

（或

failed_*

状态）。若失败，请查看

statusHistory[]

和

lastError

字段判断是否可恢复。

关于原子化备选方案（当用户在TEE外自行控制SOL私钥，或SOL交易已广播但

submit

未成功的部分失败恢复场景），请参考reference/deposit-flow.md。

Typical flows

典型流程

Market overview

市场概览

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

```
lfi perpetuals markets --json
```
展示交易对、标记价格、资金费率（若有）。

Depth + tape

深度行情与成交记录

```
lfi perpetuals orderbook BTC --json
```

lfi perpetuals trades BTC --limit 20 --json

```
lfi perpetuals orderbook BTC --json
```

lfi perpetuals trades BTC --limit 20 --json

Positions for a known wallet

已知钱包的持仓查询

lfi perpetuals positions 0xYourAddr --json

lfi perpetuals positions 0xYourAddr --json

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

“我的...”自动流程（重要——覆盖“我的”、“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.

若用户说“我有什么永续持仓”、“我的合约持仓”、“my perp positions”、“我在 Hyperliquid 上挂了哪些单”、“我永续盈亏”、“show my fills”或任何第一人称变体——请勿向用户索要钱包地址。请严格执行以下步骤：

检查会话状态：
```
lfi status --json
```

若未认证：

lfi login key --role AGENT --name "OpenClawAgent" --json

获取TEE钱包地址：
```
lfi whoami --json
```
→ 返回
```
evmAddress
```
（LiberFi服务器管理的用户TEE EVM地址）。

执行匹配查询，将EVM地址作为位置参数传入：

持仓：

lfi perpetuals positions <evmAddress> --json

当前挂单：

lfi perpetuals orders <evmAddress> --json

成交历史：

lfi perpetuals fills <evmAddress> --limit 20 --json

展示结果。若持仓/挂单/成交记录为空，请直接告知用户——不要使用其他地址重试；对于全新的TEE钱包，空结果是正确响应。

用户不知道自己的EVM地址——LiberFi服务器持有TEE钱包。技能必须通过

whoami

透明地将“我”解析为TEE钱包。

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

lfi perpetuals order-prepare --user-address 0x… --symbol BTC --side long --order-type limit --amount 0.01 --price 95000 --json

用户使用钱包对返回的
```
typedData
```
进行签名（例如MetaMask的
```
eth_signTypedData_v4
```
）。
构建
```
SignedAction
```
：包含
```
action
```
、
```
nonce
```
、
```
signature
```
（0x开头），可选
```
vaultAddress
```
来自prepare响应。

获得明确确认后：

lfi perpetuals order-submit --body '{"action":…,"nonce":…,"signature":"0x…"}' --json

API path reminder

API路径提示

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

所有CLI调用均指向OpenAPI路径

/v1/perpetuals/…

，网关会将请求代理至perpetuals-server的

/v1/…

路径。请使用

UPSTREAM_PERPETUALS_SERVICE_BASE_URL

配置网关（默认本地示例：

http://localhost:8083

——避免与openapi的

:8080

和预测服务的

:8082

冲突；当部署在同一服务器时，请使用

SERVER_PORT=8083

启动perpetuals-server）。