# Cashumints.space API – Full Overview

## Purpose
The Cashumints.space API is a public, read‑only observability, discovery, and reputation API for the Cashu mint ecosystem.

It exists to:
- Discover Cashu mints in a decentralized way
- Track availability, uptime, and incidents over time
- Fetch and keep mint metadata up to date using NUT‑06
- Ingest and expose Nostr‑based mint reviews (NIP‑87)
- Compute transparent and explainable trust scores
- Provide rich analytics and time‑series data for frontends and wallets

It explicitly does NOT:
- Custody funds
- Interact with wallets
- Simulate balances or volume
- Require authentication for read access

The API is infrastructure, not a wallet.

---

## Core Design Principles

1. History is never erased
All raw data is stored and aggregated later. Nothing is overwritten without keeping history.

2. Offline does not mean dead
Mints move through states: unknown → online → degraded → offline → abandoned. Recovery is always possible.

3. URL is not identity
Mint identity is stable even if URLs change. One mint can have multiple URLs.

4. Trust is derived, not asserted
Every trust signal is computed from stored data and exposed with a breakdown.

5. Self‑hostable by default
SQLite is the default database. PostgreSQL is optional. No Redis or external queues.

---

## High‑Level Architecture

### Layers

1. HTTP API
- Serves public read‑only endpoints
- Records pageviews
- Accepts mint submissions
- Enqueues background jobs

2. Database
- SQLite by default
- PostgreSQL optional
- Single source of truth for:
  - mints
  - mint URLs
  - probes
  - metadata snapshots and history
  - uptime rollups
  - incidents
  - reviews
  - trust scores
  - pageviews
  - jobs

3. Workers
- Stateless background processes
- Poll database for jobs
- Perform probes, aggregation, ingestion, scoring
- Never serve user traffic

---

## Mint Identity Model

### Mint
A mint is a logical entity identified internally by a stable `mint_id` (UUID).

### Mint URLs
A mint may expose multiple URLs:
- clearnet
- Tor (.onion)
- mirrors

URLs are aliases, not identities.

Any known URL resolves to the same mint_id.

---

## Mint Lifecycle

### Discovery
Mints are discovered via:
- Nostr review events (NIP‑87)
- User submissions
- Manual/admin additions
- Imports

Initial state: `unknown`

### Verification
After the first successful probe:
- Status becomes `online`
- Uptime tracking begins
- Metadata fetching is enabled

### Failure and Recovery
- Consecutive probe failures move the mint to `offline`
- Long‑term offline mints become `abandoned`
- A successful probe at any time revives the mint

---

## Status Model

Each mint is always in exactly one state:

- unknown: never successfully probed
- online: recently reachable
- degraded: reachable but unstable or slow
- offline: previously online, now unreachable
- abandoned: offline longer than configured threshold

---

## Probing and Uptime

- Probes are HTTP requests to mint endpoints
- Every probe stores a result, success or failure
- Probe frequency adapts to mint status
- Raw probe data is aggregated into uptime rollups

Rollup windows:
- 1 hour
- 24 hours
- 7 days
- 30 days

Each rollup stores:
- uptime percentage
- average and percentile RTT
- downtime duration
- incident count

---

## Metadata (NUT‑06)

- Fetched from `/info`
- Only fetched after a successful probe
- Fetched at most once per hour per mint
- Stored as a current snapshot
- All changes stored in history

Metadata includes:
- name
- pubkey
- version
- descriptions
- contact info
- MOTD
- icon_url (stored as URL only)
- supported NUTs
- advertised URLs
- TOS URL

---

## Nostr Reviews (NIP‑87)

- Ingested continuously from configured relays
- Raw events stored immutably
- Reviews linked to mints via URLs or identifiers
- Ratings and content parsed when present

Used for:
- Display
- Trust scoring
- Ecosystem analytics

---

## Trust Score

Each mint has a score from 0–100.

Derived from:
- Uptime reliability
- Response speed
- Review quantity and quality
- Metadata completeness
- Penalties for downtime and instability

Scores are:
- Computed asynchronously
- Stored with full breakdown
- Fully explainable

---

## Pageviews and Popularity

- Pageviews tracked per mint page
- Short‑lived session identifiers
- No raw IP storage

Aggregated metrics:
- views_24h / 7d / 30d
- unique sessions
- view velocity
- trending detection

Used as adoption proxies only.

---

## Database Philosophy

- Append raw data
- Derive aggregates
- Never delete history
- Always allow recomputation

---

## Intended Consumers

- Frontends (explorers, dashboards)
- Wallets (mint selection, warnings)
- Operators (transparency)

---

## One‑Sentence Summary

Cashumints.space is a decentralized, historical observability and reputation layer for the Cashu mint ecosystem.