账户API#

账户余额 `GET /account/balance`#

查询母账户或指定子账户的账户总权益、Perps 持仓名义价值、持仓模式及各 Token 资产明细。

对于保证金币种，accAvgPx、spotUpl、spotUplRatio 和 entryCost 返回空字符串。

请求参数

参数	类型	必填	说明
vaultAddress	String	否	子账户地址。省略时查询母账户；传入时查询指定子账户。

请求示例

text

GET /api/v5/exchangeos/account/balance
GET /api/v5/exchangeos/account/balance?vaultAddress=0x6d1a19e1e03b83163fb38d7336b58875e71c50c2

响应外层字段

字段	类型	说明
code	String	接口返回码。`"0"` 表示成功。
msg	String	返回消息；成功时为空字符串。
data	Array	账户余额数据。

data[] 字段

字段	类型	说明
totalEq	String	账户总权益，仅统计 `pointFlag=false` 的 Token。
notionalUsd	String	所有已形成 Perps 持仓绝对名义价值之和，以 USD 计。
positionMode	String	持仓模式：`oneWay` 或 `hedge`。
block_height	String	查询结果对应的链上区块高度。
block_timestamp	String	查询结果对应的链上区块时间，Unix 毫秒时间戳。
details	Array	各 Token 资产明细。

details[] 字段

字段	类型	说明
tokenId	String	Token ID。
collateralEnabled	Boolean	是否启用为保证金资产。
eq	String	Token 权益。
eqUsd	String	Token 权益的 USD 价值。
isoEq	String	逐仓权益；不适用时返回空字符串。
cashBal	String	现金余额。
availBal	String	可用余额。
availEq	String	可用权益；不适用时返回空字符串。
frozenMgn	String	冻结保证金。
spotFrozen	String	Spot 冻结金额。
perpFrozen	String	Perps 冻结保证金；不适用时返回空字符串。
predFrozen	String	Prediction 冻结保证金；不适用时返回空字符串。
mmr	String	维持保证金需求；不适用时返回空字符串。
mgnRatio	String	保证金率；不适用时返回空字符串。
frozenMgnRatio	String	冻结保证金率；不适用时返回空字符串。
accAvgPx	String	Spot 累计平均持仓价格；保证金币种返回空字符串。
spotUpl	String	Spot 未实现盈亏；保证金币种返回空字符串。
spotUplRatio	String	Spot 未实现盈亏率；保证金币种返回空字符串。
entryCost	String	Spot 持仓成本；保证金币种返回空字符串。
upl	String	Perps 未实现盈亏；不适用时返回空字符串。
isoUpl	String	逐仓未实现盈亏；不适用时返回空字符串。
lastPx	String	最新价格。
tokenPx	String	Token 价格。
totalLever	String	总杠杆倍数；不适用时返回空字符串。

计算口径

text

totalEq
= Σ details[].eqUsd，其中仅统计 pointFlag=false 的 Token

frozenMgn
= spotFrozen + perpFrozen + predFrozen

notionalUsd
= Σ abs(所有已形成 Perps 持仓的 positionValue)

返回规则

有效数值为零时返回 "0"。
字段不适用时返回 ""。
非保证金 Token 的保证金相关字段返回 ""。
实盘与积分盘权益不得混合计算。

响应示例

json

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "totalEq": "110060.000000",
      "notionalUsd": "9891.086264",
      "positionMode": "oneWay",
      "block_height": "12092417",
      "block_timestamp": "1785218400074",
      "details": [
        {
          "tokenId": "0",
          "collateralEnabled": true,
          "eq": "100060.000000",
          "eqUsd": "100060.000000",
          "isoEq": "0.000000",
          "cashBal": "100000.000000",
          "availBal": "98712.000000",
          "availEq": "98712.000000",
          "frozenMgn": "1288.000000",
          "spotFrozen": "0.000000",
          "perpFrozen": "1288.000000",
          "mmr": "43.500000",
          "mgnRatio": "0.000435",
          "frozenMgnRatio": "0.012872",
          "accAvgPx": "",
          "spotUpl": "",
          "spotUplRatio": "",
          "entryCost": "",
          "upl": "60.000000",
          "isoUpl": "0.000000",
          "lastPx": "1.000000",
          "tokenPx": "1.000000",
          "totalLever": "0.086948"
        },
        {
          "tokenId": "3",
          "collateralEnabled": false,
          "eq": "0.125000",
          "eqUsd": "10000.000000",
          "isoEq": "",
          "cashBal": "0.125000",
          "availBal": "0.100000",
          "availEq": "",
          "frozenMgn": "0.025000",
          "spotFrozen": "0.025000",
          "perpFrozen": "",
          "predFrozen": "0",
          "mmr": "",
          "mgnRatio": "",
          "frozenMgnRatio": "",
          "accAvgPx": "60000.000000",
          "spotUpl": "2500.000000",
          "spotUplRatio": "0.333333",
          "entryCost": "7500.000000",
          "upl": "",
          "isoUpl": "",
          "lastPx": "80000.000000",
          "tokenPx": "80000.000000",
          "totalLever": ""
        }
      ]
    }
  ]
}

持仓信息 `GET /account/positions`#

查询母账户或指定子账户的 Perps 持仓。Spot 不产生 Position。

请求参数

参数	类型	必填	说明
assetId	String	否	Perps 产品 ID。省略时返回全部持仓。
vaultAddress	String	否	子账户地址。省略时查询母账户。

请求示例

text

GET /api/v5/exchangeos/account/positions
GET /api/v5/exchangeos/account/positions?assetId=602
GET /api/v5/exchangeos/account/positions?assetId=602&vaultAddress=0x6d1a19e1e03b83163fb38d7336b58875e71c50c2

响应字段

