@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 (Polygon mainnet, chainId 137, 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
// Native USDC on Polygon (6 decimals).
const USDC_POLYGON = '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359';
const { hash } = await MiniApp.sendTransaction({
  to: USDC_POLYGON,
  data: '0xa9059cbb...', // encoded transfer(recipient, amount)
  value: '0x0',
});

Error handling

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

| Prefix | Meaning | |---|---| | USER_REJECTED: | User dismissed the signing sheet. | | TIMEOUT: | No response from the wallet after 60s. | | INSUFFICIENT_GAS_FUNDS: | Neither gasless nor token-paymaster gas available. | | NO_SESSION: | No smart account on the wallet (user not signed in). | | INVALID_PARAMS: | Malformed request (e.g. bad to address). | | TX_FAILED: | Transaction submission failed for another reason. | | NO_BRIDGE: | SDK is running outside the Coco WebView. |

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

What's available

• MiniApp.getAddress() — smart account address + chainId (Polygon, 137)
• MiniApp.getUserInfo() — name (avatar is null until v2)
• MiniApp.signMessage(message) — personal_sign
• MiniApp.signTypedData(data) — EIP-712 typed-data signing (e.g. USDC permit)
• MiniApp.sendTransaction({ to, data?, value? }) — gas-sponsored tx on Polygon
• MiniApp.sendTransactionBatch(txs) — atomic ERC-4337 UserOp batch (one nonce)
• MiniApp.getContacts() / MiniApp.saveContact(contact) — wallet contacts
• MiniApp.setTitle(title) / MiniApp.setCanGoBack(value) — host top-bar control
• MiniApp.recordTransaction(tx) — register a tx in the wallet activity feed
• MiniApp.sendWhatsAppNotification(notification) — templated WhatsApp message
• MiniApp.requestPagoMovilPayout(request) — accept payments in Bs via Pago Móvil

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

Accept payments in bolívares (Pago Móvil)

Charge the user in USD and get paid in bolívares — without touching bank rails yourself. Your mini app prices in USD; the wallet debits the user's stablecoin balance, converts at the current VES/USD rate, and delivers the Bs to the Pago Móvil account you specify (typically your commerce's account, fixed in your code). The user confirms the exact Bs amount in a native wallet sheet before anything moves.

const result = await MiniApp.requestPagoMovilPayout({
  amountUsd: 25,
  beneficiary: {
    phone: '04141234567',
    documentId: 'J401234567',
    bankCode: '0102',
    bankName: 'Banco de Venezuela',
  },
  comment: 'Pedido #123',
  reference: 'order-123', // echoed back for reconciliation
});

// result.status === 'processing' — payment queued, bank settlement is async.
// result.amountBs / result.exchangeRate — what your account receives.
// While the bank settles, the user's USD sits protected in an escrow contract:
// released to the payment when the bank confirms, refunded if it fails
// (result.escrowOrderId identifies that protection order).

How batching works

batchTransactions lets you run up to 3 of your own contract calls in the same operation as the charge. The wallet builds a single ERC-4337 UserOp containing your transactions first, then the payment — so the user sees one confirmation sheet and signs once, and the whole batch is atomic: either every step lands in the same on-chain transaction or none does. There is never an intermediate state (your call executed but the payment not queued, or vice versa), and no nonce races between steps.

Use it whenever the funds covering amountUsd need an on-chain step to become spendable first — releasing tokens from a vault or escrow, unwrapping, converting:

await MiniApp.requestPagoMovilPayout({
  amountUsd: 25,
  beneficiary: MERCHANT_PAGO_MOVIL,
  batchTransactions: [
    { to: MY_CONTRACT, data: encodedCall }, // frees the USDC that funds the charge
  ],
  reference: 'order-123',
});

Order inside the batch: your batchTransactions (in array order) → the payment. Gas for the whole batch is covered by Coco's paymaster, like every other mini-app transaction.

Extra error prefixes for this method: PAYOUT_FAILED: (bank payout could not be queued; escrow refund protects the funds) and RATE_UNAVAILABLE: (no VES/USD rate right now) on top of the common USER_REJECTED: / INSUFFICIENT_FUNDS:.

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;