wallet-integration

Wallet Integration (Para)

このスキルでは、Para と para CLI（@getpara/cli）を使って、Monad プロジェクトのフロントエンドにウォレットと認証を追加する方法を説明します。

Para では、ユーザーは埋め込み型の MPC ウォレットを利用できます。メール、電話番号、パスキー、ソーシャルプロバイダー（Google、Apple、Twitter、Discord、Facebook、Farcaster）でサインインすると、ブラウザー拡張機能なしで、すぐにウォレットを利用できます。すでにウォレットを持っているユーザー向けに、外部ウォレット（MetaMask、Coinbase、WalletConnect、Rainbow、Zerion、Rabby）への接続にも対応しています。どちらのフローも、同じ ParaProvider で処理できます。

このスキルは、フロントエンドがすでに存在することを前提としています（通常は scaffold/ スキルで web/ に生成されています）。新しいアプリのスキャフォールディングは行いません。プロジェクトのスキャフォールドは別の場所で処理するため、Para の para create テンプレートは意図的に対象外としています。

このスキルを取得するタイミング

• ユーザーが、Monad メインネットまたはテストネットのフロントエンドに、ウォレット接続またはサインインのフローを追加したい場合。
• ユーザーが、埋め込み型ウォレット、ソーシャルログイン、メール／SMS ログイン、またはパスキーログインを希望している場合。
• ユーザーが既存のフロントエンド（Next.js または Vite）に Para を追加したい場合（para init + ParaProvider + para doctor）。
• ユーザーが CLI から Para の API キー、環境、Webhook、ブランディング、認証方法を管理したい場合。
• ユーザーが、動作していないウォレット統合をデバッグしたい場合（para doctor）。

Para での Monad

Para の --networks フラグは evm に対応しています。Monad メインネットと Monad テストネットは EVM チェーンなので、EVM テンプレートを利用できます。ただし、Para には組み込みのチェーンオブジェクトとして Monad は用意されていません。para init の後、wagmi/chains から monad と monadTestnet をインポートし、ParaProvider の externalWalletConfig.evmConnector.config.{chains,transports} に渡してください（v2 ではチェーンリストがそこに格納されます。個別の wagmi.ts createConfig も defaultChain プロパティもありません）。正確なコードの変更については、references/para-monad-wiring.md を参照してください。

v2 SDK の構成 — プロバイダーを編集する前にお読みください

既存の Para 統合を更新する場合、ParaProvider の props は apiKey={...} のようなフラットな形式ではありません。v2 では、4 つの設定オブジェクトに分かれています。

• paraClientConfig={{ apiKey, env: Environment.BETA }} — 認証情報と環境（BETA / PRODUCTION）。
• config={{ appName }} — アプリのメタデータ。
• paraModalConfig={{ oAuthMethods, disablePhoneLogin, recoverySecretStepEnabled, ... }} — クライアント側のモーダル制御（表示する IDP ボタン、電話ログインの切り替え、リカバリーステップ）。oAuthMethods: [] を指定すると、すべてのソーシャルログインが非表示になります。
• externalWalletConfig={{ evmConnector: { config: { chains, transports } }, wallets: ['METAMASK', ...] }} — チェーンリスト、RPC トランスポート、表示する外部ウォレットのタイル。

デフォルトチェーンには、externalWalletConfig.evmConnector.config.chains の先頭のエントリーが使用されます。トップレベルの defaultChain プロパティはありません。完全な例は references/para-workflows.md → ステップ 7 を参照してください。

前提条件

para コマンドを使うには、ユーザーが以下のすべてを準備している必要があります。

1. @getpara/cli がグローバルにインストールされていること：npm install -g @getpara/cli（または pnpm add -g @getpara/cli、あるいは npx @getpara/cli@latest で実行）。
2. para にログインしていること：para login（ブラウザーでの OAuth フローです。完了できるのはユーザー本人だけです）。
3. Para の組織とプロジェクトが選択され、アクティブなコンテキストになっていること。para login の後、CLI は最初の組織とプロジェクトを自動選択します。必要に応じて、para orgs switch／para projects switch で切り替えます。

monskills フックは、インストールとログインが済んでいる場合にのみ para コマンドを許可します。前提条件が満たされていない場合、フックは不足している項目を正確に示してツール呼び出しを拒否します。そのメッセージをユーザーに伝え、対応を待ってください。