字段	类型	说明
block_height	String	查询结果对应的链上区块高度。
block_timestamp	String	查询结果对应的链上区块时间，Unix 毫秒时间戳。
assetId	String	产品 ID。
assetStatus	String	产品状态。
positionSide	String	持仓方向：`net`、`long` 或 `short`。
marginMode	String	保证金模式：`cross` 或 `isolated`。
leverage	String	当前持仓杠杆倍数。
pos	String	持仓数量。空头仓位为负值。
avgPx	String	开仓平均价。
markPx	String	标记价格。
positionValue	String	持仓名义价值。
upl	String	未实现盈亏。
uplRatio	String	未实现盈亏率。
liqPx	String	预估强平价。
imr	String	初始保证金率。
margin	String	持仓保证金。
mmr	String	维持保证金需求。
mgnRatio	String	保证金率。
realizedPnl	String	已实现盈亏。
fee	String	手续费。
fundingFee	String	资金费用。
tradeId	String	最近成交 ID。
closeOrderAlgo	Array	与该持仓关联的平仓 TPSL 订单。
> oid	String	订单 ID。
> assetId	String	产品 ID。
> assetStatus	String	产品状态。
> side	String	订单方向：`buy` 或 `sell`。
> positionSide	String	被减少的持仓方向。
> marginMode	String	保证金模式。
> price	String	委托价格。
> size	String	委托数量。
> reduceOnly	Boolean	是否为只减仓订单。
> triggerPx	String	触发价格。
> triggerPriceType	String	触发价格类型：`mark` 或 `index`。
> triggerCond	String	触发条件：`Gte` 或 `Lte`。
> isMarket	Boolean	触发后是否按市价执行。
> tpsl	String	TPSL 类型：`tp` 或 `sl`。
> parentOrderId	String	父订单 ID；无父订单时为空字符串。
> isActive	Boolean	是否已生效。
> tpLimit	Boolean	是否为 TP Limit。

响应示例

json

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "block_height": "12092417",
      "block_timestamp": "1785218400074",
      "assetId": "602",
      "assetStatus": "normal",
      "positionSide": "long",
      "marginMode": "isolated",
      "leverage": "20",
      "pos": "1.500",
      "avgPx": "3000.000",
      "markPx": "3020.000",
      "positionValue": "4530.000",
      "upl": "30.000",
      "uplRatio": "0.132450",
      "liqPx": "2864.100",
      "imr": "",
      "margin": "226.500000",
      "mmr": "22.650",
      "mgnRatio": "0.088304",
      "realizedPnl": "-2.265",
      "fee": "-2.265",
      "fundingFee": "0.000",
      "tradeId": "776",
      "closeOrderAlgo": [
        {
          "oid": "32733862",
          "assetId": "602",
          "assetStatus": "normal",
          "side": "sell",
          "positionSide": "long",
          "marginMode": "isolated",
          "price": "0",
          "size": "0",
          "reduceOnly": true,
          "triggerPx": "3200.000",
          "triggerPriceType": "mark",
          "triggerCond": "Gte",
          "isMarket": true,
          "tpsl": "tp",
          "parentOrderId": "",
          "isActive": true,
          "tpLimit": false
        }
      ]
    },
    {
      "assetId": "602",
      "assetStatus": "normal",
      "positionSide": "short",
      "marginMode": "isolated",
      "leverage": "10",
      "pos": "-2.000",
      "avgPx": "3100.000",
      "markPx": "3020.000",
      "positionValue": "6040.000",
      "upl": "160.000",
      "uplRatio": "0.258065",
      "liqPx": "3394.900",
      "imr": "",
      "margin": "620.000000",
      "mmr": "30.200",
      "mgnRatio": "0.038718",
      "realizedPnl": "-3.100",
      "fee": "-3.100",
      "fundingFee": "0.000",
      "tradeId": "777",
      "closeOrderAlgo": [
        {
          "oid": "32733863",
          "assetId": "602",
          "assetStatus": "normal",
          "side": "buy",
          "positionSide": "short",
          "marginMode": "isolated",
          "price": "0",
          "size": "0",
          "reduceOnly": true,
          "triggerPx": "3250.000",
          "triggerPriceType": "mark",
          "triggerCond": "Gte",
          "isMarket": true,
          "tpsl": "sl",
          "parentOrderId": "",
          "isActive": true,
          "tpLimit": false
        }
      ]
    }
  ]
}

最大可下单量 `GET /account/max-size`#

查询指定产品、当前账户的最大可买量、最大可卖量、可用资金和可平仓数量。支持在 hedge 模式下查询可平数量。

请求参数

参数	类型	必填	说明
assetId	String	是	Perps 产品 ID。
price	String	否	用于计算最大开仓数量的价格。
leverage	String	否	用于计算最大开仓数量的杠杆倍数。
reduceOnly	Boolean	否	是否查询只减仓可下量。
vaultAddress	String	否	子账户地址。省略时查询母账户。

请求示例：查询最大开仓数量

json

{
  "method": "GET",
  "path": "/api/v5/exchangeos/account/max-size",
  "query": {
    "assetId": "102",
    "price": "95000",
    "leverage": "10"
  }
}

请求示例：查询只减仓可下量

json

{
  "method": "GET",
  "path": "/api/v5/exchangeos/account/max-size",
  "query": {
    "assetId": "102",
    "reduceOnly": true
  }
}

请求示例：查询子账户

json

{
  "method": "GET",
  "path": "/api/v5/exchangeos/account/max-size",
  "query": {
    "assetId": "102",
    "price": "95000",
    "leverage": "10",
    "vaultAddress": "0x6d1a19e1e03b83163fb38d7336b58875e71c50c2"
  }
}

响应字段

字段	类型	说明
assetId	String	产品 ID。
maxBuySz	String	最大可买数量。
maxSellSz	String	最大可卖数量。
avail	String	可用资金。
longAvailPos	String	可平多仓数量；不适用时返回空字符串。
shortAvailPos	String	可平空仓数量；不适用时返回空字符串。

