1. 认证与账号范围
在控制台「系统与更新」创建 API 凭据，配置可访问账号和 read / operate / trade / admin 权限。请求头使用 Authorization: Bearer YOUR_TOKEN。不要把口令放进 URL。交互式文档里的 Authorize 按钮可填写令牌。
环境编号 account_id 与平台 UID 不同。先 GET /v1/accounts 获取你有权限的账号；其中 exchange_uid 为绑定 UID，observed_uid 为最近识别到的 UID，identity_state 为核验状态。改名不会改变编号和 UID。列表中的 overview 包含资产、最近交易、同步状态和最近事件。
curl -H 'Authorization: Bearer YOUR_TOKEN' \ https://ec.perpetualquant.fun/v1/accounts
2. 账号、资产与事件
| 接口 | 作用 | 权限 |
|---|---|---|
| GET /v1/egress | 代理列表与最近检测结果，不返回用户名密码 | admin |
| POST /v1/egress/import | body: {"content":"代理配置文本或 JSON 字符串","protocol":"socks5","preview":true}。先预览；preview:false 保存并去重。最多 100 条 / 64 KB | admin |
| POST /v1/egress/{egress_id}/test | 从服务器检测实际出口。result.state 为 ok / mismatch / failed；same_ip_routes 提示已检测的相同 IP。检测不分配账号 | admin |
| POST /v1/assign | body: {"account_id":"环境编号","egress_id":"出口编号"}。先暂停账号；保存后启动生效 | operate |
| GET /v1/accounts | 账号总览，含绑定 UID 与资产摘要 | read |
| GET /v1/network-policy；PUT /v1/network-policy | 读取或切换网络规则。PUT body: {"mode":"independent"}，每账号独立 IP；shared 为显式共享测试。切换前暂停所有账号，独立模式不允许直连 | read / admin |
| POST /v1/accounts | 创建环境，body: {"label":"账号名称","egress_id":"代理 ID"}，独立模式要求最近检测通过且实际 IP 未占用；建议带稳定 Idempotency-Key | admin |
| DELETE /v1/accounts/{account_id} | 停止维护并移入已删除；保留历史，可恢复。未结算订单或无法确认进程停止时返回 409；重复删除幂等 | admin |
| GET /v1/accounts?deleted=true | 查看有权限的已删除环境 | read |
| POST /v1/accounts/{account_id}/restore | 恢复环境，保持暂停；UID 被其他环境占用时返回 409 | admin |
| PATCH /v1/accounts/{account_id} | 修改备注，body: {"label":"新名称"}，1–60 字符 | operate |
| GET /v1/accounts/{account_id}/login-network；POST 同一路径 | 列出出口可用性及不可用原因；POST body: {"egress_id":"代理 ID"}，停止旧进程后保存分配，随后调用登录入口 | operate |
| POST /v1/accounts/{account_id}/login-qr | 缺少可用出口返回 NETWORK_REQUIRED，不创建临时登录环境；新环境启动登录；已绑定环境先返回 CHOOSE_LOGIN，提交 intent=restore_bound、expected_uid=原 UID 后创建独立登录环境，restart=true 可重新生成环境。核验 UID 后才接入；冲突返回 IDENTITY_MISMATCH。GET 仅允许读取登录环境二维码 | operate / read |
| POST /v1/accounts/{account_id}/start 或 /stop | 启动或暂停此账号维护 | operate |
| POST /v1/accounts/{account_id}/refresh | 排队读取余额、仓位和交易；立即返回 REFRESHING，查看 overview 的时间与错误判断结果 | read |
| GET /v1/accounts/{account_id}/balances 或 /positions | 最近成功采集快照，检查 stale 和 observed_at | read |
| GET /v1/ledger?account_id=… | 平台结算历史及持仓、同步进度、累计盈亏；用 next_before 翻页 | read |
| GET /v1/accounts/{account_id}/replay?symbol=BTCUSDT&start=…&end=… | 按账号和时间窗口读取真实订单回执。start/end 为毫秒时间戳，最多 25 小时；返回与窗口重叠的订单，最多 1000 笔，并提供 total、truncated、同步新鲜度和身份冲突提示。不发起交易 | read |
| POST /v1/accounts/{account_id}/sync | 请求后台同步平台持仓和结算，不发送订单 | read |
| GET /v1/history?account_id=… | 该账号事件链；支持 category、severity、q、since、until、before | read |
| GET /v1/orders?account_id=… | 本系统提交的订单与处理结果 | read |
3. 从交易检查到结算
- 读取 /v1/accounts/{account_id}/market 获取当前合约及收益率。
- POST /v1/accounts/{account_id}/order-check，携带 symbolName、direction、timeIncrements、orderAmount、walletType。此接口只检查，返回 ready、checks、preview 和 expires_at。
- 确实要下单时，使用检查结果中的参数调用订单提交接口，并使用稳定的 Idempotency-Key；完整请求字段见交互式文档。网络超时后先按原订单号查询，重试仍用原键。
- ACCEPTED 表示平台受理，未代表结算。UNKNOWN 表示结果待核对；此时不能以新键重复下单。通过订单查询、事件链和 /v1/ledger 追踪到 SETTLED。
平台 UID 未核验、重复绑定或与历史绑定不符时，不提交新订单。过期报价、平台限额和验证要求也会阻止提交，失败原因在 checks 或订单 result 中。
4. 错误与数据时间
错误响应包含 error、message、request_id。排查时用 request_id 在事件链检索。401 表示未认证，403 表示权限不足，409 通常为身份、状态或重复请求冲突。HTTP 200 仍需结合业务 state、verified、ready 和 stale 判断；排队成功不表示操作完成。
余额未知与余额为零不同；无快照表示尚未成功读取。历史同步失败时保留旧记录，不能把旧记录当作实时状态。策略应先核对 UID、数据时间与同步状态，再决定是否提交。