现货划转

类型：SESSION · 权重：—（不经过 /api/v3 限流器）

状态：已实现。

POST /v1/spot/transfer

在交易所钱包会话的资金账户（合约账户）与该会话 Canton party 的现货账户之间划转余额。与 /v1/wallet/* 一样以钱包会话 bearer token 鉴权；没有 X-MBX-APIKEY / signature。现货一侧就是 session-key 为之签发密钥的那个确定性账户（UUIDv5("rocky-spot:" + party)），因此在这里划入的资金会在该 party 会话密钥的 GET /api/v3/account 中显示。

只能划转 CUSD。链上结算启用后，钱包出资（已注册）账户完全不能使用本接口——它们的钱包是唯一的资金来源。

请求 —— JSON 请求体

POST /v1/spot/transfer
Authorization: Bearer <交易所钱包会话 token>
Content-Type: application/json

{ "asset": "CUSD", "amount": "12.5", "direction": "toSpot" }

字段	类型	必填	说明
asset	string	是	CUSD（别名 USDC 也接受并映射为 CUSD）。大小写不敏感。其他资产 → 400。
amount	string	是	正小数。
direction	string	是	toSpot（资金 → 现货）或 toFunding（现货 → 资金）。大小写不敏感；也接受 TO_SPOT / FUNDING_TO_SPOT 与 TO_FUNDING / SPOT_TO_FUNDING。

响应 — 200（值仅为示意）

{
  "asset": "CUSD",
  "direction": "toSpot",
  "amount": "12.5",
  "fundingAvailable": "987.5",
  "spotFree": "112.5"
}

字段	类型	说明
asset	string	恒为 CUSD。
direction	string	归一化为 toSpot 或 toFunding。
amount	string	解析后实际划转的金额。
fundingAvailable	string	划转后资金账户的可用余额。
spotFree	string	划转后现货账户 CUSD 的 free 余额。

钱包出资门槛（仅在交易场所启用链上结算后生效；见 链上结算）

账户	toSpot	toFunding
已注册（钱包出资）	拒绝	拒绝
已绑定 party 但尚未注册	拒绝	允许（以便清空遗留的内部余额）
未绑定 party	允许	允许

错误 —— 响应体为 { "error": "<message>" }，不是 {code,msg} 信封

HTTP	error / 原因
400	amount must be a positive decimal；only CUSD can be transferred between contract and spot accounts；unknown transfer direction: …；请求体不是合法 JSON；或账本拒绝了某个参数。
401	missing bearer token / invalid session。
403	session has no Canton party; connect a wallet first。
422	Wallet-funded account: fund via your Canton wallet; internal transfer is disabled.（见上表门槛）；或账本报告前置条件失败（如余额不足，原样透传其消息）。
500	spot transfer failed; try again。