# HODLXXI Read-Only [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/hodlxxi-read-only

## Description
Public read-only MCP server for HODLXXI agent identity, trust, receipts, and verification.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "hodlxxi-read-only": {
    "command": "npx",
    "args": ["-y","hodlxxi-read-only"]
  }
}
```

## Documentation & README

# Universal Bitcoin Identity Layer

[![pytest](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/actions/workflows/pytest.yml/badge.svg?branch=main)](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/actions/workflows/pytest.yml)
[![lint](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/actions/workflows/lint.yml)
[![security](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/actions/workflows/security.yml/badge.svg?branch=main)](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/actions/workflows/security.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

A production-focused Flask service that bridges OAuth2/OpenID Connect with Lightning Network authentication. The project couples hardened security defaults, Redis-backed rate limiting, RS256 JWT issuance, and Postgres persistence so Bitcoin-enabled applications can expose standards-compliant identity endpoints.

---

## 🚀 Highlights

- **Security-first OAuth2/OIDC core** – RS256 tokens with on-disk JWKS rotation, PKCE validation, HTTPS enforcement through `app.security`, and Redis-powered rate limiting with production fail-closed behavior and explicit non-production in-memory fallback warnings.
- **Lightning-aware identity workflows** – LNURL-auth challenge storage, Bitcoin signature verification helpers, and adapters that keep the legacy authorization views working while the storage layer matured.
- **Persistent storage** – SQLAlchemy models for OAuth clients/codes/tokens, sessions, LNURL challenges, proof-of-funds requests, and audit logs backed by Postgres with Redis coordination for ephemeral state.
- **Operational tooling** – `/metrics/prometheus` endpoint, structured JSON logging, and a reusable `create_app()` factory (`app/factory.py`) for factory-based deployments.
- **Typed configuration surface** – Environment-driven configuration validated by `app.config`, including production guardrails for secrets, Redis, and database connectivity.

---

## 🏗️ Architecture at a Glance

| Layer | Key Modules | Responsibilities |
| --- | --- | --- |
| Web application | [`app/app.py`](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/app/app.py), [`app/factory.py`](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/app/factory.py) | Flask application, OAuth2/LNURL routes, Prometheus metrics, Socket.IO events, plus the factory-based app initialization |
| Security | [`app/security.py`](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/app/security.py) | Proxy/header fixes, HTTPS enforcement, Flask-Limiter setup, logging defaults |
| Identity tokens | [`app/tokens.py`](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/app/tokens.py), [`app/jwks.py`](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/app/jwks.py) | RS256 JWT issuance, keypair persistence, JWKS publication |
| Storage | [`app/db_storage.py`](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/app/db_storage.py), [`app/database.py`](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/app/database.py), [`app/storage.py`](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/app/storage.py) | Postgres session helpers, Redis utilities, and in-memory parity for tests |
| Configuration | [`app/config.py`](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/app/config.py) | Typed env loader, production validation helpers |
| Observability | [`app/app.py`](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/app/app.py), [`deployment/README.md`](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/deployment/README.md) | Prometheus counter wiring and deployment guidance |

Further documentation lives in the [`app/`](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/app/README.md) directory and supporting deployment guides under [`deployment/`](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/deployment/README.md).

---

## 🧰 Prerequisites

- Python 3.10+
- Postgres 13+
- Redis 6+
- Bitcoin Core 24+ (for RPC-backed features)

For local development you can omit Postgres/Redis by exporting `DATABASE_URL` and `REDIS_URL` pointing to ephemeral services (e.g. docker-compose) or by relying on the in-memory storage adapter for tests.

---

## 🏁 Quick Start

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export FLASK_APP=app.app:app
export FLASK_ENV=development
export RPC_USER=bitcoinrpc
export RPC_PASSWORD=change-me
flask run
```

The service exposes:

- `/.well-known/openid-configuration`, `/oauth/token`, `/oauth/authorize`

For third-party login setup, see [Sign in with HODLXXI Integration Guide](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/docs/OIDC_INTEGRATION.md).

- `/.well-known/agent.json`, `/agent/capabilities`, `/agent/capabilities/schema`
- `/agent/skills`, `/agent/marketplace/listing`, `/agent/reputation`, `/agent/attestations`
- `/lnurl/auth` LNURL challenge endpoints
- `/metrics/prometheus` for Prometheus scrapers
- `/health` basic liveness probe

### Docker Compose quick start

If you want a production-like stack without installing Postgres/Redis/Bitcoin Core locally, use the bundled Compose file:

```bash
cp env.example .env
docker compose up --build
```

The Postgres, Redis, and Bitcoin services wait for health checks before the Flask app starts. Mounts for `./app`, `./logs`, and `./keys` ensure code edits and generated keys persist on the host. See `docs/DEV_ONBOARDING_CHECKLIST.md` for the full onboarding flow and smoke tests.

See [`TESTING.md`](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/TESTING.md) for pytest, mypy, and linting guidance.

---

