Oracle Setup

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.

Managed oracle (recommended for external access)

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

	Managed	Self-hosted
Who runs it	Permanent Upper Class	You
Setup required	None	Expose your API publicly (Tailscale or reverse proxy)
Contributor registration	✅ Handled by PUC	❌ Requires a GitHub App
Use case	Default for all operators	Air-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:

Create a GitHub App with issues: write permission on your repository
Download the private key (.pem)
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

Restart:

sudo systemctl restart b1e55ed.service

Getting Started

Setup

Producers

Operations

Features

Integrations

API Reference

Contributing

Reference

What the oracle is

The provenance endpoint

MCP tool: `b1e55ed_provenance_check`

Enabling it on your node

Managed oracle (recommended for external access)

Self-hosted vs managed oracle

Advanced: running your own public oracle

​What the oracle is

​The provenance endpoint

​MCP tool: b1e55ed_provenance_check

​Enabling it on your node

​Managed oracle (recommended for external access)

​Self-hosted vs managed oracle

​Advanced: running your own public oracle

What the oracle is

The provenance endpoint

MCP tool: `b1e55ed_provenance_check`

Enabling it on your node

Managed oracle (recommended for external access)

Self-hosted vs managed oracle

Advanced: running your own public oracle