してはいけないこと

• ユーザーの代わりに CLI をインストールしないでください。 @getpara/cli が見つからない場合は、正確なコマンドを伝えて待ってください。
• ユーザーの代わりに para login を実行しないでください。 ブラウザーのタブが開き、OAuth フローを完了できるのはユーザーだけです。（ヘッドレス環境向けに --no-browser もありますが、monskills は対話形式での使用を想定しています。ユーザー自身に選んでもらってください。）
• Web ポータルでユーザーの Para アカウントや API キーを作成しないでください。 CLI がプロジェクトとキーの作成を処理します。ユーザーを案内してください。
• para create を実行しないでください。 プロジェクトのスキャフォールディングは scaffold/ スキルが処理します。このスキルでは、すでに存在するフロントエンドに Para を統合するだけです。

既存のフロントエンドに Para を統合する

cd web   # or wherever the frontend lives
para init

para init は .pararc（組織、プロジェクト、環境のコンテキスト）を書き込みます。その後、SDK パッケージをインストールし、アプリを ParaProvider でラップして、Para の CSS をインポートします。接続後に para doctor を実行して、不足がないことを確認してください。

サンドボックス化されたターミナルやヘッドレスターミナル（実際の TTY がない環境）では、para init は TTY initialization failed: uv_tty_init returned EINVAL で終了します。その場合は para init --no-input として再実行してください。プロンプトを表示する代わりに、グローバル設定で有効な組織、プロジェクト、環境が使用されます。

コードの正確な変更箇所、パッケージの一覧、para doctor によるデバッグの流れについては、references/para-workflows.md →「既存のフロントエンドに Para を統合する」を参照してください。

次に参照するもの

参照ファイル — 必要に応じて取得してください。

• ワークフローのレシピ — 既存のフロントエンドへの Para の統合、API キーのローテーション、para keys config による認証方法／ブランディング／Webhook の設定、para doctor によるデバッグのための、推奨手順を示します。
• CLI リファレンス — para のすべてのコマンドを、認証、設定、組織／プロジェクト、キー、診断の分野ごとにまとめ、フラグや注意点を説明します。
• Monad の接続設定 — Para のプロバイダーが使用する wagmi 設定に Monad のメインネットとテストネットを追加するための、para init 後の正確な変更内容を示します。Para を統合するたびに適用してください。

ユーザーの目的に合ったワークフローのレシピから始めてください。レシピにないフラグやサブコマンドが必要な場合に限り、CLI リファレンスを参照してください。

終了コードの規約

すべての para コマンドは同じ規約に従います。標準出力だけでなく、終了コードを確認してください。

終了コード	意味	対応方法
0	成功	続行する
1	ユーザーのエラー（引数の誤り、未ログイン、不明なプロジェクト、--json を指定した para doctor でエラーを検出）	標準エラー出力を読み、入力を修正して再試行する
2	API／サーバーエラー	ユーザーに原因はありません。1 回再試行し、解消しない場合はユーザーに伝えて中止する。

para doctor --json はエラーを検出すると終了コード 1 を返します。これは想定された動作であり、CLI のバグではありません。統合に問題があることを示すシグナルとして使用してください。

シークレットの取り扱い

• para keys get --show-secret と para keys get --copy-secret は、シークレット API キーを表示またはコピーします。応答でその値をユーザーに伝えたり、コミットするファイルに貼り付けたりしないでください。公開キー（フラグなし）は .env.local に NEXT_PUBLIC_PARA_API_KEY（またはフレームワークに対応する）プレフィックス付きで記載してかまいません。
• キーを書き込む前に、環境変数のプレフィックスがフレームワークに合っていることを必ず確認してください。Next.js では NEXT_PUBLIC_、Vite では VITE_ を使用します。不一致は para doctor が検出します。
• .pararc は組織／プロジェクト ID と環境のみを保存し、シークレットは含まないため、コミットしても安全です。.env／.env.local は .gitignore に含めてください。

公式ドキュメント

• CLI の概要：https://docs.getpara.com/v2/cli/overview
• インストール：https://docs.getpara.com/v2/cli/installation
• コマンドリファレンス：https://docs.getpara.com/v2/cli/commands