快速開始

本指南帶你完成 CloudBank API 的第一條端到端流程：

1. 準備環境
2. 用錢包簽名完成登入
3. 檢查服務健康與錢包資訊
4. 提交一筆訂單簿交易
5. 發起提現

以下 API 路徑都基於 custodial-wallet 後端路徑：/api/v1。

先決條件

• EVM 錢包（MetaMask 或相容錢包）
• 錢包已配置 BSC Testnet RPC
• 視需要準備 testnet BNB 與 testnet USDC
• 本機已安裝 curl 與 jq

1) 設定環境變數

export API_ORIGIN="https://docs-test.cloudbank.to"
export API_BASE="$API_ORIGIN/api/v1"

# 你的 EOA 錢包地址（用於登入）
export ADDRESS="0xYourWalletAddress"

2) 認證流程（nonce -> sign -> JWT）

2.1 請求 nonce challenge

curl -sS -X POST "$API_BASE/auth/nonce" \
  -H "Content-Type: application/json" \
  -d "{\"address\":\"$ADDRESS\"}" | tee /tmp/cloudbank_nonce.json

預期回傳欄位：

• nonce
• message
• expiresAt

2.2 使用錢包簽名 challenge message

在錢包中使用 personal_sign，簽名 /auth/nonce 回傳的 message 原文。

MESSAGE=$(jq -r '.message' /tmp/cloudbank_nonce.json)

# 替換為你的錢包簽名結果 (0x...)
export SIGNATURE="0xYourPersonalSignSignature"

2.3 交換簽名取得 JWT

curl -sS -X POST "$API_BASE/auth/login" \
  -H "Content-Type: application/json" \
  -d "{\"address\":\"$ADDRESS\",\"signature\":\"$SIGNATURE\",\"message\":$(jq -Rs . <<< "$MESSAGE")}" \
  | tee /tmp/cloudbank_login.json

export JWT=$(jq -r '.token' /tmp/cloudbank_login.json)

3) 第一批 API 呼叫：health + wallet info

3.1 健康檢查

後端健康路由為 /health。

curl -sS "$API_ORIGIN/health" | jq

3.2 取得托管錢包資訊

curl -sS "$API_BASE/wallet/info" \
  -H "Authorization: Bearer $JWT" | jq

預期回傳欄位：

• userAddress
• custodialWalletAddress
• createdAt

4) 透過 orderbook 下單交易

4.1 讀取訂單簿深度

export MARKET_ID="0xYourMarketId"
export OUTCOME_TOKEN_ID="12345"

curl -sS "$API_BASE/orderbook/book?marketId=$MARKET_ID&outcomeTokenId=$OUTCOME_TOKEN_ID&depth=20" | jq

4.2 提交已簽名訂單

POST /api/v1/orderbook/orders 需要 EIP-712 簽名訂單 payload。

curl -sS -X POST "$API_BASE/orderbook/orders" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "marketId": "0xYourMarketId",
    "timeInForce": "GTC",
    "domain": {
      "name": "Polymarket CTF Exchange",
      "version": "1",
      "chainId": 97,
      "verifyingContract": "0xExchangeContract"
    },
    "order": {
      "salt": "1700000000000000000",
      "maker": "0xYourWalletAddress",
      "signer": "0xYourWalletAddress",
      "taker": "0x0000000000000000000000000000000000000000",
      "tokenId": "12345",
      "makerAmount": "1000000",
      "takerAmount": "550000",
      "expiration": "1767225600",
      "nonce": "1",
      "feeRateBps": "0",
      "side": "buy",
      "signatureType": "0"
    },
    "signature": "0xYourEip712OrderSignature"
  }' | jq

預期包含欄位：

• orderHash
• status
• price
• makerAmount / takerAmount

5) 提現資金

提現 asset 可用值包含 USDC、BNB。

curl -sS -X POST "$API_BASE/wallet/withdraw" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": "USDC",
    "toAddress": "0xYourDestinationAddress",
    "amount": "10.5"
  }' | jq

預期回傳欄位：

• txHash
• asset
• amount
• fee
• gasMode
• status
• createdAt

下一步

• 完整 curl 範例：/zh-TW/guide/api-examples
• 完整 API 參考：/tech/architecture/api-reference