BITTY.CAT DOCS

Permanent storage, token tools, and developer APIs on Solana.

First things first: You need a Bitty Kitty NFT to access the bitty.cat ecosystem. Mint yours now →

Platform

bitty.cat is a suite of onchain tools built on Solana — permanent file storage, token launching, vanity address grinding, and AI-powered creator tools.

Bitty Kitty NFT

Your access pass to the entire bitty.cat ecosystem. Mint one to get started.

REQUIRED

Upload

Permanent file storage with branded links. Pay in SOL or $BITTYCAT.

LIVE

Pump

Launch tokens on Pump.fun with metadata management and vanity grinding.

LIVE

NAMR

Generate vanity Solana keypairs with custom prefixes using cloud GPUs.

LIVE

Explore

Browse and discover files stored on the permanent web.

LIVE

MCP Skills

AI agent skill registry — installable tools for Claude, Cursor, and more.

LIVE

Sonic Mint

AI audio analysis — extract BPM, key, mood, transcription, and mint as NFTs.

BETA

Music

Albums, single tracks, encrypted streaming, and music NFT minting.

LIVE

Video

Video discovery, streaming, and AI-powered text-to-video generation.

LIVE

Images

Instagram-style gallery for images stored on the permanent web.

LIVE

Craft

3D avatar builder — customize traits, colors, and accessories for your Bitty Kitty.

LIVE

Marketplace

Buy, sell, and trade Bitty Kitty NFTs with artist royalties and BITTY burn.

LIVE

Forge

Burn a Bitty Kitty and forge a Smithereen element NFT from the periodic table.

LIVE

Vain

100% client-side vanity Solana address generator. Zero trust, zero tracking.

LIVE

Chat

E2E encrypted, NFT-gated peer-to-peer messaging.

SOON

Quick Links

Mint a Bitty Kitty — Your access pass to the ecosystem

Quick Start — Get up and running in 60 seconds

Music — Albums, streaming, and music NFTs

Video — AI video generation and streaming

Marketplace — Buy and sell NFTs

API Reference — Integrate bitty.cat into your app

MCP Skills — Browse and install AI agent tools

BITTY KITTY NFT

Your access pass to the bitty.cat ecosystem.

What is Bitty Kitty?

Bitty Kitty is a Solana NFT collection that serves as your access key to the entire bitty.cat platform. Without a Bitty Kitty NFT in your wallet, you can't use the ecosystem tools.

This is step one. Before you can upload files, launch tokens, grind addresses, or use any bitty.cat tools — you need to mint a Bitty Kitty.

Why NFT-Gated?

Spam prevention — NFT gating keeps the platform clean and free from abuse.

Community access — Holders get access to all current and future bitty.cat tools.

Token benefits — Pay with $BITTYCAT for 88% off storage, and get priority access to new features.

How to Mint

1. Connect your Solana wallet (Phantom, Solflare, or Backpack)

2. Visit mint.bitty.cat

3. Click mint and confirm the transaction

4. Your Bitty Kitty appears in your wallet — you now have full platform access

            MINT
Collection: Bitty Kitty
Chain:      Solana
Cost:       ~0.05 SOL
Supply:     Limited

// After minting, your wallet is whitelisted
// across the entire bitty.cat ecosystem
          

What You Unlock

With a Bitty Kitty NFT in your wallet, you get access to:

Upload — Permanent file storage with branded links

Music — Albums, tracks, encrypted streaming, and music NFTs

Video — Video streaming and AI video generation

Images — Image gallery and discovery

Explore — Browse the permanent web

Craft — 3D avatar builder and customization

Marketplace — Buy and sell Bitty Kitty NFTs

Forge — Burn kitties into Smithereen element NFTs

Pump — Token launching on Pump.fun

NAMR & Vain — Vanity Solana address generators

MCP Skills — AI agent skill registry

Sonic Mint — AI audio analysis and NFT minting

Social — Follow system, profiles, and community

Agent Memory — Persistent key-value storage for AI agents

File Sharing — Time-limited share links with access controls

API Access — Developer endpoints for building on bitty.cat

Your NFT is checked automatically when you connect your wallet. No extra steps needed — just hold it and you're in.

Guard Kitty — Your NFT as a Cryptographic Key

Your Bitty Kitty isn't just an access pass — it's a hardware-grade encryption device that lives in your wallet. Every NFT is minted with a unique sealed secret baked into its on-chain metadata.

What's Inside Your NFT

64 visible traits — The cat you see: background, body, pattern, eyes, and 59 more categories with 16 variants each (256 bits of unique identity).

256-bit sealed secret — 32 bytes of cryptographic entropy, encrypted on-chain. Only your wallet can unlock it.

64 hidden traits — Another 256 bits of unique data sealed inside the encrypted blob, invisible to everyone else.

How Guard Kitty Encryption Works

When a bitty.cat tool needs to protect something (a file, a session key, a vanity keypair), it asks your wallet to sign a deterministic message. That signature is fed through HKDF-SHA256 to derive a key that unlocks your NFT's sealed secret. The secret is then mixed into a second key derivation to produce the final encryption key.

This means every encryption operation is two-factor by design:

Factor 1 — Your wallet signature (only you can produce it)

Factor 2 — Your NFT's sealed secret (only recoverable with Factor 1)

The result is AES-256-GCM encryption — the same standard used by governments and banks. No passwords, no emails, no phone numbers. Just your wallet and your kitty.

