Developer docs
Build on BitRaffle
Show live prize competitions on your site, sell entries from your own product, run competitions by API, or use our provably-fair draws for anything you need to pick fairly.
Show competitions on your site
One script tag renders your live competitions, with checkout in a secure popup. No API key needed.
Read the guide → Sell entriesSell entries from your product
Ask the entry question, start a hosted checkout for your buyer, and get a webhook when their tickets are issued.
Read the guide → Run competitionsCreate and manage competitions
Create prizes and competitions, open them, and cancel them from your own tools.
Read the guide → Draw serviceProvably-fair draws
Pick winners from any list, with a proof anyone can check. Pay per draw in USDC.
Read the guide →Start here
- New to the API? The Quickstart gets you from key to first response in five minutes.
- Looking for an endpoint? The API reference lists every one, with request and response examples in cURL, Node.js and Python.
- Generating a client? Import openapi.json into Postman, Insomnia or any OpenAPI generator.
How it fits together
Everything you do through the API belongs to your organisation. Your secret key identifies it on every request, so responses only ever contain your own competitions, buyers and draws. Each key carries scopes that decide what it may do:
| Scope | Lets the key |
|---|---|
competitions:read | Read competitions |
winners:read | Read winners |
entries:create | Sell entries (hosted checkout) |
competitions:write | Create and manage competitions and prizes |
draws:create | Run provably-fair draws (Result-as-a-Service) |
New keys get the two read scopes. The write scopes are granted on purpose when your key is issued, so a key for a read-only integration cannot sell or create anything.
Base URL
https://www.bitraffle.io/api/v1Use the host your key was issued for: your organisation's own subdomain, or the main domain. Examples on these pages use the host you are reading them on, so you can copy them as they are.