> ## Documentation Index
> Fetch the complete documentation index at: https://daehan-base.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Farcaster 미니 앱을 Base App에서 동작하도록 마이그레이션합니다. 더 이상 사용되지 않는 SDK 메서드 교체 및 Base.dev 등록 방법을 다룹니다.

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

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

## 변경 사항

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

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

***

## 마이그레이션 경로 선택

<Tabs>
  <Tab title="앱을 변환하는 경우">
    <Tip>
      **에이전트에게 맡기세요.** `npx skills add base/skills`로 [마이그레이션 스킬](https://github.com/base/skills)을 설치한 후 에이전트에게 Farcaster 앱을 표준 웹 앱으로 마이그레이션해달라고 요청하세요. 이 스킬은 더 이상 사용되지 않는 SDK 메서드를 매핑하고, 인증 및 지갑 로직을 교체하며, Base App 경로를 자동으로 연결합니다.
    </Tip>

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

    <Steps>
      <Step title="표준 웹 스택 추가">
        아직 없다면 wagmi, viem, React Query를 설치하세요:

        ```bash Terminal theme={null}
        npm install wagmi viem @tanstack/react-query @base-org/account
        ```

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

        ```tsx config.ts lines expandable wrap theme={null}
        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;
          }
        }
        ```

        ```tsx App.tsx lines highlight={8-12} theme={null}
        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 프로바이더로 교체됩니다.
      </Step>

      <Step title="인증 및 신원 교체">
        Farcaster 로그인과 FID 기반 신원은 Base App에서 사용할 수 없습니다. 인증에는 [SIWE](https://viem.sh/docs/siwe/utilities/createSiweMessage)를, 사용자 신원에는 연결된 지갑 주소를 사용하세요.

        SIWE 메시지를 빌드, 서명, 검증합니다:

        ```tsx SignIn.tsx lines expandable wrap highlight={1,9,14-18,33-34} theme={null}
        '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>
          );
        }
        ```

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

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

      <Step title="SDK 메서드 호환성 검토">
        Base 앱에서 동작하는 것과 동작하지 않는 것, 그리고 표준 웹 대안을 [호환성 표](#base-app에서-더-이상-사용되지-않는-farcaster-sdk-메서드)에서 확인하세요.
      </Step>

      <Step title="Base.dev로 알림 마이그레이션">
        <Warning>
          알림 마이그레이션은 곧 Base.dev에서 제공될 예정입니다.
        </Warning>

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

      <Step title="Base.dev에 등록">
        아직 등록하지 않았다면 [Base.dev](https://www.base.dev)에서 프로젝트를 생성하고 앱 메타데이터를 완성하세요: 이름, 아이콘, 태그라인, 설명, 스크린샷, 카테고리, 기본 URL, [빌더 코드](/apps/builder-codes/builder-codes). 이미 등록된 앱은 재등록하거나 메타데이터를 업데이트할 필요가 없습니다.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Farcaster SDK가 없는 경우">
    앱이 이미 표준 웹 앱입니다. 스택을 확인하고 Base.dev에 등록하기만 하면 거의 완료됩니다.

    <Steps>
      <Step title="앱이 웹 및 지갑 준비 상태인지 확인">
        * 모바일 브라우저에서 로드됨 (Base App은 표준 인앱 브라우저를 사용)
        * 지갑 연결 및 컨트랙트 상호작용에 wagmi/viem 사용
        * 필요한 경우 인증에 [SIWE](https://viem.sh/docs/siwe/utilities/createSiweMessage) 사용
      </Step>

      <Step title="Base.dev에 등록">
        아직 등록하지 않았다면 [Base.dev](https://www.base.dev)에서 프로젝트를 생성하고 앱 메타데이터를 완성하세요: 이름, 아이콘, 태그라인, 설명, 스크린샷, 카테고리, 기본 URL, [빌더 코드](/apps/builder-codes/builder-codes). 이미 등록된 앱은 재등록하거나 메타데이터를 업데이트할 필요가 없습니다.
      </Step>

      <Step title="알림 통합 (선택사항)">
        <Warning>
          알림 마이그레이션은 곧 Base.dev에서 제공될 예정입니다.
        </Warning>

        Base.dev 알림 API를 사용하여 앱을 설치하고 알림에 동의한 사용자의 지갑 주소로 알림을 전송하세요.
      </Step>
    </Steps>

    <Check>
      앱이 Base App에 준비되었습니다 — Farcaster 매니페스트가 필요하지 않습니다.
    </Check>
  </Tab>
</Tabs>

***

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

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

| SDK 메서드                            | Base App에서의 대안                                                                                               |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `signIn`                           | wagmi (`useSignMessage`)를 사용한 [Sign-In with Ethereum](https://viem.sh/docs/siwe/utilities/createSiweMessage) |
| `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`)를 통해 주입된 지갑 주소 읽기                                                                        |

## 사전 점검 목록

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

<Steps>
  <Step title="지갑 및 인증에 wagmi + viem 사용">
    지갑 연결 및 컨트랙트 상호작용에 wagmi + viem을 사용합니다. 필요한 경우 인증에 [SIWE](https://viem.sh/docs/siwe/utilities/createSiweMessage)를 사용합니다.
  </Step>

  <Step title="Base.dev 메타데이터 등록 및 완성">
    프로젝트가 기본 URL이 설정된 상태로 [Base.dev](https://www.base.dev)에 등록되어 있습니다. 이름, 아이콘, 태그라인, 스크린샷, 카테고리, 설명, [빌더 코드](/apps/builder-codes/builder-codes)가 모두 입력되어 있습니다.
  </Step>

  <Step title="알림에 Base.dev API 사용 (해당하는 경우)">
    <Warning>
      알림 마이그레이션은 곧 Base.dev에서 제공될 예정입니다.
    </Warning>

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

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