Log inGet started
API reference · v0.4

Every endpoint.

One row per endpoint, grouped by domain. Auth tags tell you what you need to call it. Status badges show what's live vs. planned.

✓ 48 shipped⏱ 13 on roadmap61 total
Auth & sessionWallet (Solana)Gigs (KOL services)Orders & escrowSignals (trading ideas)Hubs (paid communities)Campaigns (multi-KOL)Chat & messagesReviewsNotificationsAdminX (Twitter) integrationSearch & discoveryTelegram bot (@kolhubwatcherbot)Spec & healthraw JSON ↗

Auth & session

Email/password signup with scrypt hashing, httpOnly cookie sessions, 30-day expiry.

POST
/api/auth/signup
Create account + auto-login
body: email, password, name, handle, role
publicshipped
POST
/api/auth/login
Verify password, set session cookie
body: email, password
publicshipped
POST
/api/auth/logout
Invalidate session row + clear cookie
sessionshipped
GET
/api/me
Return current signed-in user (no passwordHash)
sessionshipped
PATCH
/api/me/update
Update name / bio / avatarUrl
body: name?, bio?, avatarUrl?
sessionshipped
POST
/api/auth/forgot
Send password-reset email via Resend (no enumeration)
body: email
publicshipped
POST
/api/auth/reset
Verify token, set new password, auto-login
body: token, password
publicshipped

Wallet (Solana)

Phantom wallet connect via signed nonce challenge. Server verifies ed25519 signature.

POST
/api/wallet/link/nonce
Issue a one-time nonce to sign
sessionshipped
POST
/api/wallet/link
Verify signature + bind walletAddr to user
body: walletAddr, signature, nonce
sessionshipped
DELETE
/api/wallet/link
Unlink wallet from account
sessionplanned

Gigs (KOL services)

KOL-listed promotional services. POST creates a gig, orders are tracked separately.

GET
/api/gigs
List open gigs (filterable)
query: q?, niche?, seller?, limit?
publicshipped
POST
/api/gigs
Create a gig
body: title, description, priceCents, deliveryDays, niche?
KOL/ADMINshipped
GET
/api/gigs/[id]
Get gig + seller + recent orders
publicshipped
PATCH
/api/gigs/[id]
Update fields (own gig only)
KOL/ADMINshipped
DELETE
/api/gigs/[id]
Soft-cancel (with orders) or hard-delete (no orders)
KOL/ADMINshipped

Orders & escrow

Project places order → mock USDC lock → KOL delivers → project releases. State machine enforced server-side.

GET
/api/orders
List orders for the signed-in user
query: as=buyer|seller
sessionshipped
POST
/api/orders
Place order, lock mock USDC escrow, notify seller
body: gigId
PROJECT/ADMINshipped
GET
/api/orders/[id]
Get one order (buyer/seller/admin only)
sessionshipped
PATCH
/api/orders/[id]
Transition: DELIVERED / RELEASED / DISPUTED / CANCELED with role checks
body: status, deliveryUrl?
sessionshipped
POST
/api/escrow/fund
Real Solana SPL token transfer to escrow PDA
sessionv1.5
POST
/api/escrow/release
Release on-chain escrow to seller
sessionv1.5

Signals (trading ideas)

LONG/SHORT signals with TP/SL. Auto-settled by Pyth Hermes on cron.

GET
/api/signals
List signals
query: status?, side?, author?, q?
publicshipped
POST
/api/signals
Publish signal (validates R:R direction)
body: asset, side, entry, takeProfit, stopLoss, rationale?
KOL/ADMINshipped
GET
/api/signals/[id]
Get signal + author
publicshipped
PATCH
/api/signals/[id]
Owner can edit rationale or status
KOL/ADMINshipped
POST
/api/signals/[id]/settle
Manual settle (owner/admin only)
body: outcome: TP_HIT|SL_HIT|EXPIRED
KOL/ADMINshipped
POST
/api/cron/settle-signals
Auto-settle ACTIVE signals via Pyth Hermes
cronshipped

Hubs (paid communities)

KOL-run subscription Hubs with up to 3 tiers. Tier-gated post feed.

GET
/api/hubs
List hubs ordered by member count
query: q?, niche?, limit?
publicshipped
POST
/api/hubs
Create a Hub with tier prices
body: slug, name, tagline?, description?, niches[], tier1Price?, tier2Price?, tier3Price?
KOL/ADMINshipped
GET
/api/hubs/[slug]
Get hub + owner
publicshipped
PATCH
/api/hubs/[slug]
Update hub (owner only)
KOL/ADMINshipped
POST
/api/hubs/[slug]/subscribe
Subscribe at tier (mock USDC). Upgrade/downgrade re-uses row.
body: tier: T1|T2|T3
sessionshipped
DELETE
/api/hubs/[slug]/subscribe
Cancel subscription (decrements memberCount)
sessionshipped
GET
/api/hubs/[slug]/posts
List posts visible at viewer's tier
publicshipped
POST
/api/hubs/[slug]/posts
Owner posts to feed (with minTier gate)
body: body, minTier?
KOL/ADMINshipped