## ⚙️ Configuration Reference

`app/config.py` documents every supported environment variable. Highlights include:

- `JWT_ALGORITHM=RS256` to force asymmetric signing; JWKS files are stored in `JWKS_DIR`.
- `RATE_LIMIT_ENABLED` / `RATE_LIMIT_DEFAULT` for limiter tuning.
- `DATABASE_URL` or discrete `DB_*` variables for SQLAlchemy.
- `REDIS_URL`/`REDIS_*` for rate limiting and challenge/session TTL handling.
- `SOCKETIO_ASYNC_MODE` to pick a compatible backend (defaults to `eventlet` when available, otherwise falls back to `threading`).
- `FORCE_HTTPS`, `SECURE_COOKIES`, and `CSRF_ENABLED` for deployment hardening.

Run `python -m app.config` (or import `validate_config`) inside your deployment pipeline to fail fast on insecure production settings.

---

## 🧪 Testing

```bash
pytest
```

Unit tests cover configuration parsing/validation along with storage adapters. Integration tests spin up the in-memory backend to exercise OAuth and LNURL flows without external services.

---

## Product Positioning

- [Runtime Product Positioning](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/docs/RUNTIME_PRODUCT_POSITIONING.md) - current product framing: HODLXXI as a Bitcoin-native trust runtime for public-key agents and services.

## Agent Readiness

- [HODLXXI Readiness Evaluation](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/docs/READINESS_EVALUATION.md) - current external evaluation path for public agent/runtime readiness.
- [HODLXXI External Reviewer Packet](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/docs/EXTERNAL_REVIEWER_PACKET.md) - canonical public review packet for live reviewers, developers, investors, agent marketplace reviewers, and technical evaluators.
- [Agent Readiness Report v1](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/docs/AGENT_READINESS_REPORT_V1.md) - contract for public agent/service readiness reports backed by receipts and attestations.
- `GET /agent/readiness/self-scan` - public machine-readable self-scan report for the current HODLXXI runtime. It returns `schema`, `summary`, `checks`, `verification`, `report_sha256`, and current `receipt` / `attestation` status.

## Developer Quickstarts

- [Agent Receipt Quickstart](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/docs/AGENT_RECEIPT_QUICKSTART.md) — external developer flow: discovery, paid job request, polling, receipt verification, attestations, and reputation.

## 🤖 Agent, Skills, and Marketplace Discovery

The repository now exposes a coherent machine-readable agent surface:

- `/.well-known/agent.json` for the public identity/discovery document
- `/agent/capabilities` for the signed capabilities handshake
- `/agent/capabilities/schema` for the canonical JSON Schema of that handshake
- `/agent/skills` for first-class skill discovery sourced from `skills/public/`
- `/agent/marketplace/listing` for normalized directory/marketplace ingestion

For the protocol and trust model, see:

- [`docs/DOCUMENTATION_MAP.md`](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/docs/DOCUMENTATION_MAP.md) explains which docs are current, historical, experimental, or archive candidates.
- [`AGENT_PROTOCOL.md`](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/AGENT_PROTOCOL.md) for the signed discovery and job protocol
- [`TRUST_MODEL.md`](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/TRUST_MODEL.md) for the normative trust language and verification boundaries
- [`docs/AGENT_SURFACES.md`](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/docs/AGENT_SURFACES.md) for how the runtime discovery endpoints expose those claims

The current agent surface is intentionally conservative: it exposes public-key identity, declared operator metadata, paid execution, signed receipts, and observable history, while treating time-locked capital and on-chain backing as optional trust anchors rather than verified runtime facts.


### Python SDK for agents

Developers can start from the SDK index:

- `docs/sdk/README.md`

The SDK covers:

- public discovery and agent job requests
- Bitcoin-message auth challenge flow
- Nostr auth challenge flow
- receipt helpers
- signing helpers with caller-provided signers

Examples:

- `examples/python/ping_agent.py`
- `examples/python/auth_challenge_flow.py`
- `examples/python/nostr_auth_challenge_flow.py`

The SDK does not hold private keys. Applications bring their own wallet, hardware, Bitcoin Core, Nostr, or agent-runtime signer.

---

## 🤝 Contributing

1. Fork the repository and create a virtual environment.
2. Install dev dependencies with `pip install -r requirements-dev.txt`.
3. Run `pytest` before opening a pull request.
4. Follow the [code of conduct](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/CODE_OF_CONDUCT.md) and [contribution guidelines](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/CONTRIBUTING.md).

Bug reports and feature proposals are welcome via [GitHub Issues](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/issues).

---

## 📄 License

Released under the [MIT License](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/blob/HEAD/LICENSE).

### Production readiness artifact storage

Persisted readiness self-scan reports are runtime artifacts, not source files.
For hardened production deployments, set:

```text
AGENT_READINESS_REPORT_DIR=/srv/ubid/runtime/agent_readiness_reports
```

For `hodlxxi.service`, this path should live under the writable runtime area and be owned by the service user.