API Verification Endpoints

Endpoints Overview

Method	Path	Auth	Description
POST	/api/verify	❌	Verify a file hash against the blockchain
GET	/api/verify/check/:hash	❌	Quick hash lookup
POST	/api/verify/merkle	❌	Verify a Merkle proof independently

All verification endpoints are public — no authentication required. This is by design: anyone should be able to verify a timestamp without being a TimeProof user.

Quick Hash Check

The fastest way to check whether a hash exists on-chain:

GET /api/verify/check/:hash

Parameters

Parameter	Location	Description
hash	URL path	The SHA-256 hash to look up (64-character hex string)

Response (Found)

{
  "verified": true,
  "txHash": "0x7f8a19c3b42e...",
  "blockNumber": 54321,
  "timestamp": "2026-02-03T12:00:00Z",
  "network": "amoy"
}

Response (Not Found)

{
  "verified": false,
  "message": "Hash not found in blockchain records"
}

Use Case

This endpoint answers one question: “Was this file hash recorded on the blockchain?” It’s the fastest verification method — ideal for automated checks in CI/CD pipelines, audit scripts, or intake workflows.

Full Verification

For a more thorough verification that includes additional metadata:

POST /api/verify
Content-Type: application/json

Request Body

{
  "hash": "e3b0c44298fc1c149afbf4c8996fb924...",
  "fileName": "contract-v3.pdf"
}

Parameters

Field	Type	Required	Description
hash	string	Yes	SHA-256 hash of the file
fileName	string	No	Original filename (for matching against records)

Response

The response includes the transaction hash, block number, anchoring timestamp, and network — everything needed to cross-reference on Polygonscan.

Merkle Proof Verification

For files that were part of a batch, verify the Merkle proof independently:

POST /api/verify/merkle
Content-Type: application/json

Request Body

{
  "fileHash": "e3b0c44298fc1c149afbf4c8996fb924...",
  "merkleRoot": "0x123...",
  "proof": ["0xabc...", "0xdef...", "0x789..."]
}

Parameters

Field	Type	Required	Description
fileHash	string	Yes	SHA-256 hash of the specific file
merkleRoot	string	Yes	The Merkle root anchored on-chain
proof	array	Yes	Array of proof hashes (from the certificate)

How It Works

The server walks the Merkle proof: starting from your file hash, it combines it with each proof element and hashes the pair. If the final result equals the Merkle root, the proof is valid — your file was mathematically included in the batch.

This is a pure mathematical verification. The server doesn’t look up any database records — it simply computes the proof. This means you could implement the same logic locally if you wanted complete independence from TimeProof’s server.

Response (Valid)

{
  "valid": true,
  "fileHash": "e3b0c44298fc1c149afbf4c8996fb924...",
  "merkleRoot": "0x123...",
  "message": "Merkle proof is valid"
}

Response (Invalid)

{
  "valid": false,
  "message": "Merkle proof does not match the provided root"
}

Integration Examples

Python — Verify a File

import hashlib
import requests

# Compute SHA-256
with open("contract-v3.pdf", "rb") as f:
    file_hash = hashlib.sha256(f.read()).hexdigest()

# Quick check
response = requests.get(
    f"http://localhost:5050/api/verify/check/{file_hash}"
)
result = response.json()

if result["verified"]:
    print(f"Verified! TX: {result['txHash']}")
    print(f"Anchored: {result['timestamp']}")
else:
    print("Hash not found on blockchain")

JavaScript — Verify in Node.js

import { createHash, readFileSync } from 'crypto';

const fileBuffer = readFileSync('contract-v3.pdf');
const hash = createHash('sha256').update(fileBuffer).digest('hex');

const res = await fetch(
  `http://localhost:5050/api/verify/check/${hash}`
);
const result = await res.json();

if (result.verified) {
  console.log(`Verified at block ${result.blockNumber}`);
}

Shell — Quick Verification

# Compute hash
HASH=$(sha256sum contract-v3.pdf | cut -d' ' -f1)

# Verify
curl "http://localhost:5050/api/verify/check/$HASH"

Verification Logic for Self-Implementation

If you want to verify completely independently (without calling the TimeProof API), here’s the algorithm:

1. Compute the file’s SHA-256 hash — this is your leaf hash
2. Get the transaction data from the blockchain — query Polygonscan or a JSON-RPC node for the transaction’s input data
3. Decode the Merkle root from the smart contract call data
4. Walk the Merkle proof from your certificate:
   • Start with the leaf hash
   • For each proof element, concatenate (ordered by position) and SHA-256 hash the pair
   • The final result should equal the Merkle root from the transaction
5. Compare timestamps — the block timestamp is the provable “existed before” time

This can be implemented in any language that supports SHA-256 and HTTP requests (for blockchain queries).

Error Handling

Status	Meaning	Action
200	Success (check verified field)	Read the response body
400	Invalid hash format	Ensure hash is 64 hex characters
404	Endpoint not found	Check the URL path
500	Server error	Retry after a brief delay

Related Guides

• Verifying a Timestamp — step-by-step manual verification
• Third-Party Verification — for legal and audit contexts
• Polygonscan Verification — verify directly on the blockchain explorer
• API Timestamp Endpoints — creating timestamps