Oracle API

The Oracle server verifies AI-generated content and produces cryptographic attestations that miners submit on-chain to claim $CLAW. All endpoints are accessible via HTTPS at oracle.minewithclaw.com.

---

Base URL

https://oracle.minewithclaw.com

All requests must use HTTPS. HTTP requests are rejected.

Authentication

The Oracle API does not require API keys or bearer tokens. Access is rate-limited by Ethereum address and cooldown mechanics enforced on-chain.

---

Endpoints

GET /health

Health check endpoint. Returns the Oracle server status.

Request:

curl https://oracle.minewithclaw.com/health

Response (200 OK):

{
  "status": "ok",
  "version": "2.1.0",
  "uptime": 1234567,
  "currentBlock": 19500000,
  "currentEra": 1,
  "currentEpoch": 3,
  "model": "grok-4.1-fast"
}

Response Fields:

Field	Type	Description
status	string	Server status ("ok" or "degraded")
version	string	Oracle software version
uptime	number	Uptime in seconds
currentBlock	number	Latest Ethereum block observed
currentEra	number	Current mining Era
currentEpoch	number	Current Epoch within the Era
model	string	Designated AI model for current Era

---

GET /api/v1/nonce

Request a unique nonce for a mining attempt. The nonce prevents replay attacks and must be included in the attestation request.

Request:

curl "https://oracle.minewithclaw.com/api/v1/nonce?address=0xYourAddress"

Query Parameters:

Parameter	Type	Required	Description
address	string	Yes	Miner's Ethereum address (checksummed)

Response (200 OK):

{
  "nonce": "0x8a3f...b7c2",
  "expiresAt": 1710000000,
  "blockRef": 19500000
}

Response Fields:

Field	Type	Description
nonce	string	Unique nonce (hex-encoded bytes32)
expiresAt	number	Unix timestamp when the nonce expires
blockRef	number	Ethereum block number at nonce creation

Error Responses:

Status	Code	Description
400	INVALID_ADDRESS	Malformed Ethereum address
429	RATE_LIMITED	Too many nonce requests; try again later
503	SERVICE_UNAVAILABLE	Oracle is temporarily unavailable

Notes:

• Nonces expire after a limited time window. Request a fresh nonce before each claim attempt.

• Each nonce is single-use and tied to the requesting address.

---

POST /api/v1/attest

Submit AI-generated content for verification. If the content passes all checks, the Oracle returns a signed attestation.

Request:

curl -X POST https://oracle.minewithclaw.com/api/v1/attest \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xYourAddress",
    "nonce": "0x8a3f...b7c2",
    "content": "The AI-generated content string...",
    "model": "grok-4.1-fast"
  }'

Request Body:

Field	Type	Required	Description
address	string	Yes	Miner's Ethereum address
nonce	string	Yes	Nonce from /api/v1/nonce
content	string	Yes	AI-generated content to verify
model	string	Yes	AI model used for generation

Response (200 OK):

{
  "attestation": {
    "miner": "0xYourAddress",
    "nonce": "0x8a3f...b7c2",
    "blockRef": 19500000,
    "contentHash": "0xabcd...ef01",
    "model": "grok-4.1-fast",
    "timestamp": 1710000000
  },
  "signature": "0x1234...5678",
  "reward": {
    "estimated": "916000000000000000000000",
    "era": 1,
    "epoch": 3,
    "perBlock": "100000000000000000000000"
  }
}

Response Fields:

Field	Type	Description
attestation	object	The attestation data to submit on-chain
attestation.miner	string	Miner address (matches request)
attestation.nonce	string	Nonce used
attestation.blockRef	number	Block reference from nonce creation
attestation.contentHash	string	Keccak-256 hash of the AI content
attestation.model	string	AI model used
attestation.timestamp	number	Oracle signing timestamp
signature	string	ECDSA signature by Oracle signer
reward.estimated	string	Estimated reward in wei
reward.era	number	Current Era
reward.epoch	number	Current Epoch
reward.perBlock	string	Base reward for current Era (wei)

Error Responses:

Status	Code	Description
400	INVALID_NONCE	Nonce is expired or already used
400	INVALID_MODEL	Content was not generated by the designated model
400	INVALID_CONTENT	Content failed verification
403	COOLDOWN_ACTIVE	Miner's cooldown period has not elapsed
403	EPOCH_LIMIT_REACHED	Miner has reached 14 claims this epoch
429	RATE_LIMITED	Too many requests; try again later
500	INTERNAL_ERROR	Oracle internal error; retry
503	SERVICE_UNAVAILABLE	Oracle is temporarily unavailable

---

GET /metrics

Prometheus-compatible metrics endpoint for monitoring Oracle performance.

Request:

curl https://oracle.minewithclaw.com/metrics

Response (200 OK):

# HELP oracle_attestations_total Total attestations signed
# TYPE oracle_attestations_total counter
oracle_attestations_total 12345

# HELP oracle_attestation_duration_seconds Attestation processing time
# TYPE oracle_attestation_duration_seconds histogram
oracle_attestation_duration_seconds_bucket{le="1"} 10000
oracle_attestation_duration_seconds_bucket{le="5"} 12000
oracle_attestation_duration_seconds_bucket{le="10"} 12300
oracle_attestation_duration_seconds_bucket{le="+Inf"} 12345

# HELP oracle_active_miners Current unique miners
# TYPE oracle_active_miners gauge
oracle_active_miners 456

# HELP oracle_current_era Current mining era
# TYPE oracle_current_era gauge
oracle_current_era 1

# HELP oracle_current_epoch Current epoch within era
# TYPE oracle_current_epoch gauge
oracle_current_epoch 3

# HELP oracle_errors_total Total errors by type
# TYPE oracle_errors_total counter
oracle_errors_total{type="invalid_nonce"} 23
oracle_errors_total{type="cooldown_active"} 156
oracle_errors_total{type="epoch_limit"} 12

Available Metrics:

Metric	Type	Description
oracle_attestations_total	counter	Total attestations signed
oracle_attestation_duration_seconds	histogram	Processing time per attestation
oracle_active_miners	gauge	Number of unique active miners
oracle_current_era	gauge	Current Era
oracle_current_epoch	gauge	Current Epoch
oracle_errors_total	counter	Errors by type
oracle_nonces_issued	counter	Total nonces issued
oracle_uptime_seconds	counter	Server uptime

---

Error Response Format

All error responses follow a consistent JSON format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {}
  }
}

Field	Type	Description
error.code	string	Machine-readable error code
error.message	string	Human-readable description
error.details	object	Additional context (optional)

Rate Limits

Endpoint	Limit	Window
GET /health	60 requests	Per minute
GET /api/v1/nonce	10 requests	Per minute per address
POST /api/v1/attest	5 requests	Per minute per address
GET /metrics	30 requests	Per minute

Rate-limited responses return HTTP 429 with a Retry-After header.

Integration Example

Complete mining flow using curl and cast:

# Step 1: Get nonce
NONCE_RESPONSE=$(curl -s "https://oracle.minewithclaw.com/api/v1/nonce?address=$MINER_ADDRESS")
NONCE=$(echo $NONCE_RESPONSE | jq -r '.nonce')

# Step 2: Generate AI content (using your AI API)
CONTENT=$(curl -s https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $AI_API_KEY" \
  -d '{"model":"grok-4.1-fast","messages":[{"role":"user","content":"Mining prompt"}]}' \
  | jq -r '.choices[0].message.content')

# Step 3: Submit for attestation
ATTEST_RESPONSE=$(curl -s -X POST https://oracle.minewithclaw.com/api/v1/attest \
  -H "Content-Type: application/json" \
  -d "{\"address\":\"$MINER_ADDRESS\",\"nonce\":\"$NONCE\",\"content\":\"$CONTENT\",\"model\":\"grok-4.1-fast\"}")

ATTESTATION=$(echo $ATTEST_RESPONSE | jq -r '.attestation')
SIGNATURE=$(echo $ATTEST_RESPONSE | jq -r '.signature')

# Step 4: Submit on-chain (using cast/foundry)
cast send 0xe7fc311863b95e726a620b07607209965ee72bce \
  "claim(bytes,bytes)" "$ATTESTATION" "$SIGNATURE" \
  --private-key $PRIVATE_KEY

Next Steps

• Architecture — System design and data flow

• Smart Contracts — On-chain contract details

• Security — Oracle security model

• CLI Reference — CLI tools that wrap these APIs