ClawFeel API Documentation

POST Report Feel

/api/report

A Claw node reports its current Feel score, sensor data, and entropy hash to the relay. This is the primary ingestion endpoint for all network participants.

Headers

Name	Type	Description
X-Claw-Id	string	Claw node identifier (e.g. `Claw-a1b2c3d4`). Optional — can also be sent in body.

Body (JSON)

Name	Type	Description
clawId	string	Node identifier. Required if not in header.
feel	number	Feel score (0–100). Required
era	string	Current era: `Chaos`, `Transition`, or `Eternal`.
hash	string	SHA-256 entropy hash (hex).
prevHash	string	Previous hash for chain verification.
seq	number	Sequence number (monotonically increasing).
authenticity	number	Sensor authenticity score (0–7).
entropyQuality	number	Entropy quality percentage (0–100).
sensorFlags	string	7-bit string, each bit = sensor active (`1111111`).
alias	string	Human-readable node name.
type	string	`node` (hardware) or `browser` (light client).
sensors	object	Raw sensor readings (cpu, memory, etc.).
zkProof	object	Optional zero-knowledge proof for reputation boost.

Example Request

curl -X POST https://api.clawfeel.ai/api/report \
  -H "Content-Type: application/json" \
  -H "X-Claw-Id: Claw-a1b2c3d4" \
  -d '{
    "clawId": "Claw-a1b2c3d4",
    "feel": 72,
    "era": "Eternal",
    "hash": "a3f8c1d2e5b6...",
    "seq": 42,
    "authenticity": 7,
    "entropyQuality": 92,
    "sensorFlags": "1111111",
    "alias": "my-node",
    "type": "node"
  }'

Example Response

{
  "ok": true,
  "peers": 12
}

GET Network State

/api/network

Returns a snapshot of the entire network: aggregate statistics, the computed network random number, latest beacon, and all currently online nodes.

Example Request

curl https://api.clawfeel.ai/api/network

Example Response

{
  "timestamp": "2026-03-23T12:00:00.000Z",
  "tick": 1024,
  "stats": {
    "onlineNodes": 5,
    "avgFeel": 62,
    "chaos": 1,
    "transition": 3,
    "eternal": 1,
    "avgQuality": 85,
    "avgAuth": "6.2",
    "suspectCount": 0
  },
  "networkRandom": {
    "number": 47,
    "era": "Transition",
    "hash": "a3f8c1d2e5b6"
  },
  "nodes": [...],
  "beacon": {...}
}

GET Real-time Stream

/api/stream

Server-Sent Events (SSE) endpoint. Pushes network state updates every 2 seconds. Includes node data, aggregate stats, and beacon rounds.

Example Request

curl -N https://api.clawfeel.ai/api/stream

Example Response (SSE)

: connected

data: {"timestamp":"2026-03-23T12:00:00.000Z","tick":1024,"stats":{...},"nodes":[...],"beacon":{...}}

data: {"timestamp":"2026-03-23T12:00:02.000Z","tick":1025,"stats":{...},"nodes":[...],"beacon":{...}}

JavaScript Usage

const es = new EventSource("https://api.clawfeel.ai/api/stream");
es.onmessage = (e) => {
  const state = JSON.parse(e.data);
  console.log("Nodes online:", state.stats.onlineNodes);
};

GET Bootstrap Peers

/api/bootstrap

Returns the DHT peer list for new nodes joining the network. Includes relay version, DHT port, and a list of active peers with their reputation scores.

Example Request

curl https://api.clawfeel.ai/api/bootstrap

Example Response

{
  "service": "ClawFeel Relay",
  "version": "0.8.1",
  "dhtPort": 31416,
  "peers": [
    {
      "clawId": "Claw-a1b2c3d4",
      "alias": "big-shrimp",
      "feel": 72,
      "entropyQuality": 92,
      "reputation": 95
    }
  ],
  "peerCount": 1
}

GET Latest Beacon

/api/beacon/latest

Returns the most recently sealed beacon round. Beacons are sealed every 10 seconds by XOR-aggregating contributing node hashes, then SHA-256 hashing the result.

Example Request

curl https://api.clawfeel.ai/api/beacon/latest

Example Response

{
  "round": 156,
  "timestamp": "2026-03-23T12:00:10.000Z",
  "xorAccum": "a3f8c1d2e5b6...",
  "beaconHash": "e7a2b1c3d4f5...",
  "beaconNumber": 73,
  "era": "Eternal",
  "contributorCount": 5,
  "contributors": [...],
  "signature": "3045..."
}

GET Beacon by Round

/api/beacon/:round

Retrieve a specific beacon round by its number. Returns 404 if the round has not been sealed yet or has been pruned.

Path Parameters

Name	Type	Description
round	integer	Beacon round number. Required

Example Request

curl https://api.clawfeel.ai/api/beacon/42

Example Response

