TokenOne API

Bem-vindo à documentação da TokenOne API, a solução completa para criação e gestão de carteiras e tokens ERC-20 na blockchain.

Base URL: https://api.tokenone.com.br

🔐 Autenticação

Todas as requisições requerem autenticação via API Key no header:

x-api-key: YOUR_API_KEY

Como obter sua API Key:

Acesse o Dashboard TokenOne

Vá em API Keys

Clique em Copiar Chave

📚 Recursos da API

Recursos Disponíveis

Recurso	Descrição	Endpoints
Wallets	Carteiras digitais ERC-4337	3 endpoints
Tokens	Tokens ERC-20 personalizados	9 endpoints
Transfers	Transferências de tokens	3 endpoints
Audit	Logs de auditoria	1 endpoint

Total: 16 endpoints REST

🌐 Redes Suportadas

Rede	Identificador	Tipo
Polygon Mainnet	`polygon-mainnet`	Produção
Polygon Amoy	`polygon-amoy`	Testnet

💼 1. Wallets

1.1 Criar Wallet

Cria uma carteira digital (smart account) com deployment gasless.

Endpoint: POST /v1/wallets

Request:

{
  "network": "polygon-mainnet",
  "extRef": "customer-12345"
}

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`network`	string	Sim	Rede blockchain: `polygon-mainnet` ou `polygon-amoy`
`extRef`	string	Não	Referência externa para seu sistema

Response: 201 Created

{
  "id": "wallet-uuid",
  "address": "0x1234...5678",
  "network": "polygon-mainnet",
  "status": "active",
  "extRef": "customer-12345",
  "createdAt": "2025-12-23T10:00:00Z"
}

✨ Vantagem: Deployment 100% gasless via paymaster - seus usuários não precisam de MATIC/POL.

1.2 Listar Wallets

Lista todas as wallets com paginação e filtros.

Endpoint: GET /v1/wallets

Query Parameters:

Parâmetro	Tipo	Descrição	Exemplo
`page`	integer	Número da página (padrão: 1)	`1`
`pageSize`	integer	Itens por página (padrão: 20, máx: 100)	`50`
`network`	string	Filtrar por rede	`polygon-mainnet`
`status`	string	Filtrar por status	`active`
`address`	string	Filtrar por endereço	`0x123...`
`extRef`	string	Filtrar por referência externa	`customer-123`

Exemplo:

Response: 200 OK

