Overview

HashAnchor is a blockchain attestation service that anchors data hashes on-chain via Merkle trees. Submit any SHA-256 or Keccak-256 hash, and HashAnchor batches it into a Merkle tree, publishes the Merkle root to a blockchain smart contract, and issues a cryptographically signed receipt proving inclusion.

Pipeline

Key Features

• Hash Submission — Single or batch (up to 100) hash submission with deduplication
• Merkle Batching — Hashes are grouped into Merkle trees for gas-efficient on-chain anchoring
• On-Chain Verification — Public endpoint to verify any hash against the blockchain
• Signed Receipts — Ed25519-signed JSON receipts with Merkle proofs
• Webhooks — Real-time notifications with HMAC-SHA256 signatures
• Multi-Chain Support — Configurable blockchain targets (default: Polygon)
• Billing & Quotas — Tiered plans with monthly hash limits
• Batch Export — Async CSV/JSON export of hashes and receipts
• Audit Logging — Every API action is logged for compliance

Base URLs

Getting Started

Follow these five steps to submit and verify your first hash.

curl -X POST https://hashanchor.fengdeagents.site/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Corp","email":"dev@acme.com","password":"securepass123"}'

curl -X POST https://hashanchor.fengdeagents.site/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@acme.com","password":"securepass123"}'

curl -X POST https://hashanchor.fengdeagents.site/admin/api-keys \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{"tenantId":"<your-tenant-id>","name":"my-key","scopes":["submit","query"]}'

curl -X POST https://hashanchor.fengdeagents.site/v1/hashes \
  -H "Authorization: Bearer ha_<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"hash":"0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"}'

curl https://hashanchor.fengdeagents.site/v1/verify/0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

Authentication

HashAnchor supports two authentication methods. Both use the Authorization: Bearer <token> header.

API Keys (recommended for programmatic access)

