@cocowallet/miniapp-sdk

@cocowallet/miniapp-sdk

JavaScript SDK for building mini apps inside Coco Wallet. Your web app runs in an in-wallet WebView with access to the user's Smart Account (Base L2, ERC-4337 with gas paid by Coco's paymaster).

Install

npm install @cocowallet/miniapp-sdk

Usage

import { MiniApp } from '@cocowallet/miniapp-sdk';

// 1. Read the user's wallet
const { address, chainId } = await MiniApp.getAddress();
const { name } = await MiniApp.getUserInfo();

// 2. Sign a message (personal_sign over the user's EOA)
const { signature } = await MiniApp.signMessage('Login to MyApp at ' + Date.now());

// 3. Send a transaction — gas paid by Coco, no popup for approvals you already have
const USDC_BASE = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
const { hash } = await MiniApp.sendTransaction({
  to: USDC_BASE,
  data: '0xa9059cbb...', // encoded transfer(recipient, amount)
  value: '0x0',
});

// 4. Notify someone over WhatsApp — the recipient need NOT be a Coco user.
// The copy lives in a pre-approved template on the backend; you send the
// template name and the values that fill its variables, never free text.
await MiniApp.sendWhatsAppNotification({
  to: '584141234567', // E.164 digits only, no '+'
  template: 'coco_cesta_pickup_code',
  params: { name: 'Carmen', product: 'Combo Mercado Familiar', code: '123456' },
  source: 'coco-cesta', // optional, for traceability
});

Error handling

All methods reject with a plain Error whose message is prefixed with one of:

try {
  await MiniApp.sendTransaction(tx);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('USER_REJECTED:')) {
    // Let the user try again
  }
}

What's available in v1

• MiniApp.getAddress() — smart account address + chainId
• MiniApp.getUserInfo() — name (avatar is null until v2)
• MiniApp.signMessage(message) — personal_sign
• MiniApp.signTypedData(data) — EIP-712 typed-data signature (e.g. USDC permit)
• MiniApp.sendTransaction({ to, data?, value? }) — gas-sponsored tx on Base
• MiniApp.sendTransactionBatch(txs) — multiple txs atomically in one ERC-4337 UserOp
• MiniApp.sendWhatsAppNotification({ to, template, params, source? }) — templated WhatsApp to any number (recipient need not be a Coco user)

Not yet (v2): multi-chain, session keys (tap-free signing), typed-data signing, multi-call batching.

Outside the wallet

The SDK will throw NO_BRIDGE if window.flutter_inappwebview isn't present. For local dev outside the WebView, stub the methods or guard your UI:

const inCocoWallet = typeof window !== 'undefined'
  && !!(window as any).flutter_inappwebview;