AppKit 개요
AppKit은 브라우저 확장, 모바일 지갑, 릴레이 지갑의 연결 경로를 하나의 인터페이스로 제공합니다. 연결이 끝나면 AppKit Types의 WalletConnection에서 계정과 체인을 확인하고, 같은 AppKit 인스턴스로 요청·서명·잔액 조회를 이어갑니다.
@scope-connect/appkit은 화면(UI)을 포함하지 않는 SDK입니다. 지갑 선택 버튼, QR 모달, 로딩·오류 상태 같은 화면은 dApp이 만들고, SDK는 지갑 정보와 연결 기능을 제공합니다.
React·Next.js 앱이라면 화면을 직접 만드는 대신 React 바인딩(
@scope-connect/appkit-react)의 Provider·세션 훅과 기본 제공 UI(<ScopeConnect />)를 사용할 수 있습니다.
연결 방식
사용자의 지갑이 어디서 실행되는지에 따라 연결 방법이 달라집니다. AppKit은 세 가지 연결 메서드를 제공하며, 상황에 맞는 하나를 고르면 됩니다.
connect()— 등록된 기본 커넥터로 연결. 현재 환경에서 사용할 수 있는 첫 커넥터를 선택합니다. 기본 구성에서는 브라우저에 주입된 지갑을 사용합니다.selectWallet(walletId, { chainId })— 특정 지갑·체인 지정. 사용자가 목록에서 지갑과 네트워크를 직접 고른 경우에 사용합니다. SDK가 데스크톱 주입형 지갑, 모바일 SDK·인앱 브라우저·유니버설 링크, Klip App2App, Solana 연결 중 환경에 맞는 경로를 선택합니다.pair()— WalletKit으로 만든 지갑 연결. WalletKit으로 구현한 릴레이 전용 지갑(예: Scope Connect)을 QR 코드나 딥링크로 연결합니다. 릴레이 엔드포인트와 백엔드 루트가 SDK 빌드 시점에 고정되어 별도 URL 설정은 필요하지 않습니다. AppKit 생성 시 전달한 필수clientId를 사용합니다.
connect()는 등록된 커넥터 중 하나를 바로 선택하고,selectWallet()은 지갑·체인·실행 환경에 맞는 커넥터를 구성합니다. 릴레이 전용 지갑(예: Scope Connect)은 지갑 목록에 표시되더라도selectWallet()이 아니라pair()로 연결합니다.
자세한 선택 기준은 지갑 연결, 릴레이에 필요한 단계는 릴레이로 지갑 연결에서 확인합니다.
연결 방식별 공통 반환값
connect(), selectWallet(), pairing.session은 모두 WalletConnection을 반환합니다. 연결 후에는 호출 경로와 관계없이 계정과 체인을 같은 필드로 읽을 수 있습니다.
const connection = await appKit.selectWallet("metamask", {
chainId: "eip155:11155111",
});
console.log(connection.account); // eip155:11155111:0x...
console.log(connection.chainId); // eip155:11155111
console.log(connection.accounts); // ["0x..."]
connection.transport는 타입상 선택 필드지만 AppKit의 내장 커넥터는 "injected", "relay", "connect-service", "a2a" 중 하나를 설정합니다. 직접 구현한 외부 커넥터에서만 값이 없을 수 있습니다. 연결 성공은 account와 chainId를 기준으로 판단합니다. 필드 설명은 AppKit Types에서 확인합니다.
통합 순서
AppKit인스턴스를 만들고init()을 호출합니다.- 지원 네트워크와 지갑 목록으로 선택 화면을 구성합니다.
- 사용자 클릭 이벤트에서
connect(),selectWallet()또는pair()를 호출합니다. - 반환된
WalletConnection을 화면 상태에 반영합니다. - 활성 연결에서 요청·서명·잔액 조회를 실행합니다.
- 계정·체인 변경과 연결 해제를 처리합니다.
AppKit 인스턴스를 만들 때는 공개 Client ID가 항상 필요합니다. 기본 데스크톱 주입형 연결은 지갑과 직접 통신합니다. 프로젝트 설정 조회, 잔액 조회, 릴레이 토큰 발급, 모바일 유니버설 링크·Phantom 세션은 Connect 백엔드를 사용하지만, 백엔드와 릴레이 엔드포인트는 SDK에 고정되어 별도 URL 옵션이 필요하지 않습니다. 텔레메트리는 계정 주소와 서명 요청 내용을 전송할 수 있으므로, 운영 적용 전에 AppKit 설정의 보안 주의사항을 검토합니다.
주요 기능
| 영역 | 대표 API | 다음 문서 |
|---|---|---|
| 초기화 | new AppKit({ clientId }), init() | AppKit 설정 |
| 지갑 탐색과 연결 | getSupportedWallets(), getWalletsForNetwork(), connect(), selectWallet() | 지갑 연결 |
| 릴레이 페어링 | pair(), pairing.session | 릴레이로 지갑 연결 |
| 연결 상태 관리 | connection, switchNetwork(), disconnect() | AppKit Connection |
| 지갑 작업 | request(), Solana 서명, getBalance() | 요청 보내기 · 서명 · 잔액 조회 |
| React 통합 | ScopeAppKitProvider, <ScopeConnect />, useWalletConnection | React 바인딩 |
메서드 호출 형식과 반환 타입은 AppKit API에서 확인합니다. 가이드는 사용자 흐름과 구현 순서에 집중합니다.