API Reference

01 Overview

All requests are made against https://proofledger.io. All responses are JSON, UTF-8 encoded. The API is versioned under /api/v1/; breaking changes will ship under a new version prefix.

The API is intended for integrations where evidence is produced at scale — claims-intake systems, forensic pipelines, inspection apps, CMS watermarking hooks. For occasional single-file work, the web dashboard is usually simpler.

02 Authentication & Access

Proof submission and retrieval require an API key. Keys are issued from the Account page on every plan, including Free — no credit card required to make your first call.

Monthly API proof limits by plan: Free / Standard — 25 (Polygon anchoring; Bitcoin available per-anchor), Professional — 500, Business — 5,000. The web dashboard stays unlimited for Polygon on every plan; the API cap exists to keep the programmatic path abuse-resistant, not to meter proofs.

Upgrade at Pricing or contact support@proofledger.io for enterprise volumes.

1. Sign in to your account.
2. Scroll to the API Keys section.
3. Enter a label (e.g. "Claims Intake") and click Create Key.
4. Copy the key immediately — it is shown once and cannot be retrieved later.

Keys look like sk_ab12cd34_.... Store them as you would any secret: environment variable, secrets manager, or vault. Never commit keys to source control or send them in query strings.

Pass the key as a Bearer token in the Authorization header:

Authorization: Bearer sk_ab12cd34_yourLongSecretHere

Keys can be revoked at any time from the Account page. Revoked keys stop authenticating within a few seconds. If a key is compromised, revoke it immediately and issue a new one — past proofs remain valid regardless.

03 Submit a Proof

# 1. Hash the file locally — never send the file itself.
sha256sum site-inspection.pdf
# a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2

# 2. Submit the hash.
curl -X POST https://proofledger.io/api/v1/proof \
  -H "Authorization: Bearer sk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "sha256": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
    "filename": "site-inspection.pdf",
    "bitcoin_requested": true
  }'

{
  "id": 42,
  "sha256": "a1b2c3d4...f0a1b2",
  "filename": "site-inspection.pdf",
  "status": "approved",
  "created_at": "2026-04-21T14:22:03.000Z",
  "bitcoin_requested": true,
  "btc_payment_status": "PAID",
  "duplicate_of": null,
  "certificate_url": "/cert/42",
  "verification_url": "/verify.html?hash=a1b2c3d4...f0a1b2"
}

The proof is accepted and queued for on-chain anchoring. Poll GET /api/v1/proof/:id or call the public verify endpoint to see the Polygon tx hash (typically under a minute) and Bitcoin txid (daily batched anchor).

04 Retrieve a Proof

curl https://proofledger.io/api/v1/proof/42 \
  -H "Authorization: Bearer sk_YOUR_KEY_HERE"

{
  "id": 42,
  "sha256": "a1b2c3d4...f0a1b2",
  "filename": "site-inspection.pdf",
  "status": "approved",
  "polygon_status": "ANCHORED",
  "bitcoin_status": "PENDING",
  "evidence_readiness": "PENDING_BITCOIN",
  "created_at": "2026-04-21T14:22:03.000Z",
  "chain_tx": "0xabc123...",
  "chain_name": "polygon-mainnet",
  "bitcoin_txid": null,
  "btc_payment_status": "INCLUDED",
  "certificate_url": "/cert/42",
  "explorer_url": "https://polygonscan.com/tx/0xabc123...",
  "bitcoin_explorer_url": null
}

Immediately after submission, polygon_status is PENDING and chain_tx is null. The signer service picks up the job within ~30 seconds and broadcasts the transaction. Bitcoin anchors follow a daily batch cycle, so bitcoin_status may remain PENDING for up to 24 hours.

05 Verify a Proof Public

curl "https://proofledger.io/api/v1/verify?hash=a1b2c3d4...f0a1b2"

{
  "found": true,
  "proof": {
    "id": 42,
    "sha256": "a1b2c3d4...f0a1b2",
    "filename": "site-inspection.pdf",
    "created_at": "2026-04-21T14:22:03.000Z",
    "polygon_status": "ANCHORED",
    "bitcoin_status": "ANCHORED",
    "evidence_readiness": "READY_BITCOIN",
    "chain_tx": "0xabc123...",
    "bitcoin_txid": "def456...",
    "user_email": "a***@example.com"
  },
  "certificate_url": "/cert/42",
  "explorer_url": "https://polygonscan.com/tx/0xabc123...",
  "bitcoin_explorer_url": "https://blockstream.info/tx/def456..."
}

{ "found": false, "sha256": "a1b2c3d4...f0a1b2" }

06 Rate Limits & Quotas

Higher monthly caps are available on request — contact support@proofledger.io with your expected volume and use case.

07 Error Codes

All errors return a JSON body of the form {"error": "..."}. Use the HTTP status code for programmatic decisions.

08 Independent Verification

Every ProofLedger proof can be verified entirely offline — without contacting ProofLedger's servers — using the verify-proof Python package.

pip install verify-proof

# Hash a file:
verify-proof hash ./evidence.pdf

# Verify against a proof JSON downloaded from ProofLedger:
verify-proof verify ./evidence.pdf --proof ./proof.json

This is the recommended path for court-submission workflows: a party challenging admissibility can run verify-proof on their own machine against the public blockchain record, independently of whether ProofLedger is online. Source: github.com/Fulcrum-Enterprises/verify-proof.

09 Support

For API questions, integration help, or to request a higher rate limit, contact:

ProofLedger LLC
support@proofledger.io

Related: FAQ & Support · Enterprise