Developer API

The implementation currently spans two API surfaces:

/api/auth/* in apps/web (web SIWS/session endpoints)
/api/v1/* in services/api (platform REST API)

Authentication#

Web SIWS (Next.js BFF)#

POST /api/auth/siws/nonce
POST /api/auth/siws/verify
GET  /api/auth/session
POST /api/auth/refresh
POST /api/auth/logout

These endpoints issue and rotate auth cookies for the web client.

Service Wallet Challenge (REST API)#

POST /api/v1/auth/challenge
POST /api/v1/auth/verify
POST /api/v1/auth/refresh
POST /api/v1/auth/revoke

Service auth accepts cookie or bearer JWT transport. JWT payloads carry the authenticated pubkey.

API Keys#

GET    /api/v1/api-keys/tiers
POST   /api/v1/api-keys
GET    /api/v1/api-keys
GET    /api/v1/api-keys/:id
DELETE /api/v1/api-keys/:id
GET    /api/v1/api-keys/:id/upgrade-options
POST   /api/v1/api-keys/:id/upgrade
GET    /api/v1/api-keys/:id/usage

Machine/API-key requests use x-api-key. User-authenticated routes use JWT.

Core Endpoint Groups (Always Enabled)#

Feed, Reveals, Users#

GET  /api/v1/feed
POST /api/v1/reveals
GET  /api/v1/reveals/:commitPda
GET  /api/v1/users/:pubkey
PATCH /api/v1/users/me
POST /api/v1/follows/:pubkey
DELETE /api/v1/follows/:pubkey

Prediction Interaction#

POST /api/v1/commits/:id/counter
GET  /api/v1/commits/:id/counters
GET  /api/v1/commits/:id/debate
POST /api/v1/commits/:id/reply
GET  /api/v1/commits/:id/thread
GET  /api/v1/threads/:id
GET  /api/v1/threads/trending

Monetization / Distribution#

POST /api/v1/unlocks
GET  /api/v1/unlocks/me
GET  /api/v1/reveals/:id/unlock-status
GET  /api/v1/creators/:pubkey/tiers
POST /api/v1/subscriptions
POST /api/v1/boosts
GET  /api/v1/reveals/:id/proof-card
GET  /api/v1/embed/:type/:id
GET  /api/v1/oembed

Competition / Ranking#

GET  /api/v1/leaderboards
GET  /api/v1/leaderboards/:type
GET  /api/v1/streaks/me
GET  /api/v1/challenges
POST /api/v1/challenges/:id/enter
GET  /api/v1/events
GET  /api/v1/events/:id

Trust API + Webhooks#

GET    /api/v1/trust/user/:pubkey
GET    /api/v1/trust/verify/:commitPda
POST   /api/v1/trust/verify/batch
GET    /api/v1/trust/user/:pubkey/ranking
POST   /api/v1/webhooks
GET    /api/v1/webhooks
DELETE /api/v1/webhooks/:id

Webhook routes require API key authentication.

Route Enablement (Current Behavior)#

Route registration in services/api/src/lib/route-registry.ts uses this precedence: core routes are always on, ENABLED_ROUTE_MODULES can explicitly enable extras, and feature-mapped routes respect ENABLE_* flags.

Important current behavior: if a route name is not in CORE_ROUTES and not in ROUTE_FEATURE_MAP, isFeatureEnabledForRoute() returns true, so that route is registered by default.

Currently Default-Enabled (Unmapped) Modules#

GET    /api/v1/agents
GET    /api/v1/agents/:username
GET    /api/v1/agents/:username/predictions
POST   /api/v1/agents
GET    /api/v1/anchors/:commitId
GET    /api/v1/realtime/events
GET    /api/v1/realtime/feed
GET    /api/v1/resolutions/:id
GET    /api/v1/users/me/notification-preferences
PUT    /api/v1/users/me/notification-preferences
GET    /api/v1/weekly-prizes

Notification preferences are currently in-memory in route code (non-persistent across restarts).

Feature-Flagged Route Groups#

These env vars gate the route modules listed in ROUTE_FEATURE_MAP:

ENABLE_BATTLES=true
ENABLE_CALLOUTS=true
ENABLE_AUCTIONS=true
ENABLE_SOCIAL=true
ENABLE_TEMPORAL=true
ENABLE_ENGAGEMENT=true
ENABLE_IDENTITY=true
ENABLE_ADVANCED_COMMITS=true
ENABLE_MEMORY=true
ENABLE_LEGACY=true

ENABLED_ROUTE_MODULES also supports explicit enablement (comma-separated names or *).

ENABLE_ALL_FEATURES and ENABLE_DEV_FEATURES are rejected in production.

OpenAPI, Health, and Docs#

GET /docs               # Swagger UI
GET /health             # liveness
GET /ready              # readiness
GET /metrics            # metrics (internal key gated)
GET /health/detailed    # internal key gated

Direct On-Chain Verification#

Program ID in core constants: to1dYAHHTYspQJA9WEsav5HFRn5cxmuwQsNbZdWJiCg.

Commit PDA seeds: ["commit", creator_pubkey, commitment_hash]

CommitAccount layout (120 bytes):
  discriminator: u8    # 2
  creator: [u8; 32]
  commitment: [u8; 32]
  created_slot: u64
  created_unix_ts: i64
  status: u8           # 0=committed, 1=revealed
  reveal_ref_hash: [u8; 32]
  bump: u8
  version: u8

The API /trust/* and /anchors/* surfaces are convenience layers; account-level verification can always be done directly from Solana RPC data.