> ## 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.

# Oracle Setup

> Enable the b1e55ed provenance oracle: a public, no-auth endpoint for AI agents to verify signal producer track records before acting.

## 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

```text theme={null}
GET /api/v1/oracle/producers/{producer_id}/provenance
```

* **No authentication required**
* Includes an anti-Goodhart header on every response:

```text theme={null}
X-Attribution-Notice: Fields informational only. May change without notice. Optimizing against specific metrics triggers drift detection.
```

Example (managed oracle):

```bash theme={null}
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`:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```text theme={null}
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:

```bash theme={null}
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

<Warning>
  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.
</Warning>

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:

```bash theme={null}
export B1E55ED_GITHUB_APP_KEY="$(cat your-app.pem)"
```

If running under systemd, use an environment file:

```bash theme={null}
# /etc/b1e55ed/env
B1E55ED_GITHUB_APP_KEY=...
```

Then reference it in your service unit:

```ini theme={null}
[Service]
EnvironmentFile=/etc/b1e55ed/env
```

4. Restart:

```bash theme={null}
sudo systemctl restart b1e55ed.service
```