🚀 gamgyul🍊 payment & Wallet SDK

Base 체인을 위한 올인원 결제 및 지갑 연동 SDK
멀티토큰 결제, 할인 시스템, 쿠폰, 화이트리스트를 하나의 SDK로

📋 목차

개요
왜 gamgyul🍊 SDK인가?
주요 기능
가격 정책
자주 묻는 질문 (FAQ)
실제 사용 사례
문의 및 시작하기
기술 스택
핵심 기능 상세
SDK 로드맵
코드 참조

개요

gamgyul🍊 payment & Wallet SDK는 Base 체인 기반 Web3 프로젝트를 위한 완전한 결제 및 지갑 연동 솔루션입니다.

복잡한 결제 로직, 지갑 연결, 할인 시스템, 쿠폰 관리 등을 직접 구현할 필요 없이, 몇 줄의 코드로 모든 기능을 통합할 수 있습니다.

🎯 타겟 고객

Web3 스타트업: 빠른 MVP 개발이 필요한 팀
NFT 마켓플레이스: 다양한 토큰 결제를 지원해야 하는 플랫폼
게임/엔터테인먼트 Dapp: 인앱 결제 시스템이 필요한 프로젝트
구독 서비스: Web3 기반 구독 결제를 구현하려는 서비스
프리랜서 개발자: 클라이언트 프로젝트에 빠르게 결제 기능 추가

주요 기능

gamgyul🍊 SDK는 Web3 결제 시스템의 모든 복잡함을 해결해줍니다:

🔌 지갑 연결

Farcaster 지갑 직접 인젝션: 미니앱 내에서 즉시 연결 가능
다중 지갑 동시 연결: 하나의 앱에서 여러 지갑을 동시에 관리
MetaMask, Trust Wallet, Rainbow, Phantom, Coinbase Wallet 등 8개 주요 지갑 자동 지원
ENS 아바타 및 PFP 자동 로드 (Farcaster/Base 네트워크 지원)
모바일 최적화 및 브라우저 지갑 자동 감지 (EIP-6963)
지능적 지갑 우선순위: 사용 환경에 따라 최적의 지갑 추천

💳 멀티토큰 결제

5가지 결제 모드: TM, USDC, ETH, HUNT, MT 등 다양한 토큰 지원
실시간 환율 및 자동 잔액 확인
스마트 스왑: 잔액 부족 시 자동 Uniswap 연동

🎫 할인 & 쿠폰 시스템

자동 할인 계산: 토큰별 + 프로모션 + 이벤트 할인
JWT 기반 보안 쿠폰: 중복 사용 방지
CSV 화이트리스트: 최대 10,000개 지갑 일괄 관리

🌍 다중언어 지원

영어, 한국어, 일본어, 중국어 완전 지원
CJK 언어 최적화: 자동 줄바꿈 및 반응형 텍스트

📊 간단한 통합

5분만에 설치: 기본 결제 모달 즉시 사용 가능
JSON 설정: 코드 수정 없이 토큰/할인 추가
TypeScript 지원: 100% 타입 안전성

왜 gamgyul🍊 SDK인가?

🏆 경쟁 우위

기능	gamgyul🍊 SDK	기존 솔루션
멀티토큰 결제	✅ 5가지 모드	❌ 단일 토큰만
지갑 연결	✅ Farcaster 인젝션 + 다중 지갑	❌ 단일 지갑만
할인 시스템	✅ 자동 계산	❌ 수동 구현
쿠폰 시스템	✅ JWT 기반	❌ 직접 구현
화이트리스트	✅ CSV 업로드	❌ 수동 관리
PFP 표시	✅ 자동 로드	❌ 직접 구현
Farcaster 통합	✅ 내장	❌ 별도 구현
다중언어 지원	✅ 영어/한/일/중	❌ 단일 언어만
실시간 환율	✅ 30초 갱신	❌ 정적 가격
Fallback 보호	✅ 자동 처리	❌ 수동 처리

💡 핵심 가치

개발 시간 단축: 2주 → 하루루
- 복잡한 결제 로직을 직접 구현할 필요 없음
- 지갑 연결, PFP 표시, 할인 계산 등 모든 기능 내장
검증된 안정성: 프로덕션 환경에서 검증
- FARCANA 타로 서비스에서 실제 사용 중
- 수백 건의 결제 처리 경험
유연한 커스터마이징: 프로젝트에 맞게 조정
- JSON 설정만으로 토큰 추가/제거
- 테마 시스템으로 UI 커스터마이징
- 필요한 기능만 선택적 사용
완벽한 타입 안전성: 100% TypeScript
- 모든 API가 타입 정의됨
- IDE 자동완성 지원
- 컴파일 타임 에러 방지