{
  "data": [
    {
      "id": "wallet-uuid",
      "address": "0x1234...5678",
      "network": "polygon-mainnet",
      "status": "active",
      "extRef": "customer-12345",
      "createdAt": "2025-12-23T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 150,
    "totalPages": 8
  }
}

1.3 Obter Wallet por Endereço

Retorna detalhes de uma wallet específica incluindo saldos.

Endpoint: GET /v1/wallets/{address}

Path Parameters:

Parâmetro	Tipo	Descrição
`address`	string	Endereço da wallet (0x...)

Exemplo:

Response: 200 OK

{
  "id": "wallet-uuid",
  "address": "0x1234...5678",
  "network": "polygon-mainnet",
  "status": "active",
  "balance": {
    "native": "1.5",
    "tokens": [
      {
        "contractAddress": "0xtoken...",
        "symbol": "MTK",
        "balance": "1000.0",
        "decimals": 18
      }
    ]
  },
  "createdAt": "2025-12-23T10:00:00Z"
}

🪙 2. Tokens

2.1 Criar Token (Deploy)

Faz deploy de um novo token ERC-20 personalizado.

Endpoint: POST /v1/tokens

Request:

{
  "walletAddress": "0x1234...5678",
  "name": "My Loyalty Points",
  "symbol": "LPTS",
  "decimals": 18,
  "network": "polygon-mainnet",
  "initialSupplyTokens": "1000000",
  "maxSupplyTokens": "100000000",
  "metadata": {
    "description": "Pontos de fidelidade da minha plataforma",
    "website": "https://meusite.com"
  }
}

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`walletAddress`	string	Sim	Endereço da wallet que será owner do token
`name`	string	Sim	Nome do token (máx: 64 caracteres)
`symbol`	string	Sim	Símbolo do token (2-10 caracteres)
`decimals`	integer	Sim	Casas decimais (0-18, recomendado: 18)
`network`	string	Sim	Rede blockchain
`initialSupplyTokens`	string	Não	Supply inicial (ex: "1000000")
`maxSupplyTokens`	string	Não	Supply máximo
`metadata`	object	Não	Metadados adicionais

Response: 201 Created

{
  "token": {
    "id": "token-uuid",
    "contractAddress": "0xtoken...abc",
    "name": "My Loyalty Points",
    "symbol": "LPTS",
    "decimals": 18,
    "network": "polygon-mainnet",
    "deployed": true
  },
  "transactionHash": "0xtxhash...",
  "explorerUrls": {
    "transaction": "https://polygonscan.com/tx/0x...",
    "token": "https://polygonscan.com/token/0x..."
  }
}

2.2 Listar Tokens

Lista todos os tokens com filtros e paginação.

Endpoint: GET /v1/tokens

Query Parameters:

Parâmetro	Tipo	Descrição
`page`	integer	Número da página
`pageSize`	integer	Itens por página
`network`	string	Filtrar por rede
`symbol`	string	Filtrar por símbolo
`contractAddress`	string	Filtrar por endereço

Response: 200 OK

{
  "data": [
    {
      "id": "token-uuid",
      "contractAddress": "0xtoken...abc",
      "name": "My Loyalty Points",
      "symbol": "LPTS",
      "decimals": 18,
      "network": "polygon-mainnet",
      "totalSupply": "1000000",
      "deployed": true
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 45,
    "totalPages": 3
  }
}

2.3 Mint (Criar) Tokens

Cria novos tokens e envia para um destinatário.

Endpoint: POST /v1/tokens/{address}/mint

Path Parameters:

Parâmetro	Tipo	Descrição
`address`	string	Endereço do contrato do token

Request:

{
  "amountTokens": "1000",
  "to": "0xrecipient...address",
  "reason": "Recompensa por compra - Pedido #12345",
  "metadata": {
    "orderId": "12345",
    "category": "purchase-reward"
  }
}

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`amountTokens`	string	Sim	Quantidade em tokens (ex: "100" ou "1.5")
`to`	string	Sim	Endereço do destinatário
`reason`	string	Não*	Motivo da operação (*recomendado para auditoria)
`metadata`	object	Não	Dados adicionais estruturados

Response: 200 OK

{
  "transactionHash": "0xtx...hash",
  "amount": "1000",
  "to": "0xrecipient...address",
  "supplyInfo": {
    "totalSupplyBefore": "1000000",
    "totalSupplyAfter": "1001000"
  }
}

2.4 Burn (Queimar) Tokens

Queima tokens do supply da wallet owner.

Endpoint: POST /v1/tokens/{address}/burn

Request:

{
  "amountTokens": "500",
  "reason": "Programa de buyback - Dezembro 2025"
}

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`amountTokens`	string	Sim	Quantidade a queimar
`reason`	string	Não*	Motivo (*recomendado)
`metadata`	object	Não	Dados adicionais

Response: 200 OK

{
  "transactionHash": "0xtx...hash",
  "amountBurned": "500",
  "supplyInfo": {
    "totalSupplyBefore": "1001000",
    "totalSupplyAfter": "1000500",
    "percentageBurned": "0.05%"
  }
}

2.5 Burn From (Queimar de Carteira)

Queima tokens de uma carteira específica (operação de custódia).

Endpoint: POST /v1/tokens/{address}/burn-from

Request:

{
  "from": "0xuser...address",
  "amountTokens": "250",
  "reason": "Compliance - Ordem judicial #123/2025",
  "metadata": {
    "courtOrder": "123/2025",
    "court": "Tribunal Federal"
  }
}

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`from`	string	Sim	Endereço da carteira
`amountTokens`	string	Sim	Quantidade a queimar
`reason`	string	Não*	Motivo (*altamente recomendado)
`metadata`	object	Não	Dados de compliance

2.6 Pausar Token

Pausa TODAS as transferências do token (emergência).

Endpoint: POST /v1/tokens/{address}/pause

Request:

{
  "reason": "Pausa emergencial - Vulnerabilidade detectada",
  "metadata": {
    "incidentId": "SEC-2025-001",
    "severity": "CRITICAL"
  }
}

Efeito: Bloqueia todas as transferências do token até despausar.

2.7 Despausar Token

Reativa as transferências de um token pausado.

Endpoint: POST /v1/tokens/{address}/unpause

Request:

{
  "reason": "Retomar operações - Vulnerabilidade corrigida",
  "metadata": {
    "incidentId": "SEC-2025-001",
    "patchVersion": "v2.1.0"
  }
}

2.8 Bloquear Usuário

Adiciona um endereço à blocklist (não pode enviar nem receber tokens).

Endpoint: POST /v1/tokens/{address}/blocklist

Request:

{
  "userAddress": "0xuser...block",
  "reason": "Bloqueio por ordem judicial - Processo 456/2025",
  "metadata": {
    "processNumber": "456/2025",
    "court": "Tribunal de Justiça",
    "orderDate": "2025-12-20"
  }
}

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`userAddress`	string	Sim	Endereço a bloquear
`reason`	string	Não*	Motivo (*altamente recomendado)
`metadata`	object	Não	Dados legais/compliance

2.9 Desbloquear Usuário

Remove um endereço da blocklist.

Endpoint: POST /v1/tokens/{address}/blocklist/{userAddress}/unblock

Path Parameters:

Parâmetro	Tipo	Descrição
`address`	string	Endereço do token
`userAddress`	string	Endereço a desbloquear

Request:

{
  "reason": "Desbloqueio - Processo encerrado",
  "metadata": {
    "processNumber": "456/2025",
    "closureDate": "2025-12-30"
  }
}

💸 3. Transfers

3.1 Criar Transferência

Transfere tokens ERC-20 entre carteiras.

Endpoint: POST /v1/transfers

Request:

{
  "from": "0xsender...address",
  "to": "0xrecipient...address",
  "tokenAddress": "0xtoken...address",
  "amountTokens": "100",
  "reason": "Pagamento por serviços - Nota Fiscal #789",
  "metadata": {
    "invoiceId": "789",
    "service": "Consultoria"
  }
}

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`from`	string	Sim	Endereço da wallet de origem
`to`	string	Sim	Endereço do destinatário
`tokenAddress`	string	Sim	Endereço do token ERC-20
`amountTokens`	string	Sim	Quantidade (ex: "100" ou "1.5")
`reason`	string	Não*	Motivo (*recomendado)
`metadata`	object	Não	Dados adicionais

⚠️ Importante: Apenas tokens ERC-20 são suportados. Transferências de MATIC/POL não disponíveis.

Response: 200 OK

{
  "id": "transfer-uuid",
  "from": "0xsender...address",
  "to": "0xrecipient...address",
  "tokenAddress": "0xtoken...address",
  "amount": "100",
  "status": "pending",
  "hash": "0xtx...hash",
  "createdAt": "2025-12-23T15:30:00Z"
}

3.2 Listar Transferências

Lista transferências com filtros e paginação.

Endpoint: GET /v1/transfers

Query Parameters:

Parâmetro	Tipo	Descrição
`page`	integer	Número da página
`pageSize`	integer	Itens por página
`walletId`	string	Filtrar por wallet
`status`	string	Filtrar por status: `pending`, `confirmed`, `failed`
`network`	string	Filtrar por rede
`from`	string	Filtrar por remetente
`to`	string	Filtrar por destinatário
`tokenAddress`	string	Filtrar por token

3.3 Obter Transferência

Retorna detalhes de uma transferência específica.

Endpoint: GET /v1/transfers/{id}

Path Parameters:

Parâmetro	Tipo	Descrição
`id`	string	ID da transferência

📊 4. Audit (Auditoria)

4.1 Consultar Logs de Auditoria

Consulta logs de todas as operações realizadas na plataforma.

Endpoint: GET /v1/audit

Query Parameters:

Parâmetro	Tipo	Descrição	Exemplo
`page`	integer	Número da página	`1`
`pageSize`	integer	Itens por página	`50`
`route`	string	Filtrar por rota	`/v1/tokens`
`method`	string	Método HTTP	`POST`
`action`	string	Ação realizada	`mint`, `burn`, `block`
`resourceType`	string	Tipo de recurso	`tokens`, `wallets`
`statusCode`	integer	Código HTTP	`200`, `400`, `500`
`contractAddress`	string	Endereço do contrato	`0xtoken...`
`reason`	string	Filtrar por motivo	`Court order`
`startDate`	string	Data inicial (ISO 8601)	`2025-12-01T00:00:00Z`
`endDate`	string	Data final (ISO 8601)	`2025-12-31T23:59:59Z`

Exemplo - Buscar todas operações de um token:

Response: 200 OK

{
  "data": [
    {
      "id": "audit-uuid",
      "timestamp": "2025-12-23T10:00:00Z",
      "route": "/v1/tokens/:address/mint",
      "method": "POST",
      "action": "mint",
      "resourceType": "tokens",
      "resourceId": "token-uuid",
      "statusCode": 200,
      "contractAddress": "0xtoken...abc",
      "reason": "Loyalty reward",
      "metadata": {
        "amount": "1000",
        "to": "0xuser..."
      }
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "totalItems": 234,
    "totalPages": 5
  }
}

🔢 Formatos de Quantidade

A API aceita valores em formato human-friendly para melhor experiência:

Como Enviar Valores

Use o campo amountTokens com valores legíveis:

{
  "amountTokens": "100"      // 100 tokens
}

{
  "amountTokens": "1.5"      // 1.5 tokens
}

{
  "amountTokens": "0.001"    // 0.001 tokens
}

A API converte automaticamente para unidades raw (wei) baseado nos decimais do token.

Exemplo:

Token com 18 decimais

Você envia: "amountTokens": "100"

API converte para: 100000000000000000000 (wei)

Blockchain recebe o valor correto automaticamente

✅ Vantagem: Você não precisa calcular decimais manualmente!

📋 Códigos de Resposta HTTP

Código	Descrição
`200`	Sucesso (GET, PUT)
`201`	Criado com sucesso (POST)
`400`	Requisição inválida
`401`	Não autenticado (API key inválida)
`403`	Não autorizado
`404`	Recurso não encontrado
`409`	Conflito (recurso já existe)
`429`	Muitas requisições (rate limit)
`500`	Erro interno do servidor

❌ Formato de Erro

Todas as respostas de erro seguem este formato:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "amountTokens": "must be greater than 0"
    }
  }
}

