BitRaffleDocs

Draw service

Funding your balance

Draws are paid from a prepaid balance. Top it up by sending USDC on Arbitrum One, then tell us the transaction.

  1. Find the deposit address

    GET /draws/info returns settlement.depositAddress and the USDC token contract. Always read them from the API rather than copying them from anywhere else.

    curl https://www.bitraffle.io/api/v1/draws/info \
  -H "Authorization: Bearer $BITRAFFLE_SECRET_KEY"
    const res = await fetch("https://www.bitraffle.io/api/v1/draws/info", {
  headers: { Authorization: `Bearer ${process.env.BITRAFFLE_SECRET_KEY}` },
});
const { data } = await res.json();
    import os, requests

res = requests.get(
    "https://www.bitraffle.io/api/v1/draws/info",
    headers={"Authorization": f"Bearer {os.environ['BITRAFFLE_SECRET_KEY']}"},
)
data = res.json()["data"]

  2. Send USDC

    From any wallet you control, send USDC on Arbitrum One to that address. Send only the USDC token named in settlement.tokenAddress: other tokens, and USDC on other networks, cannot be credited.

  3. Report the transaction

    We read the transaction on-chain and credit exactly the USDC it moved to the deposit address. Reporting the same transaction twice credits it once.

    cURL
    curl -X POST https://www.bitraffle.io/api/v1/draws/deposit \
  -H "Authorization: Bearer $BITRAFFLE_SECRET_KEY" \
  -H "BitRaffle-Proof: $PROOF" \
  -H "Content-Type: application/json" \
  -d '{ "txHash": "0x9b1c…e4a2" }'
    Response
    {
  "balanceCents": 2500,
  "creditedCents": 2500,
  "duplicate": false
}

If the transaction is not found yet, you get 404: wait for it to be confirmed and report it again.

When the balance runs out

Revealing a draw your balance cannot cover returns 402 payment_required, with your balance and where to deposit. Nothing is charged, and the commitment stays valid: top up and reveal again.

402 Payment Required
{
  "error": "payment_required",
  "message": "Top up your prepaid balance to run draws.",
  "balanceCents": 0,
  "unitCostCents": 1,
  "deposit": {
    "depositAddress": "0x26A8…1324",
    "tokenAddress": "0xaf88…5831",
    "tokenSymbol": "USDC",
    "tokenDecimals": 6
  }
}

Usage and ledger

GET /draws/usage returns your balance, the price per draw and how many draws this key has revealed. GET /draws/ledger lists your latest deposits and draw charges. Neither needs a signed proof.