Khởi động nhanh

Hướng dẫn này giúp bạn chạy luồng API end-to-end đầu tiên của CloudBank:

1. Chuẩn bị môi trường
2. Xác thực bằng chữ ký ví
3. Kiểm tra health và thông tin ví
4. Gửi giao dịch orderbook
5. Rút tiền

Tất cả đường dẫn API bên dưới dùng base path của backend custodial-wallet: /api/v1.

Điều kiện cần

• Ví EVM (MetaMask hoặc tương thích)
• Ví đã cấu hình BSC Testnet RPC
• testnet BNB và testnet USDC khi cần
• Cài sẵn curl và jq

1) Cấu hình biến môi trường

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

# Địa chỉ ví EOA của bạn (dùng để đăng nhập)
export ADDRESS="0xYourWalletAddress"

2) Xác thực (nonce -> sign -> JWT)

2.1 Yêu cầu nonce challenge

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

Trường dữ liệu kỳ vọng:

• nonce
• message
• expiresAt

2.2 Ký challenge message bằng ví

Dùng personal_sign trong ví với đúng message từ /auth/nonce.

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

# Thay bằng chữ ký từ ví của bạn (0x...)
export SIGNATURE="0xYourPersonalSignSignature"

2.3 Đổi chữ ký lấy 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) Lệnh API đầu tiên: health + wallet info

3.1 Health check

Route health của backend là /health.

curl -sS "$API_ORIGIN/health" | jq

3.2 Lấy thông tin ví custodial

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

Trường dữ liệu kỳ vọng:

• userAddress
• custodialWalletAddress
• createdAt

4) Đặt lệnh qua orderbook

4.1 Đọc độ sâu orderbook

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 Gửi lệnh đã ký

POST /api/v1/orderbook/orders yêu cầu payload lệnh có chữ ký EIP-712.

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

Trường dữ liệu chính kỳ vọng:

• orderHash
• status
• price
• makerAmount / takerAmount

5) Rút tiền

asset có thể dùng 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

Trường dữ liệu kỳ vọng:

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

Tiếp theo

• Ví dụ curl đầy đủ: /vi/guide/api-examples
• API reference đầy đủ: /tech/architecture/api-reference