MetaMask — Carteira Web3 e recebimento de cripto no FoxHub

Fonte oficial: https://docs.metamask.io Última atualização: 2026-05-16

MetaMask é a carteira Web3 mais usada do mundo (30M+ usuários ativos). Funciona como extensão de navegador, app mobile e como SDK embarcável. Suporta toda a família EVM (Ethereum, Polygon, BSC, Arbitrum, Optimism, Base, Linea, Avalanche) e desde 2025, Solana nativamente via Snaps.

---

1. Cinco produtos principais

Produto	Para que serve
MetaMask Connect	Conectar dApp à extensão/app mobile. Sucessor do antigo @metamask/sdk.
Embedded Wallets	Login social (Google, Apple, email) — cria carteira sem o usuário saber.
Smart Accounts Kit	Contas programáveis com permissões granulares (gasless, batch, recuperação).
Snaps	Plugins dentro da carteira (suporte a chains não-EVM, regras custom).
Services (Infura)	RPC, Gas API, Token/NFT API — infraestrutura backend.

---

2. Padrões Web3 que você precisa conhecer

EIP-1193 — Ethereum Provider API

Define a interface window.ethereum que toda carteira injeta no browser.

window.ethereum.request({ method: 'eth_requestAccounts' });

EIP-6963 — Multi Injected Provider Discovery

Resolve o problema de várias carteiras instaladas (MetaMask + Coinbase + Phantom). Em vez de competir pelo window.ethereum, cada uma anuncia via evento.

window.addEventListener('eip6963:announceProvider', (event) => {
  console.log(event.detail.info.name); // 'MetaMask'
});
window.dispatchEvent(new Event('eip6963:requestProvider'));

CAIP-25 — Multichain API

Permite pedir acesso a múltiplas chains numa única sessão (EVM + Solana juntas). Base do MetaMask Connect moderno.

ERC-20 / ERC-721 / ERC-1155

• ERC-20: tokens fungíveis (USDC, USDT, BRZ, WETH)
• ERC-721: NFT único (Bored Apes)
• ERC-1155: NFTs em lote (jogos, edições limitadas)

---

3. Como integrar — stack recomendada 2026

Stack moderna para o FoxHub:

npm install @metamask/connect-evm viem wagmi @tanstack/react-query

• @metamask/connect-evm — conecta MetaMask (EVM)
• viem — substituto moderno e tipado do ethers.js
• wagmi — hooks React para Web3
• @tanstack/react-query — cache de queries on-chain

3.1 Conectar carteira

import { createEVMClient } from '@metamask/connect-evm';

const client = await createEVMClient({
  dappMetadata: { name: 'FoxHub', url: 'https://hub.centralfox.online' },
});

const accounts = await client.request({ method: 'eth_requestAccounts' });
console.log('Endereço do usuário:', accounts[0]);

3.2 Verificar saldo USDC (Polygon)

import { createPublicClient, http, erc20Abi, formatUnits } from 'viem';
import { polygon } from 'viem/chains';

const publicClient = createPublicClient({
  chain: polygon,
  transport: http()
});

const USDC_POLYGON = '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359';

const balance = await publicClient.readContract({
  address: USDC_POLYGON,
  abi: erc20Abi,
  functionName: 'balanceOf',
  args: [accounts[0]]
});

console.log(`Saldo USDC: ${formatUnits(balance, 6)}`);

3.3 Enviar pagamento ERC-20

import { encodeFunctionData, parseUnits } from 'viem';

const data = encodeFunctionData({
  abi: erc20Abi,
  functionName: 'transfer',
  args: [WALLET_FOXHUB, parseUnits('50', 6)] // 50 USDC
});

const txHash = await client.request({
  method: 'eth_sendTransaction',
  params: [{ from: accounts[0], to: USDC_POLYGON, data }]
});

---

4. Como o FoxHub pode receber cripto

4.1 Arquitetura mínima