Códigos de Erro Comuns:

Código	Descrição
`VALIDATION_ERROR`	Dados de entrada inválidos
`NOT_FOUND`	Recurso não encontrado
`UNAUTHORIZED`	API key inválida
`INSUFFICIENT_BALANCE`	Saldo insuficiente
`TOKEN_PAUSED`	Token está pausado
`USER_BLOCKED`	Usuário bloqueado
`INTERNAL_ERROR`	Erro interno

🛡️ Boas Práticas

Segurança

Nunca compartilhe sua API Key

Use HTTPS (obrigatório em produção)

Implemente rate limiting no seu lado

Valide respostas antes de processar

Auditoria

Sempre preencha reason em operações críticas:

Mint/Burn de tokens

Bloqueio/Desbloqueio de usuários

Pause/Unpause

Use metadata para rastreabilidade:

Ordens judiciais

IDs internos

Informações de compliance

Performance

Use paginação em listas grandes

Implemente cache de resultados quando apropriado

Faça requisições assíncronas para melhor UX

🚀 Workflow Exemplo: Onboarding de Cliente

Código Exemplo:

📞 Suporte

Documentação: https://docs.tokenone.com.br
Email: contato@tokenone.com.br

📄 Termos de Uso

Ao usar a TokenOne API, você concorda com nossos Termos de Serviço e Política de Privacidade.

