BitRaffleDocs

Get started

Quickstart

From a new key to your live competitions on your own page, in four steps.

  1. Get a secret key

    Request access. Your key looks like sk_ followed by 48 characters, and it is shown to you once. If you lose it, ask for a new one.

  2. Keep it on your server

    Put it in an environment variable or your secrets manager. Never ship it to a browser or a mobile app: anyone holding it can act as your organisation.

    Terminal
    export BITRAFFLE_SECRET_KEY="sk_…"

  3. List your live competitions

    curl https://www.bitraffle.io/api/v1/competitions \
  -H "Authorization: Bearer $BITRAFFLE_SECRET_KEY"
    const res = await fetch("https://www.bitraffle.io/api/v1/competitions", {
  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/competitions",
    headers={"Authorization": f"Bearer {os.environ['BITRAFFLE_SECRET_KEY']}"},
)
data = res.json()["data"]
    Response
    {
  "data": [
    {
      "id": 71,
      "title": "Win a Tudor Black Bay 58",
      "ticketPriceUSDCents": 200,
      "paymentToken": "USDC",
      "maxTickets": 3000,
      "ticketsSold": 412,
      "status": "active",
      "state": "open",
      "endDate": "2026-10-24T01:49:13.000Z",
      "imageUrl": "/uploads/1790921518423-Scf1NxFD.avif",
      "payment": {
        "acceptedTokens": [
          "USDC",
          "USDT"
        ],
        "fiat": false
      }
    }
  ]
}

    Money is always an integer in the smallest unit: ticketPriceUSDCents: 200 is $2.00. state tells you whether a competition is selling right now: only open competitions accept entries.

  4. Show them on your page

    The quickest way to show them is the widget. Buyers check out in a secure popup, and your page never navigates away.

    HTML
    <script src="https://www.bitraffle.io/widget.js" data-org="your-org"></script>

Next steps