API reference

HTTP API for api.latrinebot.com. This reference is for client integrations (dashboard apps, scripts that manage your own projects). Use the Metrics API guide for read-only OBS overlays (X-Metrics-Key).

Overview

Authentication types

Client model (LIVE mainnet)

The public dashboard is LIVE-only: there is no test-mode switch for end users. All on-chain automation (claim creator fees, buyback, holder airdrops) runs on Solana mainnet.

• New projects are created with mode: "LIVE".
• Client PATCH /api/projects/:id cannot change mode (only name, mint, settings).
• POST .../control/start and POST .../control/run-once force the project to LIVE if it was still on a legacy mode, then run mainnet cycles.
• Before starting, use GET .../preflight (or the dashboard Launch readiness panel) to confirm mint, RPC, dev wallet, balances, and engine health.
• Start and run-once also verify that the saved dev wallet can claim Pump.fun creator fees for the mint (bonding-curve creator, PumpSwap coinCreator when applicable, or a non-zero creator-fee vault).

Legacy SIM / DRY values may still appear on very old projects in the database; they are not exposed in the client UI and are not selectable via this API. Operator testing uses a separate admin surface, not documented here.

Token CA and ticker

Every project is tied to one Pump.fun token. The contract address (CA) and ticker are exposed in API responses so overlays and tools can label the token correctly.

Display tip: in your UI use $ + settings.tokenSymbol when the symbol is non-empty; fall back to shortened mint if not.

Mint programs: preflight accepts both legacy SPL Token and Token-2022 mints (typical Pump.fun tokens).

Resolve ticker before creating a project

curl -s "https://api.latrinebot.com/api/projects/symbol?mint=YOUR_MINT" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

{
  "ok": true,
  "mint": "So111...",
  "tokenSymbol": "LATRINE"
}

When you POST /api/projects or PATCH with a new mint, the server resolves tokenSymbol again. Clients cannot set the ticker manually (server-owned field).

Discovery

{ "ok": true, "service": "Latrine Bot", "site": "https://latrinebot.com", "ts": "..." }

{ "name": "Latrine Bot API", "version": "0.4.0", "docs": "https://latrinebot.com/docs" }

Authentication

The dashboard supports three sign-in methods. All of them end in the same session JWT used on protected API routes. You do not need a Solana wallet to use Google or X login, but you still need a Pump.fun dev wallet secret under Credentials to run the bot.

Sign-in methods

Separate accounts: each method creates its own user row and project list. Signing in with Google does not merge with a wallet account or X account. Use the same method you used when you created a project.

Session JWT

• Returned as token in JSON and set as an HTTP-only session cookie (7 days).
• The dashboard also stores the token in localStorage as lb_session_token and sends Authorization: Bearer <token>.
• Field name wallet in API responses is the account id (pubkey or google: / x: prefix), not always a Solana address.
• POST /api/auth/logout clears the session cookie. Clients should delete their stored JWT as well.

Which OAuth buttons are shown

{ "ok": true, "google": true, "x": true }

A. Solana wallet (Sign-In With Solana)

For Phantom and other wallets that support signMessage.

1. GET /api/auth/challenge?wallet=PUBKEY - returns nonce, message, domain, uri (nonce TTL 5 minutes).
2. User signs message in the wallet (UTF-8).
3. POST /api/auth/verify with wallet, signature (base58), message, nonce.
4. Response: { ok: true, wallet, token } plus session cookie.

B and C. Google / X OAuth (browser redirect)

Both providers use the same finish step on the dashboard. Server-side flow:

1. Browser opens GET /api/auth/google or GET /api/auth/x (302 redirect to provider).
2. User approves at Google or X.
3. Provider redirects to API callback: /api/auth/google/callback or /api/auth/x/callback.
4. API creates or loads user, mints JWT, stores it under a one-time login_code in KV (TTL 120s).
5. API redirects browser to https://latrinebot.com/app/?login_code=UUID (or auth_error=... on failure).
6. Dashboard JavaScript calls POST /api/auth/complete-oauth with { "code": "login_code" }, receives token, saves it, calls /api/auth/me.

B. Google

Redirect URI registered in Google Cloud Console must be exactly https://api.latrinebot.com/api/auth/google/callback (or your API origin if using OAUTH_API_ORIGIN).

C. X (Twitter)

Use a separate X developer app for dashboard login (X_LOGIN_CLIENT_ID, X_LOGIN_CLIENT_SECRET). This is not the same as server credentials used to post announcement tweets for projects.

