Coin OpenAPI

快速开始 ​

1. 准备凭证 ​

  1. 获取商户编号（X-Merchant-Id）。
  2. 生成 EC P-256 密钥对；私钥自行保管，公钥提交给平台（正式环境）。
  3. 测试环境可使用测试商户密钥。

2. 为每个请求加签 ​

  1. 对原始 body 字节计算 Digest（GET / DELETE 对空字节）。
  2. 构造 4 行 Canonical Signing String。
  3. 使用 ES256（DER → Base64）签名并写入 Authorization。

详见 签名规则。

鉴权与签名流程 ​

mermaid
flowchart TD
    A[准备原始 Body + Header] --> B[计算 Digest]
    B --> C[构造 Canonical String]
    C --> D[ES256 签名写入 Authorization]
    D --> E[发送请求到 /coin/v1/*]
    E --> F[服务端校验 Digest]
    F --> G{timestamp 在 ±300 秒内?}
    G -- 否 --> X1[拒绝: timestamp expired]
    G -- 是 --> H{nonce 是否重复?}
    H -- 是 --> X2[拒绝: nonce replay]
    H -- 否 --> I[按 keyId 查商户公钥]
    I --> J{ES256 验签通过?}
    J -- 否 --> X3[拒绝: sign invalid]
    J -- 是 --> K[进入业务处理]

3. 选择业务路径 ​

兑换 ​

  1. POST /coin/v1/exchange/quote
  2. POST /coin/v1/exchange/confirm（在 quote_id 过期前携带）
  3. GET /coin/v1/exchange/query

兑换流程 ​

mermaid
sequenceDiagram
    participant M as Merchant
    participant C as Coin OpenAPI

    M->>C: POST /coin/v1/exchange/quote
    C-->>M: 返回 quote_id + rate + expires_in / expires_at

    M->>C: POST /coin/v1/exchange/confirm (携带 quote_id)
    C-->>M: 返回 order_no + status

    loop 轮询或按需查询
      M->>C: GET /coin/v1/exchange/query (trade_sn/order_no)
      C-->>M: 返回最新订单状态
    end

提现 ​

提现前须先添加收款账号，拿到 receive_account_no 后再算费、下单。

  1. POST /coin/v1/receive-account/create（或先 list 获取已有账号）
  2. POST /coin/v1/withdraw/calc（可选，试算手续费）
  3. POST /coin/v1/withdraw/create
  4. GET /coin/v1/withdraw/query

提现流程 ​

mermaid
sequenceDiagram
    participant M as Merchant
    participant C as Coin OpenAPI

    M->>C: POST /coin/v1/receive-account/create
    C-->>M: 返回 receive_account_no

    Note over M,C: 若账号已存在，也可 GET /coin/v1/receive-account/list 获取 receive_account_no

    M->>C: POST /coin/v1/withdraw/calc（携带 receive_account_no）
    C-->>M: 返回两种扣款方式手续费

    M->>C: POST /coin/v1/withdraw/create（携带 trade_sn + receive_account_no）
    C-->>M: 返回 order_no + status

    loop 轮询或按需查询
      M->>C: GET /coin/v1/withdraw/query (trade_sn/order_no)
      C-->>M: 返回最新提现单状态
    end

4. 在测试环境校验签名 ​

使用测试商户调用 POST /coin/v1/test/sign，对照 digest / sign_string / is_verify。详见 签名自检。

警告

超时或不确定结果时，禁止盲目重试写接口，请先查询。详见 测试指南。