Web3 交易系统
开发与源码

接口使用与前后端联调指南

当前基线:模拟 v0.3 保留,独立链模式升级为 v0.5。新增完整历史查询、任务版本保护、已确认事件索引、只读对账和基础告警,见 设计、执行报告。历史报告与证据保留原版本。

历史 v0.4 变更记录(当前增量见页首 v0.5):独立契约api/web3-openapi.json(链服务GET /api/web3/openapi.json);config/state/tasks/单笔hash/orders/sync。金额订单字段为整数文本,数量投影在1e10上限内用JSON整数。POST需X-Dataset-ID与准确浏览器Origin,签名为授权;200/201只本地受理,202 sync等待周期扫描,503保留原签单。生成TS与真实响应测试新增检查。 当前链实现见v0.5架构,操作见开发、测试、部署,证据见本轮报告。

更新:2026-10-11。适用当前 API 0.3.0、单市场 ETH-USDT 模拟账户。字段契约以 OpenAPI ↗ 为准,运行时 GET /api/v1/openapi.json 返回二进制内嵌同版契约。Go 路由/DTO/fetch 手写,TS 类型生成;类型不代替运行时校验。

1. 认证与请求边界#

公开接口为市场、盘口、成交历史、snapshot、stream,以及 live/ready;账户和管理接口要求 Cookie 会话。注册固定 USER;ADMIN 通过启动配置或停机 init-admin 创建,没有默认密码、公开提权或密码重置接口。

注册/登录返回 user/csrf_token/dataset_id,设置 HttpOnly、SameSite=Strict 的 exchange_session Cookie。会话为 24h 绝对期限,不访问续期。密码为 12–72 UTF-8 字节。网页登录 CSRF 只存内存;写请求必须带 X-CSRF-Token。浏览器 Origin 要与服务配置一致;脚本可以无 Origin,但仍须 Cookie/CSRF。代理部署不默认信任 X-Forwarded-For。

当前前端附带 X-Dataset-ID,API 响应也带这个头;业务写请求头与当前数据集不同时返回 409 DATASET_CHANGED。该头用于识别数据集,不是认证凭证;旧脚本省略它仍兼容。GET 请求由前端检查响应数据集,服务端游标也绑定数据集。

2. 一次真实联调#

先按 README ↗ 启动本地服务。以下 Python 示例只向本地服务注册一个新的测试用户,实际增加模拟初始资金并创建/撤销真实订单;它是联调演示,不是生产待确认请求存储器。请用于独立测试数据目录。凭证仅在进程内,不打印密码、Cookie 或 CSRF。

import getpass
import http.cookiejar
import json
import urllib.request
import uuid

base = "http://127.0.0.1:8080/api/v1"
client = urllib.request.build_opener(
    urllib.request.HTTPCookieProcessor(http.cookiejar.CookieJar())
)
auth = None

def call(path, method="GET", body=None, key=None):
    headers = {"Content-Type": "application/json"}
    if auth:
        headers["X-CSRF-Token"] = auth["csrf_token"]
        headers["X-Dataset-ID"] = auth["dataset_id"]
    if key:
        headers["Idempotency-Key"] = key
    request = urllib.request.Request(
        base + path, method=method, headers=headers,
        data=None if body is None else json.dumps(body).encode(),
    )
    with client.open(request, timeout=15) as response:
        if auth and response.headers.get("X-Dataset-ID") != auth["dataset_id"]:
            raise RuntimeError("数据集变更,停止确认旧请求")
        return json.load(response)

auth = call("/auth/register", "POST", {
    "email": input("新的测试邮箱: "), "password": getpass.getpass("密码: "),
})
key = str(uuid.uuid4())
body = {"market": "ETH-USDT", "side": "BUY", "type": "LIMIT",
        "time_in_force": "GTC", "price": "0.01", "quantity": "0.0001"}