┌────────────────────────────────────────────────────────────────┐
│  Cliente FoxHub (Next.js)                                      │
│                                                                │
│  [Botão Pagar com MetaMask]                                    │
│         │                                                       │
│         ▼                                                       │
│  1. Conecta carteira (eth_requestAccounts)                     │
│  2. Mostra valor em USDC/USDT/BRZ + chain                      │
│  3. eth_sendTransaction → ERC-20 transfer                      │
│         │                                                       │
└─────────┼──────────────────────────────────────────────────────┘
          │ tx hash
          ▼
   Webhook backend FoxHub
          │
          ▼
   Confirma 12+ blocos via Infura/Alchemy
          │
          ▼
   Marca pedido como PAGO + emite NF-e via FoxNFe

4.2 Stack recomendada para o FoxHub

Camada	Tecnologia	Por quê
Carteira destino	MetaMask cold wallet + hot wallet para operação	Cold = segurança, hot = liquidez
Chain prioritária	Polygon PoS	Fees ~/bin/bash.01, finalidade ~2s, USDC nativo
Chain secundária	Base ou Arbitrum	Backup L2 da Ethereum, mais reputação
Stablecoin	USDC > USDT > BRZ	USDC tem reservas auditadas, BRZ é BRL-pegged
RPC	Infura (gratuito até 100k req/dia)	Owned pela ConsenSys (MetaMask) — integração suave
Webhook	Alchemy Notify ou QuickNode Streams	Confirma TX sem polling
Conversão BRL	Asaas Cripto ou Mercado Bitcoin OTC	Off-ramp legal no BR

4.3 Fluxo passo-a-passo

1. Cliente clica Pagar com cripto no checkout do FoxHub
2. Frontend chama createEVMClient → MetaMask abre
3. Mostra valor convertido (R$ 100 = ~$20 = 20 USDC na Polygon)
4. Cliente assina transação → tx vai pro mempool
5. Backend FoxHub escuta webhook do Alchemy
6. Após 12 confirmações (~24s na Polygon), marca PAGO
7. Emite NF-e via FoxNFe com a observação Pagamento em USDC, hash 0x...
8. Hot wallet automaticamente swap USDC → BRL via Asaas Cripto (opcional)

4.4 Considerações fiscais (Brasil)

• Receber cripto é legal mas precisa ser declarado
• Acima de R$ 35.000/mês em cripto → IN RFB 1.888/2019 (declaração obrigatória)
• Empresa precisa contabilizar como estoque de ativo ou conversão imediata
• NF-e deve sair em BRL com observação do pagamento cripto
• Ganho de capital cripto: 15% (até 5M), até 22.5% acima

4.5 Segurança

Risco	Mitigação
Hot wallet hackeada	Limite 5% do volume diário; resto em cold
Transação para chain errada	Frontend valida chainId antes de enviar
Front-running de preço	Lock cotação USD/BRL por 5min com hash assinado
MEV (sandwich)	Usar Flashbots Protect RPC
Phishing do checkout	Domínio fixo, SSL HSTS, sem iframe

---

5. Próximos passos sugeridos para o ecossistema Fox

• Criar fox-crypto-gateway — microserviço com endpoints /quote, /checkout, /confirm
• Carteira institucional Fox (Gnosis Safe multisig 2-of-3)
• Suporte a 3 stablecoins: USDC, USDT, BRZ
• Suporte a 3 chains: Polygon, Base, Arbitrum
• Integração com FoxNFe para emissão automática
• Dashboard de reconciliação em FoxReview
• LGPD: hash do wallet address, não armazenar dados PII vinculados sem consentimento

---

6. Referências

• Docs MetaMask: https://docs.metamask.io
• Wallet API: https://docs.metamask.io/wallet/concepts/wallet-api/
• Multichain (CAIP-25): https://docs.metamask.io/wallet/concepts/multichain-api/
• Infura RPC: https://docs.metamask.io/services/
• EIP-1193: https://eips.ethereum.org/EIPS/eip-1193
• EIP-6963: https://eips.ethereum.org/EIPS/eip-6963
• viem docs: https://viem.sh
• wagmi docs: https://wagmi.sh
• Receita Federal IN 1.888/2019: https://www.gov.br/receitafederal