# Hyperion

**Hyperion is the App Store for AI agents.** A hosted marketplace where developers publish MCP
servers/tools and agents discover, subscribe to, and call them entirely programmatically — no human
in the loop. Discovery is MCP-native, access is via programmatically-issued API keys, and billing is
Bitcoin pay-per-call / subscription settled through BTCPay. The primary customer is an agent, not a
person: an agent finds a tool, pays for a meter in sats, gets a key, and calls it.

## What it is

A single-file Flask service. Dark premium UI. Simple auth (username + password, no KYC).
Bitcoin-settled subscription via BTCPay, with API keys issued programmatically at signup.

### Feature overview

- **MCP-native catalog** — the index itself is an MCP server + JSON API; agents query it, resolve a
  tool, get metered, and open a stream under a signed API key.
- **Programmatic API keys** — keys are handed to an agent the moment it registers (username + password
  only, no KYC).
- **Bitcoin settlement** — Pro subscriptions ($19/mo) and metered calls are paid in BTC through
  BTCPay. No card, no KYC.
- **Free tier** — catalog discovery + 100 metered calls/month + a programmatic API key.
- **Pro tier** — unlimited discovery, 10,000 metered calls/month, priority routing, and webhook /
  metering exports. Publisher side carries a 20% platform fee, settled in BTC.

## How to run it

```bash
# 1. Install dependencies (Python 3)
pip3 install flask requests werkzeug

# 2. Run the service
python3 app.py
```

The service binds to `0.0.0.0:5000`. A BTCPay webhook posts to `/webhook/btcpay` to mark invoices paid.

## Configuration (environment variables)

All BTCPay values are overridable via env vars; sensible defaults are baked in.

| Variable                | Purpose                                    |
| ----------------------- | ------------------------------------------ |
| `HYPERION_BTCPAY_URL`   | Base URL of the BTCPay instance            |
| `HYPERION_BTCPAY_STORE` | BTCPay store ID                            |
| `HYPERION_BTCPAY_KEY`   | BTCPay API key                             |
| `HYPERION_BTCPAY_WALLET`| xpub (extended public key) of the wallet   |
| `HYPERION_SECRET`       | Flask session secret (random if unset)     |

Example:

```bash
HYPERION_BTCPAY_URL=https://btcpay.example \
HYPERION_BTCPAY_STORE=<store-id> \
HYPERION_BTCPAY_KEY=<api-key> \
HYPERION_BTCPAY_WALLET=<xpub> \
python3 app.py
```

## Files

- `app.py` — the entire application (Flask app, UI, auth, BTCPay integration).
- `LICENSE` — MIT License.

## API surface

- `/` — landing page (MCP-native catalog pitch).
- `/pricing` — Free vs. Pro pricing.
- `/register`, `/login`, `/logout` — auth.
- `/dashboard` — agent dashboard: API key, metered-call counter, Pro subscription via BTCPay.
- `/about`, `/health` — meta endpoints.
- `/api/...` — JSON routes authorized by the agent's API key.
- `/webhook/btcpay` — BTCPay payment webhook (marks invoices paid, activates Pro).

## License

MIT. See `LICENSE`.