first = call("/orders", "POST", body, key)
again = call("/orders", "POST", body, key)  # 同原键与原内容确认
assert again["replayed"] and again["result_seq"] == first["result_seq"]
seq = again["processed_seq"]
print(call("/orders?limit=20&min_seq=" + seq))
print(call("/balances?min_seq=" + seq))
# 示例假设这个低价挂单仍处于活动状态;若已成交,撤单返回终态冲突。
order_id = first["order"]["id"]
canceled = call("/orders/" + order_id + "/cancel", "POST", key=str(uuid.uuid4()))
print(call("/balances?min_seq=" + canceled["processed_seq"]))

请求异常不会证明未执行。脚本中断后仍需原身份、原 key/body 才能确认,不要直接重新运行示例来重复原操作。实际页面通过 pending.ts ↗ 先保存再发送;恢复语义见下文。

3. 写操作与确认#

操作 内容与权限 成功响应
POST /orders 当前会话账户;market、side、type、time_in_force、price、quantity 新下单 201,同键确认 200
POST /orders/{id}/cancel 只能撤当前账户单;无请求体 200;终态冲突 409
POST /admin/credits ADMIN;account_id、asset、amount、reason 200;重试仍须同操作者/目标/原键/内容
PATCH /admin/users/{id} ADMIN;明确 disabled 布尔值,不能停用 ADMIN 200;认证事务提交,不进入业务日志
POST /auth/logout 当前会话与 CSRF 200;只注销本会话

下单/撤单/注资要求 Idempotency-Key:8–128 字符,只允许字母数字及 -_.,system. 前缀保留。普通交易按 (account_id,key) 去重,同账户跨下单/撤单共享键域;管理员注资由服务端加入管理员 ID 前缀,目标账户是业务命令账户。相同内容规范化后命中首次结果;同键不同内容返回 409。第一次业务拒绝也会记忆,后来余额增加不会把旧拒绝变为成功。

processed_seq 是本次处理的日志位置,result_seq 是首次业务结论位置;同键确认也新增输入 envelope。金额和序号都是字符串,比较序号用 BigInt;前端金额不经 Number。price 最多 2 位、quantity 最多 4 位,MARKET 必须 IOC,price 表示保护价;服务端拒绝指数/符号/前导零/超精度,不静默舍入。

成功表示输入已 FULL 提交并完成核心处理,投影可能尚未提交;订单创建不表示一定成交。GTC 可挂单,IOC 可部分成交并取消余量。管理员注资仅正向模拟资产增加,不提供提现或真实链上转账。

4. 读水位与分页#

查询 返回与限制
GET /orders、/admin/orders 页对象 items/dataset_id/applied_seq/next_cursor;limit 默认 100,范围 1–100,页面用 20
GET /orders/{id} 当前投影订单;不是下单时的首次结果快照
GET /commands/by-key?key=… 当前账户首次投影结果;found=false 不证明未受理
GET /balances 当前账户余额数组;与订单请求分别查询,不构成跨请求快照
GET /admin/users 页对象;创建 rowid 排序,状态为本页读取时的状态
GET /admin/audit AUTH 后 CREDIT 分组分页;独立上界,不按跨库全局时间排序
GET /markets/ETH-USDT/book?depth=20 snapshot 字段,盘口 depth 范围 1–20
GET /markets/ETH-USDT/trades 成交页对象,rowid 游标覆盖一条命令多笔成交

投影业务查询可带 min_seq,最多等待 2s,未追上返回 503 PROJECTION_LAG。它要求“至少看见该写水位”,不冻结恰好那个历史时刻,也不增加撮合锁。用户列表来自认证库,不受业务 min_seq 控制。

分页原样 URL 编码 next_cursor,为空即结束;不要手工构造或从别的数据集/账户/接口复用。游标是 Base64 JSON 定位信息,没有加密/签名,权限仍由会话和 SQL 限制。订单首屏固定创建序号上界,后续新增不混入,但原订单状态可变化;不能当成全遍历静态快照。

