API documentation

Kairostamp exposes one paid endpoint and one free preflight endpoint. There are no accounts and no API keys: authorization is a per-request x402 payment. All examples below use placeholder values only — never send real secrets to this API.

Current terms

Base URL: https://kairostamp.com
Protocol: x402, scheme exact
Network: eip155:84532 (Base Sepolia test network)
Price: $0.01 test USDC per successful snapshot (10000 atomic units)
Mainnet is disabled. Test funds only.

POST /api/v1/snapshot/preflight (free)

Checks eligibility and returns the live payment terms and limits. It performs no outbound fetch and stores nothing.

curl -s -X POST https://kairostamp.com/api/v1/snapshot/preflight \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/"}'

{
  "eligible": true,
  "url": "https://example.com/",
  "limits": {
    "max_redirects": 3,
    "max_bytes": 1048576,
    "deadline_ms": 10000,
    "text_preview_chars": 4000
  },
  "payment": {
    "protocol": "x402",
    "scheme": "exact",
    "network": "eip155:84532",
    "network_label": "base-sepolia",
    "price": "$0.01",
    "method": "POST",
    "path": "/api/v1/snapshot",
    "configured": true
  },
  "service": { "fetch_backend_ready": true }
}

Ineligible targets return HTTP 200 with eligible: false and a reason drawn from the same error vocabulary below.

POST /api/v1/snapshot (paid)

Request body: a JSON object with a single url string (http/https, max 2048 characters, no embedded credentials).

{ "url": "https://example.com/" }

Successful response (HTTP 200):

{
  "receipt_id": "85cd424c-b68b-440e-8f4f-e02147799f30",
  "previous_chain_hash": "da27fe24…88def",
  "chain_hash": "d084fff3…b584d",
  "receipt": {
    "url": "https://example.com/",
    "fetched_at": "2026-08-21T06:32:12.771Z",
    "status_code": 200,
    "content_type": "text/html",
    "byte_length": 559,
    "sha256": "ff67a9d7…1a299d",
    "redirect_chain": [],
    "text_preview": "<!doctype html>…"
  }
}

Optional headers: Idempotency-Key makes a retried request map to the same internal request id. Responses include standard rate-limit headers.

POST /api/v1/change-check (paid)

Same price, network, engine and receipt format as the snapshot endpoint, plus one comparison. Body: url and exactly one of prior_sha256 (a 64-char lowercase hex digest) or prior_receipt_id (the id of an earlier Kairostamp receipt). Unknown properties are rejected.

{ "url": "https://example.com/", "prior_sha256": "ff67a9d7…1a299d" }

Successful response (HTTP 200):

{
  "changed": false,
  "previous_sha256": "ff67a9d7…1a299d",
  "current_sha256": "ff67a9d7…1a299d",
  "receipt_id": "85cd424c-b68b-440e-8f4f-e02147799f30",
  "previous_chain_hash": "da27fe24…88def",
  "chain_hash": "d084fff3…b584d",
  "receipt": { "url": "https://example.com/", "status_code": 200, "sha256": "ff67a9d7…1a299d" }
}

# 1. Unsigned call returns the 402 discovery challenge (Base Sepolia testnet)
curl -i -X POST https://kairostamp.com/api/v1/change-check \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/","prior_sha256":"ff67a9d7…1a299d"}'
# HTTP/1.1 402 Payment Required
# PAYMENT-REQUIRED: <base64 x402 v2 terms — eip155:84532, $0.01 test USDC>

# 2. Signed purchase
curl -i -X POST https://kairostamp.com/api/v1/change-check \
  -H 'Content-Type: application/json' \
  -H "PAYMENT-SIGNATURE: $SIGNED_AUTHORIZATION" \
  -H "Idempotency-Key: $YOUR_REQUEST_UUID" \
  -d '{"url":"https://example.com/","prior_receipt_id":"85cd424c-b68b-440e-8f4f-e02147799f30"}'

One call performs one check. There is no background monitoring and no subscription: to keep watching a URL, your agent calls the endpoint again, passing the current_sha256 or receipt_id from the previous result.

x402 payment flow

