TokenOne API - Referência Completa

Bem-vindo à documentação da TokenOne CaaS API — a solução completa para criação e gestão de carteiras (smart accounts ERC-4337) e tokens ERC-20 nas redes Polygon e XDC, com deployment 100% gasless.

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

Todos os endpoints abaixo são relativos a essa base (ex.: POST /v1/wallets → https://caas-api.tokenone.com.br/v1/wallets).

🔐 Autenticação

Como obter sua API Key

Acesse o CaaS TokenOne e faça login.

No menu lateral, abra API Keys.

Ao criar sua conta, uma chave tk_test_ já é gerada automaticamente (sandbox).

A chave de produção (tk_live_) é provisionada mediante solicitação ao suporte.

As APIs de dados (wallets, tokens, transfers, transactions, audit) são autenticadas via API Key no header:

x-api-key: SUA_API_KEY

Chaves de Teste e Produção (test / live)

A TokenOne segue o modelo Stripe: o ambiente é determinado pelo prefixo da própria chave, não pela URL. A base é sempre a mesma (caas-api.tokenone.com.br).

Prefixo	Ambiente	Redes permitidas	Dados
`tk_test_…`	Testnet (Sandbox)	`polygon-amoy`, `xdc-testnet`	Isolados (dados de teste)
`tk_live_…`	Mainnet (Produção)	`polygon-mainnet`, `xdc-mainnet`	Reais (on-chain)

Uma chave tk_test_ só opera em redes de teste e uma tk_live_ só em mainnets. Usar uma rede incompatível com o ambiente da chave retorna erro de validação.

🌐 Ambientes

Ambiente	API Key	Redes	Uso
Sandbox	`tk_test_…`	Polygon Amoy, XDC Apothem	Desenvolvimento e testes, sem custo/valor real
Produção	`tk_live_…`	Polygon Mainnet, XDC Network	Operações reais on-chain

Não há URL separada por ambiente — a mesma https://caas-api.tokenone.com.br atende os dois; o que muda é a chave.

📚 Recursos da API

Recurso	Descrição	Endpoints
Wallets	Carteiras digitais (smart accounts ERC-4337)	3
Tokens	Tokens ERC-20 personalizados	9
Transfers	Transferências de tokens ERC-20	3
Transactions	Execução de chamadas de contrato arbitrárias	1
Audit	Logs de auditoria	1

Total: 17 endpoints de dados REST (autenticados por x-api-key).

O dashboard usa endpoints de console adicionais (login, gestão de API keys, webhook secret) autenticados por JWT (Authorization: Bearer). Eles não fazem parte desta referência de integração.

🌐 Redes Suportadas

Rede	Identificador	Chain ID	Tipo	Explorer
Polygon Mainnet	`polygon-mainnet`	137	Produção (`tk_live_`)	polygonscan.com
Polygon Amoy	`polygon-amoy`	80002	Testnet (`tk_test_`)	amoy.polygonscan.com
XDC Network	`xdc-mainnet`	50	Produção (`tk_live_`)	xdcscan.io
XDC Apothem	`xdc-testnet`	51	Testnet (`tk_test_`)	apothem.xdcscan.io

💼 1. Wallets

1.1 Criar Wallet

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

Endpoint: POST /v1/wallets

Request:

{
  "network": "xdc-testnet",
  "extRef": "customer-12345"
}

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`network`	string	Sim	Rede blockchain (deve ser compatível com o ambiente da chave)
`extRef`	string	Não	Referência externa para seu sistema

Response: 201 Created

{
  "id": "wallet-uuid",
  "address": "0x1234...5678",
  "network": "xdc-testnet",
  "status": "active",
  "extRef": "customer-12345",
  "createdAt": "2026-06-03T10:00:00Z"
}

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

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": "xdc-testnet",
      "status": "active",
      "extRef": "customer-12345",
      "createdAt": "2026-06-03T10: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": "xdc-testnet",
  "status": "active",
  "balance": {
    "native": "1.5",
    "tokens": [
      {
        "contractAddress": "0xtoken...",
        "symbol": "DEBXYZ25",
        "balance": "1000.0",
        "decimals": 6
      }
    ]
  },
  "createdAt": "2026-06-03T10: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": "Debenture Empresa XYZ 2025",
  "symbol": "DEBXYZ25",
  "decimals": 6,
  "network": "xdc-testnet",
  "initialSupplyTokens": "10000000",
  "maxSupplyTokens": "100000000",
  "metadata": {
    "description": "Debenture emitida pela Empresa XYZ com vencimento em 2025",
    "website": "https://empresaxyz.com.br",
    "cnpj": "12.345.678/0001-90"
  }
}

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 (máx: 10 caracteres)
`decimals`	integer	Sim	Casas decimais: deve ser `6` (fixado no contrato)
`network`	string	Sim	Rede blockchain (compatível com o ambiente da chave)
`initialSupplyTokens`	string	Não	Supply inicial em unidades legíveis (ex: `"1000000"`)
`maxSupplyTokens`	string	Não	Supply máximo em unidades legíveis
`metadata`	object	Não	Metadados adicionais

Response: 201 Created

