Chronomancy Protocol API

Programmatic access to the QRNG training protocol. For agents, bots, researchers, and anyone who wants to interact with quantum randomness without a browser.

Base URL: https://chronomancy.app/api

Quick Start

# 1. Get protocol info
curl https://chronomancy.app/api/protocol/info

# 2. Create a session (guest — auto-created)
curl -X POST https://chronomancy.app/api/training/sessions \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"trial_count": 100}'

# 3. Run a trial
curl -X POST https://chronomancy.app/api/training/sessions/{id}/trial \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"intention": "high"}'

# 4. Repeat step 3. That's it.

Endpoints

GET /api/protocol/info

Public. Returns platform wallet address, supported modes, and endpoint documentation.

{
  "platform": "chronomancy",
  "wallet": "CfMQY3xCzNaDhCEPh2b2aFaPtejswcM3GYjgJ6g5Q6dF",
  "network": "solana-mainnet",
  "minimum_deposit_sol": 0.001,
  "binary_protocol": {
    "statistic": "z = (hits - N/2) / sqrt(N/4)",
    "intentions": ["high", "low"]
  }
}

POST /api/training/sessions

Create a training session. Auto-creates a guest identity (cookie-based). No auth required.

# Response
{
  "id": "d560f4ce-11d1-...",
  "status": "ACTIVE",
  "trial_count_target": 100
}

POST /api/training/sessions/{id}/trial

Execute one trial. Submit your intention, receive the QRNG bit and running statistics.

# Response
{
  "trial_num": 42,
  "intention": "high",
  "qrng_bit": 1,
  "qrng_source": "qrng",
  "hit": true,
  "running_z": +1.234,
  "running_hits": 25,
  "running_total": 42,
  "running_hit_rate": 0.5952,
  "leaf_hash": "5d985b0c...",
  "session_complete": false
}

qrng_source is "qrng" for hardware quantum entropy, "csprng" for fallback. leaf_hash is the Merkle leaf for this trial.

POST /api/training/sessions/{id}/stop

Stop a session early. Returns final stats and Merkle root.

{
  "trials_completed": 42,
  "z_score": 1.234,
  "hit_rate": 0.5952,
  "merkle_root": "a7c3e891..."
}

GET /api/training/stats

Get your lifetime cumulative statistics across all sessions.

{
  "total_trials": 10420,
  "total_hits": 5180,
  "hit_rate": 0.4971,
  "cumulative_z_score": -0.587
}

GET /api/bounty

Public. Get all bounty tiers and current challengers.

{
  "tiers": [
    { "threshold_z": 2.0, "min_trials": 10000, "reward_sol": 0 },
    { "threshold_z": 5.0, "min_trials": 100000, "reward_sol": 0.5 }
  ],
  "challengers": []
}

GET /api/training/leaderboard

Public. Top experimenters by z-score.

GET /api/verify/{session_id}

Public. Verify a session's Merkle proof and Solana anchor.

Authentication

Sessions are cookie-based. On your first POST /api/training/sessions, a guest identity is created and a chronomancy_guest httpOnly cookie is set. Include credentials: "include" (fetch) or -b cookies.txt (curl) on subsequent requests.

For wallet-authenticated sessions, use the Solana wallet auth flow:

# 1. Get nonce
GET /api/auth/nonce?wallet_address={addr}

# 2. Sign the nonce message with your wallet

# 3. Verify signature
POST /api/auth/verify
{ "wallet_address": "...", "signature": "...", "nonce": "..." }

# Sets chronomancy_session cookie

Agent Example

Run 100 trials from a Python script:

#!/usr/bin/env python3
import requests

s = requests.Session()
base = "https://chronomancy.app/api"

# Create session
sess = s.post(f"{base}/training/sessions",
    json={"trial_count": 100}).json()
sid = sess["id"]

# Run 100 trials
for i in range(100):
    r = s.post(f"{base}/training/sessions/{sid}/trial",
        json={"intention": "high"}).json()
    hit = "HIT" if r["hit"] else "MISS"
    print(f"Trial {r['trial_num']}: {hit} z={r['running_z']:+.3f}")

print(f"\nFinal: {r['running_hits']}/{r['running_total']}")
print(f"Z-score: {r['running_z']:+.3f}")
print(f"Source: {r['qrng_source']}")

Design Principles