Callback URL in the X developer portal: https://api.latrinebot.com/api/auth/x/callback. If login fails with a callback error, verify this URL and avoid a wrong X_LOGIN_REDIRECT_BASE override.

curl -s -X POST "https://api.latrinebot.com/api/auth/complete-oauth" \
  -H "Content-Type: application/json" \
  -d '{"code":"YOUR_LOGIN_CODE"}'

Current session

{
  "ok": true,
  "wallet": "google:1162...",
  "authProvider": "google",
  "label": "you@example.com"
}

OAuth redirect errors

On failure the API redirects to /app/?auth_error=... instead of login_code. The dashboard shows the decoded message and clears the query string.

Common values: sign-in cancelled, expired state, invalid callback, provider not configured.

Projects

Max 25 projects per account. Mint (CA) is required on create and cannot be cleared later.

Project object (public fields)

{
  "id": "uuid",
  "name": "My token",
  "mint": "base58-ca",
  "mode": "LIVE",
  "running": false,
  "hasSecrets": true,
  "settings": {
    "mint": "base58-ca",
    "tokenSymbol": "LATRINE",
    "cycleIntervalSec": 60,
    "minHolderBalance": 500000,
    "maxHolderBalance": 20000000,
    "minClaimSol": 0.005,
    "minReserveSol": 0.05,
    "rewardAsset": { "kind": "SAME", "mint": null },
    "holderRewardChoiceEnabled": false,
    "socialClaimEnabled": false,
    "holdFund": { "mode": "simple", "template": null, "customLabel": "", "goalSol": 0 },
    "eligibilityTiers": [
      { "mcUsd": 0, "minTokens": 500000, "holdCycles": 5 },
      { "mcUsd": 50000, "minTokens": 450000, "holdCycles": 6 }
    ]
  },
  "createdAt": "...",
  "updatedAt": "..."
}

settings omits operator-only fields (including legacy simulation tuning). Metrics API responses use the same public subset. Full settings keys are documented in Configuration.

Create project

POST /api/projects
{ "name": "My Project", "mint": "YOUR_CA_BASE58" }

Update project

PATCH /api/projects/:id
{
  "settings": { "cycleIntervalSec": 90 }
}

Changing mint re-fetches tokenSymbol. mint cannot be set to empty.

Public policy audit (mandatory): when settings changes fee split (buybackPercent, burnPercent), rewardAsset, holderRewardChoiceEnabled, socialClaimEnabled, or holdFund, the API appends POLICY rows to project_events and busts the token-page live cache. There is no request flag to skip logging. Severity for major holder cuts (drop ≥20 pp or to 0%) is server-defined. See Distribution transparency.

Update eligibility tiers only

Rows are normalized (sorted, deduped, holdCycles coerced). Legacy holdCyclesRequired is stripped.

PATCH /api/projects/:id
{
  "settings": {
    "eligibilityTiers": [
      { "mcUsd": 0, "minTokens": 500000, "holdCycles": 5 },
      { "mcUsd": 250000, "minTokens": 300000, "holdCycles": 10 }
    ]
  }
}

Credentials

Dev wallet secret (Base58 64-byte keypair) and RPC URL are encrypted at rest. Full secrets are never returned after save. The API derives and exposes the dev wallet public key in credentials metadata.

Save credentials

POST /api/projects/:id/secrets
{
  "devWalletSecret": "base58-secret-optional-if-updating-rpc-only",
  "rpcUrl": "https://mainnet.helius-rpc.com/?api-key=..."
}

• First save must include both dev wallet and RPC.
• Later updates may send either field alone; omitted fields keep the previous encrypted value.
• Dev wallet must be the Pump.fun launch wallet (or an on-chain claim wallet that can collect creator fees for this mint).

Credentials metadata response

{
  "ok": true,
  "credentials": {
    "savedAt": "2026-05-21T12:00:00.000Z",
    "complete": true,
    "devWallet": {
      "configured": true,
      "pubkey": "FullBase58Pubkey...",
      "display": "FullBase58Pubkey..."
    },
    "rpc": {
      "configured": true,
      "provider": "Helius",
      "host": "mainnet.helius-rpc.com",
      "hasApiKey": true,
      "display": "Helius � mainnet.helius-rpc.com � api-key ?"
    }
  }
}

Launch readiness (preflight)

Run before control/start or control/run-once. The dashboard calls this for the Launch readiness checklist. Integrations should treat ready: false as a hard block (same as the UI).