기술 스택

Frontend

React 18+: 최신 React 기능 활용
TypeScript: 100% 타입 안전성
wagmi: Web3 상태 관리
viem: 이더리움 유틸리티
Reown AppKit: 지갑 연결 (WalletConnect v2)
RainbowKit/OnchainKit: 선택적 지갑 라이브러리 지원
Farcaster SDK: 미니앱 연결
i18next: 다중언어 지원 (영어, 한국어, 일본어, 중국어)

Smart Contracts

ZapUniV4MCV2: Uniswap V4 스왑 + Mint Club V2 통합
PaymentOrchestrator: 결제 오케스트레이션 (향후)
ERC-20: 표준 토큰 인터페이스

Backend

Next.js 15: 서버 사이드 렌더링
Supabase: 데이터베이스 (화이트리스트, 쿠폰 관리)
JWT (jose): 쿠폰 세션 토큰

APIs

CoinGecko API: 실시간 토큰 가격
Mint Club V2: TM/MT 실시간 환율
Trust Wallet CDN: 토큰 로고 메타데이터
Uniswap API: 스왑 라우팅

핵심 기능 상세

1. 지갑 연동 & PFP 표시 [참조: 코드 1]

특징:

Farcaster 지갑 직접 인젝션: 미니앱 환경에서 별도 연결 없이 즉시 사용
다중 지갑 동시 관리: 하나의 세션에서 여러 지갑을 동시에 연결하고 전환
지능적 PFP 우선순위: Farcaster → Base ENS → 기본 아바타 순으로 자동 로드
실시간 지갑 상태 동기화: 연결된 모든 지갑의 잔액과 상태를 실시간으로 추적

2. 멀티토큰 결제 모달

자동 처리:

✅ 토큰 잔액 확인
✅ 결제 가능/불가능 토큰 자동 그룹화
✅ 할인 자동 계산 및 적용
✅ 실시간 환율 반영
✅ Zap 실패 시 안전한 Fallback

3. 할인 시스템

자동 적용:

기본 할인 + 프로모션 + 전역 프로모션 = 총 할인율
최대 50% 할인 제한
JSON 설정만으로 관리

4. 쿠폰 시스템

보안:

JWT 기반 1회용 세션 토큰
5분 만료 시간
Nonce 기반 중복 사용 방지

5. 화이트리스트 관리

Admin API
CSV 업로드
이벤트 리스트 조회

특징:

최대 10,000개 지갑 일괄 등록
이벤트별 그룹 관리
NFT 민팅 여부 선택 가능

6. 토큰 등록 [참조: 코드 6]

자동 처리:

Trust Wallet CDN에서 로고 자동 로드
CoinGecko에서 가격 자동 검증
우선순위에 따라 UI에 자동 표시

SDK 로드맵

Phase 1: Core SDK (Q1 2025) ✅

Phase 2: Advanced Features (Q2 2025)

Phase 3: Multi-Chain (Q3 2025)

Ethereum Mainnet 지원
Polygon 지원
Arbitrum 지원
Optimism 지원

Phase 4: Enterprise (Q4 2025)

White-label 솔루션
커스텀 스마트 컨트랙트 배포
멀티체인 자동 브릿징
고급 분석 도구

가격 정책

gamgyul🍊 SDK는 유연한 요금제로 프로젝트 규모에 맞게 선택할 수 있습니다:

🆓 Free Tier - 무료

기본적인 지갑 연결과 단일 토큰 결제를 무료로 사용하세요.

💼 Pro Tier - $99/월

스타트업과 중소 프로젝트를 위한 완전한 솔루션:

멀티토큰 결제 (5가지 모드)
자동 할인 시스템
쿠폰 및 화이트리스트 관리
월 10,000 트랜잭션
우선 이메일 지원

🏢 Enterprise Tier - $999/월

대규모 프로젝트를 위한 엔터프라이즈 솔루션:

무제한 트랜잭션
99.9% SLA 보장
24/7 전용 지원
화이트라벨 솔루션
맞춤 개발 및 온보딩

🎯 조기 액세스 혜택

