Bắt đầu

Hướng dẫn 5 phút này là điểm vào một-mạch cho luồng giao dịch đầu tiên trên CloudBank:

1. Cấu hình môi trường
2. Lấy nonce
3. Ký challenge message
4. Đăng nhập
5. Kiểm tra ví
6. Xem thị trường
7. Đặt lệnh

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 môi trường

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

# Kiểm tra nhanh kết nối
curl -sS "$API_ORIGIN/health" | jq

Định dạng phản hồi mong đợi:

{
  "status": "healthy",
  "version": "v1.0.0",
  "uptimeSeconds": 12345
}

2) Lấy nonce

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

Định dạng phản hồi mong đợi:

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

3) Ký challenge message

Yêu cầu một challenge mới, sau đó ký message bằng personal_sign trong ví.

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

export CHALLENGE_MESSAGE=$(jq -r '.message' /tmp/cloudbank_signing_nonce.json)
# Ký CHALLENGE_MESSAGE trong ví rồi điền chữ ký:
export SIGNATURE="0xYourPersonalSignSignature"

Định dạng phản hồi nonce mong đợi:

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

4) Đăng nhập

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

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

Định dạng phản hồi mong đợi:

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

5) Kiểm tra ví

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

Định dạng phản hồi mong đợi:

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

6) Xem thị trường

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

Định dạng phản hồi mong đợi:

{
  "marketId": "0xYourMarketId",
  "outcomeTokenId": "12345",
  "bids": [],
  "asks": [],
  "updatedAt": "2026-03-05T00:00:00Z"
}

7) Đặt lệnh

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

Định dạng phản hồi mong đợi:

{
  "orderHash": "0xOrderHash",
  "status": "live",
  "price": "0.55000000",
  "makerAmount": "1000000",
  "takerAmount": "550000",
  "createdAt": "2026-03-05T00:00:00Z"
}

Tiếp theo

• Bản rút gọn: /vi/guide/quickstart
• Ví dụ curl đầy đủ: /vi/guide/api-examples
• API reference: /tech/architecture/api-reference