# Cashumints.space API – Endpoints

All endpoints are read‑only unless stated otherwise.
All timestamps are ISO‑8601 UTC.
All mint‑specific endpoints accept either a mint ID or a mint URL.

---

## Resolution Rules

Endpoints support:
- `/mints/{mint_id}`
- `/mints/by-url?url=...`

The API resolves URLs to the canonical mint_id internally.

---

## Single Mint – Core

GET /mints/{mint_id}
GET /mints/by-url?url=

Returns:
- mint_id
- canonical_url
- urls[]
- name
- icon_url
- status
- offline_since
- last_success_at
- last_failure_at
- uptime_24h
- uptime_7d
- uptime_30d
- incidents_7d
- incidents_30d
- trust_score
- trust_level

---

## Mint URLs

GET /mints/{mint_id}/urls
GET /mints/by-url/urls?url=

Returns:
- canonical_url
- urls[]:
  - url
  - type (clearnet | tor | mirror)
  - active

---

## Metadata (NUT‑06)

GET /mints/{mint_id}/metadata
GET /mints/by-url/metadata?url=

Returns:
- name
- pubkey
- version
- description
- description_long
- contact
- motd
- icon_url
- urls
- tos_url
- nuts
- server_time
- last_fetched_at

---

GET /mints/{mint_id}/metadata/history
GET /mints/by-url/metadata/history?url=

Returns:
- fetched_at
- change_type
- diff
- version

---

## Status (Lightweight)

GET /mints/{mint_id}/status
GET /mints/by-url/status?url=

Returns:
- status
- offline_since
- last_checked_at
- current_rtt_ms

---

## Uptime & Reliability

GET /mints/{mint_id}/uptime
GET /mints/by-url/uptime?url=

Query:
- window=24h | 7d | 30d

Returns:
- uptime_pct
- downtime_seconds
- avg_rtt_ms
- p95_rtt_ms
- total_checks
- ok_checks

---

GET /mints/{mint_id}/uptime/timeseries
GET /mints/by-url/uptime/timeseries?url=

Query:
- window=24h | 7d | 30d
- bucket=5m | 15m | 1h

Returns:
- timestamp
- state
- ok
- rtt_ms

---

## Incidents

GET /mints/{mint_id}/incidents
GET /mints/by-url/incidents?url=

Returns:
- started_at
- resolved_at
- duration_seconds
- severity

---

## Trust

GET /mints/{mint_id}/trust
GET /mints/by-url/trust?url=

Returns:
- score_total
- score_level
- breakdown
- computed_at

---

## Reviews (Nostr)

GET /mints/{mint_id}/reviews
GET /mints/by-url/reviews?url=

Returns:
- event_id
- pubkey
- created_at
- rating
- content

---

## Popularity

GET /mints/{mint_id}/views
GET /mints/by-url/views?url=

Returns:
- views_24h
- views_7d
- views_30d
- unique_sessions_30d
- view_velocity

---

## Derived Features

GET /mints/{mint_id}/features
GET /mints/by-url/features?url=

Returns:
- supported_nuts
- supports_bolt11
- min_amount
- max_amount
- has_tor_endpoint
- has_multiple_urls
- feature_completeness_score

---

## Submission

POST /mints/submit

Body:
- mint_url

Returns:
- mint_id
- status
- message

---

## Health & Stats

GET /health
GET /stats