현재 베타 기간 동안 3개월 무료 Pro Tier를 제공합니다!

자주 묻는 질문 (FAQ)

💰 비용은 어떻게 되나요?

Free Tier로 기본 기능을 무료로 시작하세요! Pro Tier는 $99/월부터 시작합니다.

🌐 어떤 블록체인을 지원하나요?

현재 Base 체인을 지원하며, 2026년 Q1에 Ethereum, Polygon, Arbitrum, Optimism을 추가할 예정입니다.

🔒 보안은 어떻게 되나요?

JWT 기반 쿠폰 시스템과 Nonce 기반 중복 방지로 안전합니다. 모든 결제는 스마트 컨트랙트로 처리됩니다.

📞 지원은 어떻게 받나요?

무료: Discord 커뮤니티와 GitHub Issues
Pro: 24시간 이내 이메일 지원

🎨 커스터마이징이 가능한가요?

네! JSON 설정만으로 토큰과 할인을 추가할 수 있습니다. Enterprise Tier에서는 완전한 화이트라벨도 지원합니다.

📈 트랜잭션 한계는 어떻게 되나요?

Pro Tier는 월 10,000회, Enterprise Tier는 무제한입니다. 체인 가스비 외에 추가 수수료는 없습니다.

🔑 Farcaster나 다른 지갑들을 동시에 사용할 수 있나요?

네! 다중 지갑 동시 연결을 지원합니다. Farcaster 미니앱에서는 지갑 직접 인젝션으로 별도 연결 과정 없이 즉시 사용할 수 있습니다.

실제 사용 사례

🎴 TreeME 서비스

월 1,000+ 결제 처리로 검증된 안정성:

99.5% 결제 성공률
15초 평균 결제 시간
4가지 토큰 지원

문의 및 시작하기

📧 연락처

이메일: jin@collieswork.xzy

🚀 지금 시작하세요!

3개월 무료 Pro Tier 베타 테스트 참여하기:

[조기 액세스 신청]
프로젝트 설명 제출
승인 후 즉시 사용 시작!


---

## 라이선스

- **Free Tier**: 무료 사용 (상업적 사용 가능)
- **Pro/Enterprise Tier**: Commercial License

---

## 코드 참조

### 코드 1: 지갑 연동 & PFP 표시
```typescript
import { WalletProvider, useWallet } from '@gamgyul/payment-sdk';

function App() {
  return (
    <WalletProvider
      projectId="your-reown-project-id"
      networks={[base]}
      farcasterEnabled={true}  // Farcaster 지갑 인젝션 활성화
      multiWallet={true}       // 다중 지갑 연결 허용
    >
      <YourApp />
    </WalletProvider>
  );
}

function YourComponent() {
  const { address, isConnected, user, connectedWallets } = useWallet();

  // 다중 지갑 관리
  const primaryWallet = connectedWallets?.[0];
  const farcasterWallet = connectedWallets?.find(w => w.type === 'farcaster');

  // 스마트 PFP 로드 (Farcaster 우선)
  const pfpUrl = farcasterWallet?.pfpUrl ||
                 user?.pfpUrl ||
                 primaryWallet?.pfpUrl ||
                 `https://effigy.im/a/${address}.svg`;

  return (
    <div>
      {isConnected && (
        <>
          <img src={pfpUrl} alt="Profile" />
          <p>{user?.username || farcasterWallet?.username || address}</p>

          {/* 다중 지갑 표시 */}
          {connectedWallets && connectedWallets.length > 1 && (
            <div className="wallet-list">
              {connectedWallets.map((wallet, index) => (
                <div key={index}>
                  {wallet.type}: {wallet.address.slice(0, 6)}...
                </div>
              ))}
            </div>
          )}
        </>
      )}
    </div>
  );
}

코드 2: 기본 통합

npm install @gamgyul/payment-sdk

// app.tsx
import { WalletProvider, PaymentModal } from '@gamgyul/payment-sdk';

function App() {
  return (
    <WalletProvider projectId="your-project-id">
      <PaymentModal
        isOpen={true}
        amount={5.0}
        onSuccess={(txHash) => console.log(txHash)}
      />
    </WalletProvider>
  );
}

코드 3: 고급 통합 (커스텀 토큰)

import { PaymentModal, TokenMetadata } from '@gamgyul/payment-sdk';

