Malone/binance-api @ b5acbef21490ffd1335c502385ae278a007831cc

Pacifica 集成指引（Node/TypeScript）

本文件总结了在本项目中成功打通 Pacifica REST 下单/撤单/全撤与订单簿的方式、要点与排错建议。快速回归与更完整的用例请参考 docs/pacifica/TESTS.md。

关键要点（务必遵守）

签名实现必须严格按官方“签名实现”流程：构造 { timestamp, expiry_window, type, data }，递归按键名排序，生成紧凑 JSON，再用 Ed25519 对字节串签名；最终请求体将签名头与“原始业务字段”平铺，而不是包裹在 data 中。
- 参考文档：签名实现 https://docs.pacifica.fi/api-documentation/api/signing/implementation
下单与撤单“签名仅覆盖业务字段”，不能包含 account 或 agent_wallet 等请求体外层字段。
交易对符号：Pacifica 订单簿与下单要求基础符号，如 BTC。若你使用 BTC-USD 或 BTCUSDT，请在发起请求前归一化为 BTC。
client_order_id 需要 UUID（v4）。
市价单必须带 slippage_percent（如 "0.5"），可使用 IOC。
撤单签名字段：symbol + (order_id 或 client_order_id)。
全撤签名字段：all_symbols、exclude_reduce_only、可选 symbol（当 all_symbols=false 时必需）。
批量接口不对整个 batch 体签名，而是对内部每个 Create/Cancel 动作分别签名。

主要 REST 端点（已对齐）

订单簿：GET /api/v1/book?symbol=BTC（成功）
- 文档：https://docs.pacifica.fi/api-documentation/api/rest-api/markets/get-orderbook
市价单：POST /api/v1/orders/create_market（成功）
- 文档：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/create-market-order
限价单：POST /api/v1/orders/create（成功）
- 文档：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/create-limit-order
撤单：POST /api/v1/orders/cancel（成功）
- 文档：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/cancel-order
全撤：POST /api/v1/orders/cancel_all（成功）
- 文档：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/cancel-all-orders
批量：POST /api/v1/orders/batch（已支持每动作单独签名）
- 文档：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/batch-order

环境变量（最小集合）

PACIFICA_ACCOUNT：主账户公钥（Base58）。必须与私钥派生一致。
PACIFICA_ACCOUNT_PRIVATE_KEY：主账户私钥（Base58 或 64/32 字节 JSON 数组）。
可选：PACIFICA_USE_AGENT=1、PACIFICA_AGENT_WALLET、PACIFICA_AGENT_PRIVATE_KEY 用于代理钱包下单（需先绑定）。
调试：PACIFICA_DEBUG=1 打印签名数据与最终请求体（签名值只打印前缀）。

成功请求示例（简化）

订单簿（公开）

curl 'https://api.pacifica.fi/api/v1/book?symbol=BTC'

市价单（IOC）签名覆盖字段：symbol, amount, side, reduce_only, client_order_id, slippage_percent

const res = await ex.placeOrder({
symbol: 'BTC',
side: 'BUY',
type: 'MARKET',
quantity: '0.001',
tif: 'IOC',
})

限价单（GTC）签名覆盖字段：symbol, price, amount, side, tif, reduce_only, client_order_id

const res = await ex.placeOrder({
symbol: 'BTC',
side: 'SELL',
type: 'LIMIT',
quantity: '0.001',
price: '112200',
tif: 'GTC',
})

撤单（优先用 order_id；如无则用 client_order_id）
```
await ex.cancelOrder('BTC', '281317418')
```
全撤（按符号）
```
await ex.cancelAll('BTC')
```

批量（每个动作单独签名后打包）

{
"actions": [
{
  "type": "Create",
  "data": {
    /* 已签名的 create_order 体 */
  }
},
{
  "type": "Cancel",
  "data": {
    /* 已签名的 cancel_order 体 */
  }
}
]
}

常见错误与定位

400 Verification failed
- 检查 PACIFICA_ACCOUNT 与 PACIFICA_ACCOUNT_PRIVATE_KEY 是否一致（用私钥派生的公钥需等于 account）。
- 检查签名数据集是否仅包含“业务字段”，字段名/大小写与文档一致；client_order_id 必须是 UUID。
- symbol 必须是基础符号（如 BTC）。
500 Internal server error（下单）
- 常见因 symbol 不规范或 client_order_id 非 UUID；或价格/精度不合法（限价）。
403 openOrders
- 受保护/受限端点（可能为 CDN/鉴权策略）；不影响下单/撤单功能验证。

当前实现要点（本项目）

PacificaClient：Ed25519 签名、固定端点、可选代理钱包；Header 级签名已对敏感 POST 关闭（仅用 body 签名）。
PacificaAdapter：
- symbols()/depth()：使用公开端点；depth() 支持符号归一化。
- placeOrder()：市价单自动补 slippage_percent='0.5'；所有下单/撤单均归一化 symbol 为基础符号。
- cancelOrder()：签名字段仅 symbol + (order_id|client_order_id)。
- cancelAll()：签名 cancel_all_orders 的数据字段，再与 account 平铺。
- batch()：逐动作单签名，然后统一提交。
- setPositionTpSl()：使用 /api/v1/positions/tpsl，统一规范化符号并按 set_position_tpsl 规则签名。

参考文档

签名实现：https://docs.pacifica.fi/api-documentation/api/signing/implementation
Get orderbook：https://docs.pacifica.fi/api-documentation/api/rest-api/markets/get-orderbook
Create market order：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/create-market-order
Create limit order：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/create-limit-order
Cancel order：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/cancel-order
Cancel all orders：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/cancel-all-orders
Batch order：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/batch-order

INTEGRATION.md 5.9 KB Verlauf Originalformat