响应示例：oneWay 开仓查询

json

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "assetId": "102",
      "maxBuySz": "0.42",
      "maxSellSz": "0.58",
      "avail": "667.09",
      "longAvailPos": "",
      "shortAvailPos": ""
    }
  ]
}

响应示例：hedge，`reduceOnly=true`#

json

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "assetId": "102",
      "maxBuySz": "0.20",
      "maxSellSz": "0.50",
      "avail": "667.09",
      "longAvailPos": "0.50",
      "shortAvailPos": "0.20"
    }
  ]
}

用户生效梯度档位 `GET /account/position-tiers`#

仅支持 Perps，需 OK-ACCESS-* 鉴权。返回当前账户在指定合约上的生效档位，包括函数参数和派生限额表，结构与公开 GET /market/position-tiers 相同。

生效档位解析规则

根据用户地址查询绑定的档位角色 roleId。
根据合约和 roleId 查询该合约的角色特殊档位。
命中时使用特殊档位；用户未绑定角色，或该合约未配置对应角色特殊档位时，使用合约默认档位。

绑定特殊档位角色，例如 MM 或 VIP 的账户，应使用本接口结果计算可开仓上限与费率，不应使用公开默认档位。

请求参数

参数	类型	必填	说明
assetId	String	是	Perps 产品 ID。
vaultAddress	String	否	子账户地址。省略时查询母账户。

请求示例

text

GET /api/v5/exchangeos/account/position-tiers?assetId=102

响应字段

公式与行为说明与 GET /market/position-tiers 相同。

字段	类型	说明
assetId	String	产品 ID。
positionTierId	String	生效仓位梯度档位 ID。
roleId	String	生效档位角色 ID。
roleName	String	生效档位角色名称。
basePositionValue0	String	保证金率曲线的基准仓位价值。
baseMMR0	String	基准维持保证金率。
baseIMR0	String	基准初始保证金率。
mmrChangeRate	String	维持保证金率变化率。
imrChangeRate	String	初始保证金率变化率。
maxPositionValue	String	最大仓位价值。
imrCurvePosValueGrid	String	初始保证金率曲线的仓位价值网格。
maxLeverage	String	最大杠杆倍数。
tiers	Array	杠杆与最大允许仓位价值对照表。
> leverage	String	杠杆倍数。
> maxPositionAllowed	String	该杠杆下允许的最大仓位价值。

** 响应示例：绑定 MM 角色并命中特殊档位**

json

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "assetId": "102",
      "positionTierId": "16",
      "roleId": "1",
      "roleName": "MM",
      "basePositionValue0": "100000",
      "baseMMR0": "0.004",
      "baseIMR0": "0.008",
      "mmrChangeRate": "0.0002",
      "imrChangeRate": "0.0004",
      "maxPositionValue": "10000000",
      "imrCurvePosValueGrid": "10000",
      "maxLeverage": "125",
      "tiers": [
        {
          "leverage": "125",
          "maxPositionAllowed": "100000"
        },
        {
          "leverage": "50",
          "maxPositionAllowed": "3100000"
        },
        {
          "leverage": "1",
          "maxPositionAllowed": "10000000"
        }
      ]
    }
  ]
}

设置杠杆倍数 POST /account/set-leverage

设置指定 Perps 产品的杠杆倍数。实际操作账户由 user 和可选的 vaultAddress 决定。

本接口只设置杠杆，不负责切换 cross 或 isolated。当前保证金模式由链上账户设置决定。

杠杆与保证金模式通用规则

保证金模式按“账户 + assetId”维度设置。
同一账户、同一 assetId 在同一时间只能使用 cross 或 isolated，不允许两种模式并存。
hedge 模式下不会出现 long 使用 cross、short 使用 isolated 的情况。
设置后的杠杆持续生效，不因平仓或其他交易操作而改变；即使无持仓、无挂单，杠杆设置仍会保留，只有再次设置杠杆才能变更。
positionSide 为可选且允许为 null 的字段；合法非空值为 net、long 和 short。
在 oneWay 或 hedge + cross 模式下，可省略 positionSide 或传入 null。
在 hedge + isolated 模式下，必须明确传入 long 或 short。

请求字段

参数	类型	必填	说明
action	Object	是	业务动作对象，参与 EIP-712 签名。
> type	String	是	固定为 `updateLeverage`。
> assetId	String	是	Perps 产品 ID。
> positionSide	String	条件必填	`net`、`long`、`short` 或 `null`。在 hedge + isolated 模式下必须为 `long` 或 `short`。
> leverage	String	是	目标杠杆倍数，必须为大于或等于 `1` 的整数。
nonce	Number	是	当前毫秒时间戳，用于签名与防重放。
user	String	是	主账户地址。
vaultAddress	String	否	子账户地址。传入时操作指定子账户。
signature	Object	是	EIP-712 ECDSA 签名。
> Ecdsa	Object	是	ECDSA 签名对象。
>> r	String	是	`0x` 开头的签名 `r` 值。
>> s	String	是	`0x` 开头的签名 `s` 值。
>> v	Number	是	签名恢复值，`0` 或 `1`。

positionSide 传值规则

在 hedge + isolated 模式下，每个 updateLeverage action 一次只能修改 long 或 short 的其中一侧，不能在一个 action 中同时修改两侧。

若需同时修改 long 和 short，必须提交两个独立请求，并使用不同的 nonce。两笔链上交易独立执行，不具原子性。

校验与行为

