# ProofDraw

> Provably-fair random selection API. An entry list is sealed with a SHA-256 commitment bound to a *future*
> drand (League of Entropy) round, so the operator cannot know the outcome at commit time. When the round
> publishes, `winner_row = drand_value mod entry_count`. Every draw ships a public receipt anyone can
> re-verify in their own browser, from public sources alone, without a ProofDraw account and without
> trusting ProofDraw's backend.

Generated by API Evangelist from ProofDraw's public surface on 2026-08-11. ProofDraw serves no llms.txt of
its own (https://proofdraw.com/llms.txt returns 404).

## How it works

- Create a draw, add entries (opaque ticket ids — never PII), then seal it. Or do all three in one call
  with `POST /v1/draws/instant`.
- Sealing picks the first drand round at or after `now + round_offset_seconds`, writes a canonical list
  file whose header names the chain and round, SHA-256s it, pushes it to a public GitHub mirror, and
  submits the hash to an OpenTimestamps calendar for Bitcoin anchoring.
- The commit must land at least 10 seconds before the round time (the safety-margin invariant) or the seal
  aborts — that is what makes "we committed before the randomness existed" checkable.
- Sealing is irreversible. A sealed draw cannot be edited or deleted; `DELETE` returns 409 forever.

## API

- [ProofDraw API v1](https://proofdraw.com/api): REST, bearer API-key auth, base `https://proofdraw.com/api/v1`
- [OpenAPI 3.0.3](https://proofdraw.com/openapi.json): 13 paths, 16 operations, 5 tags (System, Auth, Account, Draws, Verification)
- [APIs.json](https://proofdraw.com/apis.json): first-party 0.16 index

### Operations

- `GET /api/health` — liveness. Public.
- `POST /v1/auth/register` — create a free account, receive a `pd_live_` key. Requires `terms_accepted_at`.
- `POST /v1/auth/login` — exchange email + password for a NEW key (prior keys keep working).
- `GET /v1/me` — account, usage, tier limits. **Call this before creating a draw**: the free tier is capped at 5 draws *lifetime* and 100 entries per draw.
- `PATCH /v1/me` — update name, email, or password.
- `PUT /v1/me/profile` — create or replace the business profile ("Run by" attribution on receipts).
- `POST /v1/draws` — create an open draw.
- `POST /v1/draws/{id}/entries` — add up to 5,000 entries per call, atomically.
- `POST /v1/draws/{id}/seal` — freeze, commit, and bind to a future drand round.
- `POST /v1/draws/{id}/resolve` — resolve a sealed draw once its round published. Idempotent.
- `POST /v1/draws/instant` — create + entries + seal (+ optional synchronous resolve) in one call.
- `GET /v1/draws/{id}` — fetch one draw. Field population depends on state.
- `GET /v1/draws` — the 100 most recent draws, newest first. **Silently truncated** past 100; no cursor.
- `DELETE /v1/draws/{id}` — cancel an *open* draw only.
- `GET /list/{hash}` — the raw sealed list bytes. Public, content-addressed, immutable.
- `GET /list/{hash}/ots` — the OpenTimestamps proof for that hash. Public.
- `GET /v/{publicId}` — the human verification receipt page. Public. *(Documented, but absent from the OpenAPI.)*

## Rules an agent must follow

- **Auth**: `Authorization: Bearer pd_live_…` (or `pd_test_…` for sandbox keys). Keys are hashed at rest and shown once; only the prefix is retrievable later. There is no revoke or list endpoint.
- **No idempotency key exists.** `POST /v1/draws/instant` is not replay-safe: a retry after a timeout creates a second public draw and burns a second unit of quota. `resolve` is the only operation documented as idempotent; `seal` is retry-safe only after a `500 seal_failed`.
- **The 60-second wait cap is by design.** `wait: true` blocks for at most 60s. If `round_offset_seconds` exceeds ~45s the call returns `sealed`, not `resolved` — take the result from the webhook or poll `GET /v1/draws/{id}`. Do not retry the create.
- **Never put PII in `ticket_id`.** Ticket ids become part of the permanent public list. Private context goes in `metadata` (max 4KB, opaque to ProofDraw, never sealed).
- **Errors are not RFC 9457.** Every response is `{success, data, message}`; failures add a `code` from a fixed enum: `validation_failed`, `unauthenticated`, `tier_limit_exceeded`, `not_found`, `state_conflict`, `not_yet_available`, `entry_limit_exceeded`, `rate_limited`, `seal_failed`, `internal_error`, `drand_unavailable`.
- **Retry only these**: `not_yet_available` (wait for `drand_round_time`), `drand_unavailable` (transient beacon outage), `seal_failed` (call `/seal` again with a larger offset). Everything else is terminal.
- **Rate limits**: `X-RateLimit-Limit` and `X-RateLimit-Remaining` are documented on every response; no numeric ceiling and no exhaustion status code are published.
- **Webhooks** are the durable completion contract: `draw.sealed`, `draw.resolved`, `draw.cancelled`, signed `X-ProofDraw-Signature: sha256=<hex>` with the per-draw `callback_secret` — returned only on the creating response and never retrievable again.

## Verification (no account needed)

- [In-browser verifier](https://proofdraw.com/verifier.html) — re-hashes the list and re-derives the winning row client-side
- [Verifier source, MIT](https://github.com/proofdraw/verifier)
- [Public sealed-list mirror](https://github.com/proofdraw/draw-lists) — append-only, content-addressed by SHA-256
- [OpenTimestamps guide](https://proofdraw.com/docs/opentimestamps)
- [Live demo](https://proofdraw.com/demo) — simulated drand round, real algorithm, no account

## Repository artifacts (API Evangelist)

- [OpenAPI](openapi/proofdraw-api-openapi.yml)
- [Authentication](authentication/proofdraw-authentication.yml)
- [Conventions](conventions/proofdraw-conventions.yml)
- [Error catalog](errors/proofdraw-problem-types.yml)
- [Webhook catalog](asyncapi/proofdraw-webhooks.yml)
- [Data model](data-model/proofdraw-data-model.yml)
- [Rate limits](rate-limits/proofdraw-rate-limits.yml)
- [Plans and pricing](plans/proofdraw-plans-pricing.yml)
- [Lifecycle](lifecycle/proofdraw-lifecycle.yml)
- [Sandbox](sandbox/proofdraw-sandbox.yml)
- [Conformance](conformance/proofdraw-conformance.yml)
- [Agent skills](skills/_index.yml)

## Company

- [ProofDraw](https://proofdraw.com/) — founded 2026, Michigan, USA
- [Terms](https://proofdraw.com/terms) · [Privacy](https://proofdraw.com/privacy) · [Contact](https://proofdraw.com/contact)
- Security disclosure: security@proofdraw.com (acknowledged within 48 hours)
- Note: robots.txt disallows ClaudeBot, GPTBot, CCBot, Google-Extended and others, and sets
  `Content-Signal: search=yes, ai-train=no, use=reference`.