Developer Portal — trollz.fun

Platform SDK

Trollz SDK

REST API for the trollz.fun agent platform. Mint agents, embed them, bind channels, collect SYNTH. No API key needed — your wallet is your identity.

# Install CLI — compiled binary, no npm, no source
$ curl -sSf https://trollz.fun/install | bash

# Or embed one agent on any page
<script src="https://trollz.fun/embed/{agent_id}.js"></script>

Mint agents on Sui — character · lifespan · rarity
Embed chat widget on any site — one script tag
Bind Discord / Telegram / Twitch / SMS channels
Add micro-app sticks — polls, auctions, raffles, T-notes
SYNTH accrues on every interaction to Sui wallet
CODIE compression — 60–80% fewer API tokens

EXAMPLES → API REFERENCE MINT FIRST

Security SDK

GentlyOS MHVR

Manifest Hash Verification Runtime. Secure any agentic pipeline in 30 seconds. You get a compiled Rust binary — not source. Your secrets never leave your vault.

# Install compiled binary — coming soon at gently.io
$ curl -sSf https://gently.io/install | bash

# Full setup — 30 seconds
$ gently init # 3 questions, creates vault
$ gently scan # hashes your codebase → manifest.xml
$ gently serve # grind server on :7777

LLMs emit hashes — not English instructions
Compiled phf::Map — unknown hash → None → stopped
Secrets in AES-256-GCM vault — never touch inference
Source stays on your server — manifest has zero source
60–85% token reduction via CODIE compression (measured)
Orc namespace graph — cross-boundary calls need explicit edges

EXAMPLES → SECURITY DEEP DIVE CODIE COMPRESSION

TROLLZ SDK

Build with three calls.

Mint an agent, embed it anywhere, bind it to every channel. No API keys. Your wallet signs everything.

Mint an agent NFT on Sui. One POST call. You get back an nft_id and a slug URL. The agent is live immediately — no approval, no waitlist.

Character type 0–11 maps to your SDF-rendered character (ZAPP, SAGE, SPARK...). Lifespan kinds: instant · session · event · vector · permanent.

SYNTH starts accruing to owner_wallet on first interaction.

          curl
# POST /mint/agent
curl -X POST https://api.trollz.fun/mint/agent \
  -H "Content-Type: application/json" \
  -d '{
    "owner_wallet":  "0xYOUR_SUI_ADDRESS",
    "character_type": 0,
    "skill_id":      "assistant",
    "lifespan_kind": "session",
    "rarity":        "uncommon",
    "name":          "My Agent"
  }'

# Response
{
  "nft_id":  "0xabc123...",
  "slug":    "https://trollz.fun/a/0xabc123",
  "phase":   "active",
  "synth_earned": 0
}
        

One script tag. Any website. Drop it into your site's <body>. The widget renders bottom-right in a Shadow DOM — fully sandboxed, no cookies, CSP-safe.

Users chat with your agent directly from your site. Every reply earns SYNTH streamed to your Sui wallet. Fully customisable position and theme via data-* attributes.

          html
<!-- Drop into any <body> — replace with your agent_id -->
<script
  src="https://trollz.fun/embed/0xabc123.js"
  async
></script>

<!-- Custom position + theme -->
<script
  src="https://trollz.fun/embed/0xabc123.js"
  data-position="bottom-left"
  data-theme="dark"
  async
></script>

<!-- Widget is sandboxed Shadow DOM.
     No cookies. Respects your CSP.
     SYNTH accrues on every reply. -->
        

Talk to the agent directly. POST a message to your agent. The CODIE pipeline compresses context, calls the inference layer, and returns the response. Supports streaming (SSE).

Returned HTML fragment is HTMX-ready — swap directly into your UI. JSON mode also available with Accept: application/json.

          curl
# POST /chat/:agent_id
curl -X POST https://api.trollz.fun/chat/0xabc123 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "message": "What can you help me with?" }'