{
  "token": {
    "id": "token-uuid",
    "contractAddress": "0xtoken...abc",
    "name": "Debenture Empresa XYZ 2025",
    "symbol": "DEBXYZ25",
    "decimals": 6,
    "network": "xdc-testnet",
    "deployed": true
  },
  "transactionHash": "0xtxhash...",
  "explorerUrls": {
    "transaction": "https://apothem.xdcscan.io/tx/0x...",
    "token": "https://apothem.xdcscan.io/token/0x..."
  }
}

Os explorerUrls variam conforme a rede (polygonscan.com / amoy.polygonscan.com / xdcscan.io / apothem.xdcscan.io).

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": "Debenture Empresa XYZ 2025",
      "symbol": "DEBXYZ25",
      "decimals": 6,
      "network": "xdc-testnet",
      "totalSupply": "10000000",
      "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/{contractAddress}/mint

Path Parameters:

Parâmetro	Tipo	Descrição
`contractAddress`	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/{contractAddress}/burn

Request:

{
  "amountTokens": "500",
  "reason": "Programa de buyback - Junho 2026"
}

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/{contractAddress}/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/{contractAddress}/pause

Request:

{
  "reason": "Pausa emergencial - Vulnerabilidade detectada",
  "metadata": {
    "incidentId": "SEC-2026-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/{contractAddress}/unpause

Request:

{
  "reason": "Retomar operações - Vulnerabilidade corrigida",
  "metadata": {
    "incidentId": "SEC-2026-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/{contractAddress}/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/{contractAddress}/blocklist/{userAddress}/unblock

Path Parameters:

Parâmetro	Tipo	Descrição
`contractAddress`	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 do token nativo (POL/MATIC/XDC) não estã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": "2026-06-03T15: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. Transactions

4.1 Executar Transação (chamada de contrato)

Executa uma chamada arbitrária de contrato a partir de uma smart account (gasless). Use para interagir com contratos além das operações nativas de token/transfer.

Endpoint: POST /v1/transactions/execute

Request:

{
  "from": "0xsender...address",
  "to": "0xcontract...address",
  "data": "0xa9059cbb000000000000000000000000...",
  "value": "0",
  "network": "xdc-testnet",
  "reason": "Aprovação de gasto em contrato de staking",
  "metadata": {
    "integration": "staking-v2"
  }
}

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`from`	string	Sim	Smart account de origem
`to`	string	Sim	Endereço do contrato/destino
`data`	string	Sim	Calldata codificada (hex `0x...`)
`value`	string	Não	Valor nativo a enviar (padrão `"0"`)
`network`	string	Não	Rede (compatível com o ambiente da chave)
`reason`	string	Não	Motivo (auditoria)
`metadata`	object	Não	Dados adicionais

Response: 200 OK

{
  "transactionId": "tx-uuid",
  "hash": "0xtx...hash",
  "userOpHash": "0xuserop...hash",
  "status": "pending",
  "gasFee": "0.0012"
}

📊 5. Audit (Auditoria)

5.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)	`2026-06-01T00:00:00Z`
`endDate`	string	Data final (ISO 8601)	`2026-06-30T23:59:59Z`

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

Response: 200 OK

{
  "data": [
    {
      "id": "audit-uuid",
      "timestamp": "2026-06-03T10: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 com base nos decimais do token.

Exemplo:

Tokens TokenOne usam 6 decimais.

Você envia: "amountTokens": "100"

API converte para: 100000000 (raw = 100 × 10^6)

A 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, operações)
`201`	Criado com sucesso (POST de criação)
`400`	Requisição inválida
`401`	Não autenticado (API key ausente/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 ausente ou 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 nem a exponha no front-end.

Use HTTPS (obrigatório).

Comece sempre em sandbox (tk_test_) antes de ir para produção (tk_live_).

Valide as respostas antes de processar.

Auditoria

Sempre preencha reason em operações críticas (mint, burn, pause/unpause, block/unblock).

Use metadata para rastreabilidade (ordens judiciais, IDs internos, compliance).

Performance

Use paginação em listas grandes.

Implemente cache quando apropriado.

Respeite o rate limit (ver abaixo) e implemente retry com backoff em 429.

🚀 Workflow Exemplo: Onboarding de Cliente

Código Exemplo (sandbox):

Em produção, troque a base/rede por tk_live_… + polygon-mainnet (ou xdc-mainnet).

📞 Suporte

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

Dashboard: https://caas.tokenone.com.br

Email: suporte@tokenone.com.br

📄 Termos de Uso

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

Limite de Rate (padrão): 100 requisições por minuto, por tenant. Requisições acima do limite recebem 429 Too Many Requests.

Versão da API: v1
Última Atualização: 3 de junho de 2026

TokenOne API - Referência Completa

🔐 Autenticação#

Como obter sua API Key#

Chaves de Teste e Produção (test / live)#

🌐 Ambientes#

📚 Recursos da API#

🌐 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. Transactions#

4.1 Executar Transação (chamada de contrato)#

📊 5. Audit (Auditoria)#

5.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#

🔐 Autenticação

Como obter sua API Key

Chaves de Teste e Produção (test / live)

🌐 Ambientes

📚 Recursos da API

🌐 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. Transactions

4.1 Executar Transação (chamada de contrato)

📊 5. Audit (Auditoria)

5.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