API documentation

POST /api/anchor #

Anchor one SHA-256 hash to five independent OpenTimestamps calendars. The calendars batch many hashes into a single Bitcoin transaction (~hourly), so each receipt's marginal on-chain cost is effectively zero and you are not paying network fees.

Auth

Optional X-Orpho-Api-Key or X-Pack-Token. Anonymous calls fall back to the free-tier limit of 3 anchors per 24 hours.

Request

POST /api/anchor HTTP/1.1
Host: orphograph.com
Content-Type: application/json
X-Orpho-Api-Key: orpho_xxxxxxxxxxxxxxxxxxxxxxxx

{
  "hash_hex":     "abc123…64-char lowercase hex SHA-256",
  "sha512_hex":   "def456…128-char lowercase hex SHA-512 (optional, recommended)",
  "client_label": "filename or short note (optional, max 200 chars)",
  "notify_email": "[email protected] (Pack only — emails the receipt)"
}

Body limit: 4 KB. hash_hex is the only required field. sha512_hex is a quantum hedge — Grover's algorithm halves preimage resistance, leaving SHA-256 at ~2¹²⁸ and SHA-512 at ~2²⁵⁶. Recording both makes the file→receipt binding harder to forge with a future quantum computer. client_label is opt-in; leave it out if you want the receipt to contain only the hash.

Response (200 OK)

{
  "receipt_id":      "XwTULwlh76PcCst9",
  "created_at":      "2026-05-14T14:00:00+00:00",
  "hash_hex":        "abc123…",
  "sha512_hex":      "def456…",
  "client_label":    "photo.jpg",
  "calendars_ok":    5,
  "calendars_total": 5,
  "low_redundancy":  false,
  "pack_consumed":   false,
  "pack_remaining":  0,
  "subscription_active": true,
  "successes": [
    {"calendar": "https://a.pool.opentimestamps.org",      "ots_path": "receipts/XwTULwlh76PcCst9/a.ots"},
    {"calendar": "https://b.pool.opentimestamps.org",      "ots_path": "receipts/XwTULwlh76PcCst9/b.ots"},
    {"calendar": "https://alice.btc.calendar.opentimestamps.org", "ots_path": "receipts/XwTULwlh76PcCst9/alice.ots"},
    {"calendar": "https://finney.calendar.eternitywall.com",      "ots_path": "receipts/XwTULwlh76PcCst9/finney.ots"},
    {"calendar": "https://btc.calendar.catallaxy.com",     "ots_path": "receipts/XwTULwlh76PcCst9/btc.ots"}
  ],
  "failures": []
}

low_redundancy is true when fewer than 3 calendars accepted the submission — usually transient. Retry in a minute; the failed calendars will likely succeed.

Errors

• 400 — hash is not 64 lowercase hex chars, or body is malformed JSON.
• 429 — free-tier limit exhausted. Includes Retry-After header.

curl

HASH=$(sha256sum photo.jpg | awk '{print $1}')
HASH512=$(sha512sum photo.jpg | awk '{print $1}')

curl -sS -X POST https://orphograph.com/api/anchor \
  -H "Content-Type: application/json" \
  -H "X-Orpho-Api-Key: $ORPHO_API_KEY" \
  -d "{\"hash_hex\":\"$HASH\",\"sha512_hex\":\"$HASH512\",\"client_label\":\"photo.jpg\"}"

Python (stdlib)

import hashlib, json, os, urllib.request

def anchor(path):
    s256, s512 = hashlib.sha256(), hashlib.sha512()
    with open(path, "rb") as f:
        for chunk in iter(lambda: f.read(65536), b""):
            s256.update(chunk); s512.update(chunk)
    body = json.dumps({"hash_hex": s256.hexdigest(),
                       "sha512_hex": s512.hexdigest(),
                       "client_label": os.path.basename(path)}).encode()
    req = urllib.request.Request("https://orphograph.com/api/anchor",
        data=body, method="POST",
        headers={"Content-Type": "application/json",
                 "X-Orpho-Api-Key": os.environ["ORPHO_API_KEY"]})
    with urllib.request.urlopen(req, timeout=30) as r:
        return json.loads(r.read())

POST /api/anchor/batch #

Anchor up to 50 hashes in a single round trip. Useful for folder watchers replaying a backlog, capture-daemon flushes, or batch migrations. Each item produces its own independent receipt and can succeed or fail independently.

Auth

Same model as /api/anchor. Pack tokens consume one credit per item; the rate limit applies once to the whole batch on the free tier.

Request

POST /api/anchor/batch
Content-Type: application/json
X-Orpho-Api-Key: orpho_xxxxxxxxxxxxxxxxxxxxxxxx

{
  "hashes": [
    {"hash_hex": "abc1…", "sha512_hex": "def1…", "client_label": "img_001.jpg"},
    {"hash_hex": "abc2…", "sha512_hex": "def2…", "client_label": "img_002.jpg"}
  ]
}

