Skip to content

API.md

Latest commit

 

History

History
235 lines (177 loc) · 3.91 KB

API.md

File metadata and controls

235 lines (177 loc) · 3.91 KB
Raw

REST API 文档

Base URL: http://127.0.0.1:8000

OpenAPI 交互文档: http://127.0.0.1:8000/docs

健康检查

GET /health

响应示例：

{
  "status": "ok",
  "service": "crypto-paper-wallet",
  "market_data": {
    "enabled": true,
    "url": "http://localhost:8765",
    "reachable": true
  }
}

环境变量

变量 默认 说明
PAPER_WALLET_DB data/paper_wallet.db SQLite 路径
MARKET_DATA_URL http://localhost:8765 行情服务地址
MARKET_DATA_ENABLED true 设为 false 则仅使用本地 ingest

行情（ingest / 查询 / 缓存管理）

单条 tick 注入

POST /v1/market/tick

{
  "symbol": "BTCUSDT",
  "mark_price": 67500.0,
  "index_price": 67480.0,
  "best_bid": 67490.0,
  "best_ask": 67510.0,
  "funding_rate": 0.0001,
  "bid_depth": [{"price": 67490, "qty": 1.5}],
  "ask_depth": [{"price": 67510, "qty": 2.0}],
  "volume_1m": 1500000,
  "timestamp": "2026-06-10T08:00:00Z",
  "is_stale": false,
  "is_mark_stale": false,
  "is_book_stale": false,
  "age_ms": 500
}

批量 tick 注入

POST /v1/market/ticks

Body: [{...}, {...}]

查询 tick（含 depth）

GET /v1/market/tick/{symbol}

优先返回内存缓存；无缓存时回退 market-data 外部拉取。

响应字段：symbol, mark_price, index_price, last_price, best_bid, best_ask, bid_depth[], ask_depth[], funding_rate, volume_1m, is_stale, is_mark_stale, is_book_stale, age_ms, timestamp

清除 / 刷新缓存

DELETE /v1/market/tick/{symbol}   # 清除单币种内存缓存
DELETE /v1/market/ticks           # 清空全部内存缓存
POST   /v1/market/refresh?symbols=BTCUSDT,ETHUSDT   # 从 market-data 重新拉取

过期拒单规则

订单类型 新鲜度要求
MARKET 要求 is_book_stale=false 且有 bid/ask
LIMIT / STOP_* / TAKE_PROFIT_* 挂单时不检查；is_mark_stale 不阻断市价单

钱包管理

创建钱包

POST /v1/wallets

{
  "initial_balance": 1000.0,
  "default_leverage": 20,
  "margin_mode": "cross",
  "position_mode": "hedge",
  "maker_fee": 0.0002,
  "taker_fee": 0.0005,
  "min_equity_ratio": 0.30,
  "label": "my-backtest"
}

查询 / 列表 / 删除

GET    /v1/wallets/{wallet_id}
GET    /v1/wallets
DELETE /v1/wallets/{wallet_id}

账户查询

GET /v1/wallets/{wallet_id}/account
GET /v1/wallets/{wallet_id}/positions
GET /v1/wallets/{wallet_id}/history?limit=500
GET /v1/wallets/{wallet_id}/orders

回测 tick（每根 K 线调用）

POST /v1/wallets/{wallet_id}/tick

Body 同 market tick。内部执行：

  1. 更新 Mark Price
  2. 资金费结算（UTC 0/8/16 整点）
  3. 限价/条件单撮合
  4. 全仓清算检查

下单

POST /v1/wallets/{wallet_id}/orders

{
  "symbol": "BTCUSDT",
  "side": "LONG",
  "order_type": "MARKET",
  "size": 0.01,
  "leverage": 20,
  "reduce_only": false,
  "post_only": false,
  "client_order_id": "strat-001"
}

限价单

{
  "symbol": "ETHUSDT",
  "side": "SHORT",
  "order_type": "LIMIT",
  "size": 0.5,
  "price": 3500.0
}

止损单

{
  "symbol": "BTCUSDT",
  "side": "SHORT",
  "order_type": "STOP_MARKET",
  "size": 0.01,
  "stop_price": 65000.0,
  "reduce_only": true
}

撤单

DELETE /v1/wallets/{wallet_id}/orders/{order_id}

快捷平仓

POST /v1/wallets/{wallet_id}/positions/BTCUSDT/close

{
  "side": "SHORT",
  "size": null,
  "order_type": "MARKET"
}

平多仓：side=SHORT（卖出）
平空仓：side=LONG（买入）

错误码

状态码 含义
400 参数错误 / 行情过期 / 保证金不足
404 钱包、订单或 tick 缓存不存在
502 POST /v1/market/refresh 拉取 market-data 失败