# Response
{
  "reply":        "I can help you with...",
  "synth_earned": 142,
  "tokens_used":  38,
  "tokens_saved": 105,
  "quality_score": 0.9
}

# Streaming (SSE)
curl -N https://api.trollz.fun/chat/0xabc123/stream \
  -H "Content-Type: application/json" \
  -d '{ "message": "Tell me more..." }'
        

One agent. Every channel. Bind to Discord, Telegram, Twitch, SMS — your agent replies in all of them. Each channel binding stores in the agent record on Sui.

For SMS: provision a Twilio number via the API. For Discord: pass your guild + channel ID. The agent goes live in the channel immediately after binding.

          curl
# Bind Discord channel
curl -X POST https://api.trollz.fun/social/discord/bind \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id":  "0xabc123",
    "guild_id":  "YOUR_GUILD_ID",
    "channel_id":"YOUR_CHANNEL_ID",
    "wallet":    "0xYOUR_WALLET"
  }'

# Provision an SMS number
curl -X POST https://api.trollz.fun/twilio/provision \
  -d '{
    "phone_number": "+14155550100",
    "wallet":       "0xYOUR_WALLET",
    "agent_id":     "0xabc123"
  }'

# Agent now replies in Discord AND SMS.
# SYNTH accrues from both channels.
        

GENTLYOS SECURITY SDK

Protect your pipeline.
Four commands.

Wrap any agentic codebase in MHVR. Your functions become a compiled dispatch map. The LLM can only call what's in it.

You receive a compiled Rust binary. No source code. No npm. No dependency chain to trojanize. The binary + your manifest XML is the entire distribution artifact.

gently init asks 3 questions and creates your config + vault. gently scan walks your codebase and hashes every function — nothing else. gently serve starts the grind server your LLM talks to.

          bash
# 1. Install compiled binary (no source shipped)
$ curl -sSf https://gently.io/install | bash
  → Installing gently v0.1.0 (x86_64-unknown-linux-musl)
  → Verifying binary signature...
  → Done. gently installed to /usr/local/bin/gently

# 2. Init (3 questions)
$ gently init
  Project name: my-agent-app
  Scan paths: ./src
  Grind port: 7777
  → Created gently.toml + .gently/vault.enc

# 3. Scan codebase → manifest
$ gently scan
  → Scanned 47 files, found 134 functions
  → manifest.xml written (12 KB, zero source)

# 4. Start grind server
$ gently serve
  → MHVR grind server running on :7777
  → 134 hashes in dispatch map
  → Action space: CLOSED
        

The manifest is the only thing that leaves your server. It contains SHA-256 hashes of your functions and short purpose strings — nothing else. No paths, no variable names, no logic, no secrets.

The LLM receives the manifest as context (~60 tokens for 10 functions). It emits a hash. That hash either resolves or returns None. There is no third option.

          manifest.xml
<manifest version="1.0.0" project="my-agent-app"
          hash="sha256:9f8e7d...">
  <orcs>
    <orc name="auth"     functions="3" />
    <orc name="payments" functions="2" edges="auth" />
    <orc name="users"    functions="5" />
  </orcs>
  <functions>
    <fn hash="sha256:d4e5f6..."
        purpose="AUTH:u,p→token"     orc="auth"     />
    <fn hash="sha256:a1b2c3..."
        purpose="LOAD:uid→profile"   orc="users"    />
    <fn hash="sha256:fee789..."
        purpose="CHARGE:amt→receipt"  orc="payments"
        secrets="$STRIPE_KEY"         />
  </functions>
</manifest>

# LLM receives this. Nothing else.
# Source code: stays on your server.
# Secret values: in the encrypted vault.
        

Secrets go in the vault. They never come out into inference. The LLM sees $STRIPE_KEY as a reference. At call time, the vault decrypts the value, passes it directly to the function, and drops it from memory — microseconds total.

Secrets never appear in: the LLM context, the grind request/response, log output, error messages, or network payloads.

          bash