{
  "ok": true,
  "ready": false,
  "checks": [
    {
      "id": "mint_set",
      "label": "Mint (CA)",
      "ok": true,
      "detail": "65C5dduDBr9LcAmqrQTaStAKPj3ksfk4i7TTBKKGpump",
      "required": true
    },
    {
      "id": "dev_is_creator",
      "label": "Dev wallet is creator",
      "ok": true,
      "detail": "Dev wallet matches on-chain claim wallet (...)",
      "required": true
    }
  ]
}

Check IDs

ready is true only when every required: true check has ok: true.

Scheduler control

All control routes require saved credentials, a valid mint, a passing creator-wallet check, and (recommended) preflight.ready === true. The server sets mode to LIVE before starting cycles.

First LIVE start: when platform X posting is configured, the API may post one announcement tweet per project (see operator docs). This does not affect cycle logic.

Typical 400 errors: missing credentials, invalid mint, dev wallet not creator, engine not ready. Run preflight first to surface the same checks in one response.

Status, stats, events

publicStats fields (LIVE, used by token page)

• airdropsCount - Airdrops sent
• totalDistributedSol - To holders (SOL est.)
• uniqueHoldersPaid - Holders paid
• lastEligibleCount - Eligible now (from the last snapshot)
• burnedDisplay - Tokens burned (human readable)
• totalClaimedSol - Creator fees claimed

Note: totalDistributedSol is an estimate based on cycle accounting, not a sum of on-chain transfers.

Common raw stats fields (LIVE)

Raw counters are still returned for dashboards and integrations that need deeper detail.

• cycles, cyclesAirdropped, errors
• totalClaimedSol, totalBuybackSol, totalBoughtTokensUi
• airdropsCount, uniqueHoldersPaidCount, totalAirdropTokensMillions
• lastMarketCapUsd, lastPriceUsd
• lastTierMcUsd, lastTierMinTokens, lastTierHoldCycles - active tier from the last cycle
• lastCycleAt, lastClaimAt, lastAirdropAt

Live stream (SSE)

Server-Sent Events for real-time dashboard updates (status + new log lines). Replaces aggressive polling. EventSource cannot send Authorization, so pass the JWT as ?token= (HTTPS only).

SSE events

Optional: Last-Event-ID header or ?since= for incremental event replay after reconnect.

Widgets (session auth)

CRUD for embeddable overlays. Public live data is under Public feeds (no metrics key in the browser).

Widget config schema: Widget builder guide.

Share card (session auth)

Parchment-style share images and optional X posting from the dashboard.

Metrics API keys

Manage read-only keys for external overlays (see Metrics API).

Metrics API v1 (read-only)

Dedicated guide: Metrics API (OBS, websites, untrusted environments).

Important: stats in Metrics API are LIVE mainnet counters only. mint, settings.tokenSymbol, and settings.eligibilityTiers are included when configured. activeTier summarizes the last LIVE cycle tier: { mcUsd, minTokens, holdCycles }.

Public feeds (no session)

No wallet login and no metrics key. Rate limited and edge-cached where noted.

Widget embed: Widget builder guide. OBS overlay editor: Stream Studio guide.

Stream Studio API

Anonymous layout storage for the Stream Studio editor and /stream/?l= OBS page. No session auth - writes require the device secret returned at creation.

POST /api/public/studio/layouts

Body: { projectId, preset?, config? }. projectId must exist. Presets: latrine, pumpfun, minimalism, breach, retro, noir. Response 201: layout, deviceSecret, streamUrl, studioUrl. Rate limit: 20 creates per minute per IP.

GET /api/public/studio/layouts/:id

Public read of sanitized layout config. Used by OBS and Studio when opening ?l=.

PATCH /api/public/studio/layouts/:id

Header X-Studio-Secret: <deviceSecret>. Body: { config, preset? }. Max config size 32 KB. Rate limit: 120 patches per minute per layout id per IP.

Live stats for overlays use GET /api/public/realm/:projectId/live (not Metrics API keys). Stream Studio token search loads the All tokens list via GET /api/public/ward-roll?faces=1 (LIVE projects only).

Distribution transparency API

Token pages read policy state from GET /api/public/realm/:id/live (cached ~45 s; refreshed on policy PATCH). Devs cannot disable these fields or suppress POLICY logging through any dashboard or API setting.

GET .../realm/:id/live - transparency fields

In addition to stats, publicStats, and recent activity lines, the payload includes:

