💻Installation

Get Yuki402 running on your machine in under 5 minutes. Whether you're a developer looking to integrate autonomous payments or a crypto enthusiast wanting to experience the future firsthand—this guide has you covered.

⚡ Quick Install

TL;DR for the impatient:

git clone https://github.com/Yuki402-xyz/yuki402.git
cd yuki402
npm install
cp .env.example .env.local
# Add your OpenRouter API key to .env.local
npm run dev

Open http://localhost:3000 and you're live. That's it.

📋 Prerequisites

Before diving in, make sure you have:

Required

• Node.js 18.17+ - Download here

• npm or yarn - Comes with Node.js

• Git - Download here

• OpenRouter API Key - Get yours here

Recommended

• Web3 Wallet - MetaMask, Phantom, or Coinbase Wallet

• Some crypto - For testing payments (devnet works too!)

• Modern browser - Chrome, Firefox, Brave, or Edge

Check Your Setup

# Verify Node.js version (should be 18.17+)
node --version

# Verify npm
npm --version

# Verify Git
git --version

If any of these fail, install the missing tools first.

🚀 Step-by-Step Installation

1. Clone the Repository

git clone https://github.com/Yuki402-xyz/yuki402.git
cd yuki402

What this does: Downloads the entire Yuki402 codebase to your machine.

2. Install Dependencies

npm install

What this does: Installs all required packages (Next.js, React, Tailwind, Solana Web3.js, AI SDK, etc.)

This might take 2-3 minutes. Go grab a coffee ☕

3. Set Up Environment Variables

cp .env.example .env.local

Now open .env.local in your favorite editor and add your keys:

# OpenRouter API Key (REQUIRED)
OPENROUTER_API_KEY=sk-or-v1-your_api_key_here

# Solana RPC Endpoint (optional, defaults to devnet)
NEXT_PUBLIC_SOLANA_RPC_ENDPOINT=https://api.mainnet-beta.solana.com

# Yuki System Prompt (optional, has sensible defaults)
YUKI_SYSTEM_PROMPT="Your custom prompt here..."

Getting your OpenRouter API key:

1. Visit openrouter.ai

2. Sign up or log in

3. Go to Keys → Create New Key

4. Copy and paste into .env.local

Pro tip: Start with devnet for testing (free!), then switch to mainnet when you're ready.

4. Start the Development Server

npm run dev

You should see:

  ▲ Next.js 16.0.10
  - Local:        http://localhost:3000
  - Network:      http://192.168.x.x:3000

 ✓ Ready in 2.1s

5. Open in Browser

Visit http://localhost:3000

You should see:

• Yuki's landing page with the hero section

• "Launch App" button ready to go

• Beautiful animations and glass-morphism effects

If you see this, you're golden. Welcome aboard! 🎉

🔧 Advanced Setup

Using Yarn Instead of npm

yarn install
yarn dev

Using pnpm (Faster!)

pnpm install
pnpm dev

Custom Port

npm run dev -- -p 3001

Production Build

npm run build
npm start

Production mode optimizations:

• Minified JavaScript

• Optimized images

• Tree-shaken code

• Faster load times

🌐 Solana RPC Configuration

Free Public RPCs

Devnet (Testing):

NEXT_PUBLIC_SOLANA_RPC_ENDPOINT=https://api.devnet.solana.com

Mainnet (Production):

NEXT_PUBLIC_SOLANA_RPC_ENDPOINT=https://api.mainnet-beta.solana.com

Premium RPC Providers

For production and heavy usage, use a dedicated RPC:

Helius:

NEXT_PUBLIC_SOLANA_RPC_ENDPOINT=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY

Get Helius API key

QuickNode:

NEXT_PUBLIC_SOLANA_RPC_ENDPOINT=https://YOUR_ENDPOINT.quiknode.pro/YOUR_KEY/

Get QuickNode endpoint

Alchemy:

NEXT_PUBLIC_SOLANA_RPC_ENDPOINT=https://solana-mainnet.g.alchemy.com/v2/YOUR_KEY

Get Alchemy key

Why premium RPC?

• Higher rate limits

• Better reliability

• Faster responses

• Historical data access

🧪 Verify Installation

Test the Chat Interface

1. Click "Launch App"

2. You should see the chat interface

3. Try sending a message (no wallet needed for chat)

4. AI should respond within seconds

Test Wallet Connection

1. Install MetaMask or Phantom

2. Click "Connect Wallet" in the app

3. Approve the connection

4. Your wallet address should appear

Test a Mock Payment (Optional)

1. Connect wallet

2. Make sure you're on devnet

3. Get devnet SOL from faucet

4. Request: "Generate an OpenWeatherMap API key"

5. Approve the mock payment

6. Watch Yuki work her magic!

🐛 Common Issues

Port Already in Use

Error: listen EADDRINUSE: address already in use :::3000

Solution: Kill the process or use a different port

lsof -ti:3000 | xargs kill
# OR
npm run dev -- -p 3001

Module Not Found

Error: Cannot find module 'framer-motion'

Solution: Reinstall dependencies

rm -rf node_modules package-lock.json
npm install

API Key Not Working

Error: Invalid API key

Solution:

1. Verify key is correct in .env.local

2. Make sure there are NO quotes around the key

3. Restart the dev server (Ctrl+C, then npm run dev)

4. Check OpenRouter dashboard for key status

Environment Variables Not Loading

Solution:

1. File must be named exactly .env.local

2. File must be in project root (not in app/ folder)

3. Must restart dev server after changes

4. Check .gitignore includes .env.local

🚢 Next Steps

Now that Yuki is installed:

1. Quick Start Guide - Make your first autonomous payment

2. Configuration - Set up spending limits and preferences

3. Using the Chat - Master the AI interface

💡 Pro Tips

Development Workflow:

• Keep the dev server running while coding

• Hot reload updates instantly

• Check browser console for errors

• Use React DevTools for debugging

Environment Management:

• Never commit .env.local to git

• Use .env.example as template

• Different keys for dev/prod

• Rotate keys regularly

Performance:

• Use premium RPC for production

• Enable caching where possible

• Monitor API usage/costs

• Set appropriate rate limits

🆘 Need Help?

Installation Issues:

• Check Troubleshooting Guide

• Search GitHub Issues

• Email: [email protected]

Have Suggestions?

• Open a feature request on GitHub

• Tweet at @yuki402xyz

• Join the community discussions

---

Installed successfully? Head to the Quick Start Guide to make your first autonomous payment! ⚡