Call the endpoint without a payment header. The server replies 402 with an x402 v2 PAYMENT-REQUIRED advertisement describing the network, asset, amount and recipient. Your client signs an exact-amount authorization and retries with the PAYMENT-SIGNATURE header.

The server verifies the authorization, runs the snapshot, and only then settles. If the snapshot fails, the authorization goes unused and nothing is charged. Each settled payment is processed exactly once: a repeat with the same settlement transaction hash returns the stored outcome instead of running again.

# 1. Discover terms
curl -i -X POST https://kairostamp.com/api/v1/snapshot \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/"}'
# HTTP/1.1 402 Payment Required
# PAYMENT-REQUIRED: <base64 x402 v2 terms>

# 2. Retry with a signed authorization produced by your x402 client
curl -i -X POST https://kairostamp.com/api/v1/snapshot \
  -H 'Content-Type: application/json' \
  -H "PAYMENT-SIGNATURE: $SIGNED_AUTHORIZATION" \
  -H "Idempotency-Key: $YOUR_REQUEST_UUID" \
  -d '{"url":"https://example.com/"}'

Keep signing keys inside your own agent runtime. Kairostamp never asks for a private key, seed phrase or wallet credential, and never returns one.

Limits

One URL per request; maximum request body 8 KiB.
Change check accepts exactly one baseline reference per request.
10 second fetch deadline, 1 MiB body cap, 3 redirects max.
Text preview truncated at 4,000 characters.
Rate limits: 60 paid requests and 120 preflight requests per minute per caller by default; exceeding them returns 429 with retry headers.
Private, loopback, link-local and metadata addresses are rejected; DNS is resolved and pinned server-side to prevent rebinding.

Error codes

Errors are returned as { "error": "<code>" } with a stable code. Provider and database internals are never surfaced.

code	HTTP	meaning
invalid_json	400	Request body was not valid JSON.
invalid_request	400	Body was not a JSON object.
invalid_url	400	Missing or malformed url field (max 2048 chars, http/https only).
invalid_reference	400	Change check needs exactly one of prior_sha256 or prior_receipt_id.
invalid_sha256	400	prior_sha256 must be 64 lowercase hex characters.
invalid_receipt_id	400	prior_receipt_id must be a UUID.
unknown_receipt	404	No stored receipt matches prior_receipt_id.
blocked_target	403	Target resolves to a private, internal or otherwise disallowed address.
rate_limited	429	Per-caller rate limit exceeded. Retry after the window resets.
body_too_large	413	Response body exceeded the 1 MiB cap.
invalid_redirect	502	A redirect pointed at a disallowed target.
too_many_redirects	502	More than 3 redirects.
fetch_failed	502	The target could not be fetched.
timeout	504	Target did not respond within the 10 second deadline.
dns_unavailable	503	Server-side DNS resolution was unavailable; fails closed.
pinning_unavailable	503	Safe pinned fetch backend unavailable; fails closed.
platform_unavailable	503	Snapshot backend not ready. No payment is settled.
payment_not_configured	503	Payment layer is not configured or configuration is invalid.
payment_verification_unavailable	503	Payment verification could not be performed.
settlement_unavailable	503	Settlement could not be performed after a successful snapshot.
settlement_uncertain	503	Settlement outcome is ambiguous (transport timeout). Not retried automatically; contact support with your payment details for reconciliation.
settlement_failed	402	Settlement was rejected. Nothing is stored.
payment_processing	409	The same settled payment is currently being processed.
payment_log_unavailable	503	Accounting ledger unavailable; request is not fulfilled.
evidence_store_unavailable	503	Evidence store unavailable; request is not fulfilled.
reconciliation_required	503	Settlement succeeded but bookkeeping did not; contact the operator.

Discovery

The paid route publishes x402 Bazaar discovery metadata alongside its 402 response, including a JSON Schema for the request body and an example response, so an agent can learn the contract without a human reading this page. The advertised route pattern is POST /api/v1/snapshot and POST /api/v1/change-check, both on eip155:84532 (Base Sepolia testnet).

Support and status

Operational status and bookkeeping endpoints are private to the operator and require a token. If a settlement succeeded but you did not receive a receipt, keep the settlement transaction hash and contact the operator at support@kairostamp.com for reconciliation.