DocsDevelopers

The reference lives on this site.

Base URL https://api.analogseed.dev. Keep as_live_… on a machine you control. Need numbers, colors, chords, or a giveaway without writing code? Openthe studio.

01Quickstart

GET /v1/status and GET /v1/pubkey need no key. Every response that carries entropy sends Cache-Control: no-store. Integer draws use bitmask rejection. bytes on GET /v1/random is an integer from 1 to 65536. format=raw cannot be combined withsign=true.

Batch creative draws. On 429 or 503, keep the last batch or pause. Do not substitute a language PRNG if the work claims physical entropy. Never put an API key in client-side HTML or a published sketch.

1curl -fsS https://api.analogseed.dev/v1/status

3curl -fsS \
-H "Authorization: Bearer $ANALOGSEED_API_KEY" \
-H "Content-Type: application/json" \
-d '{"kind":"integers","min":0,"max":99,"count":3,"sign":true,"nonce":"batch-7"}' \
https://api.analogseed.dev/v1/draw

9curl -fsS \
-H "Authorization: Bearer $ANALOGSEED_API_KEY" \
"https://api.analogseed.dev/v1/random?bytes=32&format=hex"

429Quota headers

Managed keys with a daily byte cap receive these headers on 200 and on 429 quota_exceeded. Unlimited keys omit them. They describe only the caller's quota.

Header	Meaning
X-AS-Quota-Limit	That key's daily byte cap.
X-AS-Quota-Remaining	Bytes remaining in the current UTC day for that key.
X-AS-Quota-Reset	Next UTC midnight, YYYY-MM-DDT00:00:00Z.

503Retry-After

Body status	Typical Retry-After	Meaning
empty	60	Not enough conditioned bytes. Nothing was taken.
sandbox_paused	300	The public reserve is held so keyed callers keep priority.
signing_unavailable	none	sign=true on an instance without an Ed25519 key.

There is never a partial response. Request a key on the access page. The endpoint returns 201 received. The secret is issued out of band.

02Integration patterns

Direct serve-once

The API output is the result: a draw, a shuffle, a weighted choice, a UUID, or raw bytes. Ask forsign: true when someone who was not in the request needs to check it. Bind a nonce you already published. Do not retry a successful call to get a better sample. Do not cache the body. A 503 with status empty means the operation did not happen.

Entropy-in-depth

When a process already has a CSPRNG and must not stall, mix conditioned bytes with fresh operating-system entropy through HKDF-SHA-256. Salt AS-HKDF-v1, infoanalogseed-csprng-reseed, 32-byte output. The IKM is the physical sample concatenated with 32 local bytes. If the API returns 429 or 503, keep the operating-system generator and label it. That fallback is not avalanche.

1import hashlib
2import hmac
3import json
4import os
5import urllib.error
6import urllib.request

8SALT = b"AS-HKDF-v1"
9INFO = b"analogseed-csprng-reseed"


12def hkdf_sha256(ikm: bytes, salt: bytes, info: bytes, length: int = 32) -> bytes:
  if not salt:
      salt = b"\x00" * 32
  prk = hmac.new(salt, ikm, hashlib.sha256).digest()
  okm = b""
  previous = b""
  counter = 1
  while len(okm) < length:
      previous = hmac.new(prk, previous + info + bytes([counter]), hashlib.sha256).digest()
      okm += previous
      counter += 1
  return okm[:length]


26def reseed(physical: bytes) -> bytes:
  local = os.urandom(32)
  return hkdf_sha256(physical + local, SALT, INFO, 32)


31def random_bytes_or_local(base: str, key: str, n: int = 32) -> tuple[bytes, str]:
  """Return (material, source). source is 'mixed' or 'os-csprng'."""
  url = f"{base}/v1/random?bytes={n}&format=hex"
  req = urllib.request.Request(url, headers={"Authorization": f"Bearer {key}"})
  try:
      with urllib.request.urlopen(req, timeout=10) as res:
          body = json.load(res)
      physical = bytes.fromhex(body["bytes"])
      return reseed(physical), "mixed"
  except urllib.error.HTTPError as exc:
      if exc.code not in (429, 503):
          raise
      return os.urandom(32), "os-csprng"

03AS-RECEIPT-V1

A receipt is an Ed25519 signature over one serve-once response. It is an origin attestation. It is not a VRF: the bytes are a physical measurement, not a function of the signing key. Asking twice is two draws.GET /v1/pubkey publishes the 32-byte public key. key_idis the first 16 hex characters of SHA-256 of that key.

The signed message is the ASCII prefix AS-RECEIPT-V1, a newline, and the UTF-8 canonical JSON of payload. Canonical JSON sorts object keys, uses no insignificant whitespace, and escapes non-ASCII as \uXXXX.

Field	Value
bytes_consumed	Pool bytes actually removed for this response
endpoint	/v1/random, /v1/draw, or /v1/sandbox/draw
issued_at	UTC timestamp YYYY-MM-DDTHH:MM:SSZ
key_id	16 hex characters, SHA-256(public key)[:16]
nonce	The caller's nonce, or JSON null
output_sha256	Hex SHA-256 of the raw bytes, or of canonical JSON of data
policy	CP2, CP1, or CP1,CP2 in pool order, without duplicates
receipt_id	Random UUID for this statement, not an input to the entropy
request_sha256	Hex SHA-256 of the canonical JSON of the normalized request, credentials excluded
source	avalanche

version is AS-RECEIPT-V1.
The Ed25519 signature verifies over that message under the published public key.
payload.key_id equals SHA-256(public key)[:16].
output_sha256 matches the served bytes or the canonical JSON of data.
If you pass an expected nonce, payload.nonce equals it exactly.

