API 範例

本頁提供 CloudBank 核心後端接口的可直接複製執行 curl 範例。

基礎 URL

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

POST /api/v1/auth/nonce

取得錢包簽名登入所需的 nonce challenge。

請求

curl -sS -X POST "$API_BASE/auth/nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xYourWalletAddress"
  }'

預期回應格式

{
  "nonce": "c7f7a4e0...",
  "message": "CloudBank Authentication\n\nAddress: 0x...\nNonce: ...",
  "expiresAt": "2026-03-05T00:00:00Z"
}

POST /api/v1/auth/login

提交簽名與 challenge message，交換 JWT。

請求

curl -sS -X POST "$API_BASE/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xYourWalletAddress",
    "signature": "0xYourPersonalSignSignature",
    "message": "CloudBank Authentication\\n\\nAddress: 0x...\\nNonce: ..."
  }'

預期回應格式

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "custodialWalletAddress": "0xYourCustodialWallet",
  "expiresAt": "2026-03-06T00:00:00Z"
}

GET /api/v1/wallet/info

取得已認證用戶的錢包檔案資訊。

請求

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

預期回應格式

{
  "userAddress": "0xYourWalletAddress",
  "custodialWalletAddress": "0xYourCustodialWallet",
  "createdAt": "2026-03-05T00:00:00Z"
}

POST /api/v1/wallet/sign

透過托管錢包對白名單合約交易進行代簽並廣播。

請求

curl -sS -X POST "$API_BASE/wallet/sign" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "0xContractAddress",
    "data": "0xabcdef12...",
    "value": "0",
    "product": "predict"
  }'

預期回應格式

{
  "txHash": "0xSignedTxHash",
  "gasMode": "user",
  "status": "pending",
  "createdAt": "2026-03-05T00:00:00Z"
}

GET /api/v1/orderbook/book

讀取訂單簿深度。

請求

curl -sS "$API_BASE/orderbook/book?marketId=0xYourMarketId&outcomeTokenId=12345&depth=20"

預期回應格式

{
  "marketId": "0xYourMarketId",
  "outcomeTokenId": "12345",
  "bids": [
    {
      "price": "0.55000000",
      "makerAmount": "100",
      "takerAmount": "55",
      "orderCount": 1
    }
  ],
  "asks": [],
  "updatedAt": "2026-03-05T00:00:00Z"
}

POST /api/v1/orderbook/orders

提交已簽名訂單。

請求

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"
  }'

預期回應格式

{
  "orderHash": "0xOrderHash",
  "marketId": "0xYourMarketId",
  "outcomeTokenId": "12345",
  "maker": "0xYourWalletAddress",
  "signer": "0xYourWalletAddress",
  "side": "buy",
  "timeInForce": "GTC",
  "price": "0.55000000",
  "makerAmount": "1000000",
  "takerAmount": "550000",
  "expiration": "1767225600",
  "nonce": "1",
  "status": "live",
  "createdAt": "2026-03-05T00:00:00Z",
  "updatedAt": "2026-03-05T00:00:00Z"
}

GET /api/v1/health

/api/v1/health 可能透過 gateway 暴露；後端原生路由為 /health。

請求

curl -sS "$API_ORIGIN/health"

預期回應格式

{
  "status": "healthy",
  "version": "v1.0.0",
  "uptimeSeconds": 12345,
  "database": { "ok": true, "latencyMs": 2 },
  "redis": { "ok": true, "latencyMs": 1 },
  "bsc": { "ok": true, "latencyMs": 45 }
}