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
오류 코드와 재시도 판단	오류 처리