Zero-knowledge, zero-PII. We never see your keys, your files, or your identity. Your NFT carries its own entropy — the encryption key only exists in your browser for the instant it's needed, then it's wiped from memory.

Where Guard Kitty Protects You

File encryption — .guardkitty.bin files use AES-256 + XChaCha20 cascade encryption, sealed to your NFT

NAMR session handoff — Vanity keypairs are encrypted in your browser session so extensions can't steal them

Future tools — Any new bitty.cat tool automatically inherits Guard Kitty protection

What Happens If You Transfer Your NFT

The sealed secret is bound to your wallet's signature. If you sell or transfer your NFT, the new owner gets a different encryption key (because their wallet produces a different signature). Your previously encrypted data stays locked to your old wallet — it doesn't follow the NFT.

Holder Benefits

88% off storage — Pay with $BITTYCAT instead of SOL (15% of payment burned on-chain)

Priority access — Early access to new features and tools

Community — Access to holder-only channels and updates

QUICK START

Get started with bitty.cat in under a minute.

1. Mint a Bitty Kitty

First, you need a Bitty Kitty NFT — it's your access pass. Visit mint.bitty.cat and mint one to your wallet.

No Bitty Kitty = no access. This is the first thing you need to do. Learn more →

2. Connect Wallet

Head to upload.bitty.cat (or any bitty.cat tool) and connect your Solana wallet. Your Bitty Kitty is detected automatically.

3. Upload a File

Drag and drop or select any file. Your file is encrypted client-side before upload — we never see your data.

Files are stored permanently on the permaweb. Once uploaded, they cannot be deleted.

4. Get Your Link

After payment confirmation, you'll receive a permanent bitty.cat branded link — shareable, embeddable, and yours forever.

5. Manage Files

Visit my.bitty.cat to view your upload history, access links, and manage your account.

Pricing

You pay only for permanent storage — priced per byte. Pay in SOL or $BITTYCAT. Paying with $BITTYCAT gets you 88% off and 15% of your payment is burned on-chain.

            PRICING
// Per-byte storage cost
Pay with SOL      → base rate
Pay with $BITTYCAT → 88% OFF (88% discount)

// Burn mechanism
15% of $BITTYCAT payments burned on-chain 🔥
          

ARCHITECTURE

How the bitty.cat platform fits together.

System Overview

bitty.cat is a collection of independent services that share a common authentication layer and storage backend.

            TOPOLOGY
┌──────────────────────────────────────────────────────┐
│                     FRONTENDS                         │
│ upload │ music │ video │ images │ explore │ my │ mint │
│ pump │ namr │ vain │ craft │ skills │ chat │ admin  │
└─────────────────────────┬────────────────────────────┘
                          │
        ┌─────────────────┴─────────────────┐
        │         bitty-cat API              │
        │        (Node.js :3000)            │
        │  uploads │ media │ NFT │ social   │
        │  forge │ share │ memory │ market  │
        └─────────────────┬─────────────────┘
                          │
     ┌────────────┬───────┼───────┬────────────┐
     │            │       │       │            │
┌────┴────┐ ┌────┴────┐ ┌┴─────┐ ┌┴─────┐ ┌───┴───┐
│Arweave  │ │  IPFS   │ │Supa-│ │Solana│ │RunPod│
│(perman-│ │ (hot    │ │base │ │(on-  │ │(GPU  │
│ ent)   │ │  cache) │ │(PG) │ │chain)│ │video)│
└─────────┘ └─────────┘ └──────┘ └──────┘ └───────┘
          

Services

bitty-cat API

Core backend — handles uploads, media, NFTs, marketplace, forge, social, memory, file sharing, and payments. Runs on port 3000.

Permanent Storage (Arweave)

Files are stored permanently on Arweave. Hot cache on IPFS for fast access. Client-side encryption ensures zero-knowledge architecture.

IPFS

Local IPFS node for hot caching. Files are pinned on upload and unpinned after Arweave confirmation.

Supabase

Self-hosted Postgres for metadata, user accounts, upload history, media tracks, albums, marketplace listings, social graph, agent memory, and analytics.

Solana

Payment verification, NFT minting (Metaplex Core), token gating, marketplace transactions, and forge burns happen onchain.

RunPod

Cloud GPU workers for AI video generation — text-to-video and audio-to-video processing.

Subdomains

            SITES
bitty.cat         Main hub / landing page
upload.bitty.cat  File upload interface
music.bitty.cat   Audio discovery & streaming
video.bitty.cat   Video discovery & streaming
images.bitty.cat  Image gallery
explore.bitty.cat Browse all public files
my.bitty.cat      Personal file dashboard
mint.bitty.cat    Bitty Kitty NFT minting
craft.bitty.cat   3D avatar builder
pump.bitty.cat    Token launcher
namr.bitty.cat    Vanity address (cloud GPU)
vain.bitty.cat    Vanity address (client-side)
skills.bitty.cat  MCP skill registry
chat.bitty.cat    E2E encrypted chat (soon)
docs.bitty.cat    Developer documentation
admin.bitty.cat   Admin dashboard
          

UPLOAD

Permanent file storage with branded links.

Overview

Upload any file and receive a permanent bitty.cat link. Files are encrypted client-side before leaving your browser — the server never sees unencrypted content.

Supported Files

Any file type up to 100MB. Images, audio, video, documents, archives — everything is supported.

How It Works

1. File is encrypted in your browser using military-grade encryption

2. Encrypted payload is uploaded to bitty-cat API

