Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.b1e55ed.permanentupperclass.com/llms.txt

Use this file to discover all available pages before exploring further.

​
What the oracle is

The oracle is a read-only, publicly accessible projection layer over the b1e55ed event store. It answers one question:
Does this signal producer have verifiable history?
It is designed for AI agents and external systems to query before acting on a producer’s signals.

​
The provenance endpoint

GET /api/v1/oracle/producers/{producer_id}/provenance
  • No authentication required
  • Includes an anti-Goodhart header on every response:
X-Attribution-Notice: Fields informational only. May change without notice. Optimizing against specific metrics triggers drift detection.
Example (managed oracle): 
curl -s \
  https://oracle.b1e55ed.permanentupperclass.com/api/v1/oracle/producers/alpha_signals_v2/provenance | jq

​
MCP tool: b1e55ed_provenance_check

Agents can call the oracle through the MCP JSON-RPC tool b1e55ed_provenance_check. Via POST /api/v1/mcp: 
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "b1e55ed_provenance_check",
    "arguments": {
      "producer_id": "alpha_signals_v2",
      "signal_type": "long_btc"
    }
  }
}

​
Enabling it on your node

Oracle routes are enabled automatically when b1e55ed starts. No additional configuration is required. Your local oracle endpoint is available at: 
curl -s http://127.0.0.1:5050/api/v1/oracle/producers/example/provenance | jq
No API key. No environment variables. If b1e55ed is running, the oracle is running.
The network-wide managed oracle is operated by Permanent Upper Class: 
oracle.b1e55ed.permanentupperclass.com
This is the oracle AI agents query by default. It aggregates provenance data across the network and handles contributor registration via the GitHub App. You do not need to run this yourself. Health check: 
curl -s https://oracle.b1e55ed.permanentupperclass.com/health

​
Self-hosted vs managed oracle

ManagedSelf-hosted
Who runs itPermanent Upper ClassYou
Setup requiredNoneExpose your API publicly (Tailscale or reverse proxy)
Contributor registration✅ Handled by PUC❌ Requires a GitHub App
Use caseDefault for all operatorsAir-gapped or sovereign deployments
For most operators, the managed oracle is the right choice. Your node feeds data into it automatically when you contribute signals.

​
Advanced: running your own public oracle

This is only necessary if you are operating a fully sovereign, air-gapped deployment or building an independent oracle network. The GitHub App key is only held by the oracle server operator (Permanent Upper Class for the managed network). Operators who run b1e55ed do not need this key.
To run a public oracle with contributor registration:
  1. Create a GitHub App with issues: write permission on your repository
  2. Download the private key (.pem)
  3. Set the environment variable on your oracle server:
export B1E55ED_GITHUB_APP_KEY="$(cat your-app.pem)"
If running under systemd, use an environment file: 
# /etc/b1e55ed/env
B1E55ED_GITHUB_APP_KEY=...
Then reference it in your service unit: 
[Service]
EnvironmentFile=/etc/b1e55ed/env
  1. Restart:
sudo systemctl restart b1e55ed.service