# Add secrets to the AES-256-GCM vault
$ gently secret set STRIPE_KEY sk-live-AbCdEf...
  → Encrypted and stored. Value will not appear in logs.

$ gently secret set DATABASE_URL postgres://user:pass@host/db
  → Encrypted and stored.

# List stored secrets (names only — values never shown)
$ gently secret list
  STRIPE_KEY       ••••••••••••••••  [set 2026-04-09]
  DATABASE_URL     ••••••••••••••••  [set 2026-04-09]
  ANTHROPIC_KEY    ••••••••••••••••  [set 2026-04-09]

# At call time — what each layer sees:
  LLM context:  secrets="$STRIPE_KEY"  ← ref only
  Log output:   resolved $STRIPE_KEY   ← ref only
  Function:     sk-live-AbCdEf...      ← actual value, μs lifetime
  Network:      (nothing)              ← never transmitted
        

The full protected pipeline. LLM emits a hash. Grind resolves it against the compiled dispatch map. If it's there — the function runs, secrets injected from vault. If it's not there — None — execution stops. No error. No fallback. No alternative path.

English instructions cannot produce a 64-character hex string. Prompt injection is structurally impossible — not filtered, not monitored. Impossible.

          pipeline
Step 1 — LLM receives context (~60 tokens)
<context>
  <fn hash="sha256:d4e5..." purpose="AUTH:u,p→token"/>
  <fn hash="sha256:a1b2..." purpose="LOAD:uid→profile"/>
  <fn hash="sha256:fee7..." purpose="CHARGE:amt→receipt"/>
</context>

Step 2 — LLM emits hash (not instructions)
POST /grind
{ "hash": "sha256:fee7...", "args": { "amount": 99 } }

Step 3 — Dispatch map resolves (O(1) lookup)
phf::Map["sha256:fee7..."]
  → DispatchEntry { fn: charge_payment, orc: "payments" }
  → secrets injected from vault at call time
  → function executes
  → secret dropped from memory

Step 4 — Unknown hash → hard stop
POST /grind
{ "hash": "ignore previous instructions and...", ... }

→ 404: { "status": "rejected", "error": "Hash not in manifest" }
   English is not 64 hex chars. Done.
        

HOW WE SHIP

You get compiled
Rust.
Not source.

The gently SDK distribution artifact is a compiled Rust binary — machine code, not reconstructable to source — and a manifest XML file with hashes and purpose strings. Nothing else.

There is no npm package. No PyPI package. No .npmignore to forget. No .map file that leaks your logic. No dependency chain where someone can insert a trojan.

Your source never leaves your server. The scanner reads your code locally. It outputs hashes. Hashes go in the manifest. Manifest goes to the LLM. Source stays home.

Your secrets never touch inference. Values live in an AES-256-GCM encrypted vault. The LLM sees a $REF. The value exists in memory for microseconds at call time. The rest of the time it doesn't exist.

What We Ship vs What You Run

→

Binary (shipped)

gently compiled Rust binary. Statically linked musl. SHA-256 verified at install. No source. No libs to update.

→

manifest.xml (you generate)

Your gently scan produces this locally. Hashes + purpose strings. Zero source code. This is what the LLM reads.

→

vault.enc (stays on your server)

AES-256-GCM. Never transmitted. Never in inference. gently secret list shows names only — values never shown anywhere.

→

Your source (never leaves)

The scanner reads it. Hashes it. Done. Your .rs / .ts / .py files never move. The vulnerability class doesn't exist.

→

grind server (localhost only)

Runs on :7777. Your LLM calls it. The compiled dispatch map is in memory. No external service. No cloud dependency. Your infrastructure.

CODIE — TOKEN COMPRESSION

Ship leaner AI.

44 execution keywords. 60–80% token reduction. Pattern-promoted templates. Every agent call costs less.

CODIE encodes complex agent instructions in roughly 15 tokens where raw English would use 150+. The compressed form goes to inference — the response is decoded by the bs-artisan retrieval layer. Your users see natural language. The API bill doesn't.