const customTokens: TokenMetadata[] = [
  {
    symbol: 'YOUR',
    name: 'Your Token',
    address: '0x...',
    chainId: 8453,
    decimals: 18,
    mode: 'direct',
    priority: 0,
    enabled: true,
    baseDiscount: 20,
  },
];

<PaymentModal
  tokens={customTokens}
  theme={{
    primary: '#9333EA',
    borderRadius: '12px',
  }}
  // ...
/>

코드 4: 쿠폰 시스템 통합

import { BenefitModal } from '@gamgyul/payment-sdk';

<BenefitModal
  isOpen={showCoupon}
  onSuccess={(sessionToken) => {
    // 무료 리딩 생성
    fetch('/api/readings/generate', {
      method: 'POST',
      body: JSON.stringify({
        sessionToken,
        // ...
      }),
    });
  }}
/>

코드 5: 화이트리스트 관리

// Admin API
import { uploadWhitelist, listWhitelists } from '@gamgyul/payment-sdk/admin';

// CSV 업로드
const result = await uploadWhitelist({
  eventName: 'Spring2025',
  csvData: `wallet_address,event_name,free_quota,enable_nft_mint
0x123...,Spring2025,1,true
0xabc...,Spring2025,5,false`,
  fid: '12345',
  walletAddress: '0x...'
});

// 이벤트 리스트 조회
const events = await listWhitelists({
  fid: '12345',
  walletAddress: '0x...'
});

코드 6: 토큰 등록 설정

// payment-tokens-main.json
{
  "tokens": [
    {
      "symbol": "YOUR",
      "name": "Your Token",
      "address": "0xYourTokenAddress",
      "chainId": 8453,
      "decimals": 18,
      "mode": "direct",
      "priority": 10,
      "enabled": true,
      "baseDiscount": 10,
      "logoUrl": "/asset/your-logo.png"
    }
  ]
}

커뮤니티 참여

gamgyul🍊 SDK는 활발한 커뮤니티를 통해 발전하고 있습니다. 여러분의 피드백과 제안을 환영합니다!

참여 방법:

피드백 제출: GitHub Issues를 통해 버그 리포트 및 기능 제안
문서 개선: 문서 오류 수정 및 개선 제안
사용 사례 공유: 여러분의 프로젝트에서 SDK를 어떻게 사용하는지 공유
커뮤니티 토론: Discord에서 다른 개발자들과 경험 공유

문의:

GitHub Issues: @gamgyul/payment-sdk
Discord: GAMGYUL Community

Made with ❤️ by gamgyul Team

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

🚀 gamgyul🍊 payment & Wallet SDK

📋 목차

개요

🎯 타겟 고객

주요 기능

🔌 지갑 연결

💳 멀티토큰 결제

🎫 할인 & 쿠폰 시스템

🌍 다중언어 지원

📊 간단한 통합

왜 gamgyul🍊 SDK인가?

🏆 경쟁 우위

💡 핵심 가치

기술 스택

Frontend

Smart Contracts

Backend

APIs

핵심 기능 상세

1. 지갑 연동 & PFP 표시 [참조: 코드 1]

2. 멀티토큰 결제 모달

3. 할인 시스템

4. 쿠폰 시스템

5. 화이트리스트 관리

6. 토큰 등록 [참조: 코드 6]

SDK 로드맵

Phase 1: Core SDK (Q1 2025) ✅

Phase 2: Advanced Features (Q2 2025)

Phase 3: Multi-Chain (Q3 2025)

Phase 4: Enterprise (Q4 2025)

가격 정책

🆓 Free Tier - 무료

💼 Pro Tier - $99/월

🏢 Enterprise Tier - $999/월

🎯 조기 액세스 혜택

자주 묻는 질문 (FAQ)

💰 비용은 어떻게 되나요?

🌐 어떤 블록체인을 지원하나요?

🔒 보안은 어떻게 되나요?

📞 지원은 어떻게 받나요?

🎨 커스터마이징이 가능한가요?

📈 트랜잭션 한계는 어떻게 되나요?

🔑 Farcaster나 다른 지갑들을 동시에 사용할 수 있나요?

실제 사용 사례

🎴 TreeME 서비스

문의 및 시작하기

📧 연락처

🚀 지금 시작하세요!

코드 2: 기본 통합

코드 3: 고급 통합 (커스텀 토큰)

코드 4: 쿠폰 시스템 통합

코드 5: 화이트리스트 관리

코드 6: 토큰 등록 설정

커뮤니티 참여

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Packages