표준 웹 앱으로 마이그레이션

2026년 4월 9일 이후, Base App은 Farcaster 매니페스트 여부에 관계없이 모든 앱을 표준 웹 앱으로 처리합니다. 아래 마이그레이션 경로를 따라 Base App에서 앱이 올바르게 작동하도록 설정하세요.

AI 코딩 에이전트를 사용하고 있나요? 마이그레이션 스킬을 설치하면 에이전트가 이 마이그레이션을 자동으로 처리해줍니다. npx skills add base/skills를 실행한 후 에이전트에게 Farcaster 앱을 표준 웹 앱으로 마이그레이션해달라고 요청하세요.

변경 사항

Base App은 Farcaster 미니 앱 스펙에서 단일 모델인 표준 웹 앱 + 지갑 방식으로 전환하고 있으며, Base.dev가 이를 지원합니다.

이전	이후
Farcaster 매니페스트 (`/.well-known/farcaster.json`)	Base.dev 프로젝트의 앱 메타데이터. 이미 등록된 앱은 메타데이터를 업데이트할 필요가 없습니다.
추가/제거 이벤트를 위한 Neynar 웹훅	Base 소유 백엔드 (Base Account / 주소 환경설정)
Neynar를 통한 FID 기반 알림	Base.dev 알림 API를 통한 지갑 주소 알림 (출시 예정)
인증 및 액션을 위한 Farcaster SDK	wagmi + viem + Sign-In with Ethereum (SIWE)
Farcaster를 통한 검색 및 발견	Base.dev 앱 메타데이터 + 빌더 코드

마이그레이션 경로 선택

앱을 변환하는 경우
Farcaster SDK가 없는 경우

에이전트에게 맡기세요. npx skills add base/skills로 마이그레이션 스킬을 설치한 후 에이전트에게 Farcaster 앱을 표준 웹 앱으로 마이그레이션해달라고 요청하세요. 이 스킬은 더 이상 사용되지 않는 SDK 메서드를 매핑하고, 인증 및 지갑 로직을 교체하며, Base App 경로를 자동으로 연결합니다.

앱이 Farcaster SDK를 사용하고 있습니다. 이 마이그레이션은 Farcaster 전용 인증, 신원, 액션을 표준 웹 방식으로 교체합니다.

표준 웹 스택 추가

아직 없다면 wagmi, viem, React Query를 설치하세요:

Terminal

npm install wagmi viem @tanstack/react-query @base-org/account

Base용 wagmi 설정을 생성하고 앱을 WagmiProvider와 QueryClientProvider로 감싸세요:

config.ts

import { http, createConfig, createStorage, cookieStorage } from 'wagmi';
import { base } from 'wagmi/chains';
import { baseAccount, injected } from 'wagmi/connectors';

export const config = createConfig({
  chains: [base],
  connectors: [
    injected(),
    baseAccount({
      appName: 'My App',
    }),
  ],
  storage: createStorage({ storage: cookieStorage }),
  ssr: true,
  transports: {
    [base.id]: http(),
  },
});

declare module 'wagmi' {
  interface Register {
    config: typeof config;
  }
}

App.tsx

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { WagmiProvider } from 'wagmi';
import { config } from './config';

const queryClient = new QueryClient();

export default function App({ children }: { children: React.ReactNode }) {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        {children}
      </QueryClientProvider>
    </WagmiProvider>
  );
}

이렇게 하면 Farcaster frame 커넥터가 Base 앱의 인앱 브라우저에서 동작하는 표준 wagmi 프로바이더로 교체됩니다.

인증 및 신원 교체

Farcaster 로그인과 FID 기반 신원은 Base App에서 사용할 수 없습니다. 인증에는 SIWE를, 사용자 신원에는 연결된 지갑 주소를 사용하세요.SIWE 메시지를 빌드, 서명, 검증합니다:

SignIn.tsx

'use client';

import { useState } from 'react';
import { createSiweMessage, generateSiweNonce } from 'viem/siwe';
import { useAccount, usePublicClient, useSignMessage } from 'wagmi';

export function SignIn() {
  const { address, chainId, isConnected } = useAccount();
  const [isSigningIn, setIsSigningIn] = useState(false);
  const { signMessageAsync } = useSignMessage();
  const publicClient = usePublicClient();

  async function handleSignIn() {
    if (!isConnected || !address || !chainId || !publicClient) {
      throw new Error('Connect your wallet before signing in');
    }

    setIsSigningIn(true);
    const nonce = generateSiweNonce();

    try {
      const message = createSiweMessage({
        address,
        chainId,
        domain: window.location.host,
        nonce,
        uri: window.location.origin,
        version: '1',
      });

      const signature = await signMessageAsync({ message });

      const valid = await publicClient.verifySiweMessage({ message, signature });
      if (!valid) throw new Error('SIWE verification failed');
    } finally {
      setIsSigningIn(false);
    }
  }

  return (
    <button
      type="button"
      onClick={handleSignIn}
      disabled={!isConnected || isSigningIn}
    >
      {isSigningIn ? 'Signing in...' : 'Sign in with Ethereum'}
    </button>
  );
}