Body limit: 64 KB. Maximum 50 items per request.

Response (200 OK)

{
  "ok": true,
  "submitted": 2,
  "succeeded": 2,
  "failed": 0,
  "results": [
    {"index": 0, "ok": true,  "receipt_id": "abc...", "created_at": "...", "calendars_ok": 5, "calendars_total": 5, "low_redundancy": false, "client_label": "img_001.jpg"},
    {"index": 1, "ok": true,  "receipt_id": "def...", "created_at": "...", "calendars_ok": 5, "calendars_total": 5, "low_redundancy": false, "client_label": "img_002.jpg"}
  ]
}

Errors

• 400 — body missing hashes array, or array empty, or more than 50 items.
• 429 — free-tier limit exhausted.

GET /api/receipt/<receipt_id> #

Fetch the canonical receipt JSON for a previously anchored hash. This is the same payload you originally received from /api/anchor, plus any upgrade events the background worker has added since (status transitions to partial → pinned, BTC pin timestamp once the calendar's Merkle root lands in a block).

Auth

None. Receipts are world-readable by ID — the ID itself is the unguessable bearer credential (96 bits of entropy from secrets.token_urlsafe(12)).

Request

GET /api/receipt/XwTULwlh76PcCst9

Response (200 OK)

{
  "receipt_id":    "XwTULwlh76PcCst9",
  "found":         true,
  "created_at":    "2026-05-14T14:00:00+00:00",
  "hash_hex":      "abc123…",
  "sha512_hex":    "def456…",
  "client_label":  "photo.jpg",
  "status":        "pinned",
  "btc_pinned_at": "2026-05-14T15:10:12+00:00",
  "calendars_ok":  5,
  "calendars_total": 5,
  "checks": [
    {"file": "a.ots",      "magic_ok": true, "hash_match": true, "ok": true},
    {"file": "alice.ots",  "magic_ok": true, "hash_match": true, "ok": true},
    {"file": "b.ots",      "magic_ok": true, "hash_match": true, "ok": true},
    {"file": "btc.ots",    "magic_ok": true, "hash_match": true, "ok": true},
    {"file": "finney.ots", "magic_ok": true, "hash_match": true, "ok": true}
  ]
}

Errors

• 400 — receipt ID does not match ^[A-Za-z0-9_-]{1,64}$.
• 404 — no receipt exists with that ID, or it has been pruned (free-tier retention).

curl

curl -sS https://orphograph.com/api/receipt/XwTULwlh76PcCst9

Python (stdlib)

import json, urllib.request
with urllib.request.urlopen(
    "https://orphograph.com/api/receipt/XwTULwlh76PcCst9", timeout=15
) as r:
    receipt = json.loads(r.read())
print(receipt["status"], receipt.get("btc_pinned_at"))

GET /api/verify/<receipt_id> #

Re-verify a receipt server-side: parse each .ots file, confirm its OpenTimestamps magic bytes are intact and the embedded SHA-256 matches the receipt's recorded hash. Returns the same shape as /api/receipt/<id> but recomputes calendars_ok from a live read of every proof file on disk — useful for "is this receipt still healthy?" health checks.

Auth

None.

Request

GET /api/verify/XwTULwlh76PcCst9

Response

Identical shape to /api/receipt/<id>. The checks[] array reflects a fresh re-read of the proof files; if any .ots file is missing or corrupted, the corresponding entry will have ok: false with the failed sub-check.

Errors

• 400 — receipt ID does not match the allowed pattern.
• 404 — receipt not found.

curl

curl -sS https://orphograph.com/api/verify/XwTULwlh76PcCst9 | python3 -m json.tool

GET /api/health #

Public liveness snapshot. Counts only — no email addresses, no claim codes, no IP addresses, no per-customer detail. Cached server-side for ~30 seconds so polling cannot degrade performance. Safe to wire into your own status board.

Auth

None.

Request

GET /api/health

Response (200 OK)

{
  "ok": true,
  "version": "0.1.0",
  "boot_at": "2026-05-14T00:00:00+00:00",
  "uptime_sec": 50400,
  "counts": {
    "receipts_on_disk": 1234
  },
  "ledger_bytes": {
    "anchor_ledger": 245678,
    "upgrade_log":    12345,
    "expiry_log":      6789
  },
  "last": {
    "anchor_at":       "2026-05-14T14:00:00+00:00",
    "upgrade_run_at":  "2026-05-14T13:55:00+00:00",
    "expiry_run_at":   "2026-05-14T12:00:00+00:00"
  },
  "calendars": [
    {"url": "https://a.pool.opentimestamps.org",  "reachable": true},
    {"url": "https://b.pool.opentimestamps.org",  "reachable": true},
    {"url": "https://alice.btc.calendar.opentimestamps.org", "reachable": true},
    {"url": "https://finney.calendar.eternitywall.com",      "reachable": true},
    {"url": "https://btc.calendar.catallaxy.com", "reachable": true}
  ],
  "btc_oracle": {"available": true, "usd_per_btc": 67500.0, "source": "coingecko"},
  "payout":     {"configured": true, "address_pool_size": 100, "xpub_set": true},
  "checked_at": "2026-05-14T14:00:30+00:00"
}

The data here is intentionally non-sensitive: counts and timestamps, not contents. The payout block reports only whether BTC checkout is configured and the size of the unused-address pool — actual balances are not exposed on this endpoint.

curl

curl -sS https://orphograph.com/api/health | python3 -m json.tool

Python (stdlib)

import json, urllib.request
with urllib.request.urlopen("https://orphograph.com/api/health", timeout=10) as r:
    health = json.loads(r.read())
print(f"{health['counts']['receipts_on_disk']} receipts, uptime {health['uptime_sec']}s")

GET /api/btc-order/<order_id>/qr.svg #

Server-rendered SVG QR code encoding a BIP-21 payment URI for a previously created Pack purchase order. The QR contains the public BTC address and amount only — no email, no order ID, no customer-identifying data is encoded into the image, so the QR cannot be used downstream to dox the purchaser.

Auth

None, but the order ID is unguessable. Anyone with the ID can read the public payment fields — exactly what a wallet app needs.

Request

GET /api/btc-order/btc_AbCdEf12345_xyz/qr.svg
Accept: image/svg+xml

Order IDs match ^btc_[A-Za-z0-9_-]{1,32}$. Mismatched IDs return 400; well-formed IDs that don't exist return 404.

Response

200 OK, Content-Type: image/svg+xml; charset=utf-8. The SVG renders a square QR encoding a string of the form:

bitcoin:bc1q…?amount=0.00010473

The companion JSON endpoint GET /api/btc-order/<order_id> (no /qr.svg suffix) returns the order status:

{
  "order_id":    "btc_AbCdEf12345_xyz",
  "status":      "awaiting_payment",
  "address":     "bc1q…",
  "amount_sats": 10473,
  "expires_at":  "2026-05-14T15:00:00+00:00",
  "tx_hash":     null
}

Errors

• 400 — order ID does not match the allowed pattern.
• 404 — order not found (typo or expired).
• 500 — QR encoder rejected the BIP-21 URI (rare; misconfigured address).

Embedding

The SVG is referenced directly from an <img> tag:

<img src="https://orphograph.com/api/btc-order/btc_AbCdEf12345_xyz/qr.svg"
     width="240" height="240" alt="Bitcoin payment QR">

GET /api/stats #

Public marketing-metrics snapshot. Strictly aggregate counts and the names of public OTS infrastructure — never customer emails, filenames, IPs, BTC balances, or any per-customer detail. Cached server-side for ~60 seconds. The response is byte-identical for every viewer, so it is safe to embed and aggressively cache.

Auth

None.

Request

GET /api/stats

Response (200 OK)

{
  "version":    "0.1.0",
  "uptime_sec": 50400,
  "boot_at":    "2026-05-14T00:00:00+00:00",
  "anchors": {
    "total":          12345,
    "last_24h":       142,
    "last_7d":        980,
    "last_anchor_at": "2026-05-14T14:00:00+00:00"
  },
  "calendars": {
    "reachable": 5,
    "total":     5,
    "items": [
      {"name": "a",      "reachable": true},
      {"name": "b",      "reachable": true},
      {"name": "alice",  "reachable": true},
      {"name": "finney", "reachable": true},
      {"name": "btc",    "reachable": true}
    ]
  },
  "btc_oracle": {
    "available":   true,
    "source":      "coingecko",
    "usd_per_btc": 67500.0
  },
  "checked_at": "2026-05-14T14:00:30+00:00"
}

Privacy invariants

The endpoint's contract guarantees these fields are never emitted:

• Customer email addresses
• Filenames or client_label values
• IP addresses (raw or truncated)
• Per-customer counts of any kind
• BTC balances (hot or cold)
• Individual receipt IDs

curl

curl -sS https://orphograph.com/api/stats | python3 -m json.tool

GET /api/badge/<receipt_id>.svg planned v0.2 #

Planned server-rendered "Anchored to Bitcoin · view receipt" SVG badge, suitable for static embeds in README files, photo portfolios, and galleries where you need an image rather than a script tag.

Until v0.2, use the existing JavaScript badge — one line of HTML pastes a live badge that links to the print-friendly receipt page, with no external fetches and no tracking:

<script src="https://orphograph.com/badge.js"
        data-receipt="XwTULwlh76PcCst9"
        async></script>

See the badge demo for the live rendered output and tampering notes.