Stacks Wrapped 2025

Your on-chain year in review. A "Spotify Wrapped" style summary for Stacks wallets showing transaction activity, fees paid, sBTC rewards, and more.

Quick Start

# Install dependencies
npm install
pip install -r requirements.txt

# Set up environment
cp .env.example .env
# Add your HIRO_API_KEY to .env

# Run locally
npm run dev

Visit http://localhost:3000 to see your Stacks Wrapped.

Architecture

api/
  wrapped.py          # Vercel serverless endpoint

src/
  wallet_wrapped.py   # Core wrapped stats generation
  hiro.py             # Hiro API client
  config.py           # Configuration
  http_utils.py       # HTTP caching, retry logic

pages/
  wrapped.tsx         # Main UI (wallet connect, stats, share card)
  index.tsx           # Redirect to /wrapped

Deployment (Vercel)

npm run build
npx vercel deploy --prod

Environment Variables

Variable	Required	Description
HIRO_API_KEY	Yes	Hiro Stacks API key
AUTH_PASSWORD_SALT	Optional	Password auth salt
AUTH_PASSWORD_HASH	Optional	Password auth hash
AUTH_SESSION_SECRET	Optional	Session secret

API

GET /api/wrapped?address={STX_ADDRESS}&year=2025

Returns:

{
  "address": "SP...",
  "year": 2025,
  "stats": {
    "total_transactions": 42,
    "total_fees_stx": 1.234,
    "sbtc_rewards_earned": 0.00123,
    "first_tx_date": "2025-01-15",
    "last_tx_date": "2025-12-01",
    ...
  }
}

Development

make setup        # Create venv + install deps
make test         # Run pytest
make lint         # Black + Ruff

License

MIT