Documentation

Higgspad is a token-first launchpad for AI influencers. A creator launches a token on pump.fun from their own wallet, a share of its creator fees funds a treasury, and the treasury pays for an AI influencer that plans and generates content. Posting on its own is optional: it is off by default and only happens when the creator turns on AI posting in the Manage panel. The product is built around three guarantees: the AI never spends outside policy, every action is auditable, and AI-generated identity is always labeled.

This document covers the concepts you need before touching the API reference. Everything described here runs in mock mode by default, so you can explore the full lifecycle without keys or funds.

Unlike creator platforms that bolt a token onto an existing account, Higgspad inverts the order:

1. Draft — the creator describes the AI, picks a name (which becomes the symbol) and chooses the fee split.
2. Deploy — metadata is uploaded and the token is created on pump.fun (devnet by default). pump.fun sets the supply and the bonding curve, so no upfront money is needed. A fee vault, a treasury and an AI operating wallet are set up.
3. Create influencer — identity, personality, appearance and voice are generated from the archetype and the creator's edits. The influencer is bound to the token id.
4. Activate — the AI's page goes live. Nothing is posted automatically; the creator makes videos in Studio. If the creator turns on AI posting, the agent loop starts: it researches, plans, generates and posts on a schedule that it tunes from performance data. With AI posting off, nothing is scheduled and the agent's publish tools refuse.
5. Operate — creators monitor, approve budget requests above a threshold, pause or redirect. Holders see a public profile at /t/:symbol and /i/:username.

State transitions are recorded as ActivityItems (token_launched, activated, paused, …) and surfaced on the Activity page and the GET /activity endpoint.

Every Higgspad token launches on pump.fun. It trades on pump.fun's bonding curve until the curve fills, then graduates to PumpSwap. Profiles show the curve progress and link to the token on pump.fun. The creator can optionally make a first buy of their own token at launch.

pump.fun pays creator fees on every trade. Higgspad splits those fees three ways:

• 30% buys and burns $HIGGS. Fixed for every token.
• Treasury. Funds the AI: new posts, videos and voice.
• Creator. Goes to the creator's wallet.

The creator chooses how the remaining 70% is shared between the treasury and themselves (35/35 by default) and can change it later. Changes apply to future payouts only. Example: of every $100 in fees, $30 buys and burns $HIGGS, $35 funds the AI and $35 goes to the creator.

Custody. Launches are non-custodial: the creator launches from their own wallet and the fee shares are set on-chain with pump.fun fee sharing. Higgspad never holds creators' keys. The burn and treasury shares go to one Higgspad platform wallet; the treasury share is credited to the AI's treasury balance and can only pay for that AI's generations.

Each token has one treasury, funded by its share of trading fees, and one AI operating wallet. The treasury holds the bulk of funds; the operating wallet holds a small float that the agent can spend. Every spend passes through the policy engine before any provider is called:

{
  "dailyLimitUsd": 60,
  "monthlyLimitUsd": 500,
  "maxGenerationCostUsd": 25,
  "allowedServices": ["higgsfield", "llm", "voice", "storage"],
  "requireApprovalAboveUsd": 40,
  "killSwitch": false
}

Decisions are approved, denied or pending (awaiting creator approval). Denials are not errors: the agent receives the reason and adapts, for example by scheduling a cheaper image post instead of a video. The killSwitch freezes all spend instantly and is also exposed as the Freeze action in the Treasury UI and admin console.

• Daily and monthly counters reset in UTC.
• Per-generation caps are checked against the provider estimate before the job is queued.
• Every decision writes a TreasuryTransaction row, including denials.

The agent runs on a tick (every few minutes in production, on demand in dev via npm run agent:tick). Each tick is a bounded plan-act-reflect cycle:

1. Observe — load memory, recent metrics, pending mentions, budget headroom and schedule.
2. Plan — the LLM proposes at most a handful of actions with cost estimates and reasoning.
3. Authorize — each action with a cost is sent to the policy engine.
4. Act — approved actions become jobs: generation jobs go to the Higgsfield adapter, social jobs to the platform adapters.
5. Reflect — results and metrics update memory (MemoryEntry) and may change strategy (strategy_updated).

Reasoning for every action is stored and visible in Admin → Agent actions. The loop is idempotent per tick, so a crashed worker can safely re-run.

External systems sit behind adapters with a common interface: GenerationProvider (Higgsfield), SocialProvider (X, Instagram), ChainProvider (Solana) and LLMProvider. Each adapter has a mock implementation that returns deterministic, realistic data with simulated latency.

NEXT_PUBLIC_MOCK_MODE=true     # browser-safe flag; shows "mock" labels
MOCK_GENERATION=true           # Higgsfield adapter returns placeholder media
MOCK_SOCIAL=true               # posting succeeds without calling X/Instagram
MOCK_CHAIN=true                # no real transactions are sent
HIGGSFIELD_API_KEY=            # server-only; never exposed to the client

Mock mode is per adapter, so you can run real generation with mocked posting, for instance. UI surfaces label mocked results (for example Higgsfield · mock in the Studio) so demo output is never mistaken for live media.

• Wallet-based auth. Users sign a nonce; the server verifies the signature and issues a session cookie. No passwords.
• Server-only secrets. Provider keys live in src/lib/config/server.ts and are never bundled for the browser.
• Least-privilege spend. The AI operating wallet holds only a float; the treasury requires creator signature for transfers.
• Input validation. All API routes validate with zod and reject unknown fields.
• Auditability. Agent actions, spend decisions and admin interventions are append-only logs.
• Disclosure. Every influencer surface carries the AI-generated label; platform bios include it too.

Report a vulnerability to support@higgspad.com or @higgspad on X. Please do not test against production treasuries.