管理员注资不存在任意目标账户按键查询接口;不确定时重发原 POST,由后端权限和幂等规则确认。

5. 未知结果与错误处理#

状态/业务码 含义与动作
400 INVALID_ORDER/INVALID_REQUEST/INVALID_LIMIT/INVALID_CURSOR 当前请求参数拒绝;修正新操作前先核查是否存在旧待确认请求
401 UNAUTHENTICATED 会话过期/停用;恢复身份后继续确认原请求
403 FORBIDDEN/CSRF_REJECTED/ORIGIN_REJECTED 权限或浏览器安全校验;当前拒绝不否定先前丢响应请求的效果
404 ORDER_NOT_FOUND 当前单笔或撤单未找到;需要区分投影尚未追上
409 IDEMPOTENCY_CONFLICT/ORDER_TERMINAL/DATASET_CHANGED 分别为原键内容冲突、订单终态、数据集变更
422 核心业务拒绝 如余额不足/资源预算;结果带两种序号,首次结论已记忆
503 OVERLOADED 当前 Submit 未入队或服务不可用;不能否定更早同键请求
503 PROJECTION_LAG/QUERY_FAILED 查询未追上或故障;保留已确认写结果,稍后重读
504 RESULT_UNKNOWN、断网、解码失败 写入是否执行未知;只能原键原内容确认

接入错误为 {error:{code,message}};已处理业务拒绝同时含 result 字段和 error。前端也把 5xx、401、429、安全校验失败与数据集变更保留为待确认状态,因为它们不能证明先前写未发生。

当前标签页的 sessionStorage 记录按数据集/账户/操作隔离;同步校验后恢复,不保存密码/Cookie/CSRF;存储失败阻止发送,移除失败保留原记录。关闭标签、清存储、换设备没有恢复保证;跨标签页不选主,由服务端幂等保障。数据集变更后停止自动确认旧操作,先核对备份/身份与当前数据。

6. 公共行情与诊断#

WS 地址 /api/v1/stream(HTTPS 用 wss),单市场不需要 market query;消息就是 Snapshot,无 type/market 包装。采样器每 100ms 读取前 20 档与最近 50 笔成交,各连接首次 tick/水位变化发送;写超时 2s 断开。前端初次挂载 REST 拉取一次,重连等待 WS tick,0.5s 至 10s 退避。

同数据集忽略倒退序号,新数据集允许低序号;完整快照可跳过中间序号,不保证浏览器收齐每笔成交。完整历史请用 trades 页接口。最近成交快照同 seq 采用文本 ID 排序,与完整历史 rowid 排序口径不同。

业务端口 /metrics 与 /debug/ 返回 404;诊断独立 loopback 监听且默认关闭,见部署手册与排障手册。

Windows 本地账号登录补充#

显式回环模式下登录 email 字段允许配置账号别名,如 pinkode;仅登录使用 LoginCredentials,注册仍 Credentials 邮箱格式与 12–72 字节密码。响应 user.email 仍为 pinkode@localhost。无本地模式时别名被拒绝。本地初始化支持用户指定八字节密码,权限/会话/CSRF 保持,见Windows 指南。

v0.5 链历史接口#

GET /api/web3/history/orders、/trades、/tasks、/events,参数 limit=1..100、wallet、cursor;返回 dataset_id、seq、items、next_cursor。空游标表示第一页,next_cursor 空表示末页。游标绑定筛选条件,新查询必须重置。GET /api/web3/tasks/{id} 返回状态、原因、时间、版本和两单详情,不包含 raw。GET /check 与 /metrics 只在回环诊断监听,不加入公开业务 OpenAPI。

— 本篇阅读完毕 —
来源:Web3 交易系统 / docs / 03-development/api-guide.md 下载原文
输入关键词,在三个知识库中搜索
支持正文检索 · 直接定位章节Esc 关闭