leverage 必须为大于或等于 1 的整数。
允许的最大杠杆由当前梯度档位、持仓价值及开仓挂单价值动态决定。
oneWay 模式不接受 long 或 short。
hedge + cross 不接受单独修改 long 或 short。
hedge + isolated 必须明确指定 long 或 short。
hedge + isolated 修改其中一侧时，不影响另一侧杠杆。
调高杠杆不进行新增保证金校验。
调低杠杆时，必须确认目标杠杆下保证金仍然充足。
超过杠杆调整允许的挂单数量时，设置会被拒绝；开发者需先撤除部分挂单。
请求值与目标设置维度的当前杠杆相同时，视为 no-op。
杠杆设置不依赖现有持仓；即使没有持仓，也会保留设置值。

** 请求示例：oneWay + cross 或 isolated**

省略 positionSide：

json

{
  "action": {
    "type": "updateLeverage",
    "assetId": "102",
    "leverage": "10"
  },
  "nonce": 1708930000000,
  "user": "0x9a8f...",
  "signature": {
    "Ecdsa": {
      "r": "0x...",
      "s": "0x...",
      "v": 1
    }
  }
}

** 请求示例：hedge + cross**

long 和 short 共用杠杆，因此同样省略 positionSide：

json

{
  "action": {
    "type": "updateLeverage",
    "assetId": "102",
    "leverage": "8"
  },
  "nonce": 1708930000001,
  "user": "0x9a8f...",
  "signature": {
    "Ecdsa": {
      "r": "0x...",
      "s": "0x...",
      "v": 1
    }
  }
}

** 请求示例：hedge + isolated，修改 long**

json

{
  "action": {
    "type": "updateLeverage",
    "assetId": "102",
    "positionSide": "long",
    "leverage": "10"
  },
  "nonce": 1708930000002,
  "user": "0x9a8f...",
  "signature": {
    "Ecdsa": {
      "r": "0x...",
      "s": "0x...",
      "v": 1
    }
  }
}

** 请求示例：hedge + isolated，修改 short**

json

{
  "action": {
    "type": "updateLeverage",
    "assetId": "102",
    "positionSide": "short",
    "leverage": "5"
  },
  "nonce": 1708930000003,
  "user": "0x9a8f...",
  "signature": {
    "Ecdsa": {
      "r": "0x...",
      "s": "0x...",
      "v": 1
    }
  }
}

响应示例

json

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "txHash": "0x..."
    }
  ]
}

设置保证金模式 `POST /account/set-margin-mode`#

设置指定 Perps 产品的保证金模式，在 cross 与 isolated 之间切换。

本接口为写操作。请求中的 action 是 EIP-712 签名对象，必须使用 canonical Action 字段完成签名。

设置维度为：

text

目标账户 × assetId

母账户和各子账户分别维护保证金模式。操作子账户时，必须在签名信封中传入 vaultAddress。

本接口仅适用于 Perps，不适用于 Spot，不接受 positionSide。在 hedge 模式下，long 和 short 必须一起切换保证金模式。

保证金模式设置规则

同一账户、同一 assetId 只能存在一种保证金模式。
同一账户、同一 assetId 不会同时存在全仓与逐仓仓位。
oneWay 模式下，该 assetId 的 net 仓位整体切换。
hedge 模式下，该 assetId 的 long 与 short 一起切换。
不允许仅切换 long 或仅切换 short。
action 不得传入 positionSide。
母账户和各子账户的设置彼此独立。
已部分平仓的仓位仍可切换保证金模式。
切换时直接修改仓位的 marginMode，不会通过先平仓再重新开仓完成。
目标模式与当前模式相同时，可作为同值设置请求完成，最终设置保持不变。
同值设置不保证产生 exchangeos-setting-updates 推送。
切换失败时，原 marginMode、仓位、杠杆及资金状态保持不变。

切换前置条件

执行切换前，系统会检查：

assetId 必须存在且为有效的 Perps 产品。
目标 marginMode 必须是该产品支持的模式。
仅支持逐仓的产品不得切换为 cross。
同一 assetId 不得存在任何未完成订单，包括普通挂单、Trigger Order、Order-Attached TPSL 和 Position-Attached TPSL。
Mark Price 必须可用。
切换后的保证金必须满足风控要求。
hedge + isolated 切换为 cross 时，long 与 short 的杠杆必须符合合并规则。

任一条件不满足时，切换失败，原有设置保持不变。

杠杆继承规则

oneWay

cross 切换为 isolated：沿用当前 net leverage。
isolated 切换为 cross：沿用当前 net leverage。

hedge + cross 切换为 isolated

long 与 short 一起切换为 isolated。
long 与 short 的初始杠杆均继承切换前共用的 cross leverage。
切换完成后，long 与 short 可分别通过 POST /account/set-leverage 调整杠杆。

hedge + isolated 切换为 cross

long 与 short 同时有仓位且杠杆不同：切换失败。
long 与 short 同时有仓位且杠杆相同：切换后使用该共同杠杆。
仅 long 有仓位：切换后共用杠杆沿用 long leverage。
仅 short 有仓位：切换后共用杠杆沿用 short leverage。
long 与 short 均无仓位：共用杠杆使用该 assetId 当前有效的账户设置值。

cross 切换为 isolated 的保证金校验

系统从全仓余额划转足够资金至逐仓仓位。

每个仓位所需的初始保证金：

text

positionIM
= abs(pos) × avgPx ÷ leverage

负未实现盈亏所需的额外补足金额：

text

negativeUplBuffer
= abs(min(0, upl))

单一仓位所需划转金额：

text

requiredTransfer
= positionIM + negativeUplBuffer

hedge 模式下，如果 long 与 short 都有仓位，分别计算后加总：

text

requiredTransferTotal
= Σ(positionIM + negativeUplBuffer)

校验条件：

text

coinMaxTransfer >= requiredTransferTotal

等于边界时允许切换：

text

coinMaxTransfer == requiredTransferTotal

低于需求值时拒绝：

text

coinMaxTransfer < requiredTransferTotal

切换成功后：

系统从全仓余额划转 requiredTransferTotal 至对应逐仓仓位。
仓位的 marginMode 更新为 isolated。
逐仓仓位余额增加相应的划转金额。

