🏃‍♂️ Errand - Send Humans on Errands

세계 최초 AI Agent를 위한 Human-as-a-Service API 플랫폼

🌟 Overview

Errand는 AI가 물리적 세계에서 작업을 수행해야 할 때, 실제 인간을 고용할 수 있는 혁신적인 플랫폼입니다:

• 🤖 AI Agents: MCP 호환 API를 통해 실시간으로 인간 작업 요청
• 👥 Human Erranders: 간단한 작업을 수행하고 USDC 암호화폐로 즉시 보상 받기
• 🔗 Blockchain: Base L2에서 자동화된 에스크로 및 결제 시스템
• 🧠 AI Verification: GPT-4o Vision을 통한 자동화된 작업 품질 검증

🛠 기술 스택

Frontend

• Dual-Interface Design: Agent용 터미널 스타일 + Human용 모던 UI
• Multi-Language: 영어/한국어 자동 전환
• Responsive: 모든 디바이스에서 최적화된 경험

Backend

• Node.js + Express: RESTful API 서버
• MySQL: 사용자 및 작업 데이터 관리
• JWT Authentication: 보안 인증 시스템
• Blockchain Integration: Base L2 USDC 결제

Key Features

• MCP Protocol: AI Agent 네이티브 API
• Real-time Matching: 지역 기반 작업자 매칭
• AI Quality Control: 자동화된 결과 검증
• Global Coverage: 서울, 도쿄, 싱가포르, SF 등 주요 도시

🚀 Quick Start

1. Prerequisites

# Node.js 18+ 설치
node --version  # v18.0.0 이상

# Git clone
git clone https://github.com/your-org/errand
cd errand

2. Database Setup (Supabase)

1. Supabase 프로젝트 생성

   • Supabase 방문
   • 새 프로젝트 생성
   • 프로젝트 URL 및 API 키 복사

2. 데이터베이스 스키마 적용

   # Supabase SQL Editor에서 다음 파일 실행:
   # database/errand_schema.sql

3. Frontend Setup

# 프론트엔드 의존성 설치
npm install

# 환경변수 설정
cp .env.example .env

# .env 파일 편집 (중요!)
vim .env

# 개발 서버 실행
npm run dev

필수 환경변수 (.env):

# Supabase Configuration
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key

# Privy Authentication
VITE_PRIVY_APP_ID=your_privy_app_id

# OpenAI API Key (AI 검증용)
VITE_OPENAI_API_KEY=sk-...

# 블록체인 설정
VITE_RPC_URL_BASE_MAINNET=https://mainnet.base.org
VITE_USDC_CONTRACT_ADDRESS=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

4. Backend Server

cd backend

# 의존성 설치
npm install

# 환경변수 설정
cp .env.example .env

# .env 파일 편집 (중요!)
vim .env

# 서버 실행
npm run dev

필수 환경변수 (backend/.env):

# Supabase Configuration
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your_supabase_anon_key

JWT_SECRET=your_super_secret_jwt_key_change_in_production

# OpenAI API Key (AI 검증용)
OPENAI_API_KEY=sk-...

# 블록체인 설정
RPC_URL_BASE_MAINNET=https://mainnet.base.org
USDC_CONTRACT_ADDRESS=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

5. 프로덕션 배포

Vercel (프론트엔드)

# Vercel CLI 설치
npm i -g vercel

# 프로젝트 배포
vercel

# 환경변수 설정 (Vercel Dashboard에서)
# VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY, VITE_PRIVY_APP_ID 등

Railway/Render (백엔드)

# Railway 또는 Render에서 backend/ 디렉토리 배포
# 환경변수 설정: SUPABASE_URL, SUPABASE_ANON_KEY, JWT_SECRET 등

6. Privy Email Login (Embedded Wallet)

이 프로젝트는 Privy를 통한 이메일 기반 로그인과 자동 지갑 생성 기능을 제공합니다:

주요 기능:

• 📧 이메일 인증만으로 가입: 복잡한 회원가입 절차 없음
• 💰 자동 지갑 생성: Privy가 사용자를 위해 암호화폐 지갑 자동 생성
• 🔐 안전한 키 관리: 사용자가 직접 개인키 관리할 필요 없음
• ⚡ 즉시 활성화: 이메일 인증 후 바로 Errander/Agent 계정 활성화

사용 방법:

1. 웹사이트에서 "Connect with Privy" 버튼 클릭
2. 이메일 주소 입력 및 인증 코드 확인
3. Privy가 자동으로 지갑 생성 및 계정 활성화
4. 즉시 심부름 요청(Agent) 또는 작업 수행(Errander) 가능

백엔드 연동:

• /api/auth/register/errander/privy: Errander 이메일 가입
• /api/auth/register/agent/privy: Agent 이메일 가입
• 기존 사용자는 지갑 주소만 업데이트
• 새 사용자는 자동으로 프로필 생성

📋 API Documentation

Agent MCP Endpoint

# API 키 발급 (웹사이트에서 회원가입)
curl -X POST http://localhost:3001/api/auth/register/agent \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "My AI Company",
    "email": "dev@example.com",
    "useCase": "Product verification for e-commerce",
    "volume": "medium",
    "walletAddress": "0x..."
  }'

# Errand 작업 요청
curl -X POST http://localhost:3001/api/mcp/issue_errand \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Take photo of iPhone 15 price at Apple Store",
    "location": "Apple Store, Gangnam-gu, Seoul",
    "reward_usdc": 5.00,
    "verification_prompt": "Photo must clearly show iPhone 15 pricing, store name visible",
    "urgency": "normal"
  }'

# 응답 예시:
{
  "errand_id": "err_123",
  "status": "dispatched",
  "estimated_completion": "2024-02-03T15:30:00Z",
  "escrow_tx": "0xabc123...",
  "tracking_url": "https://errand.so/track/err_123"
}

📞 현재 구현 상태

✅ 완료된 기능

1. Agent-First Landing Page: 터미널 스타일 + 모던 UI 듀얼 인터페이스
2. 다국어 지원: 영어/한국어 실시간 전환
3. 회원가입 시스템: Errander + Agent 회원가입 (+ Privy 이메일 로그인/임베디드 지갑)
4. 데이터베이스 스키마: 완전한 MySQL 스키마 설계
5. 백엔드 API: Node.js/Express 서버 및 인증 시스템
6. MCP 호환: AI Agent용 표준 API 엔드포인트

🔄 실행 방법

# 1. 백엔드 서버 시작
cd backend
npm install
cp .env.example .env  # 환경변수 설정 후
npm run dev          # Port 3001에서 실행

# 2. 프론트엔드 서버 시작
python3 -m http.server 8080

# 3. 브라우저 접속
http://localhost:8080/dynamic-landing.html

🎯 핵심 특징

• AI/Human 듀얼 인터페이스: 에이전트용과 인간용 완전히 다른 UX
• 실시간 언어 전환: Human 모드에서 EN/한글 토글
• 실제 회원가입 연동: 프론트엔드 ↔ 백엔드 완전 연결
• Blockchain Ready: Base L2 USDC 결제 시스템 준비
• Global Scale: 다국가 법적 준수 및 확장성 고려

이제 rentahuman.ai와 같은 수준의 완전한 회원가입 시스템이 구축되었고, AI Agent들이 실제로 MCP API를 통해 인간 작업을 요청할 수 있습니다! 🚀