README.md

---

🌟 Overview

Resonate is an AI-native music platform that uses AI, agent interfaces, and blockchain rails as product primitives, not afterthoughts. Artists upload releases, split songs into stems, and sell licensed assets in stablecoin. Listeners get a full music app with an AI DJ, marketplace, and wallet-native purchases. AI agents discover, quote, and buy stems over HTTP with x402. No account, no OAuth, just curl + USDC + a signed receipt.

The human studio, storefront API, x402 payment flow, and MCP interface are peers over the same on-chain catalog. Three audiences, one catalog:

• Artists: upload releases, mint stems as NFTs, price per-license type (personal / remix / commercial), earn royalties via on-chain payment splitter.
• Listeners: full music app: player, library, playlists, marketplace, AI DJ, curator-resolved disputes. Wallet-native purchases. You own what you buy.
• Agents: storefront endpoints, licensing-aware quotes, x402 HTTP payments, machine-readable purchase receipts. No account required.

---

⚡ Key Capabilities

• Programmable stems: AI-separated 6-stem assets (vocals, drums, bass, guitar, piano, other) as the core monetizable unit · Upload flow
• x402 commerce: machine-to-machine stem purchases over HTTP with USDC settlement and structured receipts · x402 payments
• MCP tools: catalog.search, stem.quote, stem.download over Streamable HTTP at /mcp · MCP server
• Resonate Shows: escrow-backed fan campaigns that turn city-level demand into booking signals · Shows
• AI DJ: taste-constrained agent runtime with commerce-aware recommendations · Agent commerce
• Smart accounts: ERC-4337 Kernel accounts with session keys for gasless UX · Account abstraction
• Marketplace: on-chain stem trading with licensing tiers and stablecoin settlement · Contracts
• Community curation: dispute flows and curator-resolved content quality signals · Curation

See the feature catalog for the full index of implemented, partial, planned, and retired capabilities.

---

🏗️ Architecture

flowchart LR
  Studio["Human Studio<br>Next.js"] --> API["NestJS API<br>modular backend"]
  Agents["Agents<br>OpenAPI + MCP + x402"] --> API
  API --> Catalog["Catalog, pricing,<br>rights, library"]
  API --> Commerce["Marketplace, Shows +<br>x402 stablecoin settlement"]
  API --> Runtime["AI DJ + agent runtime"]
  API --> Ingestion["Upload + stem processing"]
  API --> Remix["Remix Studio +<br>AI generation"]
  Commerce --> Chain["Smart accounts +<br>Resonate contracts"]
  Ingestion --> Worker["Demucs worker"]
  Remix --> SAW["Stable Audio worker<br>GPU, scale-to-zero"]
  Catalog --> Data["Postgres, Redis,<br>GCS, Pub/Sub"]
  Runtime --> Data
  Worker --> Data

Resonate deploys as a full-stack music and agent-commerce system: Cloud Run services, Pub/Sub pipelines, Cloud SQL, Redis, GCS, ERC-4337 smart accounts, and a Terraform-managed GCP edge. Application CI publishes immutable images; resonate-iac applies infrastructure releases.

→ Application architecture · Deployment architecture

---

🚀 Quick Start

For the full development setup guide with detailed explanations, see Getting Started.

Prerequisites

Tool	Install
Node.js 22.12+	nodejs.org or nvm install 22
Docker	docker.com/get-started
Make	Pre-installed on macOS/Linux; Windows: use WSL
Foundry (contracts)	getfoundry.sh

Forked Sepolia (recommended)

# Install dependencies
npm install -g npm@11.14.1
cd contracts && ./scripts/install-deps.sh
cd ../backend && npm ci
cd ../web && npm ci --legacy-peer-deps
cd ../desktop && npm ci
cd ..

# Start infrastructure + worker + chain fork + contracts
export SEPOLIA_RPC_URL=https://sepolia.drpc.org
make dev-up
make worker-gpu
make local-aa-fork
make deploy-contracts

# Start services (separate terminals)
make backend-dev     # NestJS API on port 3000
make web-dev-fork    # Next.js on port 3001 (chain 11155111, local RPC)

Local-Only (offline fallback)

make dev-up
make worker-gpu
make contracts-deploy-local

make backend-dev     # port 3000
make web-dev-local   # port 3001 (chain 31337)

Stop & Clean

make db-reset        # Reset database
make dev-down        # Stop Postgres, Redis, Pub/Sub, Demucs worker
make local-aa-down   # Stop Anvil + Alto

---

📖 Documentation

Document	Description
User Guide	In-app manual at /help — how to use Resonate (all personas)
Getting Started	Full development setup guide
Feature Catalog	Index of all platform capabilities
Project Specification	Vision, architecture, and roadmap
Deployment Architecture	GCP, smart accounts, blockchain, x402 topology
Environment Variables	App runtime and provider configuration
Local AA Development	Account abstraction setup
Demucs Worker	GPU stem separation setup
x402 Payments	Machine-to-machine stem purchases
MCP Server	Agent tool discovery and setup
Core Contracts	Stem NFT and marketplace contracts
Troubleshooting	Common issues and fixes
Contributing	Contribution guidelines

---

🛠️ Tech Stack

Layer	Technology
Frontend	Next.js 15, TanStack Query, Viem/Wagmi
Backend	NestJS, Prisma, BullMQ, GCP Pub/Sub, PostgreSQL
Blockchain	Solidity, Foundry, ERC-4337, ZeroDev
AI	Demucs (htdemucs_6s), Vertex AI
Infrastructure	Docker, Redis, GCP Pub/Sub, GitHub Actions

---

📄 License

MIT © 2024-2026