Configuration

The public dashboard runs mainnet LIVE only. Every field below maps to project data stored in the cloud. Click Apply settings after bot changes, Save tiers when you only edit the tier table, and Save credentials for the dev wallet and RPC.

Identity

On POST /api/projects, the API rejects a missing mint. Client PATCH cannot set tokenSymbol; only a mint change triggers a new lookup.

Cycle timing

After you press Start, the first on-chain cycle runs in about 3 seconds, then repeats every interval.

Claim, reserve, buyback

For the project token (the default reward), the buyback route is chosen automatically: bonding curve before graduation, PumpSwap AMM after the curve completes. For SOL / USDC / custom-token rewards, see Airdrop reward below.

Airdrop reward (what holders receive)

Eligibility and holder snapshots are always computed against the project mint - holders must hold your token to qualify. Only the distributed asset is configurable. Choose it under Bot settings - Airdrop reward; it is stored as settings.rewardAsset.

Reward mint (CA) (rewardAsset.mint) is required only for CUSTOM and must be a valid base58 SPL mint with a Jupiter swap route. It is independent from the project mint: holders still qualify on your token, but receive the reward mint. An invalid or routeless mint is rejected; an unrecognized rewardAsset safely degrades to SAME so existing projects keep working with no migration.

All reward types stay self-financing: gas, ATA rent, and (for USDC / custom) the Jupiter swap are paid from claimed creator fees before sizing the spend. Logs and overlay show the reward token's own ticker (e.g. $USDC or your custom symbol), not the project ticker.

Launch readiness adds a reward_asset check that probes a read-only Jupiter route for USDC / custom rewards (required to pass) and is informational for SOL / project-token rewards.

Public distribution transparency

When you change holder-facing policy in the dashboard and press Apply settings, Latrine Bot writes a permanent public audit line automatically. There is no toggle to disable this, no setting to change severity rules, and no way to hide a logged change from the token page or your dashboard Output after it is saved.

What triggers a public log line

Each successful PATCH /api/projects/:id that changes any of the following appends one or more POLICY events to project_events:

Major distribution cut is decided by the platform, not by you: holder airdrop % drops by 20 points or more, or goes to 0%. You cannot change that threshold or suppress the alert styling.

Where holders and you see it

• Token page banner - current fee split bar, default payout, and perk toggles (poolSplit, publicFeatures on GET .../realm/:id/live).
• Hold fund goal - when you use Hold with a goal and hold % is above zero, the token page shows a Hold fund transparency card with purpose, SOL saved, and an optional progress bar (holdFund on the same live endpoint). Dex Vault mode shows a separate public card with vault balance and progress toward ~$299.
• Distribution history - sidebar list of past POLICY lines (same endpoint, policyHistory).
• Activity log - highlighted POLICY rows in the public feed; sticky Creator policy change banner for the latest change (policyAlert, permanent until the next change).
• Dashboard Output - the same POLICY lines via GET .../events or the live SSE stream (usually within ~1-2 s while the bot is running).

The token page refreshes about every 20 seconds. After Save, expect a short delay before the public page shows the new banner or history entry. The dashboard asks for confirmation before saving when a public policy change is detected.

API shapes: Distribution transparency API.

Hold fund transparency

When your Creator fee split keeps a non-zero hold slice, part of each cycle's pooled creator fees is reserved for your hold fund. In simple and goal modes the reserve stays on the dev wallet (stats.totalHeldSol). In Dex Vault mode hold fees transfer to a locked vault wallet each cycle - segregated from the dev wallet - until DexScreener is paid. The dashboard block Hold fund transparency lets you explain why you keep that slice and, optionally, show progress toward a SOL goal or Dex payment on your Stream Studio overlay and token page.

This is not holder hold cycles in the tier table. Hold cycles gate eligibility streaks; hold fund is the creator's fee-split reserve counter.

When the block appears

The hold fund panel is visible in Bot settings only when hold % (the remainder after distribute + burn) is greater than zero. If you set distribute + burn to 100%, hold fund settings reset to simple mode internally.

