API Documentation

Authentication

All API requests require authentication via an API key. Include your key in the X-API-Key header.

curl -H "X-API-Key: YOUR_API_KEY" \
https://api.comet.example/api/v1/blocks

Rate Limits

Rate limits are applied per API key. Check response headers for current limits:

Header	Description
X-RateLimit-Limit	Requests per minute
X-RateLimit-Remaining	Remaining requests in current window
X-RateLimit-Reset	Unix timestamp when window resets

Endpoints

Chain

GET /api/v1/chain/summary

Get chain summary including latest height and average block time

Blocks

GET /api/v1/blocks

List blocks with pagination

Parameters: limit (max 100), before (cursor)

GET /api/v1/blocks/{height}

Get block by height

Transactions

GET /api/v1/txs

List transactions

Parameters: limit, offset, failed, height

GET /api/v1/txs/{tx_hash}

Get transaction by hash (includes events)

Events

GET /api/v1/events

List events

Parameters: event_type, tx_hash, limit, offset

Statistics

GET /api/v1/stats

Get pre-computed chain statistics (TPS, avg block time, etc.)

Anchors (Data Anchoring)

Anchor data hashes on the blockchain to create proof of existence.

POST /api/v1/anchors

Create a new anchor

Body: {"namespace": "document", "data_hash": "sha256_hex", "metadata": {...}}

Namespaces: document, audit, certificate, sensor, supply-chain

Returns: anchor_id, namespace, status, tx_hash

GET /api/v1/anchors

List and search anchors

Parameters: limit, offset, namespace, status, data_hash, tx_hash, created_from, created_to

GET /api/v1/anchors/{anchor_id}

Get anchor details by ID

GET /api/v1/anchors/by-hash/{data_hash}

Find anchors by data hash (returns array)

Parameters: namespace, latest (single result), include_revoked

POST /api/v1/anchors/verify

Verify if a hash has been anchored

Body: {"data_hash": "sha256_to_verify"}

Returns: anchored, status, revoked, tx_hash

GET /api/v1/anchors/{anchor_id}/history

Get anchor history (created → submitted → confirmed → revoked)

Returns: history[], transactions[]

POST /api/v1/anchors/{anchor_id}/revoke

Revoke an anchor

Body (optional): {"reason": "..."}

GET /api/v1/txs/{tx_hash}/status

Get transaction confirmation status

Anchor Status Flow

pending → submitted → confirmed
↘ failed
confirmed → revoked

Error Codes

Code	Description
401	Missing or invalid API key
404	Resource not found
429	Rate limit exceeded
500	Internal server error