Coin OpenAPI

Quick Start ​

1. Prepare credentials ​

  1. Obtain a merchant ID (X-Merchant-Id).
  2. Generate an EC P-256 key pair; keep the private key and submit the public key to the platform (production).
  3. In the test environment you may use the test merchant keys.

2. Sign every request ​

  1. Compute Digest over the raw body bytes (empty bytes for GET/DELETE).
  2. Build the 4-line Canonical Signing String.
  3. Sign with ES256 (DER → Base64) and set Authorization.

See Request Signing.

Auth & Signing Flow ​

mermaid
flowchart TD
    A[Prepare raw Body + Header] --> B[Compute Digest]
    B --> C[Build Canonical String]
    C --> D[Write ES256 signature into Authorization]
    D --> E[Send request to /coin/v1/*]
    E --> F[Server verifies Digest]
    F --> G{timestamp within ±300 seconds?}
    G -- No --> X1[Reject: timestamp expired]
    G -- Yes --> H{Is nonce duplicated?}
    H -- Yes --> X2[Reject: nonce replay]
    H -- No --> I[Look up merchant public key by keyId]
    I --> J{ES256 signature valid?}
    J -- No --> X3[Reject: sign invalid]
    J -- Yes --> K[Enter business handling]

3. Pick a business path ​

Exchange ​

  1. POST /coin/v1/exchange/quote
  2. POST /coin/v1/exchange/confirm (with quote_id before expiry)
  3. GET /coin/v1/exchange/query

If notify_url was set, a webhook is also sent; see Exchange Order. Query remains available.

Exchange Flow ​

mermaid
sequenceDiagram
    participant M as Merchant
    participant C as Coin OpenAPI

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

    M->>C: POST /coin/v1/exchange/confirm (with quote_id)
    C-->>M: Return order_no + status

    C->>M: POST notify_url (terminal webhook)

    loop Poll or query on demand
      M->>C: GET /coin/v1/exchange/query (trade_sn/order_no)
      C-->>M: Return latest order status
    end

Withdraw ​

Before withdrawing, create a receive account first, obtain receive_account_no, then calculate fees and place the order.

  1. POST /coin/v1/receive-account/create (or list existing)
  2. POST /coin/v1/withdraw/calc (optional fee preview)
  3. POST /coin/v1/withdraw/create
  4. GET /coin/v1/withdraw/query

If notify_url was set, a webhook is also sent; see Withdraw Order. Query remains available.

Withdraw Flow ​

mermaid
sequenceDiagram
    participant M as Merchant
    participant C as Coin OpenAPI

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

    Note over M,C: If the account already exists, you may also GET /coin/v1/receive-account/list to obtain receive_account_no

    M->>C: POST /coin/v1/withdraw/calc (with receive_account_no)
    C-->>M: Return fees for both charge types

    M->>C: POST /coin/v1/withdraw/create (with trade_sn + receive_account_no)
    C-->>M: Return order_no + status

    C->>M: POST notify_url (terminal webhook)

    loop Poll or query on demand
      M->>C: GET /coin/v1/withdraw/query (trade_sn/order_no)
      C-->>M: Return latest withdraw order status
    end

4. Validate signing in sandbox ​

Call POST /coin/v1/test/sign with the test merchant to compare digest / sign_string / is_verify. See Sign Self-Check.

WARNING

Never blindly retry write endpoints after timeouts. Query first. See Testing Guide.