Modes

Dex Vault (guaranteed mode)

Dex Vault is a locked vault for hands-free DexScreener Enhanced Token Info (~$299). After you complete Dex Prefill and click Activate Dex Vault, hold fees from your creator hold % slice transfer to a dedicated vault wallet each cycle - segregated from the dev wallet. The dev wallet cannot spend those funds. When the vault reaches the quoted target, Latrine pays Dex Paid automatically. Activation is irreversible. API field remains mode: "guaranteed".

• Before activation - hold fees stay on the dev wallet; a POLICY line records that Dex Vault is selected.
• Hold % lock - you cannot decrease hold % below the locked value while Dex Vault is active; you may increase it.
• Public data - vault public key, balance, execution status (e.g. Accumulating, Ready to pay Dex), and progress appear on the token page and in holdFund on the live API.
• Dashboard API - session routes under /api/projects/:id/hold-fund/guaranteed/* (upload, preflight, draft, enable). See API reference.

Purpose templates (goal mode)

Pick one purpose under Purpose. Amounts are always in SOL, not USD.

Goal (SOL) is optional but required for a progress bar. Without a positive goal, viewers still see the purpose and held SOL on the token page and stream. Changing hold fund settings triggers a POLICY audit line (see above) when hold % > 0.

Only you edit hold fund in the dashboard. Stream Studio and the token page are read-only. In Dex Vault mode public holdFund.heldSol is the vault balance, not stats.totalHeldSol. Enable the hold-vault layer in Studio to show the card on stream.

Holder reward choice (Holder perk)

Optional perk for eligible holders on your public token page (/realm/:projectId) and the homepage showcase when enabled. Holders pick what they receive each cycle: project token (buyback), SOL, or USDC. Eligibility and snapshot weight stay on your project mint - only the payout asset changes per wallet.

The dev default from rewardAsset is shown as DEV DEFAULT in the UI. Wallets without a saved preference receive the dev default cohort. Saved prefs are read each cycle and split the airdrop budget across SAME / SOL / USDC cohorts. API: Holder perks API.

X post boost (Boost)

Optional social perk: anyone can post on X about your token and paste the link + wallet on the token page. The boost is active for a fixed time window (default 1 hour) and affects every airdrop cycle that runs while the window is open. Payouts come from the same creator-fee pool as regular holder drops.

Core rules

Step-by-step (holder or non-holder)

1. Dev enables Enable X post boost in Bot settings.
2. On the token page, open the Boost panel. GET .../social-claim returns a suggested template (ticker, CA, Running on @Latrine_bot).
3. User publishes a post on X that passes validation (see below).
4. User pastes the full post link (x.com/... or twitter.com/...) and their wallet, then clicks Claim boost.
5. Server fetches the tweet via X API, validates text, and stores a row with status: pending and boost_until (now + window).
6. On each airdrop cycle while now < boost_until and status is still pending, the engine applies the boost (see outcomes below).
7. After a cycle that actually pays that wallet, the claim moves to status: paid. The tweet URL remains unusable even if the hour has not ended.
8. If the hour ends before any paying cycle, the boost simply stops applying. The tweet URL is still burned.

What happens in each cycle

Social boost runs after the normal hold-cycle gate. It does not change eligibility history or bypass hold streaks for full tier status.

Intro share is a small discovery airdrop, not full holder eligibility. Holders who are still gated by hold cycles are treated like non-holders for boost purposes until they pass the streak.

Dashboard settings

Post requirements

Validated server-side when the claim is submitted (case-insensitive):

• $TICKER - your project symbol with the dollar sign
• Full project mint (CA) anywhere in the text - the word CA: is optional (the template includes it for clarity)
• @Latrine_bot - platform handle from X_TWITTER_HANDLE
• At most one distinct Solana-length address in the tweet (blocks multi-CA abuse)
• Tweet must still exist (not deleted); server returns 404 if gone

Common errors

API reference: Holder perks API. Eligibility interaction: X post boost.

Holder filters (fallback)

All token amounts in the dashboard are whole tokens (the number you would see on Pump.fun or in a wallet). The bot converts to base units internally when comparing on-chain balances.

Once DexScreener reports market cap, the active tier floor from eligibilityTiers replaces the fallback min holder for that cycle.

Eligibility tiers

Stored as eligibilityTiers: an array of { mcUsd, minTokens, holdCycles } rows. Use Save tiers to PATCH only tiers, or Apply settings to save tiers together with other bot fields. See Eligibility.

Reset to default calls POST /api/projects/:id/tiers/reset-default and restores the platform default table above.

Launch readiness (preflight)

Before Start or Run now, open Launch readiness in the Controls panel (or call GET /api/projects/:id/preflight from your integration). The dashboard blocks Start and Run now until every required check passes.

1. Select your project. Preflight runs automatically after load and after you save credentials or bot settings (debounced).
2. Click Check again to refresh without starting a cycle.
3. When the summary says Ready to launch, you may Start or Run now. If it says Not ready yet, fix failed required lines first.

What preflight checks

Response field ready is true only when every check with required: true has ok: true. Optional checks (market data, recommended balance) help you tune settings but do not block launch.

Full API shape and curl examples: API reference - Launch readiness.

PATCH /api/projects/:id (client fields)

Client PATCH accepts name, mint, and settings. It cannot change mode (always mainnet LIVE for end users).

Inside settings, the API merges and clamps these keys (via server sanitizeSettings):

• mint - kept in sync with top-level mint when you PATCH mint
• cycleIntervalSec, minHolderBalance, maxHolderBalance
• minClaimSol, minReserveSol, slippageBps, buybackPercent, burnPercent
• rewardAsset - normalized to { kind, mint }; kind in SAME | SOL | USDC | CUSTOM, mint required (valid base58) only for CUSTOM, otherwise null. Invalid input degrades to SAME.
• holderRewardChoiceEnabled - boolean, holder perk on the token page
• socialClaimEnabled - boolean, X post boost on the token page
• socialBoostDurationMin - integer minutes (5-1440)
• socialHolderBoostMultiplier - number (1-3)
• socialNonHolderWeightRatio - number (0-0.5)
• holdFund - { mode, template, customLabel, goalSol } - see Hold fund transparency. Normalized server-side; simple mode clears template fields.
• eligibilityTiers - normalized (sorted, deduped); legacy holdCyclesRequired is stripped

tokenSymbol is server-owned: any tokenSymbol in the PATCH body is ignored. Operator-only keys (legacy simulation tuning and other internal knobs) are not documented here and are omitted from public API responses.

PATCH /api/projects/:id
{
  "name": "My token",
  "mint": "YOUR_CA_BASE58",
  "settings": {
    "cycleIntervalSec": 90,
    "minClaimSol": 0.01,
    "buybackPercent": 80,
    "rewardAsset": { "kind": "CUSTOM", "mint": "REWARD_MINT_BASE58" },
    "holderRewardChoiceEnabled": true,
    "socialClaimEnabled": true,
    "holdFund": {
      "mode": "goal",
      "template": "dex",
      "customLabel": "",
      "goalSol": 4
    },
    "eligibilityTiers": [
      { "mcUsd": 0, "minTokens": 500000, "holdCycles": 5 }
    ]
  }
}

Use { "kind": "SOL" }, { "kind": "USDC" }, or { "kind": "SAME" } for the other reward types (mint is ignored unless kind is CUSTOM).

Credentials (separate save)

Not part of Apply settings - use Save credentials (POST /api/projects/:id/secrets):

• devWalletSecret - Base58 private key of the Pump.fun launch / claim wallet (64 bytes when decoded).
• rpcUrl - Full Helius (or compatible) mainnet URL with API key in the query string.

Click Test RPC after save to verify connectivity. Credentials metadata (pubkey, masked RPC host) is available at GET /api/projects/:id/credentials.

Full setup guide � Modes � Preflight API