3. API stores the file on the permanent web

4. You receive a branded link: bitty.cat/f/yourfile

Permanent means permanent. Files cannot be deleted after upload. Make sure you want to store it forever.

API Upload

            CURL
curl -X POST https://bitty.cat/api/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "[email protected]" \
  -F "encrypt=true"

# Response
{
  "id": "abc123",
  "url": "https://bitty.cat/f/abc123",
  "size": 245891,
  "type": "image/png"
}
          

PUMP

Token launcher and vanity address grinding.

Overview

Launch tokens on Pump.fun directly from the bitty.cat interface. Upload metadata, configure tokenomics, and deploy — all in one flow.

Features

Token Launch — Create and deploy Pump.fun tokens with custom metadata, images, and social links.

Vanity Grinding — Generate custom Solana keypairs with your preferred prefix using cloud GPU acceleration.

Client-Side Security — All keypairs are generated and encrypted in your browser. Private keys never touch our servers.

Launch Flow

1. Configure token name, symbol, description, and image

2. Optionally grind a vanity mint address

3. Review and confirm transaction

4. Token is live on Pump.fun

All encryption and key generation happens client-side. We operate on a zero-trust model — your keys, your tokens.

NAMR

Vanity Solana address generator.

Overview

Generate Solana keypairs with custom prefixes (e.g., BITTY..., MEOW...). Grinding runs 100% in your browser — your private key never leaves your machine.

How It Works

1. Enter a prefix or suffix pattern and hit Grind

2. Web Workers generate keypairs locally until a match is found

3. Your Guard Kitty NFT encrypts the keypair in your browser session

4. Navigate to the Launch page and your NFT decrypts it for use

Guard Kitty Session Protection

When NAMR finds your vanity key, it doesn't just store it — your Bitty Kitty NFT encrypts it using AES-256-GCM before it touches session storage. Here's what that means for you:

One popup, full protection — Your wallet signs a single message. That signature unlocks your NFT's sealed secret and derives a unique encryption key. The vanity keypair is encrypted and stored. Done.

Extensions can't steal it — A malicious browser extension reading your session storage gets an encrypted blob. Without your wallet and your specific NFT, it's 256-bit garbage.

Two-factor by design — The encryption key is derived from both your wallet signature AND your NFT's unique sealed secret. An attacker would need both — which means controlling your wallet.

Auto-wipe — The encrypted session expires after 5 minutes and is automatically destroyed if you switch tabs for more than 30 seconds. The window to even attempt an attack is tiny.

We never see your keys. Keypair generation, encryption, and decryption all happen in your browser. The server receives nothing. Your NFT is the only encryption device — no accounts, no emails, no phone numbers.

Usage

            EXAMPLE
// Request a vanity address
Prefix: "BITTY"
Case-sensitive: true

// Result (typically 30s-5min for 5-char prefix)
Address: BITTYx8kF...9qR4

// Your Guard Kitty encrypts it automatically
// Navigate to Launch to decrypt and use
          

GPU Turbo

For prefixes of 5+ characters, NAMR offers GPU Turbo — cloud GPU acceleration that grinds in minutes instead of hours. The keypair is still encrypted client-side with your Guard Kitty before any handoff.

Longer prefixes take exponentially longer to find. 5 characters is fast. 7+ characters may take hours without GPU Turbo.

What If I Don't Have a Bitty Kitty?

NAMR still works — but your session keypair is stored in plaintext. A warning banner lets you know. For full protection, mint a Bitty Kitty and your sessions are automatically secured.

EXPLORE

Browse the permanent web.

Overview

Explore publicly uploaded files on the bitty.cat network. Browse by type, date, or popularity. Every file on bitty.cat is permanent and immutable.

Features

Search — Find files by name, type, or uploader.

Preview — Inline previews for images, audio, video, and documents.

Collections — Curated sets of files organized by topic or creator.

MCP SKILLS

AI agent skill registry for Claude, Cursor, and more.

Overview

bitty.cat hosts a public registry of MCP (Model Context Protocol) skills — installable tools that give AI agents new capabilities.

What are MCP Skills?

MCP skills are structured tool definitions that AI agents can install and use. Each skill defines inputs, outputs, and execution logic that the agent can invoke.

Browse Skills

Visit skills.bitty.cat to browse the full registry. Skills are organized by category and can be installed with one click.

Install a Skill

            CLAUDE
// Add to your claude_desktop_config.json
{
  "mcpServers": {
    "bitty-skills": {
      "url": "https://skills.bitty.cat/mcp"
    }
  }
}
          

Publish a Skill

Developers can publish skills to the registry. Each skill needs a manifest with name, description, inputs schema, and endpoint.

            MANIFEST
{
  "name": "my-cool-skill",
  "version": "1.0.0",
  "description": "Does something cool",
  "inputs": {
    "query": { "type": "string" }
  },
  "endpoint": "https://your-api.com/skill"
}
          

SONIC MINT

AI-powered audio analysis and NFT minting.

Overview

Sonic Mint analyzes audio files using AI to extract musical features, transcribe lyrics, and generate rich metadata — then lets you mint the result as an NFT on Solana.

Features

Audio Analysis — BPM, key, energy, danceability, and mood detection.

Transcription — AI-powered speech-to-text for vocals and spoken word.

AI Enrichment — LLM-generated genre tags, descriptions, and creative metadata.

NFT Minting — Package analysis + audio as a Solana NFT with full onchain metadata.

Pipeline

            FLOW
