빠른 시작

이 가이드는 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 경로는 /health입니다.

curl -sS "$API_ORIGIN/health" | jq

3.2 커스터디얼 지갑 정보 조회

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

예상 필드:

• userAddress
• custodialWalletAddress
• createdAt

4) 오더북 거래 제출

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 예제: /ko/guide/api-examples
• 전체 API 레퍼런스: /tech/architecture/api-reference