이 예시는 클라이언트 측에서 서명을 검증합니다. 서버 측 세션이나 재사용 공격 방지가 필요한 경우, 서버 발급 논스 및 백엔드 검증이 포함된 전체 패턴은 사용자 인증 가이드를 참고하세요.

wagmi의 useAccount를 사용하여 연결된 지갑 주소를 사용자 신원으로 읽고, 지갑과 체인이 준비될 때까지 SIWE 실행을 차단하세요.

SDK 메서드 호환성 검토

Base 앱에서 동작하는 것과 동작하지 않는 것, 그리고 표준 웹 대안을 호환성 표에서 확인하세요.

Base.dev로 알림 마이그레이션

알림 마이그레이션은 곧 Base.dev에서 제공될 예정입니다.

Farcaster 기반 알림(Neynar, FID, 토큰을 통한)은 Base App 사용자에게 전달되지 않습니다. 지갑 주소로 전송하는 Base.dev 알림 API로 교체하세요.

Base.dev에 등록

아직 등록하지 않았다면 Base.dev에서 프로젝트를 생성하고 앱 메타데이터를 완성하세요: 이름, 아이콘, 태그라인, 설명, 스크린샷, 카테고리, 기본 URL, 빌더 코드. 이미 등록된 앱은 재등록하거나 메타데이터를 업데이트할 필요가 없습니다.

Base App에서 더 이상 사용되지 않는 Farcaster SDK 메서드

아래 Farcaster 미니 앱 SDK 메서드는 2026년 4월 9일 이후 Base App에서 호출되지 않습니다. 나열된 대안으로 마이그레이션하세요.

SDK 메서드	Base App에서의 대안
`signIn`	wagmi (`useSignMessage`)를 사용한 Sign-In with Ethereum
`sendToken`	wagmi (`useWriteContract`)를 사용한 표준 ERC-20 전송
`openUrl`	`window.open(url)`
`openMiniApp`	`window.open(url)`
`viewToken`	딥링크: `https://base.app/coin/base-mainnet/TOKEN_ADDRESS`
`viewProfile`	딥링크: `https://base.app/profile/WALLET_ADDRESS`
`swapToken`	wagmi, viem 또는 선호하는 온체인 라이브러리로 스왑 트랜잭션 구성
`requestCameraAndMicrophoneAccess`	대안 없음
`close`	대안 없음
`addMiniApp`	Base App이 앱 설치를 자동으로 처리합니다. SDK 불필요.
`viewCast`	Base App에서 불필요
`composeCast`	Base App에서 불필요
`ready`	불필요. 앱은 로드되면 표시 준비가 됩니다.
사용자 컨텍스트 및 FID	wagmi (`useAccount`)를 통해 주입된 지갑 주소 읽기

사전 점검 목록

앱 마이그레이션이 완료되었는지 확인하기 전에 다음 사항을 검토하세요:

지갑 및 인증에 wagmi + viem 사용

지갑 연결 및 컨트랙트 상호작용에 wagmi + viem을 사용합니다. 필요한 경우 인증에 SIWE를 사용합니다.

Base.dev 메타데이터 등록 및 완성

프로젝트가 기본 URL이 설정된 상태로 Base.dev에 등록되어 있습니다. 이름, 아이콘, 태그라인, 스크린샷, 카테고리, 설명, 빌더 코드가 모두 입력되어 있습니다.

알림에 Base.dev API 사용 (해당하는 경우)

알림 마이그레이션은 곧 Base.dev에서 제공될 예정입니다.

알림은 Neynar, FID, 토큰이 아닌 Base.dev 알림 API를 통해 지갑 주소로 전송됩니다.

위의 모든 단계가 완료되었다면, 앱이 표준 웹 앱으로 Base App에 준비된 것입니다.

퀵스타트

성장

알림

빌더 코드

표준 웹 앱으로 마이그레이션

변경 사항

마이그레이션 경로 선택

Base App에서 더 이상 사용되지 않는 Farcaster SDK 메서드

사전 점검 목록

​변경 사항

​마이그레이션 경로 선택

​Base App에서 더 이상 사용되지 않는 Farcaster SDK 메서드

​사전 점검 목록

변경 사항

마이그레이션 경로 선택

Base App에서 더 이상 사용되지 않는 Farcaster SDK 메서드

사전 점검 목록