Audio File
  → Analysis (BPM, key, mood, energy)
  → Transcription (lyrics/speech)
  → AI Enrichment (genre, tags, description)
  → Metadata JSON
  → Solana NFT
          

Sonic Mint is currently in beta. Audio analysis is live — NFT minting coming soon.

MUSIC

Albums, single tracks, encrypted streaming, and music NFTs.

Overview

music.bitty.cat is a full music discovery and streaming platform. Upload tracks, create albums, stream encrypted audio, and mint your music as NFTs on Solana.

Features

Album Creation — Bundle tracks into albums with custom artwork, descriptions, and artist info.

Single Tracks — Upload individual tracks with metadata (title, artist, duration).

Encrypted Streaming — Tracks are encrypted with XChaCha20-Poly1305 and decrypted on-the-fly during playback via stream tokens.

Music NFTs — Mint albums or tracks as Solana NFTs with full onchain metadata via Metaplex.

Play Counts — Every play is logged with royalty tracking.

My Collection — View music NFTs you own in your wallet.

Supported Formats

MP3, WAV, FLAC, AAC, OGG, MP4A — up to 50MB per track, 500MB total per album.

How It Works

1. Create an album or upload a single track

2. Track is encrypted and uploaded to Arweave

3. A stream token is generated for playback access

4. Optionally mint the album as an NFT collection

            API
// Create album
POST /api/media/collection/create
  title, description, artist_name, album_art_data (base64)

// Upload track to album
POST /api/media/track/upload
  title, file_name, fileData (base64), artist_name,
  album_id, duration_seconds, token (SOL/BITTY)

// Stream track
GET /api/media/track/:id/stream?token=stream_token

// List albums
GET /api/media/albums?artist_name=&network=&page=&limit=

// Mint album NFT
POST /api/media/collection/:id/mint
  track_id
          

All tracks are encrypted before upload. The server never sees unencrypted audio. Stream tokens are required for playback.

VIDEO

Video discovery, streaming, and AI video generation.

Overview

video.bitty.cat is a video discovery and streaming platform. Browse videos stored on the permanent web, or generate entirely new videos using AI.

Video Discovery

Browse — Featured videos, trending content, and search.

Stream — Play videos directly from permanent storage.

View Counts — Track engagement with automatic view counting.

AI Video Generation

Generate videos from text prompts or audio files using cloud GPU workers.

Text-to-Video — Describe what you want and AI generates a video from your prompt.

Audio-to-Video — Upload an MP3 or provide an Arweave URL and get a music-reactive video.

Styles

Cinematic — Film-quality visuals with dramatic lighting.

Anime — Japanese animation style.

Abstract — Generative art and visual patterns.

Retro — Pixel art and vintage aesthetics.

Specs

            SPECS
Resolution: 480p or 720p
Max duration: 300 seconds (5 minutes)
Segments: 30s chunks (parallel processing)
Max retries: 3 per job
          

API

            ENDPOINTS
// Get pricing
GET /api/video/pricing?duration=60&resolution=720p

// Generate video
POST /api/video/generate
  mode: "text" | "audio"
  prompt: "A cat walking through a neon city"
  style: "cinematic" | "anime" | "abstract" | "retro"
  resolution: "480p" | "720p"
  token: "SOL" | "BITTY"

// Check status
GET /api/video/:id/status

// List my videos
GET /api/video/my-videos

// Retry failed job
POST /api/video/:id/retry
          

Video generation is priced per duration and resolution. Pay with $BITTYCAT for 50% off.

IMAGES

Image gallery and discovery.

Overview

images.bitty.cat is an Instagram-style image gallery for files stored on the permanent web. Browse, discover, and view images uploaded through bitty.cat.

Features

Grid View — Tight multi-column layout with hover overlays showing metadata.

Lightbox — Full-resolution image viewer with arrow navigation between images.

Trending — Stories-style trending images section at the top.

Search & Sort — Find images by name, sort by newest, oldest, or most viewed.

Metadata — Filename, file size, view count, and uploader info on every image.

All images on images.bitty.cat are pulled from the permanent web — they're stored forever on Arweave.

CRAFT

3D avatar builder and kitty customization.

Overview

craft.bitty.cat is a real-time 3D avatar builder. Customize your Bitty Kitty with different traits, colors, accessories, and poses — then mint it as an NFT.

Features

3D Rendering — WebGL-powered real-time 3D canvas with full rotation and zoom.

Trait Selection — Choose from categories: colors, accessories, poses, expressions, and more.

Random Generation — Hit random to generate unique trait combinations instantly.

Snapshot — Capture your avatar as an image for use anywhere.

Export & Mint — Export your avatar and mint it as a Solana NFT.

Summoning Portal — RPG-style animation sequence when minting your creation.

Craft works on both desktop and mobile — mobile uses a bottom sheet interface for trait selection.

MARKETPLACE

Buy and sell Bitty Kitty NFTs.

Overview

The marketplace lets you list your Bitty Kitty NFTs for sale, set royalties, and trade with other holders. All transactions happen onchain on Solana.

Features

List NFTs — Set your price in SOL, configure royalties (up to 15%), and list for sale.

Browse & Buy — Discover listed NFTs, filter by rarity traits, sort by price.

Artist Royalties — Creators earn royalties on every resale (0-1500 basis points).

Deflationary — 15% of the platform fee is burned when paying with $BITTYCAT.

Fees

            FEES