{
  "ok": true,
  "status": "live",
  "poolSplit": { "distributePct": 100, "burnPct": 0, "holdPct": 0 },
  "holdFund": {
    "mode": "goal",
    "template": "dex",
    "label": "Dex Paid",
    "purposeLine": "Holding for Dex Paid",
    "customLabel": "",
    "goalSol": 4,
    "heldSol": 0.016,
    "holdPct": 10,
    "showProgress": true,
    "progressPct": 0.4
  },
  "publicFeatures": {
    "holderRewardChoice": true,
    "socialClaimBoost": true,
    "defaultRewardLabel": "$TICKER",
    "defaultRewardKind": "SAME"
  },
  "policyHistory": [
    {
      "at": "2026-06-06T04:34:03.000Z",
      "body": "Distribution changed. Holders 61% -> 100%. Burn 0% -> 0%. Hold 39% -> 0%.",
      "severity": "warn",
      "time": "04:34:03"
    }
  ],
  "policyAlert": {
    "at": "2026-06-06T04:34:03.000Z",
    "body": "Distribution changed. Holders 61% -> 100%. …",
    "severity": "warn",
    "ageSec": 120
  },
  "recent": [ … ]
}

Human-oriented rules: Configuration - Distribution transparency.

Dex Vault API (session)

Dashboard-only routes for Dex Prefill and Activate Dex Vault. Require session auth (same JWT as other /api/projects/:id routes). User-facing name: Dex Vault (locked vault - hold fees segregated from dev); persisted API mode: guaranteed.

Public image URLs (no auth) for DexScreener order creation:

• GET /api/public/hold-fund/:projectId/icon
• GET /api/public/hold-fund/:projectId/header

After activation, hold % slices route to the vault each cycle until Dex payment completes. Hold % cannot decrease below the locked value.

Holder perks API (no session)

Public endpoints for the Holder perk (reward currency choice) and Boost (X post drop) panels on token pages. The same contracts are mirrored under /api/public/latrine/... for the homepage showcase project bound via SHOWCASE_PROJECT_ID. Configure toggles in the dashboard: Holder reward choice, X post boost.

X post boost mechanics

Per-token realm (/api/public/realm/:projectId/...)

Homepage showcase (/api/public/latrine/...)

Same JSON shapes as realm routes above, scoped to the operator-bound showcase project (not a generic project id in the path).

GET .../reward-options

{
  "ok": true,
  "enabled": true,
  "options": ["SAME", "SOL", "USDC"],
  "defaultKind": "SAME",
  "defaultRewardKind": "SAME",
  "defaultRewardLabel": "Project token (buyback)",
  "rewardMint": null,
  "ticker": "$TICKER"
}

POST .../reward-preference

Body: { wallet, message, nonce, signature, kind } where kind is SAME, SOL, or USDC. Obtain message + nonce from GET /api/auth/challenge?wallet= (SIWS). The signed message must match the challenge wallet. Returns { ok: true, kind }.

GET .../social-claim

{
  "ok": true,
  "enabled": true,
  "ticker": "$TICKER",
  "mint": "FULL_MINT_BASE58",
  "handle": "@Latrine_bot",
  "template": "$TICKER\nCA: ...\nRunning on @Latrine_bot"
}

POST .../social-claim

Body: { tweetUrl, wallet } where wallet is a base58 Solana pubkey (32-byte). No session or SIWS signature - the server trusts the pasted wallet for this claim only. The tweet must already be public; the Worker fetches text and validates $TICKER, full mint CA, and @handle.

On success (boost window starts immediately, default 1 hour):

{
  "ok": true,
  "status": "pending",
  "boostUntil": "2026-06-05T12:00:00.000Z",
  "message": "Boost active until ... Your wallet will join the next drop."
}

Rules recap: one X post URL per token forever (global); one active claim per wallet per token while the hour runs; different wallets can each claim different posts on the same token; the same wallet can boost other tokens in parallel. Common errors: 400 validation (missing $TICKER, mint, or @handle in tweet, or more than one CA in text), 403 feature disabled, 404 tweet deleted or project not LIVE, 409 tweet URL already used, or wallet already has an active boost on this token, 429 rate limit, 502 could not fetch tweet text.

Rate limits (per IP, per minute)

• reward-options, reward-preference GET, social-claim GET: 60
• reward-preference POST: 20
• social-claim POST: 10

Errors and limits

Failed requests return JSON:

{ "ok": false, "error": "Human-readable message" }

Auth challenge: 20 requests per minute per IP; verify: 30 per minute per IP.

Public widget live: 120 requests per minute per IP per widget id.

Metrics API guide � Getting started � Security � Metrics API test page