Developers

A small API for results nobody can question

Commit your entries, draw at the announced moment, and hand your users a proof. JSON over HTTPS at https://apis.veritrus.com/v1: versioned, idempotent, and results within a few seconds of the draw time.

See a real one: this proof, checked in the browser, or its full JSON from the API. The exact format, for building your own checker: Proof format v1 (draft).

Test phase. Access is by invitation while Veritrus is in test. Proofs are signed with a test key and the log may be reset at launch.

The flow

Commit

When the draw is triggered, send the entries (row numbers and anonymous holder IDs, never names) and a countdown. You get back the run time, the beacon round, and a signed commit.

Run

Count down to beacon.roundAt, then call run. Too early gets 409 too_early with Retry-After; if the beacon is late, 503, and you wait.

Verify & show

Check the proof with the open verifier against keys you trust, before announcing. Store the whole response; link your users to it.

Endpoints

Method	Path	What
GET	/v1/health	Up, and the database answers
GET	/v1/keys	Current and retired public signing keys
POST	/v1/executions	Commit: lock the entries; get the run time and beacon round (needs an API key and Idempotency-Key)
POST	/v1/executions/{id}/run	Draw, at or after the beacon round (needs an API key)
POST	/v1/executions/{id}/cancel	Cancel, only before the run time (needs an API key)
GET	/v1/executions/{id}	The full public record, for verification
GET	/v1/log	The public, append-only log

Commit a draw

curl https://apis.veritrus.com/v1/executions \
  -H "Authorization: Bearer $VERITRUS_API_KEY" \
  -H "Idempotency-Key: 9b1c0d2e-…:1" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "draw.one",
    "groupRef": "3f2b6a1e-…",
    "clientRef": "9b1c0d2e-…",
    "runInSeconds": 10,
    "entries": [
      { "row": 1, "holder": "f6cha45crapxuq5ug7j5vsy3gq" },
      { "row": 4, "holder": "nq2l5dxw3m7r4ztbmh6ok2pfya" }
    ]
  }'

Verify before you announce

import { verifyExecution } from '@veritrus/core/verify';

const x = await (await fetch(`https://apis.veritrus.com/v1/executions/${id}`)).json();
const report = verifyExecution({
  commit: x.commit, outcome: x.outcome, log: x.log,
  publicKeys: PINNED_KEYS,   // keys you trust, e.g. saved from /v1/keys
});
if (!report.ok) throw new Error('Do not announce: the proof does not check out');
console.log(report.result.winner);   // { row, holder }

Rules that keep it honest

Retries are safe

Every commit carries an Idempotency-Key: a retry returns the same execution, never a second draw. Running a drawn execution again returns the same result.

No redraws

Cancel only before the run time; it's signed and logged. After that, the only way forward is to run, so nobody can draw again until they like the result.

No personal data

Entries are row numbers and anonymous holder IDs. Unknown fields are rejected, so names can't slip in by accident.

Pin our keys

Verify against public keys you saved, not only the live key list, and alarm if they ever differ. Keys rotate with overlap; old proofs keep verifying.