What it is
Token Tails links three loops. Shelters register rescued cats, and AI turns each one into a
collectible character. Players collect, feed, stake, and play with those cats across pixel
platformers, a match-3 mode and the 3D stealth game Catnip Heist, earning Tails (rescue points with no cash
value) and catnip. Anyone can buy an AI portrait of their
own pet or a card pack, and purchases flow back to shelter partners. Ownership is recorded as NFTs
on Stellar.
Repository
| Path | What | Stack |
|---|
backend/ | REST API: auth, cats, blessings, shelters, games, payments, AI generation, cron | NestJS 9, MongoDB, Stripe, Stellar SDK, OpenAI, Gemini |
client/ | Website, game shell, portrait funnel, feed, marketplace; also the mobile web bundle | Next.js 16, React 19, Phaser 4, Capacitor 7, Stellar Wallets Kit |
catnip-heist/ | Catnip Heist, built into the client and hosted on /heist | three.js, Vite |
cms/ | Admin console for shelters and staff | Next.js 16, Firebase Auth, TinyMCE |
contracts/ | Soroban NFT contracts (production), SKALE ERC-721s, faucets, archived prototypes | Rust, Solidity, Node |
shelter-rail/ and ShelterSplit | Shelter payout contracts (ShelterSplit, DonateRouter) on seven EVM chains (Arc, Tempo, Arbitrum, Avalanche, Base, Robinhood Chain, Monad), their Foundry tests, and the donate SDK and widget | Solidity 0.8.24, Foundry, plain JS |
docs/ | Project documentation | Markdown |
extra/ | Traction figures and the settlement rail proposal | Markdown |
Quick start
# API
cd backend && cp .env.example .env && npm install && npm run dev # :3005
# Website
cd client && cp .env.example .env.local && npm install && npm run dev # :3000
# Admin
cd cms && cp .env.example .env.local && npm install && npx next dev --turbo -p 3001 # :3001
Full setup, environment variables, and gotchas are in docs/DEVELOPMENT.md.
Documentation
| Read this | When you need |
|---|
| Architecture | The big picture: components, domain, auth, request flows |
| Development | To run things locally |
| Deployment | To ship the API, web apps, CDN assets, or store builds |
| Backend, API, Data model | Server internals, every endpoint, every collection |
| Client, Games, Mobile | The web app, the Phaser games, Capacitor builds |
| CMS | The admin console |
| Contracts | Chains, deployed addresses, faucets, licensing |
| History | How the project got here |
Highlights
- AI pipeline: OpenAI classifies a rescued cat's look and writes its story; Gemini paints its avatar and 4K themed pet portraits.
- Five game modes on Phaser 4, including an 80-level platformer and a 30-level match-3 with per-level leaderboards.
- Dual currency: Tails as rescue points, catnip as capped competitive score, plus an airdrop progression system.
- Payments through Stripe (Checkout and Payment Elements), Stellar (XLM and USDC) and a crypto checkout (USDC, EURC, USDC.e and USDG on seven EVM chains), all verified on the server.
- Shelter payouts: sponsored treats, wallet gifts and an x402 agent endpoint pay through ShelterSplit, with a public payouts page and on-chain receipts. Live on mainnet on seven chains since Oct 7, 2026, with testnet copies for trying it out.
- One codebase for web, iOS, and Android.
Traction
Figures and sources are in extra/traction.md.
License
This repository is commercially licensed. See COMMERCIAL_LICENSE.md.
The contracts/ folder carries additional license files; see
docs/CONTRACTS.md.
The ShelterSplit contract, its tests and scripts in contracts/shelter-split/
and the shelter-rail/ SDK are MIT licensed; see the LICENSE file in each folder.