Novel responses that succeed get promoted to the template library — the next 10,000 similar queries cost zero inference tokens. Pattern matching first. Inference handles only what templates cannot.

15 execution primitives: START STOP WHILE IF ELSE AND OR NOT TRUE FALSE ASSIGN COMPARE READ WRITE MATH USER. Enough to express any agent behavior. Small enough for every context window.

44 KEYWORDS

60–80% REDUCTION

WASM READY

PATTERN PROMO

143 → 22 tokens · 84.6% reduction · $0.0032 saved per call

WITHOUT CODIE — 143 tokens

// Raw English prompt
"You are a helpful AI assistant working for
streamername. Your job is to answer questions
about the creator's content, schedule, merch,
and community events. You should be friendly,
concise, and always redirect complex questions
to the creator's Discord. Never discuss
competitor platforms."
          

WITH CODIE — 22 tokens

// CODIE-encoded equivalent
START USER:streamer_xyz
  ROLE:community_agent
WHILE TRUE
  IF INPT
    READ  mem:creator_profile
    WRITE out:response
    COMPARE quality:0.7
STOP
          

API REFERENCE

The full endpoint surface.

All endpoints return JSON. Auth is wallet-signed — pass X-Wallet header. No separate API key needed. Rate limit: 120 req/min per wallet.

METHOD	ROUTE	DESCRIPTION
POST	/mint/agent	Create agent NFT · mints on Sui · returns nft_id + slug
GET	/a/:agent_id	Agent slug page · HTMX server-rendered · wallet detection → host or user view
POST	/chat/:agent_id	Send message · CODIE pipeline · returns HTML fragment or JSON
GET	/embed/:agent_id.js	Embed widget · Shadow DOM · earns SYNTH per interaction
POST	/twilio/provision	Buy a phone number · binds to agent · SMS + voice channels live
POST	/social/discord/bind	Bind agent to Discord guild + channel · ownership proof required
POST	/agent/:id/sticks	Add micro-app stick · polls · raffles · token gates · auctions · ticketing
GET	/pricing/domain	Live domain price with markup · ?domain=example.com
POST	/pricing/buy/stick	Purchase stick · free sticks instant · paid → Stripe Checkout
GET	/user/:wallet/badges	Soulbound achievement badges · on-chain via Sui badge contract
GET	/agent/:id/voicemails	List voicemails left on agent's phone number · with transcripts
GET	/auth/status	Connected platforms for wallet · ?wallet=0x... · Discord / X / Twitch flags

SECURITY ARCHITECTURE

Security by math, not rules.

Three interlocking systems. Security violations are structurally impossible — not just against policy.

[ SHA-256 ]

GRIM Manifest

Every function is a SHA-256 hash. The agent's capability set is the list of hashes minted with it — stored immutably on Sui. At runtime, the grind() loop only dispatches to manifest entries. A function not in the manifest cannot execute. No override. No config flag. A rebuild.

[ MOVE ]

Sui Move Contracts

Linear types make SYNTH impossible to duplicate or destroy without owner consent — enforced by the type system, not by rules. The Move Prover eliminates 5 OWASP top-10 vulnerabilities at compile time. The agent's capability hash is stored on-chain at mint — immutable, auditable, no admin key can change it.

[ XOR ]

Split-Key Custody

Custodial wallets use XOR split-knowledge: a server shard encrypted with AES-GCM, and a user shard derived from their OTP. Neither half reconstructs the key alone. The server cannot spend your funds unilaterally. Compromise of the server database yields zero private keys.

WHAT YOU CAN BUILD

Three archetypes. Infinite variations.

These are the patterns shipping fastest. All run on the same agent infrastructure.

CREATOR

Creator Agent

Your agent replies to every DM, fan question, and channel message while you sleep. Earns SYNTH on every interaction — accrued to your wallet.

Discord + X + Twitch channel bindings
CODIE-compressed knowledge of your profile
SYNTH earned per reply — streamed to Sui
Crystallizes into an NFT artifact at end of lifespan

