본문으로 건너뛰기

AppKit API

AppKit은 dApp에서 지갑 연결, JSON-RPC 요청, EIP-3009 전송 승인 서명, Solana 트랜잭션 서명, 잔액 조회와 연결 상태를 다루는 기본 클래스입니다. 이 API Reference는 현재 배포된 SDK에서 dApp이 사용할 수 있는 공개 API를 설명합니다.

텔레메트리 전송 항목을 확인하세요

텔레메트리는 기본 비활성이며 사용자가 명시적으로 켜야 합니다. clientId가 필수여도 telemetry를 넘기지 않으면 아무것도 전송하지 않습니다. telemetry: true 또는 옵션 객체로 켜는 순간 현재 구현은 연결 주소와 서명 요청 값을 전송할 수 있으므로, 보안 검토가 끝난 뒤에 켭니다.

기본 사용 예제​

다음 예제는 브라우저의 injected EVM 지갑에 연결하고 체인 ID를 읽습니다.

src/connect.ts
import { AppKit, AppError, AppResultCode } from "@scope-connect/appkit";

const appKit = new AppKit({
clientId: "ck_public_example",
});
appKit.init();

export async function connectAndReadChain(): Promise<string> {
try {
const connection = await appKit.connect();
const chainId = await appKit.request<string>({ method: "eth_chainId" });
console.info(connection.account, chainId);
return chainId;
} catch (error) {
if (error instanceof AppError && error.code === AppResultCode.USER_REJECTED) {
throw new Error("사용자가 지갑 요청을 취소했습니다.");
}
throw error;
}
}

성공하면 CAIP-10 계정과 16진수 EVM 체인 ID가 출력됩니다.

이 기본 예제는 telemetry와 userHash를 생략하므로 텔레메트리 이벤트와 사용자 식별값을 전송하지 않습니다. 사용자 단위 분석이 필요할 때만 보안·개인정보 정책을 검토한 뒤 두 옵션을 설정하세요. 자세한 내용은 AppKitOptions의 사용자 식별값(userHash)과 AppKit 설정를 참고합니다. 백엔드 루트와 릴레이 엔드포인트는 SDK 빌드 시점에 고정되어 옵션으로 넘기지 않습니다.

생성과 초기화​

new AppKit(options)​

필수 프로젝트 식별값(clientId)과 선택 사용자 식별값(userHash), 지갑 커넥터, 선택적 릴레이·모바일 의존성을 구성합니다.

constructor(options: AppKitOptions)
파라미터필수설명
options예AppKitOptions. clientId만 필수이고 userHash는 선택이며, connectors를 생략하면 InjectedConnector 하나를 등록합니다.

반환: 새 AppKit 인스턴스입니다.

오류: clientId가 없거나 공백이면 INVALID_CONFIG를 던집니다. userHash는 선택이므로 없거나 공백이어도 오류가 아니며, 사용자 식별값을 전송하지 않는 것으로 처리됩니다. 그 외의 오류는 호출자에게 던지지 않도록 구현되어 있습니다. 다만 텔레메트리가 구성되면 페이지 수명 주기 리스너를 등록하므로 부작용이 없는 생성자는 아닙니다.

import { AppKit, getOrCreateUserHash } from "@scope-connect/appkit";

// 사용자 단위 집계를 원할 때 — userHash 전달
const appKit = new AppKit({ clientId: "ck_public_example", userHash: getOrCreateUserHash() });

// 원하지 않을 때 — 생략(연결·서명 동작은 동일)
const appKitWithoutUser = new AppKit({ clientId: "ck_public_example" });

init(config?)​

인스턴스를 초기화 상태로 전환합니다. 동기적이며 부작용이 없습니다. 체인·지갑 허용 목록은 더 이상 여기에 전달하지 않고, 프로젝트 콘솔 설정을 백엔드에서 가져오는 loadConfig()로 로드합니다. 생성자에 필수 clientId를 지정한 뒤 init()에는 앱 키나 URL을 추가로 전달하지 않습니다.

init(config?: AppKitConfig): void
파라미터필수설명
config아니요AppKitConfig. 현재는 예약된 빈 타입이라 전달해도 효과가 없습니다.

반환: void. 동기적으로 완료됩니다.

오류: 현재 구현은 오류를 던지지 않습니다.

appKit.init();

loadConfig()​

프로젝트 콘솔에서 활성화한 네트워크·지갑 목록을 백엔드(GET /api/v1/connect/config, X-App-Key = clientId)에서 가져와 getSupportedWallets·getSupportedNetworks와 연결 시 체인 허용 목록에 반영합니다. 과거 init({ chains })가 하던 역할을 대체합니다.

프로젝트 콘솔에 등록된 항목은 SDK 내장 목록에 없어도 노출됩니다 — 지갑은 rdns/유니버설 링크로, 네트워크는 CAIP-2 id로 런타임 항목이 만들어지므로 새 지갑·새 체인을 SDK 릴리스 없이 추가할 수 있습니다.

loadConfig(): Promise<void>

반환: 로드가 끝나면 void로 이행됩니다.

오류: 없음. 프로젝트가 활성화한 항목이 없거나 첫 요청이 실패하면 전체 내장 정보를 사용합니다. 이전 호출에서 프로젝트 설정을 성공적으로 불러온 뒤 다시 호출한 요청이 실패하면 기존 설정을 유지합니다. 프로젝트 설정이 바뀌면 다시 호출해도 됩니다.

appKit.init();
await appKit.loadConfig();

// 프로젝트 콘솔에서 활성화한 네트워크(로드 전이면 전체 내장 목록)
const networks = appKit.getSupportedNetworks();

관련 API​

영역문서
지갑 연결과 릴레이 페어링연결
요청·서명·잔액·상태요청·서명·잔액 조회
공개 타입과 지갑·네트워크 정보핵심 타입
독립 클라이언트와 직접 구성용 함수선택적 API
오류 코드와 재시도 판단오류 처리