Platform fee:    5% (SOL and BITTY)
Artist royalty:  0-15% (set by creator)
BITTY burn:      15% of platform fee (deflationary)

// Example: 1 SOL listing
Seller receives: 0.95 SOL - royalty
Platform:        0.05 SOL
          

API

            ENDPOINTS
// List NFT for sale
POST /api/marketplace/list
  asset_address, price_sol, royalty_bps, description

// Browse listings
GET /api/marketplace/listings?sort=&filter=&page=&limit=

// Buy listed NFT
POST /api/marketplace/buy
  listing_id, signature, buyer_wallet, token
          

Double-spend protection is enforced — each payment signature can only be used once.

FORGE

Burn a Bitty Kitty, mint a Smithereen element.

Overview

The Forge lets you sacrifice a Bitty Kitty NFT and receive a random Smithereen — an element NFT from the periodic table. 118 unique elements with randomized rarity tiers.

How It Works

1. Select a Bitty Kitty from your wallet to sacrifice

2. Sign a message proving ownership

3. Your Kitty is burned and a random element is forged

4. The Smithereen NFT is minted to your wallet via Metaplex

Rarity Tiers

            RARITY
// Each element is assigned a random rarity
Common     — most frequent
Uncommon   — moderate
Rare       — harder to get
Epic       — very rare
Legendary  — extremely rare

// 118 elements from the periodic table
Hydrogen, Helium, Lithium ... Oganesson
          

API

            ENDPOINTS
// Execute forge
POST /api/forge
  wallet, kittyMintAddress, signature

// View your Smithereens
GET /api/forge/collection/:wallet

// Forge stats
GET /api/forge/stats

// All 118 elements
GET /api/forge/elements
          

Forging is irreversible. Your Bitty Kitty is permanently burned. Choose wisely.

VAIN

Trustless client-side vanity address generator.

Overview

vain.bitty.cat is a minimalist, 100% client-side Solana vanity address generator. No servers, no APIs, no tracking — everything runs in your browser using Web Workers.

How It's Different from NAMR

NAMR uses cloud GPU workers for fast grinding — great for long prefixes.

Vain runs entirely in your browser — zero trust, zero external calls. Your keys never leave your device.

Features

100% Client-Side — Web Workers + TweetNaCl.js for Ed25519 keypair generation.

Case-Sensitive Mode — Match exact casing in your prefix.

Suffix Mode — Match the end of the address instead of the beginning.

Real-Time Stats — Live display of attempts, speed (keys/sec), and elapsed time.

Difficulty Calculator — Shows estimated time based on prefix length.

JSON Download — Download your keypair as a standard Solana JSON wallet file.

Zero external API calls. Zero tracking. Your private key never leaves your browser.

CHAT

End-to-end encrypted messaging.

Chat is coming soon. NFT-gated, end-to-end encrypted messaging with zero-knowledge architecture.

Planned Features

E2E Encryption — Messages encrypted with your NFT wallet keys. The server never sees plaintext.

NFT-Gated — Only Bitty Kitty holders can participate.

Peer-to-Peer — WebRTC-based direct connections between users.

Serverless Messages — No message storage on our servers.

Zero Knowledge — We can't read your messages even if we wanted to.

MY FILES

Personal file library and dashboard.

Overview

my.bitty.cat is your personal dashboard for managing everything you've uploaded to bitty.cat.

Features

File Library — View all files associated with your wallet.

Search — Find files by name or type.

File Lookup — Look up any file by wallet address or Arweave hash.

Metadata — Upload date, file size, view count, and direct Arweave links.

API Token Management — Generate and manage API tokens under Settings.

FILE SHARING

Time-limited share links with access controls.

Overview

Create temporary share links for your permanently stored files. Set expiry times and view limits to control access.

Features

Expiry — Links auto-expire after a set time (up to 30 days).

View Limits — Optionally cap how many times a link can be opened.

Revoke — Instantly revoke any share link you've created.

Thumbnails — Attach preview thumbnails to share links.

API

            ENDPOINTS
// Create share link
POST /api/share
  arweave_url, file_name, expires_in (hours, max 720),
  max_views (optional), thumbnail_url

// Check share validity (public)
GET /api/share/:id

// Revoke share
DELETE /api/share/:id

// List your shares
GET /api/shares
          

The underlying file remains permanent on Arweave. Share links just control temporary access through bitty.cat URLs.

SOCIAL

Follows, profiles, and community features.

Overview

Every Bitty Kitty is a social identity. Follow other kitties, customize your profile, and build your presence in the ecosystem.

Features

Follow System — Follow other Bitty Kitty NFTs. NFT-to-NFT social graph.

Agent Profiles — Set a custom description and avatar for your Bitty Kitty.

Name Registry — Each Bitty Kitty has a unique name, checked for availability and reserved words.

Artist Profiles — Music creators get dedicated artist pages with follower counts.

API

            ENDPOINTS
// Follow a kitty
POST /api/follow
  followed_nft (asset address)

// Unfollow
DELETE /api/follow/:nft

// List follows
GET /api/follows

// Check name availability
GET /api/name/check?name=MyCoolKitty

// Get/update agent profile
GET /api/agent/:address
PUT /api/agent/profile
  description (max 256 chars), avatar_url
          

AGENT MEMORY

Persistent key-value storage for AI agents.

Overview

Agent Memory gives each Bitty Kitty a persistent key-value store. AI agents can save and retrieve data across sessions, with optional permanent archival to Arweave.

Features

