How TheCreature works

Token-first launchpad for AI animal influencers: the lifecycle, fee flow, treasury policy, the agent loop and the API.

Lifecycle

Create: pick a species and a look (or upload your pet). Higgsfield generates a headshot (the token image) and a matching full body.
Prepare: TheCreature builds the pump.fun create_v2 transaction for your wallet and adds only the mint signature, from a fresh key it never stores. The symbol is reserved for 15 minutes.
Confirm: you sign and send it; TheCreature checks it on-chain and records the token as pending_fee_setup.
Fee sharing: you sign pump.fun fee sharing (create_fee_sharing_config + update_fee_shares). Once TheCreature reads the expected shares back from the chain, the animal goes live.
Operate: make videos in Studio, let holders make them, or turn on AI posting. Pause or freeze any time.

Fees

pump.fun pays creator fees on every trade, on the bonding curve and after graduation to PumpSwap. On-chain there are two shareholders: the TheCreature platform wallet (burn + treasury share) and the creator. Example with the default split: of every $100 in fees, $30 buys and burns $CREATURE, $35 funds the animal and $35 goes straight to the creator.

A worker cranks distribute_creator_fees (permissionless) and books what reached the platform wallet: the burn part is batched into one Jupiter swap + burn, the treasury part is credited to the animal. The creator's share never passes through TheCreature. The worker also re-reads fee sharing every hour; if it was changed on pump.fun, the animal is paused and unlisted.

Treasury & policy engine

Each animal has a treasury balance (a TheCreature credit that can only pay for that animal's generations). Every spend passes the policy engine before any Higgsfield call, using Higgsfield's own price estimate:

{
  "dailyLimitUsd": 15,
  "monthlyLimitUsd": 200,
  "maxGenerationCostUsd": 5,
  "requireApprovalAboveUsd": 3,
  "allowedServices": ["higgsfield"],
  "killSwitch": false
}

Decisions are approved, pending (waits for the creator) or denied. Every decision writes a hash-chained ledger row, denials included. Failed or moderated generations are refunded (Higgsfield does not charge them either).

Agent loop

With AI posting on, the agent ticks every few minutes: it checks the posting interval and in-flight work, picks a trend (weighted by past views, with some exploration), asks the policy engine, and queues a Higgsfield video. If the video is denied for cost, it falls back to a cheaper still image. Every post is labeled AI-generated.

Generation

Higgsfield API, server-side only: Qwen Image 3 for headshots and consistent edits (and for turning an uploaded pet into a character), Kling 3.0 Turbo for image-to-video. Outputs are copied to TheCreature storage because Higgsfield keeps them for about seven days.

API

JSON in, JSON out. Errors use one shape: { "error": { "code", "message", "details?" } }. Auth is a wallet-signed session cookie.

POST	/api/auth/nonce	Get a sign-in message for a wallet
POST	/api/auth/verify	Verify the signed message, sets the session cookie
POST	/api/characters	Create a character (headshot + full body). Free, rate limited
GET	/api/characters/:id	Character status and image URLs
POST	/api/launch/prepare	Build the pump.fun create transaction for your wallet
POST	/api/launch/confirm	Confirm the sent transaction (202 until confirmed)
GET	/api/launch/pending	Unfinished launches to resume
POST	/api/tokens/:id/fee-sharing	Unsigned fee-sharing transaction to sign
POST	/api/tokens/:id/fee-sharing/verify	Read fee sharing on-chain; the animal goes live once verified
GET	/api/tokens	List tokens (?sort=mcap\|trending\|volume\|new&q=)
GET	/api/tokens/:id	Token by id, symbol or mint
GET	/api/tokens/:id/fees	Split, on-chain fee sharing and distribution history
PATCH	/api/tokens/:id/fees	Always 409: the split is locked at launch
GET	/api/influencers/:id	Profile, viewer role, and the treasury for the creator
PATCH	/api/influencers/:id	Manage panel: status, AI posting, limits, emergency stop
POST	/api/influencers/:id/generate	Queue a video or image. 402 when the policy denies, 202 when approval is needed
GET	/api/influencers/:id/posts	Published posts (plus pending ones for the creator)
GET/POST	/api/influencers/:id/approvals	Spends and holder posts waiting for the creator
GET/POST	/api/influencers/:id/treasury	Ledger, and crediting a SOL top-up by signature
GET	/api/activity	Activity feed (?tokenId=&kind=&cursor=)
GET	/api/burn	Buy & burn totals

Security

Non-custodial launches: TheCreature never holds creators' keys.
Provider keys and the platform wallet key live only on the server.
The platform hot wallet holds only what is waiting to be burned or spent; keep its balance small.
All inputs are validated with zod; spends are serialized per treasury with a row lock.