Docs
How this thing is built
Each system is isolated so the simulation layer can be replaced by real execution without rebuilding the app.
Systems
Holder eligibility
Reads $PET balance for the connected wallet and compares it to an admin-set threshold (token amount or USD value). Eligibility controls wake/sleep, never ownership.
AI decision system
Personality profiles drive entry appetite, sizing, stop-out and signal preference. The language layer composes thoughts and call reasoning from personality plus live context — the swap point for a hosted model.
Market data system
A provider interface with a demo Solana-style feed today; Jupiter or Birdeye drop in behind the same interface with no UI changes.
Simulation engine
Opens, marks and closes paper positions against live prices. Every result carries audit metadata.
Real execution engine
Implements the same interface but is deliberately unimplemented. Signing would run server-side through managed keys, never in a browser.
NFT system
One PET NFT per creature, permanently owned by the spawning wallet. Mint and pet wallet addresses link to the explorer.
System states
DEMO
Seeded population and a synthetic market feed. Nothing is persisted.
SIMULATION
Real market data, paper positions, full audit metadata. Current default.
LIVE
Real execution. Off by default and gated behind admin plus server-side key management.
Security
- User wallets never hand over private keys. Connection is read-only plus signature requests.
- No private keys, API secrets, service keys or signing credentials are exposed to the browser.
- No secrets in frontend environment variables.
- If PET-controlled wallets are introduced, signing happens in server-side key management only.
- A simulated transaction is never displayed as an on-chain trade.
Data model
| table | columns |
|---|---|
| users | id, created_at, primary_wallet |
| wallets | id, user_id, address, chain, verified_at |
| pets | id, number, name, owner_wallet, pet_wallet, mint_address, status, personality, mood, level, xp, stage, created_at |
| pet_ownership | pet_id, wallet_address, from_at, to_at |
| eligibility_checks | id, wallet_address, balance, threshold, mode, eligible, checked_at |
| traits | id, pet_id, trait_key, acquired_at |
| xp_events | id, pet_id, amount, reason, multiplier, at |
| thoughts | id, pet_id, text, source, at |
| calls | id, pet_id, token, token_address, direction, conviction, reason, result_pct, at |
| positions | id, pet_id, token, entry_price, exit_price, size_sol, pnl_sol, pnl_pct, mode, opened_at, closed_at |
| activity | id, pet_id, kind, text, mode, meta, at |
| evolutions | id, pet_id, stage, note, at |
| nft_metadata | pet_id, mint_address, uri, attributes, minted_at |
| config | key, value, updated_by, updated_at |
This build runs the full system client-side against a demo feed so every flow is verifiable. Connecting a hosted database and server-side agent loop swaps the data source only.