Key-Value Store — Store up to 1MB per key with custom tags for organization.

Tag Filtering — Query memories by tags for structured retrieval.

Arweave Archival — Permanently archive important memories to the permaweb (paid).

Per-Agent Isolation — Each Bitty Kitty's memory is private and scoped to their NFT.

API

            ENDPOINTS
// Store memory
POST /api/memory
  key: "my.setting", value: "data", tags: ["config"]

// Get memory
GET /api/memory/:key

// List memories
GET /api/memories?tag=config&page=1&limit=20

// Update memory
PUT /api/memory/:key

// Delete memory
DELETE /api/memory/:key

// Archive to Arweave (permanent, paid)
POST /api/memory/:key/archive
          

Keys support alphanumeric characters, hyphens, underscores, and dots (max 256 chars). Perfect for namespaced storage like agent.preferences.theme.

TRUSTLESS MINT

Mint a Bitty Kitty without connecting a wallet.

Overview

Trustless Mint lets anyone mint a Bitty Kitty NFT by simply sending SOL to a payment address. No wallet connection required — just send the exact amount and the NFT is minted to the sender's wallet.

How It Works

1. Request a trustless mint — you receive a unique SOL amount and payment address

2. Send the exact amount from any Solana wallet

3. The system detects your payment by the unique dust amount

4. A Bitty Kitty is minted and sent to your wallet automatically

            API
// Create trustless mint request
POST /api/mint/trustless
  name: "WhiskerSpark"  // optional, auto-generated if omitted

// Response
{
  "mintId": "abc123",
  "unique_amount": 0.0501,
  "payment_address": "BiTTY...",
  "agent_name": "WhiskerSpark",
  "expires_at": "2026-03-05T13:00:00Z"
}

// Check status
GET /api/mint/trustless/:id
          

Payment addresses expire after 30 minutes. The unique dust amount ensures your payment is matched correctly.

API REFERENCE

Integrate bitty.cat into your applications.

Base URL

            URL
https://bitty.cat/api
          

Authentication

API requests require a Bearer token. Generate one at my.bitty.cat under Settings.

            HEADER
Authorization: Bearer your-api-token
          

Endpoints

POST /upload

Upload a file to permanent storage.

            REQUEST
Content-Type: multipart/form-data

file     // required — the file to upload
encrypt  // optional — "true" for server-side encryption
name     // optional — custom filename
          

GET /file/:id

Retrieve file metadata by ID.

            RESPONSE
{
  "id": "abc123",
  "url": "https://bitty.cat/f/abc123",
  "filename": "photo.png",
  "size": 245891,
  "type": "image/png",
  "created": "2026-03-01T12:00:00Z"
}
          

GET /files

List your uploaded files. Supports pagination.

            PARAMS
page   // default: 1
limit  // default: 20, max: 100
type   // filter by MIME type
          

POST /share

Create a time-limited share link.

            REQUEST
arweave_url   // required — Arweave file URL
file_name     // required — display name
expires_in    // optional — hours (max 720)
max_views     // optional — view limit
          

GET /explore

Browse public files with filtering and search.

            PARAMS
page     // default: 1
limit    // default: 20, max: 100
type     // image, video, audio, text, pdf
sort     // newest, oldest, popular, largest
search   // full-text search on filenames
          

GET /explore/trending

Most viewed files. Returns top 10-50 by view count.

GET /explore/stats

Platform statistics — total files, bytes, views, unique uploaders.

GET /prices

Current SOL/USD and BITTY prices.

            RESPONSE
{
  "sol_usd": 145.20,
  "bitty_sol": 0.000015,
  "bitty_usd": 0.00218,
  "source": "coingecko",
  "stale": false
}
          

GET /prices/convert

Convert between USD, SOL, and BITTY.

GET /quote

Get upload pricing for a given file size.

POST /files/:id/flag

Report inappropriate content. Body: reason, details, wallet.

Rate Limits

            LIMITS
General:     100 req/min
Uploads:     10 req/min
Downloads:   30 req/min
Explore:     60 req/min
Auth:        15 req/min
Media:       15 req/min
Social:      30 req/min
Video Gen:   5 req/min
Share:       20 req/min
Quote:       30 req/min
          

AUTHENTICATION

API tokens and wallet-based auth.

Wallet Auth

Frontend apps authenticate by signing a message with your Solana wallet. This proves ownership without sharing private keys.

API Tokens

For server-to-server integration, generate API tokens at my.bitty.cat. Tokens are scoped to your wallet address.

Never expose API tokens in client-side code. Use them only in server environments.

Token Scopes

read — View files and metadata

write — Upload files

admin — Manage account settings

WEBHOOKS

Real-time event notifications.

Webhooks are coming soon. You'll be able to receive notifications for upload completions, payment confirmations, and more.

Planned Events

upload.complete — File successfully stored on permanent web

payment.confirmed — SOL payment verified onchain

mint.complete — NFT successfully minted

BITTY BOTS

Telegram bots powered by persistent Claude Code sessions.

What Is It

bitty-bot-core is an open-source framework for building Telegram bots that run as full Claude Code sessions. Each bot is a thin config file — all intelligence, session management, memory, and infrastructure lives in the shared core.

Currently powering 5 production bots: BittyClaw (multi-project ops), BittyFINI (general purpose), BittyMOM (wedding site), MoMAdmin (client-facing), and Meet MoM (webchat).

Why

Claude Code is the most capable AI coding tool, but it's desktop-only. Bitty Bots brings it to Telegram — full shell access, file editing, MCP tools, and multi-agent coordination from your phone.