isolated 切换为 cross 的保证金校验#

系统将逐仓仓位余额转回全仓，并以切换后的假设账户状态重新进行风控校验。

校验条件：

text

coinEquityAfter >= coinPerpPosFrozenMarginAfter

其中：

coinEquityAfter：假设逐仓仓位已转为全仓后的保证金币权益。
coinPerpPosFrozenMarginAfter：假设切换完成后，所有全仓 Perps 仓位所需的保证金占用。

等于边界时允许切换：

text

coinEquityAfter == coinPerpPosFrozenMarginAfter

低于需求值时拒绝：

text

coinEquityAfter < coinPerpPosFrozenMarginAfter

切换成功后：

对应逐仓仓位的 posIsoPerpBalance 转回全仓。
仓位的 marginMode 更新为 cross。
原逐仓仓位余额归零。
切换后由全仓保证金共同承担仓位风险。

精度与边界规则

保证金校验使用链上风控系统的内部定点精度。
计算过程不得先按 API Response 的显示小数位截断或四舍五入。
比较条件使用 >=，等于需求值时允许切换。
即使差额小于 API 显示精度，只要内部精确值低于需求值，仍会被拒绝。
API 返回的 availBal、availEq、upl、avgPx 等字段仅用于估算，不能保证完全重现链上最终校验结果。
coinMaxTransfer 是风控校验使用的内部可划转额度。
如果 OpenAPI 未直接返回 coinMaxTransfer，应以同步回执或 GET /trade/transaction 的链上结果为最终判定。
账户仍有 0.000001 可用余额不能直接说明资金足够，必须与本次切换所需的 requiredTransferTotal 按内部精度比较。

请求字段

参数	类型	必填	说明
action	Object	是	业务动作对象，参与 EIP-712 签名。不得包含 `positionSide`。
> type	String	是	固定为 `updateMarginMode`。
> assetId	String	是	Perps 产品 ID。
> marginMode	String	是	目标保证金模式：`cross` 或 `isolated`。
nonce	Number	是	当前毫秒时间戳，用于签名与防重放。
user	String	是	主账户地址。
vaultAddress	String	否	子账户地址。传入时操作指定子账户。
signature	Object	是	EIP-712 ECDSA 签名。
> Ecdsa	Object	是	ECDSA 签名对象。
>> r	String	是	`0x` 开头的签名 `r` 值。
>> s	String	是	`0x` 开头的签名 `s` 值。
>> v	Number	是	签名恢复值，`0` 或 `1`。

保证金模式是 assetId 维度的统一设置。在 hedge 模式下，同一 assetId 的 long 与 short 必须一起切换，不允许两侧使用不同的 marginMode。

请求示例：母账户从 cross 切换为 isolated

json

{
  "action": {
    "type": "updateMarginMode",
    "assetId": "102",
    "marginMode": "isolated"
  },
  "nonce": 1708930100000,
  "user": "0x742d35cc00000000000000000000000000000000",
  "signature": {
    "Ecdsa": {
      "r": "0x1111111111111111111111111111111111111111111111111111111111111111",
      "s": "0x2222222222222222222222222222222222222222222222222222222222222222",
      "v": 1
    }
  }
}

请求示例：子账户从 isolated 切换为 cross

json

{
  "action": {
    "type": "updateMarginMode",
    "assetId": "102",
    "marginMode": "cross"
  },
  "nonce": 1708930100001,
  "user": "0x742d35cc00000000000000000000000000000000",
  "vaultAddress": "0x6d1a19e1e03b83163fb38d7336b58875e71c50c2",
  "signature": {
    "Ecdsa": {
      "r": "0x1111111111111111111111111111111111111111111111111111111111111111",
      "s": "0x2222222222222222222222222222222222222222222222222222222222222222",
      "v": 1
    }
  }
}

响应：同步模式成功

同步等待链上回执。响应结构与 GET /trade/transaction 返回的交易回执一致。

updateMarginMode 成功回执为 Empty；成功时不返回 response。客户端不得将缺少 response 视为异常，应使用 status="ok" 判断链上执行成功。

json

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "blockHash": "0xbb177081b88369e4005bbf2098632579441b3b7b9c405a52d4d54fb03df15ee7",
      "blockHeight": "109575200",
      "txHash": "0x518a4e71ad4525b3fa2fad9f4c9284d13e23af022c081b9d065f047976b831a0",
      "txIndex": "0",
      "status": "ok"
    }
  ]
}

同步成功后：

code="0" 表示 OpenAPI 成功取得交易回执。
status="ok" 表示 updateMarginMode 已在链上执行成功。
response 被省略表示该 Action 成功回执为 Empty。
可使用 GET /account/leverage-info 确认最新 marginMode。
若设置实际发生变更，也可通过 exchangeos-setting-updates 接收更新。

响应：同步模式链上执行失败

如果交易已上链，但链上业务校验失败，外层 code 仍为 "0"，status 为 "err"，失败原因位于 response.code 和 response.message。

以下示例为 nonce 校验失败：

json

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "blockHash": "0xbb177081b88369e4005bbf2098632579441b3b7b9c405a52d4d54fb03df15ee7",
      "blockHeight": "109575200",
      "txHash": "0x518a4e71ad4525b3fa2fad9f4c9284d13e23af022c081b9d065f047976b831a0",
      "txIndex": "0",
      "status": "err",
      "response": {
        "code": "30004",
        "message": "Nonce validation failed"
      }
    }
  ]
}

此时：

保证金模式切换失败。
原 marginMode 保持不变。
原仓位、杠杆和资金状态保持不变。
不得只根据外层 code="0" 判断切换成功。
不应使用相同 nonce 重新提交。

响应：同步模式未及时取得回执#

