> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qfex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 子账户 REST API

> 用于子账户管理的 REST 接口

QFEX 为子账户工作流提供三个 REST 接口：

* `GET /user/subaccounts`
* `POST /user/subaccounts`
* `POST /user/transfer`

这些接口均要求身份认证。

## 身份认证

CLI 使用以下方式之一认证请求：

* 执行 `qfex login` 后发送 `Authorization: Bearer <access_token>`；或
* 已配置 API 密钥时，发送 QFEX HMAC 请求头。

使用 HMAC 认证时，以密钥私密部分对 `${nonce}:${unix_ts}` 进行 HMAC-SHA256 签名，然后将结果编码为十六进制。

发送以下请求头：

* `x-qfex-public-key`
* `x-qfex-hmac-signature`
* `x-qfex-nonce`
* `x-qfex-timestamp`

## 列出子账户

返回当前已认证用户的子账户 ID，不包含主账户 ID。

```http theme={null}
GET /user/subaccounts
```

CLI 命令：

```sh theme={null}
qfex account subaccounts list
```

示例：

```sh theme={null}
curl https://api.qfex.com/user/subaccounts \
  -H "accept: application/json" \
  -H "x-qfex-public-key: $QFEX_PUBLIC_KEY" \
  -H "x-qfex-hmac-signature: $SIG" \
  -H "x-qfex-nonce: $NONCE" \
  -H "x-qfex-timestamp: $TS"
```

响应结构：

```json theme={null}
{
  "account_ids": [
    "11111111-1111-1111-1111-111111111111",
    "22222222-2222-2222-2222-222222222222"
  ]
}
```

## 创建子账户

为当前已认证用户分配一个新的子账户。

```http theme={null}
POST /user/subaccounts
Content-Type: application/json
```

CLI 命令：

```sh theme={null}
qfex account subaccounts create
```

CLI 发送空 JSON 对象作为请求体。

示例：

```sh theme={null}
curl https://api.qfex.com/user/subaccounts \
  -X POST \
  -H "content-type: application/json" \
  -H "accept: application/json" \
  -H "x-qfex-public-key: $QFEX_PUBLIC_KEY" \
  -H "x-qfex-hmac-signature: $SIG" \
  -H "x-qfex-nonce: $NONCE" \
  -H "x-qfex-timestamp: $TS" \
  -d '{}'
```

## 主账户与子账户之间转账

在当前已认证用户拥有的两个账户之间转移余额。

```http theme={null}
POST /user/transfer?src_account_id=<account-id>&dst_account_id=<account-id>
Content-Type: application/json
```

CLI 命令：

```sh theme={null}
qfex account subaccounts transfer --from <account-id|primary> --to <account-id|primary> --amount <usd>
```

CLI 将 `primary` 解析为当前用户的主账户 ID，然后发送：

* 查询参数 `src_account_id`；
* 查询参数 `dst_account_id`；
* JSON 请求体 `{"amount": <number>}`。

示例：

```sh theme={null}
curl "https://api.qfex.com/user/transfer?src_account_id=$PRIMARY_ACCOUNT_ID&dst_account_id=$SUBACCOUNT_ID" \
  -X POST \
  -H "content-type: application/json" \
  -H "accept: application/json" \
  -H "x-qfex-public-key: $QFEX_PUBLIC_KEY" \
  -H "x-qfex-hmac-signature: $SIG" \
  -H "x-qfex-nonce: $NONCE" \
  -H "x-qfex-timestamp: $TS" \
  -d '{"amount":100}'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.