Guia de Carteiras - TokenOne API

🎯 Visão Geral

As carteiras TokenOne são Smart Contract Accounts (ERC-4337) de última geração, projetadas para oferecer a melhor experiência aos seus usuários finais, eliminando as complexidades tradicionais da blockchain.

Com a TokenOne, você pode criar e gerenciar milhares de carteiras para seus clientes sem que eles precisem entender nada sobre blockchain, chaves privadas ou taxas de gas.

💡 Por Que Smart Accounts?

Carteiras Tradicionais (EOA) vs Smart Accounts

Característica	EOA Tradicional	TokenOne Smart Account
Experiência do Usuário	❌ Complexa - usuário gerencia chave privada	✅ Simples - sem chaves privadas
Taxas de Gas	❌ Usuário paga toda transação	✅ Gasless - totalmente patrocinado
Recuperação de Conta	❌ Impossível se perder a chave	✅ Recuperação via custódia
Onboarding	❌ Requer MATIC/POL para começar	✅ Deploy instantâneo sem fundos
Segurança	❌ Segurança depende do usuário	✅ Lógica programável de segurança
Batch Operations	❌ Uma operação por vez	✅ Múltiplas operações atômicas

🚀 Vantagens para seu Negócio

1. Onboarding Sem Fricção

Fluxo Tradicional (Web3):
1. Usuário instala wallet (MetaMask, etc)
2. Cria conta e faz backup de 12 palavras
3. Compra MATIC em exchange
4. Transfere para wallet
5. Finalmente pode usar seu app
❌ Taxa de abandono: ~80%

Fluxo com TokenOne:
1. Usuário cria conta no seu app
2. Pronto! ✅
✅ Taxa de conversão: 95%+

Para o seu negócio:

Onboarding em segundos, não em dias

Zero fricção - usuário não precisa saber o que é blockchain

Conversão massivamente superior

2. Controle e Segurança

Como operador da plataforma, você tem:

✅ Custódia das carteiras - você é o owner das smart accounts

✅ Capacidade de pausar/bloquear em caso de fraude ou atividade suspeita

✅ Auditoria completa de todas operações on-chain

✅ Compliance facilitado - rastreabilidade total para reguladores

✅ Chaves privadas protegidas com AWS KMS (Key Management Service)

Ideal para:

Tokenização de ativos financeiros regulados

Fundos de investimento digitais

Programas de fidelidade e recompensas

Plataformas que precisam controle sobre movimentações

3. Custos Previsíveis e Escaláveis

✅ Gas totalmente patrocinado - seus usuários nunca pagam

✅ Sem infraestrutura - não precisa gerenciar nodes ou wallets

📚 Como Funcionam as Smart Accounts?

Arquitetura Conceitual

┌─────────────────────────────────────────────┐
│         Seu Usuário Final                    │
│  (Não precisa saber nada de blockchain)      │
│                                              │
│  "Quero comprar R$ 1.000 em tokens"          │
└─────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────┐
│         Sua Aplicação                        │
│  (Frontend/Backend)                          │
│                                              │
│  • Autentica usuário                         │
│  • Processa pagamento                        │
│  • Chama TokenOne API                        │
└─────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────┐
│         TokenOne API                         │
│                                              │
│  • Cria/gerencia smart accounts              │
│  • Patrocina gas via paymaster               │
│  • Submete transações                        │
└─────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────┐
│         Polygon Blockchain                   │
│                                              │
│  • Smart Accounts (ERC-4337)                 │
│  • Tokens ERC-20                             │
│  • Auditoria pública                         │
└─────────────────────────────────────────────┘

Fluxo de Criação de Carteira

🔐 Modelo de Custódia

Como Funciona a Propriedade das Carteiras

┌────────────────────────────────────────────────┐
│  Plataforma TokenOne (Owner)                    │
│  • EOA que controla todas smart accounts        │
│  • Assina todas UserOperations                  │
│  • Chaves protegidas com AWS KMS                │
└────────────────────────────────────────────────┘
           │ controls
           ▼
┌────────────────────────────────────────────────┐
│  Smart Account do Investidor "INV-001"          │
│  • Address: 0xabc123...                         │
│  • Balance: 10.000 COTAS_FUNDO                  │
│  • Controlada 100% pela sua plataforma          │
└────────────────────────────────────────────────┘

O que isso significa:

✅ Você tem controle total via API - nenhuma ação acontece sem sua autorização
✅ Usuário não pode mover fundos sem passar pela sua aplicação
✅ Ideal para ativos regulados - você controla quem pode transferir
✅ Conformidade - você pode bloquear/pausar contas quando necessário

⚠️ Responsabilidade: Você é responsável pela segurança da API Key e pela conformidade regulatória

Quando usar este modelo:

✅ Tokenização de recebíveis, debêntures, fundos

✅ Programas de fidelidade e recompensas

✅ Qualquer ativo que exige controle regulatório

✅ Plataformas que querem UX simplificada

Quando NÃO usar:

❌ Carteiras autocustodiais (usuário controla chaves)

❌ DeFi descentralizado (sem intermediários)

💼 Casos de Uso: Tokenização de Ativos Financeiros

Caso 1: Tokenização de Recebíveis

Problema: Empresas têm recebíveis travados por 30-90 dias, sem liquidez.

Solução com TokenOne:

Emissão

Empresa emite duplicata de R$ 100.000 com vencimento em 60 dias

TokenOne cria token representando essa duplicata

Token é fracionado em 100 partes de R$ 1.000 cada

Distribuição

Sistema cria wallets para investidores automaticamente

Aloca tokens de duplicata para carteiras dos investidores

Investidores compram com deságio (ex: R

950 p or R

1.000)

Negociação Secundária

Investidor A quer sair antes do vencimento

Transfere 10 tokens para Investidor B via API

Tudo rastreável e auditável on-chain

Liquidação

No vencimento, empresa paga R$ 100.000

Sistema queima (burn) os tokens

Distribui valor para detentores pro-rata

Benefícios:

✅ Liquidez instantânea para recebíveis

✅ Fracionamento - múltiplos investidores em uma duplicata

✅ Mercado secundário - investidores podem sair antes do vencimento

✅ Auditoria completa - cadeia de custódia transparente

✅ Custos reduzidos vs. securitização tradicional (FIDC)

Caso 2: Fundos de Investimento Tokenizados

Problema: Distribuição de fundos é cara, burocrática e limitada a horários bancários.

Solução com TokenOne:

Estruturação do Fundo

Gestora cria token representando cotas do fundo

Define supply inicial (ex: 1 milhão de cotas)

Metadados incluem CNPJ, gestora, estratégia, taxa de administração

Aplicação (D+0)

Investidor deposita R$ 10.000 via PIX

Sistema calcula cotas (R$ 10.000 ÷ cota atual)

Cria wallet para investidor (se não existir)

Emite (mint) cotas para a wallet instantaneamente

Tudo em segundos, não em D+1

Resgate

Investidor solicita resgate de 100 cotas

Sistema queima (burn) as cotas da wallet

Calcula valor (100 cotas × cota atual)

Processa pagamento via TED/PIX

Gestão Ativa

Cota atualizada diariamente no sistema

Patrimônio líquido auditável on-chain

Movimentações rastreáveis em tempo real

Benefícios:

✅ Distribuição 24/7 - sem horário de fechamento

✅ Liquidação instantânea de cotas

✅ Custos reduzidos - sem custodiante tradicional

✅ Conformidade CVM - auditoria on-chain

✅ Transparência - investidor vê saldo em tempo real

Exemplo Real:

Fundo Tradicional:
Investidor aplica R$ 50.000 → Espera D+1 → Cotas creditadas em 24h

Fundo Tokenizado TokenOne:
Investidor aplica R$ 50.000 → Cotas na wallet em 10 segundos ✅

Caso 3: Emissão de Debêntures Tokenizadas

Problema: Emissão de debêntures é cara (bancos cobram 2-5% de estruturação) e pouco acessível.

Solução com TokenOne:

Estruturação da Emissão

Empresa cria token de debêntures (ex: DEB2025A)

Define: valor nominal (R$ 1.000), taxa (CDI + 2%), vencimento (5 anos)

Série registrada on-chain com metadados completos

Subscrição

Investidores subscrevem via plataforma

Wallets criadas automaticamente

Tokens de debêntures alocados instantaneamente

Valor captado vai para empresa

Pagamento de Cupons (Juros Semestrais)

Sistema busca todos os detentores de debêntures on-chain

Calcula pro-rata para cada investidor

Distribui cupom automaticamente via PIX/TED

Tudo automatizado, zero erro humano

Amortização e Resgate

Empresa faz pagamento parcial (amortização)

Sistema queima tokens proporcionalmente

No vencimento, queima total e liquidação

Benefícios:

✅ Captação 24/7 sem intermediários bancários

✅ Custos reduzidos - sem taxa de estruturação de 2-5%

✅ Mercado secundário - debêntures negociáveis entre investidores

✅ Pagamento automatizado de cupons via smart contracts

✅ Transparência total - investidores veem tudo on-chain

✅ Conformidade CVM - auditoria permanente

Exemplo Real:

Emissão Tradicional:
Banco estrutura → 3-6 meses → Custo de 2-5% do volume → Limitado a investidores qualificados

Emissão Tokenizada:
TokenOne estrutura → 1-2 semanas → Custo de 0.5-1% → Acessível a qualquer investidor ✅