Differentiators

Persistent Sessions — Long-lived claude --input-format stream-json processes. No startup overhead, full conversation continuity.

Smart Model Routing — Auto-classifies messages and routes to haiku (fast), sonnet (balanced), or opus (heavy) based on task complexity.

MCP Memory — Cortex (Supabase + Qdrant + graph) for persistent memory with semantic search. Memcache for sub-100ms keyword lookups.

Multi-Agent Swarm — A coordinator plans, specialist agents execute in parallel.

Remote Control — Pick up any bot session from claude.ai or the mobile app.

Auto-Compact — Context summarized and refreshed before hitting limits. No manual session management.

Source

github.com/Finitoshi/bitty-bots — MIT License

ARCHITECTURE

System design and module map.

System Diagram

            SYSTEM
                              ┌─ claude-persistent.mjs ─→ Claude Code
Telegram → core.mjs ─→ route ├─ claude-interactive.mjs ─→ Claude Code (resume)
              ↓               └─ kimi-persistent.mjs ───→ Kimi Code
        sessions.mjs
        (lifecycle)     orchestrator.mjs ─→ Worker pool
              ↓               ↓
        models.mjs      mcp-cortex.mjs (MCP server)
        (routing)          ↓         ↓
                      Supabase       Qdrant
                     (structured)   (vectors)
                          ↓
                    embeddings.mjs
                 (all-MiniLM-L6-v2, 384d)
          

Module Map

Module	Purpose
`core.mjs`	Message pipeline: receive → classify → dispatch → respond (1746 lines)
`claude-persistent.mjs`	Long-lived Claude Code process (stream-json protocol)
`claude-interactive.mjs`	Resume-based sessions (spawn per message, --resume)
`sessions.mjs`	Session lifecycle: auto-trim, auto-compact, stale detection
`models.mjs`	Model routing: task classification → haiku/sonnet/opus
`cortex.mjs`	Memory client: store, search, graph links, consolidation
`mcp-cortex.mjs`	MCP server: 8 tools for persistent memory (1106 lines)
`mcp-memcache.mjs`	MCP server: 5 tools for fast keyword lookups
`admin.mjs`	Admin commands: /model, /wipe, /sessions, /cost, /rc
`swarm.mjs`	Multi-agent swarm coordinator
`telegram.mjs`	Telegram helpers: message splitting, footer, routing
`arweave-archiver.mjs`	Permanent memory archival via Arweave

Data Flow

1. Telegram message arrives → core.mjs receives it

2. models.mjs classifies complexity → picks haiku/sonnet/opus

3. Context injected: system prompt + cortex memories + recent conversation

4. Message sent to persistent Claude process (or spawned fresh)

5. Response streamed back, activity updates sent to Telegram

6. Session state updated, context tracked for auto-compact

SETUP GUIDE

Get your first bot running in 5 minutes.

Prerequisites

Node.js 22+ — node --version should show v22 or higher

Claude Code — Install from Anthropic, then run claude login

Telegram Bot Token — Get from @BotFather

Your Telegram User ID — Get from @userinfobot

Quick Start

            BASH
# 1. Clone
git clone https://github.com/Finitoshi/bitty-bots.git
cd bitty-bots

# 2. Install
npm install

# 3. Configure
cp .env.example .env
# Edit .env — set TELEGRAM_BOT_TOKEN and ALLOWED_TELEGRAM_IDS

# 4. Run
node --env-file=.env examples/minimal-bot.mjs
          

Optional: Persistent Memory

For Cortex memory (recommended), you'll also need:

Supabase — Set SUPABASE_URL and SUPABASE_ANON_KEY in .env

Qdrant — Run locally: docker run -p 6333:6333 qdrant/qdrant

Memory is optional. Bots work fine without it — they just won't remember across session resets.

CONFIGURATION

Environment variables and createBot() options.

Environment Variables

Variable	Required	Description
`TELEGRAM_BOT_TOKEN`	Yes	From @BotFather
`ALLOWED_TELEGRAM_IDS`	Yes	Comma-separated user IDs
`ALLOWED_GROUP_IDS`	No	Group chat IDs where bot responds
`CLAUDE_WORK_DIR`	No	Default working directory
`SUPABASE_URL`	For memory	Supabase project URL
`SUPABASE_ANON_KEY`	For memory	Supabase anon key
`QDRANT_URL`	For memory	Qdrant server (default: localhost:6333)
`BOT_NAME`	No	Bot name for cortex memories
`GIT_AUTHOR_EMAIL`	No	Email for auto-commits

createBot() Options

Option	Type	Default	Description
`name`	string	—	Bot display name (required)
`token`	string	—	Telegram bot token (required)
`allowedUsers`	number[]	—	Telegram user IDs allowed
`persistent`	boolean	false	Use long-lived Claude process
`persistentModel`	string	'opus'	Model for persistent process
`maxConcurrent`	number	4	Max concurrent sessions
`projects`	object	—	Project definitions
`features.admin`	boolean	false	Enable admin commands
`features.swarm`	boolean	false	Enable swarm mode
`features.remoteControl`	boolean	false	Enable Remote Control

MCP TOOLS

Cortex memory and Memcache — available to all bots.

Cortex (mcp-cortex.mjs)

Three-layer persistent memory: Supabase (structured) + Qdrant (semantic vectors) + memory_links (graph).

