시작하기

이 5분 튜토리얼은 CloudBank 첫 거래 흐름을 한 번에 따라갈 수 있는 진입 가이드입니다.

1. 환경 설정
2. nonce 발급
3. 챌린지 메시지 서명
4. 로그인
5. 지갑 확인
6. 마켓 조회
7. 주문 제출

아래 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"
export ADDRESS="0xYourWalletAddress"

# 연결 확인
curl -sS "$API_ORIGIN/health" | jq

예상 응답 형식:

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

2) nonce 발급

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

예상 응답 형식:

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

3) 챌린지 메시지 서명

새 nonce 챌린지를 요청한 뒤, 반환된 message를 지갑 personal_sign으로 서명하세요.

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)
# 지갑에서 CHALLENGE_MESSAGE를 서명한 뒤 값 입력:
export SIGNATURE="0xYourPersonalSignSignature"

nonce 응답 예상 형식:

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

4) 로그인

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)

예상 응답 형식:

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

5) 지갑 확인

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

예상 응답 형식:

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

6) 마켓 조회

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

예상 응답 형식:

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

7) 주문 제출

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": "0xOrderHash",
  "status": "live",
  "price": "0.55000000",
  "makerAmount": "1000000",
  "takerAmount": "550000",
  "createdAt": "2026-03-05T00:00:00Z"
}

다음 단계

• 축약 버전: /ko/guide/quickstart
• 전체 curl 예제: /ko/guide/api-examples
• API 레퍼런스: /tech/architecture/api-reference