Verifiable dice roll from a seed, with a re-derivable transcript

$0.005 USDC per call · Business, finance and compliance · POST /api/v1/dice-roll · Id dice-roll

Rolls dice notation (for example 4d6kh3+2) from a caller seed with a documented SHA-256 counter-mode stream and returns every die, the kept/dropped marks and a full draw transcript, for agents and referees that need a roll anyone can re-derive. Optionally checks a claimed total or claimed faces against the re-derived roll. Does NOT provide unpredictable randomness: the seed is public input, so anyone who knows it knows the outcome; do not use it for gambling or security. Exploding dice, rerolls, success counting, d% and fudge dice return unsupported.

What you get

Disputed rolls end with a hash-checkable transcript instead of an argument.

Call it

Send the JSON body below to https://agents.writerslogic.com/api/v1/dice-roll. An unpaid request answers 402 with the price and how to pay; a request that fails with a 5xx status is not charged.

curl -i -X POST https://agents.writerslogic.com/api/v1/dice-roll \
  -H 'content-type: application/json' \
  -d '{"notation":"4d6kh3+2","seed":"campaign-7/session-3/roll-12"}'

Input

Field	Type	Required	Description
`notation`	string; length 1..200	yes	Dice notation: terms of NdM (N 1-100, M 2-1000) or integers joined by + and -; optional kh/kl/dh/dl with a count on a group. At most 20 groups and 1000 dice.
`seed`	string; length 1..200	yes	Caller seed string. Public: the outcome is a pure function of notation and seed.
`expectTotal`	integer; -100000000..100000000	no	Optional claimed total to verify.
`expectRolls`	array<integer; 1..1000>; max 1000 items	no	Optional claimed faces in notation order, before keep/drop marks.
`includeTranscript`	boolean	no	Default true. False drops blocks and draws (the transcript digest stays).

Example request body

{
  "notation": "4d6kh3+2",
  "seed": "campaign-7/session-3/roll-12"
}

Result

The response is { "data": ..., "_provenance": ... }. data carries these fields; _provenance is a signed W3C Verifiable Credential with a C2PA-style manifest, checked free at POST /api/v1/verify-provenance.

Field	Type	Required	Description
`status`	string; one of "pass", "fail", "unknown", "unsupported"	no	pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass.
`notation`	string; length 0..200	no	Canonical notation (or the input when unsupported).
`total`	integer	no
`rolls`	array<integer>; max 1000 items	no	Every die face, in notation order.
`groups`	array<object>	no
`constants`	integer	no	Sum of the integer terms.
`rejectedWords`	integer	no	Words discarded by rejection sampling.
`transcriptSha256`	string	no	SHA-256 of the JCS-canonical draws array.
`blocks`	array<object>	no
`draws`	array<object>	no
`algorithm`	string	no	The exact stream and sampling algorithm.
`witnesses`	array<object>	no
`versions`	object	no	Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile).
`limits`	array<string>	no
`deterministic`	boolean	no	Always true: pure code, no model.

Pay and connect

Available through: x402 (USDC on Base), MCP. MCP clients reach it through the creative-games-kit package.

Machine-readable

This agent as JSON (schemas, example, OpenAPI operation)
Free signed sample response
OpenAPI 3.1 · Catalog · Index of every agent