交易已提交，但同步等待期间未收到链上回执时，返回 80106，并在 data 中保留 txHash。

json

{
  "code": "80106",
  "msg": "transaction accepted but receipt notification was not received",
  "data": [
    {
      "txHash": "0x518a4e71ad4525b3fa2fad9f4c9284d13e23af022c081b9d065f047976b831a0"
    }
  ]
}

80106 不是最终失败状态。交易可能已成功执行，客户端不得直接重新提交，应使用该 txHash 查询：

text

GET /api/v5/exchangeos/trade/transaction?txHash=0x518a4e71ad4525b3fa2fad9f4c9284d13e23af022c081b9d065f047976b831a0

调整逐仓保证金 `POST /account/adjust-isolated-margin`#

为逐仓仓位增加或减少保证金。这是写操作，SDK 组装 updateIsolatedMargin action。

增加或减少由 direction 指定，而非由 amount 的正负号指定；amount 必须大于 0。

目标仓位必须已经存在，否则调整逐仓保证金失败。

请求字段

参数	类型	必填	说明
action	Object	是	业务动作对象，参与 EIP-712 签名。
> type	String	是	固定为 `updateIsolatedMargin`。
> assetId	String	是	Perps 产品 ID。
> positionSide	String	是	目标逐仓仓位方向：`long` 或 `short`。
> direction	String	是	调整方向：`crossToIso` 表示增加逐仓保证金；`isoToCross` 表示减少逐仓保证金。
> amount	String	是	调整金额，必须大于 `0`。
nonce	Number	是	当前毫秒时间戳，用于签名与防重放。
user	String	是	主账户地址。
vaultAddress	String	否	子账户地址。传入时操作指定子账户。
signature	Object	是	EIP-712 ECDSA 签名。

约束

目标仓位必须存在且保证金模式必须为 isolated。
crossToIso 上限为账户可用保证金。
isoToCross 上限为在不破坏维持保证金要求前提下可划出的金额。

请求示例：增加 100 USDS 逐仓保证金#

json

{
  "action": {
    "type": "updateIsolatedMargin",
    "assetId": "102",
    "positionSide": "long",
    "direction": "crossToIso",
    "amount": "100"
  },
  "nonce": 1708930500000,
  "user": "0x9a8f...",
  "signature": {
    "Ecdsa": {
      "r": "0x...",
      "s": "0x...",
      "v": 1
    }
  }
}

响应示例

json

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "txHash": "0x..."
    }
  ]
}

设置持仓模式 `POST /account/set-position-mode`#

在 oneWay 与 hedge 之间切换。设置维度为账户；母账户与各子账户独立设置。

切换前置条件#

账户不得存在任何持仓。
账户不得存在普通挂单、Trigger 或 Attached TPSL。
目标值与当前 positionMode 相同时视为 no-op。

杠杆继承规则

oneWay → hedge

long leverage 等于原 net leverage。
short leverage 等于原 net leverage。
若 assetId 当前为 isolated，切换完成后 long 和 short 可分别调整杠杆。

hedge → oneWay#

net leverage 取 long leverage 与 short leverage 中较小的值。

切换 positionMode 不会改变各 assetId 当前的 marginMode。

请求字段

参数	类型	必填	说明
action	Object	是	业务动作对象，参与 EIP-712 签名。
> type	String	是	固定为 `updatePositionMode`。
> mode	String	是	目标持仓模式：`oneWay` 或 `hedge`。
nonce	Number	是	当前毫秒时间戳，用于签名与防重放。
user	String	是	主账户地址。
vaultAddress	String	否	子账户地址。传入时操作指定子账户。
signature	Object	是	EIP-712 ECDSA 签名。

请求示例：将母账户切换为 hedge

json

{
  "action": {
    "type": "updatePositionMode",
    "mode": "hedge"
  },
  "nonce": 1708930550000,
  "user": "0x742d35cc...",
  "signature": {
    "Ecdsa": {
      "r": "0x...",
      "s": "0x...",
      "v": 1
    }
  }
}

请求示例：将子账户切换为 hedge

json

{
  "action": {
    "type": "updatePositionMode",
    "mode": "hedge"
  },
  "nonce": 1708930550001,
  "user": "0x742d35cc...",
  "vaultAddress": "0x6d1a19e1e03b83163fb38d7336b58875e71c50c2",
  "signature": {
    "Ecdsa": {
      "r": "0x...",
      "s": "0x...",
      "v": 1
    }
  }
}

响应示例

json

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "txHash": "0x..."
    }
  ]
}

查询杠杆倍数 `GET /account/leverage-info`#

查询账户在指定 Perps 产品上的有效杠杆设置及当前允许的最大杠杆。

请求参数

参数	类型	必填	说明
assetId	String	是	Perps 产品 ID。
positionSide	String	否	在 hedge + isolated 模式下，可指定 `long` 或 `short`。
vaultAddress	String	否	子账户地址。省略时查询母账户。

请求示例：查询全部有效杠杆设置

text

GET /api/v5/exchangeos/account/leverage-info?assetId=102

请求示例：查询 hedge + isolated 的 long#

text

GET /api/v5/exchangeos/account/leverage-info?assetId=102&positionSide=long

请求示例：查询子账户

text

GET /api/v5/exchangeos/account/leverage-info?assetId=102&vaultAddress=0x6d1a19e1e03b83163fb38d7336b58875e71c50c2

返回规则

hedge + cross 的 maxLeverage 必须按 long 和 short 两个方向的持仓及开仓挂单分别计算，最终返回两者中较小的值，因为共享杠杆变更会同时影响两侧。
hedge + isolated 的 maxLeverage 则按 long 和 short 各自独立计算。

响应字段

字段	类型	说明
assetId	String	产品 ID。
marginMode	String	保证金模式：`cross` 或 `isolated`。
positionSide	String	持仓方向。在 hedge + isolated 模式下返回 `long` 或 `short`。
leverage	String	当前有效杠杆。
maxLeverage	String	当前允许设置的最大杠杆。

