Two endpoints. Plain JSON.

Base URL

https://bitseal.orygn.tech

Accepts a precomputed manifest (root hash, leaves, metadata, proof-of-work token) and returns the signed seal plus a PDF certificate. The server re-derives the root from the supplied leaves before signing, so a client cannot pin a signature to a root that does not match its own leaves. Every call requires a valid pow_token obtained from GET /api/challenge below; browser callers also need a Cloudflare Turnstile token.

curl -X POST https://bitseal.orygn.tech/api/seal \
  -H "Content-Type: application/json" \
  -H "X-API-Client: acme-sealer/1.2" \
  -d '{
    "root_hash": "6d56f7...",
    "merkle_tree": ["a1b2c3...", "d4e5f6..."],
    "seal_mode": "merkle-blake3-64k-v2",
    "chunk_size_bytes": 65536,
    "blake3_hash": "...",
    "sha3_512_hash": "...",
    "entropy": 7.91,
    "filename": "contract.pdf",
    "size_bytes": 130000,
    "mime_type": "application/pdf",
    "pow_token": { "challenge_id": "...", "nonce": "..." }
  }'

For the easiest integration use the official Python SDK (github.com/OrygnsCode/BitSeal-SDK), which transparently handles the challenge/solve/submit round-trip and the X-API-Client header.

Returns a fresh proof-of-work challenge bound to the requesting client IP. Solve it locally by computing SHA-256(challenge || str(nonce)) until the digest has at least difficulty leading zero bits, then submit { challenge_id, nonce } as the pow_token field on POST /api/seal. At the default difficulty of 18 a solution takes approximately 250 ms on a modern laptop. Challenges expire after 5 minutes and each is valid for exactly one seal.

curl "https://bitseal.orygn.tech/api/challenge"

Looks up a root on the public ledger. Returns the three-axis verdict: ledger presence, Ed25519 signature validity, and Merkle tree consistency. Each axis is reported on its own field.

If you only check one field, check all_axes_pass. The legacy valid field is always trueon a 200 response: it means "the root was found in the ledger and a verdict was produced," not "the seal passed every cryptographic check." A naive consumer that writes if (res.valid) accept() will treat a tampered or signature-failed seal as good. Use all_axes_pass as the single boolean trust gate, or read the per-axis fields directly to apply your own policy.

curl "https://bitseal.orygn.tech/api/verify?root=6d56f7...&token=<turnstile>"

Transparency log

Every seal occupies a monotonic seal_index position in a Merkle log. The Authority periodically signs a Signed Tree Head (STH) committing the BitSeal ledger to a particular Merkle root over every seal up to that moment. Each STH's signature is submitted to OpenTimestamps and Bitcoin-anchored within 1 to 24 hours, so deletion or omission of any committed seal becomes cryptographically detectable against a public Bitcoin block. The three endpoints below let any holder of a seal walk the math themselves and independently confirm their seal's inclusion. Full spec at spec/log-sth.md.

Returns the most-recently-published Signed Tree Head. The shape mirrors a single element of /api/log/heads below. No Turnstile gating; per-IP rate limited.

curl "https://bitseal.orygn.tech/api/log/heads/latest"

Returns recent Signed Tree Heads, ordered by sth_index descending. Pagination via before_sth_index.

curl "https://bitseal.orygn.tech/api/log/heads?limit=10"

Returns a Merkle inclusion proof showing that a given seal was committed by a Signed Tree Head. The response includes the seal's three log-leaf fields (so a verifier can recompute the leaf hash locally), the target STH, and the proof itself. Anyone can fold the proof against the STH's merkle_root using a generic BLAKE3 library; see web/scripts/inclusion-verify-third-party-demo.mjs in the repo for a 95-line reference implementation with no BitSeal-specific dependencies.

curl "https://bitseal.orygn.tech/api/log/inclusion?seal_index=39"

Programmatic access (SDK, scripts)

Programmatic callers should set a non-empty X-API-Client header on every request. The server uses it as an integration identifier in logs, as an additional rate-limit dimension (see below), and as the signal that lets the caller skip the Cloudflare Turnstile widget gate, which is only useful for browsers that can render the challenge. The proof-of-work requirement still applies, header or not, the SDK handles the challenge round-trip transparently.

The reference Python SDK sends X-API-Client: BitSeal-SDK/<version> python/<ver> on every request. Third-party integrations should set their own identifier, e.g. X-API-Client: acme-sealer/1.2. Allowed format is [A-Za-z0-9_-./+ ], 1 to 128 characters. Malformed values are rejected with a 400.

Rate limits

Limits are enforced over sliding windows. The server returns 429 with a Retry-After header and a retry_after_seconds field in the JSON body. An IP that hits a honeypot path is silently blocklisted for 24 hours and the same 429 shape is returned, so a probing scanner learns nothing about why it was throttled.

Edge protection in front of these app-level limits: Cloudflare Bot Fight Mode + JS Detections + a zone-level rate-limit rule (5 requests per IP per Cloudflare colo per 10 seconds on /api/seal). Legitimate browser and SDK traffic is unaffected.

Need higher throughput for an integration, a research audit, or a production batch? Email [email protected] and describe the use case.

Offline verification

The cryptography here is standard and published. Given the manifest, the public key at /.well-known/bitseal-authority-key.json, and a BLAKE3 plus Ed25519 library, anyone can verify a seal with no network call to BitSeal. The Python SDK does this, and its source is the normative reference.