binance-api/docs/pacifica/TESTS.md

Pacifica 集成测试说明（可直接运行）

一、准备工作

• 环境变量（.env）：
  • PACIFICA_BASE_URL=https://api.pacifica.fi
  • PACIFICA_WS_URL=wss://ws.pacifica.fi
  • PACIFICA_ACCOUNT（主账户公钥，Base58）
  • PACIFICA_PRIVATE_KEY 或 PACIFICA_ACCOUNT_PRIVATE_KEY（主账户私钥，Base58 或 32/64 字节 JSON 数组）
  • 可选代理钱包：PACIFICA_AGENT_WALLET、PACIFICA_AGENT_PRIVATE_KEY
• 推荐开启 debug：PACIFICA_DEBUG=1（会打印签名数据与打码后的最终请求体）

二、测试脚本

• 入口：examples/pacifica_test.ts

• 运行：

  PACIFICA_ENABLE_TEST_ORDER=1 yarn test:pacifica
  # 启用 TP/SL 单例测试
  PACIFICA_ENABLE_TEST_ORDER=1 PACIFICA_ENABLE_TEST_STOP=1 yarn test:pacifica
  # WebSocket 简易订阅（深度/订单/余额/成交），默认 15s 后退出
  yarn test:pacifica:ws
  

三、覆盖范围（已打通）

• 市价下单（BUY/SELL，IOC）
• 限价下单（GTC）与撤单（cancelOrder）
• 全撤（cancelAll）
• 仓位 TP/SL（使用 /api/v1/positions/tpsl，set_position_tpsl 签名）
  • 支持单独设置 TP 或 SL（推荐先验证单例，可规避部分后端校验路径）
• 批量接口（/api/v1/orders/batch）：
  • 混合用例（Create 两笔 + Cancel 其中一笔），逐动作单独签名
  • 注意 Create 的签名字段需包含 reduce_only

四、重要细节

• 符号规范化：下单/TP/SL/订单簿等都使用基础符号（如 BTC），测试脚本已统一处理
• 签名仅覆盖业务字段；account/agent_wallet 不参与签名
• client_order_id 使用 UUID；slippage_percent 默认 0.5
• 知悉问题：openOrders() 在当前环境返回 403（CDN/白名单/权限），不影响其他路径

• WebSocket（无需 login）：

  • 连接 wss://ws.pacifica.fi/ws，然后直接发送订阅消息：

    {"method":"subscribe","params":{"source":"prices"}}
    {"method":"subscribe","params":{"source":"book","symbol":"BTC","agg_level":1}}
    {"method":"subscribe","params":{"source":"account_info","account":"<BASE58>"}}
    {"method":"subscribe","params":{"source":"account_balance","account":"<BASE58>"}}
    {"method":"subscribe","params":{"source":"account_positions","account":"<BASE58>"}}
    {"method":"subscribe","params":{"source":"account_orders","account":"<BASE58>"}}
    

• 心跳：每 60s 内需有消息；建议每 30s 发送 {"method":"ping"}，服务端会返回 {"channel":"pong"}

• channel 值与订阅源一致：prices、book、trades、account_info、account_balance、account_positions、account_orders

五、常见错误与处理

• Verification failed：
  • 检查签名字段是否与文档一致（大小写、嵌套结构）；
  • 检查 PACIFICA_ACCOUNT 与私钥派生公钥是否一致；
• 500 Internal server error（TP/SL）：
  • 先用 TP 或 SL 单例测试；保留 PACIFICA_DEBUG=1 日志提交官方定位

六、参考文档

• 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
• Create stop order：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/create-stop-order
• Create position TP/SL：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/create-position-tp-sl
• Batch order：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/batch-order
• 签名实现：https://docs.pacifica.fi/api-documentation/api/signing/implementation
• WS 订阅：
  • Prices：https://docs.pacifica.fi/api-documentation/api/websocket/subscriptions/prices
  • Orderbook：https://docs.pacifica.fi/api-documentation/api/websocket/subscriptions/orderbook
  • Account info：https://docs.pacifica.fi/api-documentation/api/websocket/subscriptions/account-info
  • Account balance：https://docs.pacifica.fi/api-documentation/api/websocket/subscriptions/account-balance
  • Account positions：https://docs.pacifica.fi/api-documentation/api/websocket/subscriptions/account-positions