响应示例：oneWay + cross

json

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "assetId": "102",
      "marginMode": "cross",
      "leverage": "10",
      "maxLeverage": "30"
    }
  ]
}

响应示例：oneWay + isolated

json

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "assetId": "102",
      "marginMode": "isolated",
      "leverage": "10",
      "maxLeverage": "25"
    }
  ]
}

以上为两种独立状态示例。同一账户、同一 assetId 不会同时返回 cross 与 isolated。

响应示例：hedge + cross#

json

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "assetId": "102",
      "marginMode": "cross",
      "leverage": "8",
      "maxLeverage": "20"
    }
  ]
}

响应示例：hedge + isolated

json

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "assetId": "102",
      "marginMode": "isolated",
      "positionSide": "long",
      "leverage": "10",
      "maxLeverage": "30"
    },
    {
      "assetId": "102",
      "marginMode": "isolated",
      "positionSide": "short",
      "leverage": "5",
      "maxLeverage": "20"
    }
  ]
}

查询交易手续费率 `GET /account/trade-fee`#

查询指定产品的交易手续费率。

手续费正负号规则：

正值：平台收取手续费。
负值：返佣。实际费率可能因账户等级或费率方案而不同。

请求参数

参数	类型	必填	说明
assetId	String	否	产品 ID。

请求示例

text

GET /api/v5/exchangeos/account/trade-fee?assetId=102

响应字段

字段	类型	说明
assetId	String	产品 ID。
taker	String	Taker 手续费率。正值表示收费，负值表示返佣。
maker	String	Maker 手续费率。正值表示收费，负值表示返佣。

响应示例

json

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "assetId": "102",
      "taker": "0.000500",
      "maker": "0.000200"
    }
  ]
}

资金流水（账单） `GET /account/bills`#

查询账户余额变动流水。每条流水对应一次余额变动，可追溯、可对账、可幂等。涵盖 Perps 和 Spot，语义与订单历史一致，最多查询最近一年的数据。

balChg 为 String：

正值表示余额增加或入账。
负值表示余额减少或扣款。
例如：扣费时 balChg="-0.00196"；而 fills.fee="0.00196" 表示费用金额，两者语义不同。

分页规则

记录位于 data[0].data，按 cTime 从新到旧返回。
每页在 data[0].nextCursor 返回下一页令牌。令牌为不透明值，客户端不得解析或自行构造。
使用 data[0].hasMore 判断是否继续请求。hasMore=false 且 nextCursor="" 表示最后一页。
不得以“返回笔数小于 limit”判断终点。使用 billType 或 flowCategory 等过滤条件时，本页记录数可小于 limit 且仍有后续数据。
begin 和 end 仅用于时间窗过滤，不作为续传游标。与 cursor 同时传入时，以 cursor 定位起点。
首页不传 cursor。
billId 是全市场共用的全局单调序列。对于单一用户视图，不保证连续；不得以序号差值推算记录数，也不得以序号缺口判断数据丢失。数据完整性由分页契约保证。

请求参数

参数	类型	必填	说明
billType	String	否	按账单类型过滤。
flowCategory	String	否	按资金流类别过滤。
assetId	String	否	按产品 ID 过滤。
begin	String	否	时间窗起点，Unix 毫秒时间戳。
end	String	否	时间窗终点，Unix 毫秒时间戳。
cursor	String	否	上一页返回的续传令牌。首页不传。
limit	String	否	返回记录数量。
vaultAddress	String	否	子账户地址。省略时查询母账户。

请求示例

text

GET /api/v5/exchangeos/account/bills?billType=funding_fee&assetId=102&limit=100
GET /api/v5/exchangeos/account/bills?cursor=1&limit=100
GET /api/v5/exchangeos/account/bills?flowCategory=transfer&begin=1704067200000&end=1704070800000&limit=100

响应字段

字段	类型	说明
data	Array	账单记录。
> assetId	String	产品 ID；不适用时返回空字符串。
> bal	String	余额变动后的余额。
> balChg	String	余额变动金额。正值表示入账，负值表示扣款。
> billId	String	账单 ID。全市场全局单调序列；对单一用户不保证连续。
> billType	String	账单类型。
> cTime	String	账单生成时间，Unix 毫秒时间戳。
> flowCategory	String	资金流类别。
> from	String	转出方地址；不适用时返回空字符串。
> marginMode	String	保证金模式；不适用时返回空字符串。
> oid	String	关联订单 ID；不适用时返回空字符串。
> to	String	转入方地址；不适用时返回空字符串。
> tokenId	String	Token ID。
> tradeId	String	关联成交 ID；不适用时返回空字符串。
hasMore	Boolean	是否仍有更多记录。
nextCursor	String	下一页续传令牌；最后一页返回空字符串。

响应示例

json

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "data": [
        {
          "assetId": "",
          "bal": "100",
          "balChg": "+100",
          "billId": "137074380-27-0",
          "billType": "deposit",
          "cTime": "1790068571545",
          "flowCategory": "transfer",
          "from": "",
          "marginMode": "",
          "oid": "",
          "to": "0x112001ee52b6a119272b273f9062208f7d75c6fd",
          "tokenId": "1771",
          "tradeId": ""
        }
      ],
      "hasMore": false,
      "nextCursor": ""
    }
  ]
}

账户详情 `GET /account/detail`#

查询账户的 Agent、子账户、母账户关系、用户等级及其他账户级设置。

请求参数

无。

请求示例#

text

GET /api/v5/exchangeos/account/detail

响应字段