Limitações de Rate:

Production: 1000 requisições/minuto

Sandbox: 100 requisições/minuto

Versão da API: v2
Última Atualização: 23 de Dezembro de 2025

Guia de Integração Rápida

TokenOne API#

🔐 Autenticação#

📚 Recursos da API#

Recursos Disponíveis#

🌐 Redes Suportadas#

💼 1. Wallets#

1.1 Criar Wallet#

1.2 Listar Wallets#

1.3 Obter Wallet por Endereço#

🪙 2. Tokens#

2.1 Criar Token (Deploy)#

2.2 Listar Tokens#

2.3 Mint (Criar) Tokens#

2.4 Burn (Queimar) Tokens#

2.5 Burn From (Queimar de Carteira)#

2.6 Pausar Token#

2.7 Despausar Token#

2.8 Bloquear Usuário#

2.9 Desbloquear Usuário#

💸 3. Transfers#

3.1 Criar Transferência#

3.2 Listar Transferências#

3.3 Obter Transferência#

📊 4. Audit (Auditoria)#

4.1 Consultar Logs de Auditoria#

🔢 Formatos de Quantidade#

Como Enviar Valores#

📋 Códigos de Resposta HTTP#

❌ Formato de Erro#

🛡️ Boas Práticas#

Segurança#

Auditoria#

Performance#

🚀 Workflow Exemplo: Onboarding de Cliente#

📞 Suporte#

📄 Termos de Uso#

TokenOne API

🔐 Autenticação

📚 Recursos da API

Recursos Disponíveis

🌐 Redes Suportadas

💼 1. Wallets

1.1 Criar Wallet

1.2 Listar Wallets

1.3 Obter Wallet por Endereço

🪙 2. Tokens

2.1 Criar Token (Deploy)

2.2 Listar Tokens

2.3 Mint (Criar) Tokens

2.4 Burn (Queimar) Tokens

2.5 Burn From (Queimar de Carteira)

2.6 Pausar Token

2.7 Despausar Token

2.8 Bloquear Usuário

2.9 Desbloquear Usuário

💸 3. Transfers

3.1 Criar Transferência

3.2 Listar Transferências

3.3 Obter Transferência

📊 4. Audit (Auditoria)

4.1 Consultar Logs de Auditoria

🔢 Formatos de Quantidade

Como Enviar Valores

📋 Códigos de Resposta HTTP

❌ Formato de Erro

🛡️ Boas Práticas

Segurança

Auditoria

Performance

🚀 Workflow Exemplo: Onboarding de Cliente

📞 Suporte

📄 Termos de Uso