{
  "round": 42,
  "timestamp": "2026-03-23T11:53:00.000Z",
  "beaconHash": "b4c5d6e7f8a9...",
  "beaconNumber": 28,
  "era": "Chaos",
  "contributorCount": 3
}

GET Beacon Range

/api/beacons

Query a range of beacon rounds. Returns up to 100 rounds per request. Useful for historical analysis and verification.

Query Parameters

Name	Type	Description
from	integer	Start round (inclusive). Default: `1`
to	integer	End round (inclusive). Default: `999999`

Example Request

curl "https://api.clawfeel.ai/api/beacons?from=1&to=10"

Example Response

{
  "rounds": [
    { "round": 1, "beaconHash": "...", ... },
    { "round": 2, "beaconHash": "...", ... }
  ],
  "count": 2
}

GET Search Transactions

/api/explorer/txs

Search recent Feel report transactions. Supports filtering by hash prefix, clawId, or alias. Returns newest first.

Query Parameters

Name	Type	Description
search	string	Filter by hash prefix, clawId, or alias.
limit	integer	Max results (1–200). Default: `50`

Example Request

curl "https://api.clawfeel.ai/api/explorer/txs?search=Claw&limit=10"

Example Response

[
  {
    "hash": "a3f8c1d2e5b6...",
    "prevHash": "9e8d7c6b5a4f...",
    "clawId": "Claw-a1b2c3d4",
    "alias": "big-shrimp",
    "feel": 72,
    "era": "Eternal",
    "seq": 42,
    "authenticity": 7,
    "entropyQuality": 92,
    "timestamp": "2026-03-23T12:00:00.000Z"
  }
]

GET Transaction Detail

/api/explorer/tx/:hash

Look up a specific transaction by its hash prefix. The prefix must be at least 8 hex characters.

Path Parameters

Name	Type	Description
hash	string	Hash prefix (min 8 chars). Required

Example Request

curl https://api.clawfeel.ai/api/explorer/tx/a3f8c1d2

Example Response

{
  "hash": "a3f8c1d2e5b6...",
  "clawId": "Claw-a1b2c3d4",
  "feel": 72,
  "era": "Eternal",
  "seq": 42,
  "authenticity": 7,
  "entropyQuality": 92,
  "sensorFlags": "1111111",
  "type": "node",
  "timestamp": "2026-03-23T12:00:00.000Z"
}

GET Node Detail

/api/explorer/node/:id

Look up a specific node by clawId or alias. Supports partial matching. Returns full node state including online status and history.

Path Parameters

Name	Type	Description
id	string	ClawId or alias (supports partial match). Required

Example Request

curl https://api.clawfeel.ai/api/explorer/node/Claw-a1b2c3d4

Example Response

{
  "clawId": "Claw-a1b2c3d4",
  "alias": "big-shrimp",
  "feel": 72,
  "era": "Eternal",
  "hash": "a3f8c1d2e5b6...",
  "authenticity": 7,
  "entropyQuality": 92,
  "reputation": 95,
  "type": "node",
  "online": true,
  "firstSeen": 1711180800000,
  "lastSeen": 1711267200000
}

GET Network Overview

/api/explorer/overview

Returns high-level network statistics: total online nodes, transaction count, and the latest beacon round number.

Example Request

curl https://api.clawfeel.ai/api/explorer/overview

Example Response

{
  "totalNodes": 5,
  "totalTxs": 847,
  "latestBeacon": 156
}

GET Random Number Bearer Token

/api/v1/random

Generate a single cryptographically secure random value derived from the latest beacon. Supports configurable bit length and output format. Uses HKDF-like entropy expansion from the beacon hash.

Query Parameters

Name	Type	Description
bits	integer	Entropy bits (8–4096). Default: `256`
format	string	Output format: `hex`, `base64`, `decimal`, `bytes`. Default: `hex`

Headers

Name	Type	Description
Authorization	string	`Bearer <api_key>` Required

Example Request

curl -H "Authorization: Bearer cf_your_api_key_here" \
  "https://api.clawfeel.ai/api/v1/random?bits=256&format=hex"

Example Response

{
  "random": "a3f8c1d2e5b6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1",
  "bits": 256,
  "format": "hex",
  "beacon_round": 156,
  "contributors": 5,
  "timestamp": "2026-03-23T12:00:10.000Z",
  "signature": "3045..."
}

GET Batch Random Bearer Token

/api/v1/random/batch

Generate multiple independent random values in a single request. Each value is derived from the same beacon round but with a unique index, ensuring statistical independence.

Query Parameters

Name	Type	Description
count	integer	Number of values (1–100). Default: `10`
bits	integer	Entropy bits per value (8–4096). Default: `256`
format	string	Output format: `hex`, `base64`, `decimal`, `bytes`. Default: `hex`

Headers

Name	Type	Description
Authorization	string	`Bearer <api_key>` Required

Example Request

curl -H "Authorization: Bearer cf_your_api_key_here" \
  "https://api.clawfeel.ai/api/v1/random/batch?count=5&bits=64&format=hex"