字段	类型	说明
user	String	当前账户地址。
parentAccount	String	母账户地址。母账户返回空字符串。
subAccounts	Array	子账户列表。
> address	String	子账户地址。
> positionMode	String	子账户持仓模式：`oneWay` 或 `hedge`。
positionMode	String	当前账户持仓模式：`oneWay` 或 `hedge`。
level	String	用户等级。
ip	String	已配置的 IP 地址列表。
agents	Array	Agent 列表。
> address	String	Agent 地址。
> status	String	Agent 状态，例如 `active` 或 `expired`。
> expiry	String	Agent 到期时间，Unix 毫秒时间戳。

响应示例

json

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "user": "0x2e988a386a799f506693793c6a5af6b54dfaabfb",
      "parentAccount": "",
      "subAccounts": [
        {
          "address": "0x6d1a19e1e03b83163fb38d7336b58875e71c50c2",
          "positionMode": "hedge"
        },
        {
          "address": "0x93f51fc5190b1e7bb82238bcc2f93430b43a9243",
          "positionMode": "oneWay"
        }
      ],
      "positionMode": "oneWay",
      "level": "VIP5",
      "ip": "117.37.203.58,117.37.203.57",
      "agents": [
        {
          "address": "0xa880d6cc607a05ea617307ab3b0d335e8d8424ee",
          "status": "active",
          "expiry": "1816754400000"
        },
        {
          "address": "0x1563915e194d8cfba1943570603f7606a3115508",
          "status": "expired",
          "expiry": "1785218400000"
        }
      ]
    }
  ]
}

查询用户限额 `GET /account/limits`#

查询母账户或指定子账户当前生效的链上交易限额，包括 Action 额度、cancelAll 日限额、撤单豁免额度和挂单数限额。

母账户和子账户的限额按账户地址分别记录和独立计算，彼此不共享额度或用量。批量交易的额度按交易笔数计算。

Action Limit 与 `actionLimit.used` 计算规则#

每个钱包地址均有可执行链上交易操作的 Action 额度：

每个钱包地址初始拥有 30,000 Actions。
每完成 1 USD 的交易量，默认增加 1 Action limit。
普通下单、撤单和改单各计为 1 Action used；cancelAll 计为 5 Action used。
撤单限额为 min(actionLimit × 2, limit + 200,000)。
action_used >= limit 时，普通 Action 进入限速状态；action_used >= cancel_limit 时，撤单进入限速状态。
限速状态下每 5 秒可提交一次请求。

请求参数

参数	类型	必填	说明
vaultAddress	String	否	子账户地址。省略时查询母账户；传入时查询指定子账户。网关会验证该地址是否属于当前已认证用户。母账户与子账户限额独立记录和计算。

请求示例

text

GET /api/v5/exchangeos/account/limits
GET /api/v5/exchangeos/account/limits?vaultAddress=0x6d1a19e1e03b83163fb38d7336b58875e71c50c2

响应字段

字段	类型	说明
actionLimit	Object	用户 Action 请求额度。
> initial	String	用户初始 Action 额度。
> earned	String	用户通过成交量获得的 Action 额度。
> purchased	String	用户通过 `reserveRequestWeight` 购买的 Action 额度。
> granted	String	系统通过治理设置额外授予的 Action 额度。
> used	String	账户自开始记录以来累计消耗的 Action 额度，不按日重置。批量操作按内部 Action 数量累计。
> remaining	String	当前可用 Action 额度，以服务端计算结果为准。
> isThrottled	Boolean	是否已进入限流状态。
> throttleIntervalMs	String	进入限流后的最小请求间隔，单位为毫秒；未限流时仍返回当前配置值。
cancelAll	Object	用户 `cancelAll` 日限额。
> dailyLimit	String	当前统计周期内允许调用 `cancelAll` 的总次数。
> used	String	当前周期已使用的 `cancelAll` 次数；每日重置。
> remaining	String	当前统计周期内剩余可用次数。
> periodStartMs	String	当前统计周期起始时间，Unix 毫秒时间戳。
> periodEndMs	String	当前统计周期结束时间，Unix 毫秒时间戳。
cancelExemption	Object	Action 额度受限后，用于撤销既有挂单的专用豁免额度。
> limit	String	撤单操作可使用的累计豁免额度。
> remaining	String	剩余撤单豁免额度。
openOrders	Object	用户当前挂单数及挂单上限。
> current	String	当前未完成挂单数量。
> limit	String	当前实际生效的挂单数量上限。
> userOverride	String	管理员为该用户单独设置的挂单上限。未设置时返回 `""`；管理员明确设置为零时返回 `"0"`。
block_timestamp	String	查询结果对应的链上区块时间，Unix 毫秒时间戳。
block_height	String	查询结果对应的链上区块高度。

当 openOrders.userOverride 已设置时，openOrders.limit 直接使用该值。未设置时：

text

openOrders.limit
= min(
    initial_limit + weighted_volume / volume_per_extra_order,
    max_limit
  )

weighted_volume
= spot 成交额
+ perp 成交额
+ prediction 成交额 × prediction_volume_multiplier

默认值：

text

initial_limit = 2000
volume_per_extra_order = 1,000,000
max_limit = 10000
prediction_volume_multiplier = 10

客户端应以 openOrders.limit 判断实际生效的挂单上限。

响应示例

json

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "actionLimit": {
        "initial": "30000",
        "earned": "125000",
        "granted": "0",
        "purchased": "10000",
        "used": "20000",
        "remaining": "145000",
        "isThrottled": false,
        "throttleIntervalMs": "5000"
      },
      "cancelAll": {
        "dailyLimit": "10",
        "periodStartMs": "1789056000000",
        "periodEndMs": "1789142400000",
        "remaining": "8",
        "used": "2"
      },
      "cancelExemption": {
        "limit": "330000",
        "remaining": "320000"
      },
      "openOrders": {
        "current": "128",
        "limit": "2000",
        "userOverride": "0"
      },
      "block_timestamp": "1789092000074",
      "block_height": "12092410"
    }
  ]
}