Check a pasted response on /verify, or download the standalone verifiers below. Changing one bit of the output fails the check.

04analogseed-mcp

The official MCP server speaks stdio. Cursor, Claude Desktop, and other clients draw the same public primitives. With ANALOGSEED_API_KEY set, draws usePOST /v1/draw and raw bytes use GET /v1/random. Without a key, draws use the public sandbox. A 429 or 503 includes Retry-After when the API sent it. The key-request call does not return a secret.

Variable	Default	Role
ANALOGSEED_API_URL	https://api.analogseed.dev	API origin, no trailing path.
ANALOGSEED_API_KEY	unset	Bearer token. Omit it to stay on the sandbox.

Cursor reads .cursor/mcp.json in the project, or the user-level MCP config. Claude Desktop reads claude_desktop_config.json(~/Library/Application Support/Claude/ on macOS,%APPDATA%\Claude\ on Windows). Restart the client after saving.

1{
"mcpServers": {
  "analogseed": {
    "command": "npx",
    "args": ["-y", "analogseed-mcp"],
    "env": {
      "ANALOGSEED_API_URL": "https://api.analogseed.dev",
      "ANALOGSEED_API_KEY": "as_live_..."
    }
  }
}
12}

Sandbox ceilings: raw at most 64 bytes, uuids at most 4, integers, floats, and weighted draws at most 16, shuffle at most 50 items. sign=true asks for an AS-RECEIPT-V1 receipt. That signature is not a VRF.

Tool	What it calls
draw_integers	kind=integers. Bitmask rejection. replacement=false is partial Fisher–Yates.
draw_floats	kind=floats. Uniform in [min, max).
shuffle_items	kind=shuffle.
weighted_choice	kind=weighted. Positive integer weights.
draw_uuids	kind=uuids.
random_bytes	With a key: GET /v1/random. Sandbox: kind=raw. Encoding is hex or base64.
service_status	GET /v1/status. Coarse readiness only.

05OpenAPI 3.1

Every public operation and component schema. A download of the same document is in the next section.

OpenAPI 3.1.0 · Analog Seed 1.3.0. Conditioned avalanche entropy from a physical noise source. Served bytes are one-time. An optional Ed25519 signature is an AS-RECEIPT-V1 entropy receipt, not a verifiable random function.

Draw an unbiased primitive

POST /v1/draw

Turns serve-once avalanche bytes into raw, integers, floats, a shuffle, a weighted choice, or UUID version 4. Integer ranges use bitmask rejection, not modulo. Leftover rejection bytes are discarded. sign=true attaches an Ed25519 AS-RECEIPT-V1 entropy receipt.

Auth: BearerAuth · Entropy

BodyRequired

application/json

kind = raw

Field	Type	Notes
bytes *	integer	1…65536
encoding	"hex" \| "base64"	default "hex"
kind *	const "raw"
nonce	string \| null	length 1…128, default null
sign	boolean	Attach an Ed25519 `AS-RECEIPT-V1` origin receipt. · default false

kind = integers

Field	Type	Notes
count *	integer	1…1024
kind *	const "integers"
max *	integer
min *	integer
nonce	string \| null	length 1…128, default null
replacement	boolean	default true
sign	boolean	Attach an Ed25519 `AS-RECEIPT-V1` origin receipt. · default false
step	integer	1……, default 1

kind = floats

Field	Type	Notes
count *	integer	1…1024
kind *	const "floats"
max	number	default 1
min	number	default 0
nonce	string \| null	length 1…128, default null
sign	boolean	Attach an Ed25519 `AS-RECEIPT-V1` origin receipt. · default false

kind = shuffle

Field	Type	Notes
items *	—[]
kind *	const "shuffle"
nonce	string \| null	length 1…128, default null
pick	integer	1…512
sign	boolean	Attach an Ed25519 `AS-RECEIPT-V1` origin receipt. · default false

kind = weighted

Field	Type	Notes
choices *	object[]
count	integer	1…256, default 1
kind *	const "weighted"
nonce	string \| null	length 1…128, default null
replacement	boolean	default true
sign	boolean	Attach an Ed25519 `AS-RECEIPT-V1` origin receipt. · default false

kind = uuids

Field	Type	Notes
count	integer	1…256, default 1
kind *	const "uuids"
nonce	string \| null	length 1…128, default null
sign	boolean	Attach an Ed25519 `AS-RECEIPT-V1` origin receipt. · default false

OutResponses

Status	Meaning
200	Unbiased primitive derived from serve-once avalanche bytes. Headers: X-AS-Policy, X-AS-Quota-Limit, X-AS-Quota-Remaining, X-AS-Quota-Reset, X-AS-Source.
400	Invalid request body, parameter out of range, or body larger than 64 KiB.
401	Missing, malformed, or invalid Bearer API key.
429	Daily byte quota exceeded (`quota_exceeded`) or per-minute rate limit reached (`rate_limited`).
503	Entropy pool temporarily exhausted (`empty`) or signing key unavailable.

Schemas19 components

Field	Type	Notes
bytes_consumed *	integer	1……
policy *	string	example "CP2"
source *	"avalanche"

06Verifiers

The Python tool prints valid and exits 0, or printsinvalid: … on stderr and exits 1.--pubkey-hex takes 64 hex characters.--expect-nonce is optional. The JavaScript file is the same checks on WebCrypto.

python verify_receipt.py receipt.json --pubkey-file pubkey.json --expect-nonce ticket-1
node verify_receipt.mjs receipt.json --pubkey-file pubkey.json --expect-nonce ticket-1

verify_receipt.py

Python. Needs the cryptography package.

Download

verify_receipt.mjs

Node 20+ and this browser. No npm packages.

Download

openapi.json

OpenAPI 3.1 snapshot of the public API.

Download