Example Response

{
  "random": [
    "a3f8c1d2e5b6f7a8",
    "9e8d7c6b5a4f3e2d",
    "b1c2d3e4f5a6b7c8",
    "d9e0f1a2b3c4d5e6",
    "f7a8b9c0d1e2f3a4"
  ],
  "count": 5,
  "bits": 64,
  "format": "hex",
  "beacon_round": 156,
  "contributors": 5,
  "timestamp": "2026-03-23T12:00:10.000Z"
}

GET Random in Range Bearer Token

/api/v1/random/range

Generate a uniformly distributed random integer within a specified range [min, max] (inclusive). Uses rejection sampling to eliminate modular bias.

Query Parameters

Name	Type	Description
min	integer	Minimum value (inclusive). Default: `1`
max	integer	Maximum value (inclusive). Default: `100`. Must be > min.

Headers

Name	Type	Description
Authorization	string	`Bearer <api_key>` Required

Example Request

curl -H "Authorization: Bearer cf_your_api_key_here" \
  "https://api.clawfeel.ai/api/v1/random/range?min=1&max=100"

Example Response

{
  "random": 42,
  "min": 1,
  "max": 100,
  "beacon_round": 156,
  "contributors": 5,
  "timestamp": "2026-03-23T12:00:10.000Z"
}

GET Verify Beacon Bearer Token

/api/v1/random/verify

Verify a specific beacon round by recomputing the XOR accumulator and beacon hash from the original contributors. Returns whether all cryptographic checks pass.

Query Parameters

Name	Type	Description
round	integer	Beacon round number to verify. Required

Headers

Name	Type	Description
Authorization	string	`Bearer <api_key>` Required

Example Request

curl -H "Authorization: Bearer cf_your_api_key_here" \
  "https://api.clawfeel.ai/api/v1/random/verify?round=42"

Example Response

{
  "round": { ...full beacon object... },
  "recomputed": {
    "xorAccum": "a3f8c1d2...",
    "beaconHash": "e7a2b1c3...",
    "beaconNumber": 73,
    "era": "Eternal"
  },
  "verification": {
    "valid": true,
    "reason": null,
    "xorMatch": true,
    "hashMatch": true,
    "numberMatch": true
  }
}

GET API Usage Status Bearer Token

/api/v1/status

Check your API key's usage statistics: tier, rate limits, remaining requests in the current window, and total historical usage.

Headers

Name	Type	Description
Authorization	string	`Bearer <api_key>` Required

Example Request

curl -H "Authorization: Bearer cf_your_api_key_here" \
  https://api.clawfeel.ai/api/v1/status

Example Response

{
  "tier": "free",
  "requestsUsed": 23,
  "requestsRemaining": 77,
  "resetAt": "2026-03-23T13:00:00.000Z",
  "totalRequests": 156,
  "createdAt": "2026-03-20T08:00:00.000Z"
}

SDK AI Agent SDK

Let AI Agents make verifiable random decisions using hardware entropy. Works with LangChain, OpenAI function calling, AutoGPT, and any AI framework.

Installation

JavaScript / TypeScript

import { ClawAgent } from 'clawfeel/agent'

const agent = new ClawAgent({ mode: 'fast' })

Methods

All methods return a result with a cryptographic proof object for audit trails.

Method	Description	Example
decide(options)	Pick one randomly from array	`agent.decide(['left', 'right'])`
weighted(options, weights)	Weighted random selection	`agent.weighted(['common', 'rare'], [80, 20])`
shuffle(array)	Cryptographic Fisher-Yates shuffle	`agent.shuffle([1,2,3,4,5])`
sample(array, n)	Pick n unique items	`agent.sample(players, 5)`
probability(p)	True with probability p	`agent.probability(0.3)`
gaussian(mean, std)	Normal distribution	`agent.gaussian(100, 15)`

LangChain / OpenAI Tool

Use ClawFeel as a native tool in LangChain, OpenAI function calling, or any framework that supports tool definitions.

OpenAI Function Calling

import { clawfeelTool } from 'clawfeel/agent'

// Use as OpenAI function calling tool
const tools = [clawfeelTool]

// The tool auto-registers these functions:
// - clawfeel_decide: Pick from options with hardware entropy
// - clawfeel_shuffle: Cryptographic shuffle
// - clawfeel_sample: Random sampling
// - clawfeel_probability: Coin flip with custom probability

CLI Usage

Make agent decisions directly from the command line.

Terminal

npx clawfeel --agent-decide "option1,option2,option3"

Proof of Decision

Every decision includes a cryptographic proof object for full auditability.

Example Response

{
  "decision": "option2",
  "index": 1,
  "proof": {
    "entropy": "a3f8c1...256-bit hex",
    "hash": "sha256:9b2e4f...",
    "timestamp": "2026-03-24T12:00:00.000Z",
    "sensors": 7,
    "feel": 73,
    "nodeId": "Claw-a1b2c3d4"
  }
}

API Reference