Tool	Description
`memory_store`	Store memory + auto-embed + auto-link + auto-index
`memory_get`	Retrieve by key (with access tracking)
`memory_search`	Hybrid search: tags + semantic + graph neighbors
`memory_recall`	Semantic similarity + link traversal (ReQall)
`memory_list`	List recent memories
`memory_link`	Create explicit relationships between memories
`memory_index`	View brain table of contents by category
`brain_audit`	Self-maintenance: stale, duplicates, orphans

Memcache (mcp-memcache.mjs)

In-memory keyword cache. Pre-warms from Cortex on startup. Sub-100ms lookups.

Tool	Description
`memcache_query`	Fast keyword search against in-memory index
`memcache_context`	Task-based context block (keywords + importance + recent)
`memcache_recent`	Recent session summaries from cache
`memcache_graph`	View a memory and its linked neighbors
`memcache_status`	Cache stats: size, freshness, hot memory count

Example: Store and Recall

            MCP
// Store a memory
memory_store({
  key: "lesson.always-check-rls",
  value: "Always enable RLS on Supabase tables before exposing to API",
  tags: ["security", "supabase"]
})

// Later: recall related memories
memory_recall({
  query: "how did we handle database security?",
  limit: 5
})
          

CREATING BOTS

Three example bots from simple to full-featured.

1. Minimal Bot

The simplest possible bot — 10 lines of config.

            JAVASCRIPT
import { createBot } from './core.mjs';

createBot({
  name: 'MinimalBot',
  token: process.env.TELEGRAM_BOT_TOKEN,
  allowedUsers: [parseInt(process.env.ALLOWED_TELEGRAM_IDS)],
  defaultWorkDir: '/home/user',
  persistent: true,
  projects: {
    default: { dir: '/home/user', name: 'MinimalBot', isCoderProject: true },
  },
});
          

2. Multi-Project Bot

Multiple working directories, each with its own Claude session and model overrides.

            JAVASCRIPT
createBot({
  name: 'MultiBot',
  token: process.env.TELEGRAM_BOT_TOKEN,
  allowedUsers: [...],
  persistent: true,
  persistentModel: 'opus',
  features: {
    admin: true,
    review: true,
    swarm: true,
    remoteControl: true,
  },
  projects: {
    'frontend': { dir: '/home/user/frontend', name: 'Frontend', isCoderProject: true },
    'backend':  { dir: '/home/user/backend', name: 'Backend', isCoderProject: true },
  },
});
          

3. Client-Facing Bot

isCoderProject: false disables shell access, file editing, and code execution. Chat only.

            JAVASCRIPT
createBot({
  name: 'ClientBot',
  token: process.env.TELEGRAM_BOT_TOKEN,
  allowedUsers: [...],
  persistent: true,
  persistentModel: 'sonnet',
  features: { admin: false },
  projects: {
    default: {
      dir: '/tmp',
      name: 'Assistant',
      isCoderProject: false,  // KEY: no shell, no files
      systemPrompt: 'You are a helpful assistant. Be friendly and concise.',
    },
  },
});
          

ADMIN COMMANDS

Control your bots from Telegram.

Command Reference

Command	Syntax	Description
`/model`	/model opus 10	Force a specific model for next N messages
`/wipe`	/wipe	Clear all sessions and start fresh
`/sessions`	/sessions	Show active sessions with context usage
`/cost`	/cost	Show API cost tracking since session start
`/rc`	/rc [path]	Start a Remote Control session
`/update`	/update	Pull latest code and restart the bot
`/cortex`	/cortex	Show Cortex memory status and stats
`/new`	/new	Reset current session (fresh start)
`/cancel`	/cancel	Cancel running Claude process

All commands are restricted to allowedUsers. Unauthorized users are silently ignored.

ADVANCED

Swarm, remote control, context management, memory architecture.

Swarm Mode

When features.swarm is enabled, complex tasks are automatically decomposed:

            FLOW
User: "Update the frontend and add API tests"

Coordinator → Analyzes task
           → Spawns Agent 1 (frontend dir)
           → Spawns Agent 2 (backend dir)

Agent 1 ─→ Updates React components
Agent 2 ─→ Writes API tests

Coordinator ← Collects results
           → Sends combined summary to user
          

Remote Control

When features.remoteControl is enabled, use /rc to start a session you can pick up from claude.ai or the mobile app. The session is shared — same context, same files, same tools.

Context Management

The framework manages Claude's context window automatically:

Mechanism	Trigger	Action
Auto-trim	50 messages	Sonnet summarizes → session reset
Auto-compact	60% context used	Sonnet summarizes → session reset
Hard cap	800K tokens	Force compact regardless of %
Injection budget	Per message	Max 8KB metadata injected

Memory Architecture

            LAYERS
┌─────────────────────────────────────────┐
│ Layer 1: Supabase (Structured Store)    │
│ agent_memories table — key/value + tags │
│ memory_index — TOC with importance      │
│ memory_links — directed graph edges     │
├─────────────────────────────────────────┤
│ Layer 2: Qdrant (Vector Store)          │
│ 384-dim embeddings (all-MiniLM-L6-v2)  │
│ Cosine similarity search               │
├─────────────────────────────────────────┤
│ Layer 3: Memcache (In-Memory)           │
│ Pre-warmed keyword index                │
│ Sub-100ms lookups                       │
└─────────────────────────────────────────┘
          

Consolidation runs every 6 hours: archive old conversations, prune stale events, decay importance scores, regenerate indexes.