230 lines
2.8 KiB
Markdown
230 lines
2.8 KiB
Markdown
# Cashumints.space API – Endpoints
|
||
|
||
Base path:
|
||
|
||
/v1
|
||
|
||
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:
|
||
- `/v1/mints/{mint_id}`
|
||
- `/v1/mints/by-url?url=...`
|
||
|
||
The API resolves URLs to the canonical mint_id internally.
|
||
|
||
---
|
||
|
||
## Single Mint – Core
|
||
|
||
GET /v1/mints/{mint_id}
|
||
GET /v1/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 /v1/mints/{mint_id}/urls
|
||
GET /v1/mints/by-url/urls?url=
|
||
|
||
Returns:
|
||
- canonical_url
|
||
- urls[]:
|
||
- url
|
||
- type (clearnet | tor | mirror)
|
||
- active
|
||
|
||
---
|
||
|
||
## Metadata (NUT‑06)
|
||
|
||
GET /v1/mints/{mint_id}/metadata
|
||
GET /v1/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 /v1/mints/{mint_id}/metadata/history
|
||
GET /v1/mints/by-url/metadata/history?url=
|
||
|
||
Returns:
|
||
- fetched_at
|
||
- change_type
|
||
- diff
|
||
- version
|
||
|
||
---
|
||
|
||
## Status (Lightweight)
|
||
|
||
GET /v1/mints/{mint_id}/status
|
||
GET /v1/mints/by-url/status?url=
|
||
|
||
Returns:
|
||
- status
|
||
- offline_since
|
||
- last_checked_at
|
||
- current_rtt_ms
|
||
|
||
---
|
||
|
||
## Uptime & Reliability
|
||
|
||
GET /v1/mints/{mint_id}/uptime
|
||
GET /v1/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 /v1/mints/{mint_id}/uptime/timeseries
|
||
GET /v1/mints/by-url/uptime/timeseries?url=
|
||
|
||
Query:
|
||
- window=24h | 7d | 30d
|
||
- bucket=5m | 15m | 1h
|
||
|
||
Returns:
|
||
- timestamp
|
||
- state
|
||
- ok
|
||
- rtt_ms
|
||
|
||
---
|
||
|
||
## Incidents
|
||
|
||
GET /v1/mints/{mint_id}/incidents
|
||
GET /v1/mints/by-url/incidents?url=
|
||
|
||
Returns:
|
||
- started_at
|
||
- resolved_at
|
||
- duration_seconds
|
||
- severity
|
||
|
||
---
|
||
|
||
## Trust
|
||
|
||
GET /v1/mints/{mint_id}/trust
|
||
GET /v1/mints/by-url/trust?url=
|
||
|
||
Returns:
|
||
- score_total
|
||
- score_level
|
||
- breakdown
|
||
- computed_at
|
||
|
||
---
|
||
|
||
## Reviews (Nostr)
|
||
|
||
GET /v1/mints/{mint_id}/reviews
|
||
GET /v1/mints/by-url/reviews?url=
|
||
|
||
Returns:
|
||
- event_id
|
||
- pubkey
|
||
- created_at
|
||
- rating
|
||
- content
|
||
|
||
---
|
||
|
||
## Popularity
|
||
|
||
GET /v1/mints/{mint_id}/views
|
||
GET /v1/mints/by-url/views?url=
|
||
|
||
Returns:
|
||
- views_24h
|
||
- views_7d
|
||
- views_30d
|
||
- unique_sessions_30d
|
||
- view_velocity
|
||
|
||
---
|
||
|
||
## Derived Features
|
||
|
||
GET /v1/mints/{mint_id}/features
|
||
GET /v1/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 /v1/mints/submit
|
||
|
||
Body:
|
||
- mint_url
|
||
|
||
Returns:
|
||
- mint_id
|
||
- status
|
||
- message
|
||
|
||
---
|
||
|
||
## Health & Stats
|
||
|
||
GET /v1/health
|
||
GET /v1/stats
|
||
|