wallet-integration

Wallet Integration (Para)

This skill covers adding wallet + authentication to the frontend of a Monad project using Para and the para CLI (@getpara/cli).

Para gives users embedded MPC wallets — they sign in with email, phone, passkey, or a social provider (Google, Apple, Twitter, Discord, Facebook, Farcaster) and instantly have a wallet, no browser extension required. It also supports connecting external wallets (MetaMask, Coinbase, WalletConnect, Rainbow, Zerion, Rabby) for users who already have one. The same ParaProvider handles both flows.

This skill assumes the frontend already exists (typically scaffolded by the scaffold/ skill into web/). It does not scaffold a new app — Para's para create template is intentionally out of scope here, since the project scaffold is handled elsewhere.

When to fetch this skill

• The user wants any wallet connect / sign-in flow on their frontend, on Monad mainnet or testnet.
• The user wants embedded wallets, social login, email/SMS login, or passkey login.
• The user has an existing frontend (Next.js or Vite) and wants to add Para to it (para init + ParaProvider + para doctor).
• The user wants to manage Para API keys, environments, webhooks, branding, or auth methods from the CLI.
• The user wants to debug a wallet integration that isn't working (para doctor).

Monad on Para

Para's --networks flag supports evm. Monad mainnet and Monad testnet are EVM chains, so they fit the EVM template — but Para doesn't ship Monad as a built-in chain object. After para init, you import monad and monadTestnet from wagmi/chains and pass them through externalWalletConfig.evmConnector.config.{chains,transports} on the ParaProvider (v2 stores the chain list there — there is no separate wagmi.ts createConfig and no defaultChain prop). See references/para-monad-wiring.md for the exact code edits.

v2 SDK shape — read before editing the provider

If you're updating an existing Para integration, the ParaProvider props are not a flat apiKey={...}. v2 splits them into four config objects:

• paraClientConfig={{ apiKey, env: Environment.BETA }} — credentials and environment (BETA / PRODUCTION).
• config={{ appName }} — app metadata.
• paraModalConfig={{ oAuthMethods, disablePhoneLogin, recoverySecretStepEnabled, ... }} — client-side modal controls (which IDP buttons render, phone toggle, recovery step). Empty oAuthMethods: [] hides all social login.
• externalWalletConfig={{ evmConnector: { config: { chains, transports } }, wallets: ['METAMASK', ...] }} — chain list, RPC transports, and which external-wallet tiles appear.

Default chain = first entry in externalWalletConfig.evmConnector.config.chains. There is no top-level defaultChain prop. Full example in references/para-workflows.md → step 7.

Prerequisites

Before any para command will work, the user must have all of these in place:

1. @getpara/cli installed globally: npm install -g @getpara/cli (or pnpm add -g @getpara/cli, or run via npx @getpara/cli@latest).
2. para logged in: para login (browser OAuth flow — only the user can complete it).
3. A Para organization and project selected as active context. After para login, the CLI auto-selects the first org and project; switch with para orgs switch / para projects switch if needed.

The monskills hook gates para commands on install + login. If a prereq is missing, the hook denies the tool call with the exact missing piece — surface that message to the user and wait.

What NOT to do

• Do not install the CLI for the user. If @getpara/cli is missing, tell them the exact command and wait.
• Do not run para login for the user. It opens a browser tab and only the user can complete the OAuth flow. (--no-browser exists for headless setups, but monskills is for interactive use — let the user choose.)
• Do not create a Para account or API key for the user via the web portal. The CLI handles project + key creation — guide them through it.
• Do not run para create. Project scaffolding is handled by the scaffold/ skill; this skill only integrates Para into a frontend that already exists.

Integrate Para into the existing frontend

cd web   # or wherever the frontend lives
para init

para init writes .pararc (org + project + environment context), then you install the SDK packages, wrap the app in ParaProvider, and import Para's CSS. After wiring, run para doctor to verify nothing is missing.

In a sandboxed or headless terminal (no real TTY), para init will exit with TTY initialization failed: uv_tty_init returned EINVAL — re-run as para init --no-input and it will use the active org/project/env from global config instead of prompting.

See references/para-workflows.md → "Integrate Para into the existing frontend" for the exact code edits, package list, and para doctor debugging loop.

Where to look next

Reference files — fetch on demand:

• Workflow recipes — opinionated sequences for: integrating Para into the existing frontend, rotating an API key, configuring auth methods/branding/webhooks via para keys config, debugging with para doctor.
• CLI reference — every para command grouped by area (auth, config, orgs/projects, keys, diagnostics) with notes on flags and gotchas.
• Monad wiring — the exact post-para init edits to add Monad mainnet + testnet to the wagmi config that Para's provider consumes. Apply this after every Para integration.

Start with the workflow recipe that matches the user's goal. Drop into the CLI reference only when you need a flag or subcommand not covered there.

Exit-code contract

Every para command follows the same convention — check exit codes, not just stdout:

Exit code	Meaning	How to react
0	Success	Continue
1	User error (bad args, not logged in, unknown project, para doctor found errors with --json)	Read stderr, fix the input, retry
2	API/server error	Not the user's fault. Retry once; if it persists, tell the user and stop.

para doctor --json exits 1 when it finds errors — that's expected behaviour, not a CLI bug. Use it as the signal that the integration has issues.

Secrets hygiene

• para keys get --show-secret and para keys get --copy-secret print/copy the secret API key. Never echo the value back to the user in your response, and never paste it into a file you commit. The public key (no flag) is fine to include in .env.local under a NEXT_PUBLIC_PARA_API_KEY (or framework-equivalent) prefix.
• Always check the env-var prefix matches the framework before writing the key: NEXT_PUBLIC_ for Next.js, VITE_ for Vite. para doctor flags mismatches.
• .pararc is safe to commit (it only stores org/project IDs and environment, no secrets). .env/.env.local should be in .gitignore.

Official docs

• CLI overview: https://docs.getpara.com/v2/cli/overview
• Installation: https://docs.getpara.com/v2/cli/installation
• Command reference: https://docs.getpara.com/v2/cli/commands