🔒 Segurança e Compliance

Proteção de Chaves

Como as chaves são protegidas:

┌─────────────────────────────────────────┐
│  AWS Key Management Service (KMS)        │
│  • Chaves nunca saem do HSM              │
│  • Criptografia nível militar            │
│  • Auditoria de todos os acessos         │
└─────────────────────────────────────────┘
           │ assina
           ▼
┌─────────────────────────────────────────┐
│  Platform Owner EOA                      │
│  • Controla todas smart accounts         │
│  • Assina UserOperations                 │
└─────────────────────────────────────────┘

Boas práticas:

✅ API Key no backend, nunca no frontend

✅ Rate limiting e monitoramento de chamadas

✅ Webhooks para notificações de transações

✅ Logs de auditoria completos via API

Conformidade Regulatória

Para ativos financeiros regulados:

✅ CVM (Comissão de Valores Mobiliários)

Auditoria on-chain de todas as movimentações

Rastreabilidade completa de detentores

Conformidade com Instrução 555 (crowdfunding)

✅ BACEN (Banco Central)

KYC/AML via sua plataforma (off-chain)

Bloqueio de contas suspeitas via API

Relatórios para COAF quando necessário

✅ LGPD (Lei Geral de Proteção de Dados)

Dados pessoais no seu banco (off-chain)

Apenas endereços públicos on-chain

Direito ao esquecimento: deletar off-chain, queimar tokens on-chain

📊 Gestão e Monitoramento

Métricas Importantes para Acompanhar

Operacionais:

Total de wallets criadas

Wallets ativas (com saldo > 0)

Taxa de ativação (wallets usadas ÷ wallets criadas)

Volume de transações (últimas 24h/7d/30d)

Financeiras:

Valor total tokenizado (TVL - Total Value Locked)

Volume de negociação secundária

Distribuição de saldos (concentração de holdings)

Segurança:

Operações falhadas (últimas 24h)

Tentativas de acesso não autorizado

Wallets bloqueadas/pausadas

Exemplo de Dashboard:

📊 Visão Geral do Fundo Tokenizado XPTO

Wallets Criadas:        2.450
Investidores Ativos:    1.823 (74.4%)
Patrimônio Líquido:     R$ 45.230.000,00
Cotas Emitidas:         3.200.000
Cota Atual:             R$ 14,13

Movimentações (30 dias):
Aplicações:    842  |  R$ 12.300.000
Resgates:      234  |  R$ 3.100.000
Líquido:       +608 |  +R$ 9.200.000

Status da Blockchain:
✅ 100% das transações confirmadas
⚡ Tempo médio: 8 segundos
💰 Gas patrocinado: R$ 1.240,00 (mês)

Versão do Documento: 2.0
Última Atualização: 23 de Dezembro de 2025

Wallets ERC-4337

Guia de Carteiras - TokenOne API#

🎯 Visão Geral#

💡 Por Que Smart Accounts?#

Carteiras Tradicionais (EOA) vs Smart Accounts#

🚀 Vantagens para seu Negócio#

1. Onboarding Sem Fricção#

2. Controle e Segurança#

3. Custos Previsíveis e Escaláveis#

📚 Como Funcionam as Smart Accounts?#

Arquitetura Conceitual#

Fluxo de Criação de Carteira#

🔐 Modelo de Custódia#

Como Funciona a Propriedade das Carteiras#

💼 Casos de Uso: Tokenização de Ativos Financeiros#

Caso 1: Tokenização de Recebíveis#

Caso 2: Fundos de Investimento Tokenizados#

Caso 3: Emissão de Debêntures Tokenizadas#

🔒 Segurança e Compliance#

Proteção de Chaves#

Conformidade Regulatória#

📊 Gestão e Monitoramento#

Métricas Importantes para Acompanhar#

Guia de Carteiras - TokenOne API

🎯 Visão Geral

💡 Por Que Smart Accounts?

Carteiras Tradicionais (EOA) vs Smart Accounts

🚀 Vantagens para seu Negócio

1. Onboarding Sem Fricção

2. Controle e Segurança

3. Custos Previsíveis e Escaláveis

📚 Como Funcionam as Smart Accounts?

Arquitetura Conceitual

Fluxo de Criação de Carteira

🔐 Modelo de Custódia

Como Funciona a Propriedade das Carteiras

💼 Casos de Uso: Tokenização de Ativos Financeiros

Caso 1: Tokenização de Recebíveis

Caso 2: Fundos de Investimento Tokenizados

Caso 3: Emissão de Debêntures Tokenizadas

🔒 Segurança e Compliance

Proteção de Chaves

Conformidade Regulatória

📊 Gestão e Monitoramento

Métricas Importantes para Acompanhar