API keys have the format ha_<64 hex chars> (66 characters total). They are the primary authentication method for all /v1/* endpoints.

Authorization: Bearer ha_a1b2c3d4e5f6...

• Keys are hashed (SHA-256) before storage — the full key is shown only once at creation
• Each key has configurable scopes and a rate limit
• lastUsedAt is updated on every successful authentication

JWT Tokens (for account management)

JWT tokens are issued by POST /auth/register and POST /auth/login. They expire after 7 days.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

JWT tokens are primarily used for the /auth/me endpoint and admin operations.

Scopes

Hash Submission

All hashes must be 0x-prefixed, 64 hex character strings (32 bytes), matching the pattern /^0x[0-9a-fA-F]{64}$/.

POST /v1/hashes

Submit a single hash for anchoring.

Request body:

{
  "hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "externalId": "invoice-2024-001"   // optional, max 255 chars
}

Responses:

POST /v1/hashes/batch

Submit up to 100 hashes in a single request.

Request body:

{
  "hashes": [
    { "hash": "0xabc...001", "externalId": "doc-1" },
    { "hash": "0xabc...002" },
    { "hash": "0xabc...003", "externalId": "doc-3" }
  ]
}

Response (202):

{
  "accepted": 2,
  "duplicates": 1,
  "results": [
    { "hash": "0xabc...001", "status": "accepted", ... },
    { "hash": "0xabc...002", "status": "duplicate", ... },
    { "hash": "0xabc...003", "status": "accepted", ... }
  ]
}

Query Endpoints

All query endpoints are tenant-scoped — you only see your own data. Requires query or admin scope.

GET /v1/stats

Dashboard statistics for your tenant.

{
  "totalHashes": 1250,
  "pendingHashes": 12,
  "anchoredHashes": 1230,
  "totalBatches": 45,
  "failedBatches": 0,
  "monthlyHashes": 150
}

GET /v1/hashes/:hash

Look up the status of a specific hash. Returns 404 if not found within your tenant.

curl https://hashanchor.fengdeagents.site/v1/hashes/0xabcdef... \
  -H "Authorization: Bearer ha_<key>"

GET /v1/batches

Paginated list of Merkle batches containing your hashes.

{
  "data": [
    {
      "id": "uuid",
      "merkleRoot": "0x...",
      "leafCount": 50,
      "status": "anchored",
      "createdAt": "2024-01-15T10:30:00Z",
      "txHash": "0x...",
      "blockNumber": 12345678
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 45 }
}

GET /v1/batches/:id

Detailed view of a specific batch, including all your hashes in that batch.

{
  "id": "uuid",
  "merkleRoot": "0x...",
  "leafCount": 50,
  "status": "anchored",
  "txHash": "0x...",
  "blockNumber": 12345678,
  "blockTimestamp": 1705312200,
  "gasUsed": "45000",
  "hashes": [
    { "id": "uuid", "hash": "0x...", "status": "anchored", "externalId": "doc-1", "createdAt": "..." }
  ]
}

Device / IoT Endpoints

Register physical devices (IoT sensors, robots, edge gateways) and submit device-signed hashes. The platform verifies the signature using the device's registered public key before anchoring.

Register Device

curl -X POST /v1/device/register \
  -H "Authorization: Bearer ha_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "sensor-001",
    "publicKey": "hex-encoded-ed25519-public-key",
    "algorithm": "ed25519",
    "metadata": { "location": "factory-A" }
  }'

# Response: 201
# { "id": "uuid", "deviceId": "sensor-001", "algorithm": "ed25519", "status": "active" }

Submit Signed Hash

curl -X POST /v1/device/submit-signed \
  -H "Authorization: Bearer ha_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "sensor-001",
    "hash": "0xabc...",
    "signature": "hex-encoded-signature",
    "metadata": { "sensorType": "temperature", "value": 23.5 }
  }'

# Response: 202
# { "status": "accepted", "id": "123", "hash": "0xabc...", "signatureVerified": true }

List Devices

Device History

Returns paginated submission history for a specific device.

Public Verification

Verification is fully public — no authentication required. Anyone can verify a hash.

GET /v1/verify/:hash

curl https://hashanchor.fengdeagents.site/v1/verify/0xabcdef...

Anchored hash response (200):

{
  "verified": true,
  "status": "anchored",
  "hash": "0xabcdef...",
  "anchor": {
    "txHash": "0x...",
    "blockNumber": 12345678,
    "blockTimestamp": 1705312200,
    "chainId": 137,
    "contractAddress": "0x...",
    "onChainTimestamp": 1705312200
  },
  "receipt": { ... }
}

Pending hash response (200):

{
  "verified": false,
  "status": "pending",
  "hash": "0xabcdef...",
  "anchor": null,
  "receipt": null
}

Unknown hash response (404):

{
  "verified": false,
  "status": "not_found",
  "hash": "0xabcdef..."
}

Status Values

Receipts

Once a hash is anchored on-chain, a cryptographically signed receipt is generated containing a Merkle proof of inclusion.

GET /v1/receipts/:hash

Retrieve the anchor receipt for a specific hash. Returns 404 if the receipt has not been generated yet.

AnchorReceipt structure:

{
  "@context": "https://hashanchor.fengdeagents.site/receipt/v1",
  "hash": "0xabcdef...",
  "merkleRoot": "0x...",
  "proof": [
    { "position": "left", "data": "0x..." },
    { "position": "right", "data": "0x..." }
  ],
  "anchor": {
    "chainId": 137,
    "contractAddress": "0x...",
    "txHash": "0x...",
    "blockNumber": 12345678,
    "blockTimestamp": 1705312200
  },
  "signature": "base64-encoded-ed25519-signature"
}

Signature Verification

The signature field is an Ed25519 signature over the JSON-serialized { hash, merkleRoot, proof, anchor } object.

GET /v1/public-key

Retrieve the server's Ed25519 public key to verify receipt signatures.

curl https://hashanchor.fengdeagents.site/v1/public-key

Webhooks

Receive real-time notifications when your hashes are anchored. Webhook payloads are signed with HMAC-SHA256.

Endpoints

Create Webhook

curl -X POST https://hashanchor.fengdeagents.site/v1/webhooks \
  -H "Authorization: Bearer ha_<key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook",
    "events": ["hash.anchored"],
    "secret": "your-secret-min-16-chars"
  }'

• url — HTTPS endpoint (required, max 2048 chars)
• events — Array of event types to subscribe to (default: all)
• secret — HMAC secret, 16–255 chars (auto-generated if omitted)

Update Webhook

curl -X PATCH https://hashanchor.fengdeagents.site/v1/webhooks/:id \
  -H "Authorization: Bearer ha_<key>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/new-endpoint", "status": "disabled"}'

HMAC-SHA256 Signature Verification

Each webhook delivery includes a signature header. Verify it to ensure the payload is authentic:

// Node.js example
const crypto = require('crypto');

function verifyWebhook(payload, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected)
  );
}

Retry Logic

Failed deliveries are retried up to 3 times with exponential backoff:

Multi-Chain

HashAnchor supports anchoring to multiple blockchains. Chain configurations are managed by admins.

Default Chain

The default anchoring target is Polygon (chain ID 137). When no specific chain is configured, all hashes are anchored on Polygon.

Chain Configuration (Admin)

POST /admin/chains

{
  "name": "Polygon Mainnet",
  "chainId": 137,
  "rpcUrl": "https://polygon-rpc.com",
  "contractAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "privateKey": "0x...",
  "confirmations": 5,
  "isDefault": true
}

GET /admin/chains — List all chain configs (private key excluded from response).

Billing & Quotas

HashAnchor uses monthly hash submission limits based on your plan tier.

Plans

Quota Headers

When a plan is assigned, every submission response includes quota headers:

Quota Exceeded

When you exceed your monthly limit, submission endpoints return 429:

{
  "message": "Monthly hash limit reached (100). Upgrade your plan for higher limits."
}

Rate Limiting

Rate limits are enforced per API key using a Redis-backed 60-second fixed window.

Configuration

Each API key has a configurable rateLimitPerMinute (default: 60, max: 10,000). This is set at key creation time.

Response Headers

Every authenticated response includes rate limit headers:

Rate Limit Exceeded (429)

When the limit is exceeded, the response includes a Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 45
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0

{
  "message": "Rate limit exceeded"
}

The Retry-After value is the number of seconds until the current window resets.

Batch Export

Export your hashes or receipts as CSV or JSON files. Exports run asynchronously and are available for download once complete.

Start an Export

Request body:

{
  "format": "csv",           // "csv" (default) or "json"
  "filters": {
    "status": "anchored",    // optional
    "from": "2024-01-01",    // optional
    "to": "2024-12-31"       // optional
  }
}

Response (202):

{
  "id": "export-uuid",
  "status": "pending",
  "type": "hashes",
  "format": "csv"
}

Check Status / Download

GET /v1/export/:id

• In progress: Returns 200 with { id, status, type, format, totalRows }
• Completed: Streams the file download with appropriate Content-Type and Content-Disposition headers
• Expired: Returns 410 Gone — export files expire after 24 hours

curl -O https://hashanchor.fengdeagents.site/v1/export/<export-id> \
  -H "Authorization: Bearer ha_<key>"

Audit Logging

Every authenticated API request is automatically logged for compliance and debugging.

Logged Fields

Action Naming Convention

Query Audit Logs (Admin)

GET /admin/audit-logs

Admin API

Admin endpoints require the admin scope. They manage tenants, API keys, chains, and system operations.

Tenant Management

Create tenant body:

{
  "name": "Acme Corp",                // 1-255 chars, required
  "contactEmail": "admin@acme.com"    // optional
}

API Key Management

Create API key body:

{
  "tenantId": "uuid",                  // required
  "name": "production-key",            // 1-255 chars, required
  "scopes": ["submit", "query"],       // default: [] (unrestricted)
  "rateLimitPerMinute": 120            // 1-10000, default: 60
}

Response (201):

{
  "id": "uuid",
  "tenantId": "uuid",
  "keyPrefix": "ha_a1b2c",
  "name": "production-key",
  "scopes": ["submit", "query"],
  "rateLimitPerMinute": 120,
  "createdAt": "2024-01-15T10:30:00Z",
  "key": "ha_a1b2c3d4e5f6...full64hexchars"
}

Chain Configuration

See the Multi-Chain section for chain management endpoints.

Dead Letter Queue

GET /admin/dlq/stats

Returns DLQ statistics and recent jobs for monitoring failed background tasks.

{
  "counts": { "completed": 0, "waiting": 2, "active": 0 },
  "recentJobs": [
    { "id": "job-id", "data": { ... }, "timestamp": 1705312200 }
  ]
}

Returns 503 if the DLQ is not configured.

Error Handling

All errors follow a consistent JSON format:

{
  "error": "Human-readable error message"
}

HTTP Status Codes

Scope Errors

HTTP/1.1 403 Forbidden

{
  "error": "Insufficient scope. Required: submit or admin"
}

Validation Errors

HTTP/1.1 400 Bad Request

{
  "error": "Invalid hash format"
}

API Reference

Complete list of all API endpoints.

For interactive API testing, use the Swagger UI or download the OpenAPI spec.