API Reference

Base URL:    https://rugmunch.io/api/v1
Spec:        /openapi.json on this site (snapshot, 835 routes, captured 2026-08-24)
Interactive: /docs (Swagger) and /redoc on the API host

Authentication

Two systems coexist. Use the auth service (/api/auth) for new integrations — the backend-native /api/v1/auth routes are legacy.

Auth service (better-auth) — https://rugmunch.io/api/auth

Endpoint	Purpose
POST /api/auth/sign-up/email	Register with email + password
POST /api/auth/sign-in/email	Login — returns session token/cookie
GET /api/auth/get-session	Current session (returns null when anonymous)

curl -X POST https://rugmunch.io/api/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

The web app uses this path exclusively; wallet sign-in flows through the same service (OAuth: Google/GitHub/X + wallet linking on the legacy surface).

Legacy backend auth — /api/v1/auth (maintenance mode)

Still served (JWT bearer), kept for existing clients: register, login, logout, me, change-password, cookie-token, jwks, 2FA (setup/enable/verify/login), OAuth (google/github/x url+callback), wallet linking, delete-account.

Per-request auth

Method	Header	Used for
Session/Bearer token	Authorization: Bearer <token>	User-facing API
API key	X-API-Key: <key>	Service-to-service
x402 proof	X-PAYMENT: <signed-proof>	Pay-per-call tools
Client fingerprint	X-Client-ID: <id>	Trial-gated anonymous calls

Core platform endpoints

Endpoint	Purpose
GET /health, GET /live, GET /ready, GET /version	Health & liveness
GET /.well-known/x402	x402 payment discovery
GET /mcp/tools, GET /mcp/info	MCP server discovery
GET /api/v1/catalog/stats	Platform data stats
GET /api/v1/databus/health	DataBus provider health

Errors — RFC 7807 Problem Details

{
  "type": "https://rugmunch.io/errors/invalid-token",
  "title": "Invalid authentication token",
  "status": 401,
  "detail": "JWT expired or malformed",
  "instance": "/api/v1/token/scan"
}

Status	Meaning
400	Validation failed
401	Missing/expired credentials
402	x402 payment required — quote in response, see x402 Payments
403	Insufficient tier
405	Wrong HTTP method for this route
429	Rate limit exceeded
500	Unexpected server error

Data-vs-success

Data endpoints return 200 with {"data": null, "reason": "no_data", "sources_tried": [...]} when upstreams have no data. Check reason — HTTP 200 does not guarantee data. Empty paid results are refundable.

Response headers

Header	Meaning
X-Request-ID	Correlation id for support
X-Response-Time-Ms	Server processing time
X-RateLimit-Limit / -Remaining / -Reset	Rate limit state
X-Degraded-Stores	Upstream providers currently failing over
Deprecation / Sunset	Legacy route warnings

Rate limits

Tier	Rate	Daily cap	Auth
Anonymous	10 req/min	trial-gated	fingerprint
Free	10 req/min	100/day	session or API key
Pro	60 req/min	10,000/day	session
Enterprise	custom	custom	custom

x402-paid calls are metered by payment, not by these caps.

Route families (835 routes in the snapshot)

Prefix	Count	What lives there
/api/v1/databus/*	108	DataBus core (free + premium)
/api/v1/x402-tools/*	77	Per-tool security/intel scanners
/api/v1/x402-databus/*	39	Paid DataBus endpoints (wallets, markets, RAG)
/api/v1/x402/*	30	Payment gateway (pricing, invoices, webhooks)
/api/v2/scanner/*	9	Scanner v2 (async multi-engine)
/api/v1/rugmaps/*	12	Maps, entities, fund flows
/api/v1/rugcharts/*	9	Charts, signals, TA
/api/v1/wallet-clusters/*	8	Cluster detection & funding paths
/api/v1/auth/*	25	Legacy auth (better-auth /api/auth preferred)
/api/v1/catalog/*	10	Token/wallet catalog + RAG search
/mcp/*	5	MCP server

Full machine-readable spec: openapi.json (OpenAPI 3.1, captured from the live API on 2026-08-24). Programmatic clients should codegen from this file.