GET

Public entropy

Get service catalog

/api/v2/entropy

AUTHENTICATIONNone · publicService ownerentropy-serviceContract sourceOpenAPISTATUSProduction listed

Purpose and usage

What this endpoint does

Return supported physical sample classes, byte limits, source-signature assurance, and the current generation and source-key discovery paths.

When to use it

Start every Entropy Lab integration here to discover the current generation path, source-key path, supported assurance, and byte ceilings instead of hard-coding them.

OUTCOME · Discover

What changes

Read-only projection; it grants no mutation, settlement, traffic, or authority change.

WHY IT MATTERS

Gives people and agents a contract-backed way to discover service catalog.
Provides bounded, nonce-bound physical entropy with a verifiable source envelope while keeping source credentials and private signing material isolated.

ISOLATION + AUTHORITY

Caller authorization, nonce, requested byte count, physical source, source key, signed envelope, consumer conditioning, application randomness model, and downstream cryptographic use remain distinct. A valid source signature proves envelope provenance and integrity, not fitness for every cryptographic protocol or permission to perform a downstream action.

BEFORE YOU CALL

No bearer credential is required; apply bounded filters and canonical public identifiers where the contract provides them.
Use the live OpenAPI schema as the authority for the exact request shape and response model.
Resolve the required assurance and byte count, fetch the current source key, generate a fresh caller nonce, and define the consuming application's conditioning and replay policy.

WHAT TO DO NEXT

Fetch the current source key and request only the minimum sample size with a fresh caller nonce.
Verify the returned envelope and apply the consuming application's conditioning, health, and replay policy before use.

AGENT GUIDANCE

Use service catalog only for the purpose and lifecycle stage described by this operation; do not treat it as authority for an adjacent action.
Use the live OpenAPI schema as the authority for the exact request shape and response model.
Validate source ID, key ID, signature, nonce echo, byte count, encoding, freshness, and replay posture, then apply the consuming application's required conditioning and health policy.
Use response links and canonical identifiers instead of constructing internal service URLs or scraping the website.

Contract reference

Use the deployed OpenAPI for exact parameters, schemas and security requirements. The tables below provide integration guidance.

Open this operation in OpenAPI

Request and response

Make the request

Examples illustrate integration intent; the referenced OpenAPI operation and component schemas define the executable shape.

PARAMETERS

Headers, path, query, and body

NAMELOCATIONPRESENCETYPE / RULES / PURPOSE

RESPONSES

Status and payload examples

200Current physical-source sample contract, limits, assurance, and verification-key discovery path.Read completed · JSON RESPONSE+

{
  "version": "2",
  "generation_endpoint": "/api/v2/entropy/samples",
  "source_key_endpoint": "/api/v2/entropy/source-key",
  "authentication": "bearer",
  "required_scope": "entropy:write",
  "required_assurance": "source_signed",
  "maximum_entropy_bytes": 65536,
  "maximum_noise_bytes": 4096,
  "source_proof": "Ed25519 signature generated by the physical entropy source"
}

INTEGRATION DECISION

CALLER ACTION: Accept the returned representation or receipt, then fetch the current source key and request only the minimum sample size with a fresh caller nonce.
RETRY SAFETY: Repeat only when the integration needs a fresher authoritative projection.
STATE RECONCILIATION: Use returned identifiers and versions as the comparison point for later reads. Refresh the entropy record and compare request nonce, source identity, byte count, digest, signing key, assurance, and retention commitment.

OPERATIONAL NOTES

Security and lifecycle guarantees

Start here. Agents should discover limits and endpoint paths rather than hard-code them, then fetch source_key_endpoint before requesting or verifying a sample.
This catalog does not generate randomness and grants no key-management, beacon, lottery, oracle, trading, or settlement authority. It accepts no headers, query parameters, or request body.
The published limits are request ceilings, not a claim that every application should consume the maximum. Choose the minimum byte count required by the downstream protocol. Responses are no-store.

Reference version and availability details

This route is implemented in canonical gateway source and appears in the production OpenAPI snapshot observed 2026-10-02T23:27:55.510Z. Authentication, tenant, feature, venue, and market policy still apply.

Verify the exact production OpenAPI operation Return to the V2 directory