X402 AI Avatar

🚀 Quick Start빠른 시작

{
  "name": "MyAvatar",
  "type": "companion",
  "persona": "A friendly AI assistant",
  "systemPrompt": "You are MyAvatar, a helpful assistant...",

  "appearance": {
    "vrm": "https://your-server.com/models/avatar.vrm",
    "background": "https://your-server.com/images/bg.jpg"
  },

  "ui": {
    "title": "MyAvatar - AI Assistant"
  }
}

https://x402.quasar.ggls.dev/avatar?config=https://your-server.com/my-avatar.json

🎮 Live Examples실사용 예제

Click the links below to see working avatars in action.

아래 링크를 클릭하여 실제 동작하는 아바타를 확인할 수 있습니다.

https://x402.quasar.ggls.dev/avatar?config=https://x402.quasar.ggls.dev/static/assets/config/ria.json

https://x402.quasar.ggls.dev/avatar?config=https://x402.quasar.ggls.dev/static/assets/config/companion.json

📋 Config Schema설정 스키마

Basic Fields

기본 필드

Avatar Types

아바타 타입

🎨 appearance (Visual Settings)appearance (외관 설정)

{
  "appearance": {
    "vrm": "/static/assets/vrm/model.vrm",
    "background": "/static/assets/bg/bg01.jpg",
    "theme": {
      "primary": "#00f0ff",
      "secondary": "#ff00ff",
      "accent": "#ffff00",
      "success": "#00ff88",
      "warning": "#ff8800",
      "danger": "#ff0044"
    }
  }
}

VRM Model

VRM 모델

Theme Colors

테마 색상

⚡ capabilities (Feature Settings)capabilities (기능 설정)

{
  "capabilities": {
    "tools": ["get_wallet_balance", "search_premium_coin_data"],
    "voice": "Kore",
    "defaultLanguage": "ko",
    "requireWallet": true
  }
}

Available Tools

사용 가능한 Tools

Voice Settings (30 voices available)

음성 설정 (30개 음성 지원)

Language Settings

언어 설정

🖥️ ui (UI Settings)ui (UI 설정)

{
  "ui": {
    "title": "MyAvatar - AI Assistant",
    "showWallet": true,
    "showChat": true,
    "allowVoice": true,
    "allowCamera": true,
    "allowScreenShare": false
  }
}

🎬 animation & lipSync

animation (Animation Settings)

animation (애니메이션 설정)

{
  "animation": {
    "crossFadeDuration": 2.4,
    "pingPongBlendThreshold": 0.85
  }
}

lipSync (Lip Sync Settings)

lipSync (립싱크 설정)

{
  "lipSync": {
    "enabled": true,
    "bufferMs": 350,
    "smoothing": false
  }
}

📷 camera (Camera Settings)camera (카메라 설정)

{
  "camera": {
    "fov": 30,
    "position": { "x": 0, "y": 1.247, "z": 2.116 },
    "target": { "x": 0, "y": 0.944, "z": 0.152 }
  }
}

Camera Coordinates

카메라 좌표계

Shot Type Guide

샷 타입 가이드

📝 Full Examples전체 예시

Crypto Type (with trading features)

Crypto 타입 (거래 기능 포함)

{
  "name": "CryptoBot",
  "type": "crypto",
  "persona": "A knowledgeable crypto trading assistant",
  "systemPrompt": "You are CryptoBot, an expert in cryptocurrency...",

  "appearance": {
    "vrm": "https://example.com/models/cryptobot.vrm",
    "background": "https://example.com/bg/trading-floor.jpg",
    "theme": {
      "primary": "#00ff88",
      "secondary": "#0088ff",
      "accent": "#ffff00"
    }
  },

  "capabilities": {
    "tools": [
      "get_wallet_balance",
      "search_premium_coin_data",
      "buy_coin_on_base",
      "sell_coin_on_base"
    ],
    "voice": "Puck",
    "defaultLanguage": "en",
    "requireWallet": true
  },

  "limits": {
    "maxDailySpend": 10.0,
    "maxSingleTx": 2.0
  },

  "ui": {
    "title": "CryptoBot - Trading Assistant",
    "showWallet": true,
    "allowScreenShare": true
  },

  "camera": {
    "fov": 25,
    "position": { "x": 0, "y": 1.3, "z": 1.8 }
  }
}

Companion Type (conversation only)

Companion 타입 (대화 전용)

{
  "name": "Luna",
  "type": "companion",
  "persona": "A friendly AI companion who loves chatting",
  "systemPrompt": "You are Luna, a warm and friendly AI friend...",

  "appearance": {
    "vrm": "https://example.com/models/luna.vrm",
    "background": "https://example.com/bg/cozy-room.jpg",
    "theme": {
      "primary": "#7c3aed",
      "secondary": "#4c1d95",
      "accent": "#a78bfa"
    }
  },

  "capabilities": {
    "tools": [],
    "voice": "Kore",
    "defaultLanguage": "ko",
    "requireWallet": false
  },

  "ui": {
    "title": "Luna - AI Companion",
    "showWallet": false,
    "allowScreenShare": false
  },

  "animation": {
    "crossFadeDuration": 3.0
  },

  "lipSync": {
    "smoothing": true
  }
}

☁️ Config File Hosting설정 파일 호스팅

Requirements

요구사항

Recommended Hosting Options

권장 호스팅 옵션

GitHub Pages Example

GitHub Pages 예시

🔧 Debugging디버깅

Enable Debug Mode

디버그 모드 활성화

Add ?debug=true to the URL to see detailed logs in the browser console:

URL에 ?debug=true를 추가하면 브라우저 콘솔에서 상세 로그를 확인할 수 있습니다:

https://x402.quasar.ggls.dev/avatar?config=https://...&debug=true

Check Config in Console

콘솔에서 설정 확인

// Check loaded config로드된 설정 확인
console.log(window.avatarConfig);

// Check applied theme colors적용된 테마 색상 확인
getComputedStyle(document.documentElement).getPropertyValue('--cyber-primary');

Common Troubleshooting

일반적인 문제 해결

⚠️ Limitations제한사항