Raffaly Transparency API

Welcome to the Raffaly API documentation. Our public API provides transparent access to raffle audit data, entry statistics, and odds calculations to ensure trust and verifiability in every draw.

Key Features

• Tamper-proof audit records - Every draw includes cryptographic signatures
• Real-time entry statistics - Track total, paid, and free entries
• Odds calculation - Calculate winning probability for any number of entries
• Webhook notifications - Get notified when draws complete
• Rate limited - 60 requests/minute for public access

Base URL

https://raffaly.com/api/v1

Quickstart

1. Get Audit Record

Retrieve the tamper-proof audit record for a raffle draw:

curl https://raffaly.com/api/v1/raffles/{raffle_uuid}/audit \
  -H "Accept: application/json"

Response:

{
  "raffle_id": "550e8400-e29b-41d4-a716-446655440000",
  "draw_id": "660e8400-e29b-41d4-a716-446655440001",
  "drawn_at_utc": "2025-11-06T20:32:01+00:00",
  "total_entries": 142,
  "rng_seed_hash": "sha256:a1b2c3...",
  "winner_entry_id": "12345",
  "signature_hash": "sha256:d4e5f6...",
  "prize_name": "iPhone 15 Pro"
}

2. Get Entry Statistics

Check how many entries a raffle currently has:

curl https://raffaly.com/api/v1/raffles/{raffle_uuid}/entries/stats \
  -H "Accept: application/json"

3. Calculate Odds

Calculate winning probability for a given number of entries:

curl https://raffaly.com/api/v1/raffles/{raffle_uuid}/odds?entries=5 \
  -H "Accept: application/json"

Headers

Rate Limiting

All public endpoints are rate limited to 60 requests per minute per IP address. Rate limit information is returned in response headers:

• X-RateLimit-Limit - Total requests allowed per minute
• X-RateLimit-Remaining - Remaining requests in current window
• Retry-After - Seconds until rate limit resets (when exceeded)

Error Handling

Errors follow a consistent format:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "request_id": "req_abc123"
  }
}

Common Error Codes

Next Steps