API Examples

This page provides copy-ready curl examples for core CloudBank backend endpoints.

Base URL

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

POST /api/v1/auth/nonce

Get a nonce challenge for wallet-sign login.

Request

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

Expected response shape

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

POST /api/v1/auth/login

Exchange signature + challenge message for JWT.

Request

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

Expected response shape

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

GET /api/v1/wallet/info

Get the authenticated user wallet profile.

Request

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

Expected response shape

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

POST /api/v1/wallet/sign

Sign and broadcast a whitelisted transaction from custodial wallet.

Request

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

Expected response shape

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

GET /api/v1/orderbook/book

Read orderbook depth.

Request

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

Expected response shape

{
  "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

Submit a signed order.

Request

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

Expected response shape

{
  "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 may be exposed by gateway routing. The backend route is /health.

Request

curl -sS "$API_ORIGIN/health"

Expected response shape

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