账户与订单

本页是账户 / 订单 / 持仓 / 风险 / 触发单 / Bootstrap 相关的 JSON-RPC 读方法，以及链上实时只读 REST（/api/v1/chain/*）。写操作见 写操作，推送见 统一 WebSocket，事件见 事件投影。

账户/角色

getAccount

账户全貌：余额、持仓、衍生指标。合法 address 但链上从未出现 → 返回零值壳（balance="0"、nonce=0、空 positions），不回 -32004。

参数	类型	必填	说明
address	Address20	是	账户地址

响应 data：

字段	类型	说明
address	Address20	账户地址
balance	String	余额（SCALE_6）
nonce	u64	当前 nonce
role_mask	u64	角色位掩码
account_value	String	总价值 = balance + Σ(uPnL)（SCALE_6）；mark==0 的市场 uPnL 计 0
total_margin_used	String	已用保证金（SCALE_6）= Σ 持仓保证金（逐仓 isolated_margin / 全仓 position_im）+ Σ 挂单 IM
total_notional	String	总名义价值（SCALE_6）
withdrawable	String	展示用近似值 = max(0, account_value − total_margin_used)（SCALE_6，含 uPnL）。≠ 链上 WithdrawRequest 上限（链上用 cross_cash_available，不含 uPnL）。见 write-actions §7.0
cross_cash_available	String	全仓 cash 可用 = balance − Σ(Cross IM)（SCALE_6，不含 uPnL）。链上 available_balance；用于提现 / reduce_only / 划逐仓；可为负
cross_trading_available	String	全仓交易可用 = cross_cash_available + Cross uPnL（SCALE_6）。链上 cross_trading_available；用于全仓开仓 / 加仓 admission；可为负
positions	Map<MarketId, PositionResponse>	持仓映射（key = MarketId u32）。仅含已开仓（size != 0）的市场；只设了杠杆或预存逐仓保证金但未开仓的市场不出现在此（其锁定资金仍反映在 total_margin_used / admission 字段）
agents	AgentResponse[]	已授权 agent 列表
dms_deadline_ms	u64?	Dead-Man-Switch 截止时刻（毫秒）；null = 未开启
inviter_rebate_ratio_bps	u32?	邀请者返佣档位（bps；须已注册推荐码；下线成交时抽进返佣池的比例）；null = 走全局默认
inviter_keep_ratio_bps	u32	邀请者自留比例（bps；默认 10 000 = 100 % 自留）

PositionResponse：

字段	类型	说明
symbol	String	交易对名
size	String	仓位大小（sz 精度），正=多，负=空
entry_vwap	String	开仓均价 VWAP（px 精度）
mark_price	String	当前标记价（px 精度；与 marks 主题同源）
margin_mode	MarginMode	"Cross" · "Isolated"
leverage	u32	杠杆倍数
isolated_margin	String	逐仓保证金（SCALE_6）；Cross 为 "0"
margin_used	String	占用保证金（SCALE_6）
unrealized_pnl	String	未实现盈亏 = size × (mark − entry)（SCALE_6）
notional	String	名义价值 =
liquidation_price	String?	强平价（px 精度）；无法计算时 null。公式见 下单预估与强平价
roe	String?	ROE 比率（SCALE_6）；IM=0 时 null

AgentResponse：

字段	类型	说明
address	Address20	Agent 的 secp256k1 API-wallet 地址
role_mask	u64	Agent 被授予的角色位图
expires_at_ms	u64	过期时间（毫秒）；0 = 永不过期

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "address": "0x1111222233334444555566667777888899990000",
      "balance": "100000.000000",
      "nonce": 42,
      "role_mask": 1,
      "account_value": "101117.250000",
      "total_margin_used": "4861.725000",
      "total_notional": "48617.250000",
      "withdrawable": "96255.525000",
      "cross_cash_available": "95138.275000",
      "cross_trading_available": "96255.525000",
      "positions": {
        "1": {
          "symbol": "BTC-USDT",
          "size": "0.50000",
          "entry_vwap": "95000.00",
          "mark_price": "97225.00",
          "margin_mode": "Cross",
          "leverage": 10,
          "isolated_margin": "0",
          "margin_used": "4861.725000",
          "unrealized_pnl": "1117.250000",
          "notional": "48617.250000",
          "liquidation_price": "87450.00",
          "roe": "0.229800"
        }
      },
      "agents": [{
        "address": "0xaaaa111122223333444455556666777788889999",
        "role_mask": 1,
        "expires_at_ms": 0
      }],
      "dms_deadline_ms": null,
      "inviter_rebate_ratio_bps": null,
      "inviter_keep_ratio_bps": 10000
    }
  }
}

getAccountOrders

查询账户当前挂单。

参数	类型	必填	说明
address	Address20	是	账户地址

响应 data： AccountOrdersResponse — address + orders: RestingOrderResponse[]

RestingOrderResponse：

字段	类型	说明
order_id	u64	系统订单 ID
owner	Address20	挂单账户
market_id	u32	市场 ID
symbol	String	交易对名
side	Side	"Bid" · "Ask"
price	String	限价（px 精度）
qty	String	原始数量（sz 精度）
remaining	String	未成交余量（sz 精度）
filled	String	已成交量 = qty − remaining（sz 精度）
tif	TimeInForce	"Gtc" · "Ioc" · "Fok" · "PostOnly"
reduce_only	bool	仅减仓
order_type	String	"Limit"（Gtc/PostOnly）· "Market"（Ioc/Fok）
client_order_id	String?	客户端订单 ID
placed_at_ms	u64	挂单时刻（毫秒）
expires_at_ms	u64?	GTD 过期时刻；null = GTC 长挂

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "address": "0x1111222233334444555566667777888899990000",
      "orders": [{
        "order_id": 1001,
        "owner": "0x1111222233334444555566667777888899990000",
        "market_id": 1,
        "symbol": "BTC-USDT",
        "side": "Bid",
        "price": "97100.00",
        "qty": "1.00000",
        "remaining": "0.50000",
        "filled": "0.50000",
        "tif": "Gtc",
        "reduce_only": false,
        "order_type": "Limit",
        "client_order_id": "my-cloid-1",
        "placed_at_ms": 1717200000000,
        "expires_at_ms": null
      }]
    }
  }
}

getPosition

按地址+市场查单仓位（含实时衍生指标）。账户不存在、无该市场持仓、或 symbol 无效 → -32004。

参数	类型	必填	说明
address	Address20	是	账户地址
symbol	String	是	交易对名

响应 data： PositionResponse（同 getAccount 中的持仓结构）

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "symbol": "BTC-USDT",
      "size": "0.50000",
      "entry_vwap": "95000.00",
      "mark_price": "97225.00",
      "margin_mode": "Cross",
      "leverage": 10,
      "isolated_margin": "0",
      "margin_used": "4861.725000",
      "unrealized_pnl": "1117.250000",
      "notional": "48617.250000",
      "liquidation_price": "87450.00",
      "roe": "0.229800"
    }
  }
}

getMarketSettings

查询账户在某市场的保证金偏好（与写侧 SetLeverage / SetMarginMode / SetIsolatedMargin 对称）。合法 address + 合法 symbol → 恒 200；该 (账户, 市场) 在链上无记录时返回默认偏好壳（margin_mode: "Cross", leverage: 0, isolated_margin: "0.000000"），不回 -32004。仅 symbol 无效 → -32004。

参数	类型	必填	说明
address	Address20	是	账户地址
symbol	String	是	交易对名

响应 data：

字段	类型	说明
address	Address20	账户地址
symbol	String	交易对名
margin_mode	MarginMode	"Cross" · "Isolated"
leverage	u32	杠杆倍数；0 = tier 最高杠杆
isolated_margin	String	逐仓预存保证金（SCALE_6）；Cross 为 "0"

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "address": "0x1111222233334444555566667777888899990000",
      "symbol": "BTC-USDT",
      "margin_mode": "Isolated",
      "leverage": 10,
      "isolated_margin": "5000.000000"
    }
  }
}

listAccounts

账户列表（分页 + 可选多维度过滤）。

参数	类型	必填	说明
offset	usize	否	默认 0
limit	usize	否	默认 100，最大 500
role	RoleFilter	否	按角色过滤（trader/oracle_operator/settlement_operator/admin/liquidator/quoter）
referral_code	String	否	按注册的推荐码检索（≤1 命中）
referred_by_code	String	否	按绑定的推荐码检索

响应 data： AccountListItem[]

字段	类型	说明
address	Address20	账户地址
balance	String	余额（SCALE_6）
nonce	u64	当前 nonce
role_mask	u64	角色位掩码
position_count	usize	持仓数（仅计 size != 0 的市场）

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": [{
      "address": "0x1111222233334444555566667777888899990000",
      "balance": "100000.000000",
      "nonce": 42,
      "role_mask": 1,
      "position_count": 1
    }],
    "page": { "offset": 0, "limit": 100, "total": 1024 }
  }
}

---

getOrderStatus

按 order_id 或 (address, symbol, client_order_id) 查订单生命周期。二选一。

参数	类型	必填	说明
order_id	u64	条件	按 order_id 直接查（与 cloid 互斥）
client_order_id	String	条件	按 cloid 查（需同时给 address + symbol）
address	Address20	条件	cloid 模式必填
symbol	String	条件	cloid 模式必填

响应 data：

字段出现规则：status 为 open 或 closed 时，market_id · symbol · side · price · qty · remaining · filled 必返；unknown 时仅 order_id + status（cloid 查询可能附带 client_order_id）。

字段	类型	说明
order_id	u64	订单 ID
status	OrderLifecycleStatus	"open" · "closed" · "unknown"
market_id	u32	市场 ID（open/closed）
symbol	String	交易对名（open/closed）
side	Side	"Bid" · "Ask"（open/closed）
price	String	限价（px 精度；open/closed）
qty	String	原始数量（sz 精度；open/closed）
remaining	String	余量（sz 精度；open/closed）
filled	String	已成交量（sz 精度；open/closed）
avg_price	String?	成交均价（px 精度）；有成交时返回，零成交撤单等省略
client_order_id	String?	下单携带 cloid 时返回
close_reason	CloseReason	仅 closed："filled"/"ioc_expired"/"cancelled"/"gtd_expired"/"fok_rejected"/"market_delisted"/"amend_clamped_at_filled"

终态查询：出块时写入硬盘 archive（永久）；内存 index 仅保留近 24h 热缓存。重启不回灌内存；getOrderStatus closed miss 时直读 archive（O(log N) 点查）。

open 单 fill/avg：来自 order_lifecycle 增量索引（出块 ingest + 启动 journal 窗口回补），不扫 journal。

响应示例（open）：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "order_id": 1001,
      "status": "open",
      "market_id": 1,
      "symbol": "BTC-USDT",
      "side": "Bid",
      "price": "97100.00",
      "qty": "1.00000",
      "remaining": "0.50000",
      "filled": "0.50000",
      "avg_price": "97050.00",
      "client_order_id": "my-cloid-1"
    }
  }
}

响应示例（closed）：

{
  "jsonrpc": "2.0", "id": 2,
  "result": {
    "height": 12345,
    "data": {
      "order_id": 1000,
      "status": "closed",
      "market_id": 1,
      "symbol": "BTC-USDT",
      "side": "Bid",
      "price": "97100.00",
      "qty": "1.00000",
      "remaining": "0.00000",
      "filled": "1.00000",
      "avg_price": "96800.00",
      "client_order_id": "my-cloid-1",
      "close_reason": "filled"
    }
  }
}

响应示例（unknown）：

{
  "jsonrpc": "2.0", "id": 3,
  "result": {
    "height": 12345,
    "data": {
      "order_id": 9999,
      "status": "unknown"
    }
  }
}

getUserFees

用户自定义费率（不含返佣比例；返佣见 getAccount.inviter_rebate_ratio_bps 与 getExchangeConfig.global_rebate_ratio_bps）。

参数	类型	必填	说明
address	Address20	是	账户地址

响应 data： address / custom_maker_fee_rate(String?, SCALE_6, null=市场默认) / custom_taker_fee_rate(String?, 同上)

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "address": "0x1111222233334444555566667777888899990000",
      "custom_maker_fee_rate": "0.000100",
      "custom_taker_fee_rate": null
    }
  }
}

风险/清算

getLiquidatablePositions

需清算仓位列表（按 shortfall 降序）。emergency_halt 市场不列出。

参数	类型	必填	说明
symbol	String	否	按市场过滤
market_id	u32	否	精确市场过滤；携带时优先于 symbol
offset	usize	否	默认 0
limit	usize	否	默认 100，最大 1000

响应 data · LiquidatablePosition[]：

字段	类型	说明
account	Address20	账户地址
market_id	u32	市场 ID
symbol	String	交易对名
size	String	仓位大小（sz 精度）
entry_vwap	String	开仓均价（px 精度）
mark_price	String	标记价（px 精度）
equity	String	账户权益（SCALE_6）
mm_required	String	所需维持保证金（SCALE_6）
shortfall	String	缺口 = mm_required − equity（SCALE_6）

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": [{
      "account": "0x3333444455556666777788889999000011112222",
      "market_id": 1,
      "symbol": "BTC-USDT",
      "size": "-2.00000",
      "entry_vwap": "98000.00",
      "mark_price": "97225.00",
      "equity": "500.000000",
      "mm_required": "1200.000000",
      "shortfall": "700.000000"
    }],
    "page": { "offset": 0, "limit": 100, "total": 3 }
  }
}

getEstimatedLiquidationPrice

估算强平价（what-if，不修改状态）。逐仓口径：margin = IM(entry 名义, leverage)，不读账户权益。 公式与全仓 / 逐仓展示差见 下单预估与强平价。

参数	类型	必填	精度	说明
symbol	String	是	—	交易对名
size	String	是	sz_decimals	仓位大小（signed decimal，正=多，负=空）
entry_price	String	否	px_decimals	入场价，默认用 mark
leverage	u32	是	—	杠杆倍数

响应 data：

字段	类型	说明
symbol	String	交易对名
size	String	假设仓位
entry_price	String	假设入场价
mark_price	String	当前标记价
leverage	u32	杠杆倍数
margin	String	所需保证金（SCALE_6）
liquidation_price	String?	强平价（px 精度）；null = 无法被强平

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "symbol": "BTC-USDT",
      "size": "1.00000",
      "entry_price": "95000.00",
      "mark_price": "97225.00",
      "leverage": 10,
      "margin": "9722.500000",
      "liquidation_price": "87450.00"
    }
  }
}

---

getAllOpenOrders

全局/按市场挂单列表。

参数	类型	必填	说明
symbol	String	否	不传查全局
offset	usize	否	默认 0
limit	usize	否	默认 100，最大 1000

响应 data： RestingOrderResponse[]（同 [getAccountOrders#getaccountorders 的 orders 项）

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": [{
      "order_id": 1001,
      "owner": "0x1111222233334444555566667777888899990000",
      "market_id": 1,
      "symbol": "BTC-USDT",
      "side": "Bid",
      "price": "97100.00",
      "qty": "1.00000",
      "remaining": "1.00000",
      "filled": "0",
      "tif": "Gtc",
      "reduce_only": false,
      "order_type": "Limit",
      "client_order_id": null,
      "placed_at_ms": 1717200000000,
      "expires_at_ms": null
    }],
    "page": { "offset": 0, "limit": 100, "total": 2048 }
  }
}

getTriggerOrders

查询账户的离线触发单列表。

参数	类型	必填	说明
address	Address20	是	账户地址
symbol	String	否	按市场过滤

响应 data · TriggerOrdersResponse： address + triggers: TriggerOrderResponse[]

TriggerOrderResponse：

字段	类型	说明
trigger_id	u64	触发单 ID
owner	Address20	挂单账户
market_id	u32	市场 ID
symbol	String	交易对名
side	Side	"Bid" · "Ask"
order_type	TriggerOrderType	"market" · "limit"
qty	String	下单数量（sz 精度）
trigger_price	String	触发线（px 精度）
trigger_direction	TriggerDirection	"Above" · "Below"
limit_price	String?	限价（仅 limit，px 精度）
tif	TimeInForce	TIF
reduce_only	bool	仅减仓
client_order_id	String?	客户端订单 ID
created_at_block	u64	创建块高
created_at_ms	u64	创建时刻（毫秒）
expires_at_ms	u64?	过期时刻；null = 永不过期

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "address": "0x1111222233334444555566667777888899990000",
      "triggers": [{
        "trigger_id": 7001,
        "owner": "0x1111222233334444555566667777888899990000",
        "market_id": 1,
        "symbol": "BTC-USDT",
        "side": "Ask",
        "order_type": "limit",
        "qty": "0.50000",
        "trigger_price": "95000.00",
        "trigger_direction": "Below",
        "limit_price": "94900.00",
        "tif": "Gtc",
        "reduce_only": true,
        "client_order_id": "sl-1",
        "created_at_block": 12340,
        "created_at_ms": 1717199000000,
        "expires_at_ms": null
      }]
    }
  }
}

getOcoPairs

查询账户的 OCO 组合单列表（含 Active / Resolved）。

参数	类型	必填	说明
address	Address20	是	账户地址
symbol	String	否	按市场过滤

响应 data · OcoPairsResponse： address + pairs: OcoPairResponse[]

OcoPairResponse：

字段	类型	说明
pair_id	u64	OCO pair ID
owner	Address20	挂单账户
market_id	u32	市场 ID
symbol	String	交易对名
status	OcoStatus	"Active" · "Resolved"
legs	OcoLegs	腿 ID 引用（externally-tagged，见 enums.md §6）
placed_at_block	u64	创建块高
client_pair_id	u64?	客户端 pair ID
parent_order_id	u64?	Bracket：关联开仓 entry 的系统 order_id；无 bracket 绑定时为 null

OcoLegs wire 形态：

变体	字段
TwoLimits	primary_order_id, secondary_order_id
StopMarketAndLimit	stop_trigger_id, limit_order_id
StopLimitAndLimit	stop_trigger_id, limit_order_id
TwoTriggers	primary_trigger_id, primary_kind, secondary_trigger_id, secondary_kind

示例：

{
  "StopMarketAndLimit": {
    "stop_trigger_id": 7001,
    "limit_order_id": 1003
  }
}

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "address": "0x1111222233334444555566667777888899990000",
      "pairs": [{
        "pair_id": 8001,
        "owner": "0x1111222233334444555566667777888899990000",
        "market_id": 1,
        "symbol": "BTC-USDT",
        "status": "Active",
        "legs": {
          "StopMarketAndLimit": {
            "stop_trigger_id": 7001,
            "limit_order_id": 1003
          }
        },
        "placed_at_block": 12341,
        "client_pair_id": 100,
        "parent_order_id": null
      }]
    }
  }
}

getTriggerOrder

按 trigger_id 查单笔触发单（仍待触发才有；已 activate/cancel/expire 则 -32004）。

参数	类型	必填	说明
trigger_id	u64	是	触发单 ID

响应 data： TriggerOrderResponse（同 [getTriggerOrders#gettriggerorders 列表项）

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "trigger_id": 7001,
      "owner": "0x1111222233334444555566667777888899990000",
      "market_id": 1,
      "symbol": "BTC-USDT",
      "side": "Ask",
      "order_type": "limit",
      "qty": "0.50000",
      "trigger_price": "95000.00",
      "trigger_direction": "Below",
      "limit_price": "94900.00",
      "tif": "Gtc",
      "reduce_only": true,
      "client_order_id": "sl-1",
      "created_at_block": 12340,
      "created_at_ms": 1717199000000,
      "expires_at_ms": null
    }
  }
}

getOcoPair

按 pair_id 查单笔 OCO 组合单（含 Active / Resolved）。

参数	类型	必填	说明
pair_id	u64	是	OCO pair ID

响应 data： OcoPairResponse（同 [getOcoPairs#getocopairs 列表项）

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "pair_id": 8001,
      "owner": "0x1111222233334444555566667777888899990000",
      "market_id": 1,
      "symbol": "BTC-USDT",
      "status": "Active",
      "legs": {
        "StopMarketAndLimit": {
          "stop_trigger_id": 7001,
          "limit_order_id": 1003
        }
      },
      "placed_at_block": 12341,
      "client_pair_id": 100,
      "parent_order_id": null
    }
  }
}

getAllTriggerOrders

全局 / 按市场触发单列表（admin / monitoring）。遍历 trigger_orders 主表，按 trigger_id 升序分页。

参数	类型	必填	说明
symbol	String	否	不传查全局
offset	usize	否	默认 0
limit	usize	否	默认 100，最大 1000

响应 data： TriggerOrderResponse[]（带 page）

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": [{
      "trigger_id": 7001,
      "owner": "0x1111222233334444555566667777888899990000",
      "market_id": 1,
      "symbol": "BTC-USDT",
      "side": "Ask",
      "order_type": "limit",
      "qty": "0.50000",
      "trigger_price": "95000.00",
      "trigger_direction": "Below",
      "limit_price": "94900.00",
      "tif": "Gtc",
      "reduce_only": true,
      "client_order_id": "sl-1",
      "created_at_block": 12340,
      "created_at_ms": 1717199000000,
      "expires_at_ms": null
    }],
    "page": { "offset": 0, "limit": 100, "total": 15 }
  }
}

getAllOcoPairs

全局 / 按市场 OCO 组合单列表（admin / monitoring）。遍历 oco_pairs 主表，按 pair_id 升序分页（含 Active / Resolved）。

参数	类型	必填	说明
symbol	String	否	不传查全局
offset	usize	否	默认 0
limit	usize	否	默认 100，最大 1000

响应 data： OcoPairResponse[]（带 page）

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": [{
      "pair_id": 8001,
      "owner": "0x1111222233334444555566667777888899990000",
      "market_id": 1,
      "symbol": "BTC-USDT",
      "status": "Active",
      "legs": {
        "TwoTriggers": {
          "primary_trigger_id": 7001,
          "primary_kind": "StopMarket",
          "secondary_trigger_id": 7002,
          "secondary_kind": "StopLimit"
        }
      },
      "placed_at_block": 12341,
      "client_pair_id": 100,
      "parent_order_id": 1001
    }],
    "page": { "offset": 0, "limit": 100, "total": 8 }
  }
}

---

Bootstrap

getBootstrap

一致性首屏聚合。单次 index.read() 同 height 保证一致性。

不含触发单 / OCO — 条件委托请调 getTriggerOrders + getOcoPairs，或订阅 WS triggerUpdates.{address}。

参数	类型	必填	说明
address	Address20	否	返回账户摘要
symbols	String[]	否	返回指定市场盘口
book_depth	usize	否	盘口每侧档数；0 = 全深度；默认 50

响应 data：

字段	类型	说明
markets	MarketListItem[]	市场列表（不含 Delisted）
account	AccountSummaryResponse?	账户摘要（提供 address 时返回）
books	Map<String, BookView>	symbol → 盘口（bids/asks/spread/state_hash）
action_meta	ActionsMetaResponse	45 Action 鉴权元数据

BookView：

字段	类型	说明
state_hash	Hex32	盘口状态哈希
bids	Level[]	买单档位
asks	Level[]	卖单档位
spread	String?	价差（px 精度）；任一侧空时 null

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "markets": [{
        "symbol": "BTC-USDT",
        "market_id": 1,
        "kind": "Native",
        "lifecycle": "Active",
        "emergency_halt": false,
        "price_decimals": 2,
        "size_decimals": 5,
        "max_leverage": 50,
        "mark_price": "97225.00",
        "prev_day_price": "96500.00",
        "open_interest": "10.50000",
        "open_interest_notional": "1021862.500000",
        "day_ntl_volume": "12500000.000000",
        "day_base_volume": "128.50000"
      }],
      "account": {
        "address": "0x1111222233334444555566667777888899990000",
        "balance": "100000.000000",
        "nonce": 42,
        "role_mask": 1,
        "account_value": "101117.250000",
        "total_margin_used": "4861.725000",
        "total_notional": "48617.250000",
        "withdrawable": "96255.525000",
        "cross_cash_available": "95138.275000",
        "cross_trading_available": "96255.525000",
        "positions": {},
        "agents": [],
        "dms_deadline_ms": null,
        "inviter_rebate_ratio_bps": null,
        "inviter_keep_ratio_bps": 10000
      },
      "books": {
        "BTC-USDT": {
          "state_hash": "0xabc123def456789012345678901234567890abcdef1234567890abcdef123456",
          "bids": [{ "price": "97200.00", "qty": "1.50000", "cumulative_qty": "1.50000" }],
          "asks": [{ "price": "97250.00", "qty": "2.10000", "cumulative_qty": "2.10000" }],
          "spread": "50.00"
        }
      },
      "action_meta": {
        "action_version": 2,
        "actions": [{ "name": "PlaceOrder", "auth": "master_or_agent_with_role", "role": "Trader", "master_only": false }]
      }
    }
  }
}

链上实时只读（Chain proxy）

:::info 定位说明

以下路由 透传 Chain JSON-RPC（getAccount / getAccountOrders），响应外层为 { "height", "data" }。
做市系统应直连 POST /api/v1/query 的 getAccount / getAccountOrders；本组接口主要方便 前端应用直接读链上快照。选型见 做市商对接指南 §1.2。

:::

本组对以下接口透传链 JSON-RPC（getAccount / getAccountOrders），响应形态与 getAccount 一致，外层为 { "height", "data" }（非本组其他接口常用的 { "data" } 单条包装）。

场景	推荐数据源
当前余额 / 持仓 / 保证金（做市）	链读写 getAccount
当前余额 / 持仓（读侧代理）	本组 chain proxy
历史成交 / 流水 / 已关闭委托	derive 索引（/api/v1/fills 等）

错误码补充

HTTP	场景
400	缺少 address
404	链 RPC -32004（账户/资源不存在）
502	链节点不可达、RPC 错误或响应解码失败

GET /api/v1/chain/account

链上账户实时快照（代理 getAccount）。

Query

Param	Type	Required	Description
address	string	yes	账户地址

Response 200

{
  "height": 12345,
  "data": {
    "address": "0x1111222233334444555566667777888899990000",
    "balance": "100000.000000",
    "nonce": 42,
    "account_value": "101117.250000",
    "total_margin_used": "4861.725000",
    "total_notional": "48617.250000",
    "withdrawable": "96255.525000",
    "cross_cash_available": "95138.275000",
    "cross_trading_available": "96255.525000",
    "positions": [{
      "market_id": 1,
      "symbol": "BTC-USDT",
      "size": "0.50000",
      "entry_vwap": "95000.00",
      "mark_price": "97225.00",
      "margin_mode": "Cross",
      "leverage": 10,
      "isolated_margin": "0",
      "unrealized_pnl": "1117.250000",
      "notional": "48617.250000",
      "liquidation_price": "87450.00",
      "margin_used": "4861.725000",
      "roe": "0.229800"
    }]
  }
}

positions 为数组（本分册将链上 Map<market_id, Position> 展开）；字段见 schemas — ChainAccountView。

GET /api/v1/chain/open-orders

链上当前挂单（代理 getAccountOrders）。

Query

Param	Type	Required	Description
address	string	yes	账户地址

Response 200

{
  "height": 12345,
  "data": {
    "address": "0x1111222233334444555566667777888899990000",
    "orders": [{
      "order_id": 1001,
      "owner": "0x1111222233334444555566667777888899990000",
      "market_id": 1,
      "symbol": "BTC-USDT",
      "side": "Bid",
      "price": "97100.00",
      "qty": "1.00000",
      "remaining": "0.50000",
      "filled": "0.50000",
      "tif": "Gtc",
      "reduce_only": false,
      "client_order_id": "my-cloid-1",
      "placed_at_ms": 1717200000000,
      "expires_at_ms": null,
      "order_type": "Limit"
    }]
  }
}

---