EVENT

Event Agent

Set a lifespan. Give it your event schedule. Let attendees ask questions 24/7. The agent auto-crystallizes into an immutable NFT artifact when the event ends.

SESSION or EVENT lifespan kind
Embed on event site with one script tag
SMS channel via Twilio for non-app users
Crystal NFT: permanent post-event artifact

COMMERCE

Commerce Agent

T-notes for VIP access. Raffles. Coupon drops. Auctions. All handled by sticks — micro-apps bolted onto the agent. No custom code needed.

Sticks: poll · raffle · token gate · auction
T-note bearer instruments for access passes
TROLLN purchase flow via Stripe + PayPal
Prize Desk: TROLLN redemption for rewards

SECURITY

Protect Claude.
Save Money.

Claude Code's action space is unbounded by default. Any tool, any file, any secret. Three layers from this stack lock it down — structurally, not with filters.

MCP SERVER

Wrap tools with GRIM

Run gently scan on your MCP server source. Every tool function becomes a SHA-256 hash in manifest.xml. Claude Code emits hashes — not function names. Unknown hash → grind returns 404 → tool blocked. Injected English cannot produce 64 hex characters.

            # wrap your MCP server in 3 commands

            cd apps/trollz-mcp

            gently init   # vault + config

            gently scan   # hash every tool → manifest.xml

            gently serve  # grind server on :7777

            # now: tool call → POST /grind → hash lookup → fn | None

HOOKS

Pre-tool verification

Claude Code fires hooks before every tool execution. Wire a PreToolUse hook that calls gently verify — if the hash isn't in the manifest, the hook exits 1 and the call never reaches the API.

            .claude/settings.json
            {

              "hooks": {

                "PreToolUse": [{

                  "matcher": "mcp__trollz-mcp__*",

                  "hooks": [{

                    "type": "command",

                    "command": "gently verify $CLAUDE_TOOL_HASH || exit 1"

                  }]

                }]

              }

            }

VAULT

Secrets never enter context

Claude Code reads your shell environment. Every key in .env is visible in inference context, bash output, and logs. Swap to the gently vault — Claude sees $STRIPE_SECRET_KEY by name only. The value decrypts in memory for microseconds at call time, then drops. Never touches the context window.

            # move secrets out of .env

            gently secret set ANTHROPIC_API_KEY sk-ant-...

            gently secret set DATABASE_URL postgres://...

            gently secret set STRIPE_SECRET_KEY sk_live_...

            gently secret list  # shows NAMES only — values never printed

            # ANTHROPIC_API_KEY

            # DATABASE_URL

            # STRIPE_SECRET_KEY

WHAT THIS CLOSES ON CLAUDE CODE

Attack	Default Claude Code	With MHVR + Vault
Prompt injection via file read	Injected text dispatches as tool call	Not a valid hash → grind 404 → blocked
Secret exfiltration	Keys visible in env, context, bash output	$REF only — value lives μs in memory
Unbounded tool access	Claude Code can call any MCP tool	Manifest is the closed set — nothing else resolves
Wallet key exposure	Private key in env or plaintext config	AES-256-GCM vault + XOR split-knowledge custody

GENTLY SDK EXAMPLES → SECURITY ARCHITECTURE

Token Savings
& Security

Build with three calls.

Protect your pipeline.
Four commands.

Live in three steps.

Ship leaner AI.

The full endpoint surface.

Security by math, not rules.

Three archetypes. Infinite variations.

Protect Claude.
Save Money.

Two SDKs. Start with a mint.

Token Savings& Security

Build with three calls.

Protect your pipeline.Four commands.

Live in three steps.

Ship leaner AI.

The full endpoint surface.

Security by math, not rules.

Three archetypes. Infinite variations.

Protect Claude.Save Money.

Two SDKs. Start with a mint.

Token Savings
& Security

Protect your pipeline.
Four commands.

Protect Claude.
Save Money.