Campaigns (multi-KOL)

Project-led campaigns with N slots. Each slot is its own escrow.

GET
/api/campaigns
List OPEN/IN_PROGRESS campaigns
query: owner?
publicshipped
POST
/api/campaigns
Create campaign + slots in one transaction
body: title, description, slots: [{title, niche?, priceCents, deliveryDays?}, ...]
PROJECT/ADMINshipped
GET
/api/campaigns/[id]
Get campaign + slots + applicants
publicshipped
PATCH
/api/campaigns/[id]
Owner: edit fields or close/cancel
PROJECT/ADMINshipped
POST
/api/campaigns/[id]/slots/[slotId]
Slot state machine: apply/accept/reject/deliver/release/cancel
body: action: apply|accept|reject|deliver|release|cancel, deliveryUrl? (deliver)
sessionshipped

Chat & messages

1:1 conversations with 4-second polling. SSE upgrade planned.

GET
/api/conversations
List threads with last message + other party
sessionshipped
POST
/api/conversations
Get-or-create 1:1 with another user
body: handle
sessionshipped
GET
/api/conversations/[id]/messages
Fetch thread, marks read for me
query: since?
sessionshipped
POST
/api/conversations/[id]/messages
Send message (coalesces notifs to recipient at 60s)
body: body
sessionshipped
GET
/api/conversations/[id]/stream
Server-Sent Events for live messages
sessionv1.5

Reviews

Reviews are gated to users with at least one RELEASED order between them.

POST
/api/reviews
Leave 1–5★ review on a counterparty
body: handle, rating, body?
sessionshipped
GET
/api/reviews
List reviews for a user
query: handle, kind=received|left
publicplanned

Notifications

In-app bell, polled every 30s. Auto-fired by every transactional event.

GET
/api/notifications
Last 30 + unread count
sessionshipped
POST
/api/notifications
Mark all read
sessionshipped
POST
/api/notifications/email
Cron: send digest email for unread > 24h
cronplanned

Admin

ADMIN-only platform overrides + reporting.

PATCH
/api/admin/users/[id]
Verify/unverify user, change role
body: verified?, role?
ADMINshipped
POST
/api/admin/orders/[id]/force
Force-resolve disputed order
ADMINplanned
GET
/api/admin/stats
Platform KPIs JSON for dashboard
ADMINplanned
POST
/api/admin/users/[id]/ban
Ban a user (revokes sessions)
ADMINplanned

X (Twitter) integration

OAuth claim verification + post snapshot capture for delivery proofs.

GET
/api/x/oauth/start
Begin X OAuth flow, store state cookie
sessionv1.5
GET
/api/x/oauth/callback
Exchange code, store X user id, mark handle verified
sessionv1.5
POST
/api/x/snapshot
Capture post text+metrics at submission/24h/7d
body: url, orderId|slotId
sessionv1.5

Search & discovery

Cross-entity search across users, gigs, hubs, signals, campaigns.

GET
/api/search
Aggregated search across the platform
query: q, kinds?
publicplanned

Telegram bot (@kolhubwatcherbot)

Posts every gig, signal, campaign, order, subscription, and signal-settlement event to a Telegram group. Bot token + chat IDs set via Railway env vars.

POST
/api/dev/telegram-test
Send a test message from the dev console
body: channel?: 'public'|'admin', text?: string
ADMINshipped

Spec & health

Self-describing API spec + uptime check.

GET
/api/openapi
API_GROUPS as JSON for tooling
publicshipped
GET
/api/health
DB ping + email/pyth status (for uptime monitors)
publicshipped

Calling from JavaScript

Sessions are httpOnly cookies — `fetch` from the same origin includes them automatically. From a different origin set `credentials: 'include'`.

// Login (cookie set automatically)
await fetch("/api/auth/login", {
  method: "POST",
  headers: { "content-type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({ email, password }),
});

// Create a gig as a KOL
await fetch("/api/gigs", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    title: "Threaded breakdown",
    description: "12-tweet thread, 24h delivery.",
    priceCents: 30000, deliveryDays: 3, niche: "DeFi",
  }),
});

// Place an order as a project
await fetch("/api/orders", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ gigId }),
});

// Auto-settle signals (cron)
await fetch("/api/cron/settle-signals", {
  method: "POST",
  headers: { "x-cron-secret": process.env.CRON_SECRET },
});
API reference — KolHub