Referência da API

A API COFRI fornece infraestrutura de custódia para L-BTC, USDt e DePix. Todas as requisições usam JSON sobre HTTPS.

Base URL https://api.cofri.digital

· Todos os valores monetários estão em satoshis (inteiros). 1 L-BTC = 100.000.000 sat.

Autenticação

Use Bearer Token no header Authorization de todas as requisições autenticadas.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Tokens de acesso expiram em 1 hora. Use o endpoint /auth/refresh com o refresh token (válido por 7 dias) para renovar sem novo login.

Erros

Todos os erros seguem o mesmo envelope:

{ "status": false, "message": "...", "code": "ERROR_CODE", "timestamp": 1779900000 }

HTTP	Código	Causa
400	VALIDATION_ERROR	Payload inválido ou campos faltando
401	UNAUTHORIZED	Token ausente, inválido ou expirado
403	FORBIDDEN	Sem permissão para o recurso
404	NOT_FOUND	Recurso não encontrado
422	VALIDATION_ERROR	Email já registrado, saldo insuficiente
429	RATE_LIMIT_EXCEEDED	Muitas requisições — aguarde
500	INTERNAL_ERROR	Erro interno

Rate Limiting

Endpoint	Limite	Janela
POST /auth/login	5 req	5 min
POST /auth/register	3 req	1 hora
Demais	100 req	1 min

Login

POST /auth/login Retorna access + refresh token

Campo	Tipo		Descrição
email	string	obrig.	E-mail da conta
password	string	obrig.	Senha

POST /auth/login
Content-Type: application/json

{ "email": "eu@exemplo.com", "password": "minhasenha" }

// Resposta 200
{
  "status": true,
  "data": {
    "access_token": "eyJ...",
    "refresh_token": "eyJ...",
    "expires_in": 3600,
    "user": { "id": "uuid", "name": "...", "email": "..." }
  }
}

Registro

POST /auth/register Cria conta e provisiona carteira

Campo	Tipo		Descrição
name	string	obrig.	Nome completo
email	string	obrig.	E-mail único
password	string	obrig.	Mínimo 8 caracteres
company_name	string	—	Nome da empresa (opcional)

// Resposta 201
{
  "status": true,
  "message": "Account created successfully",
  "data": { "access_token": "eyJ...", "user": { ... } }
}

Refresh Token

POST /auth/refresh Renova o access token

Campo	Tipo
refresh_token	string	obrig.

Perfil

GET /auth/me Dados do usuário autenticado

🔒Requer token

{ "status": true, "data": { "id": "uuid", "name": "...", "email": "...", "role": "user" } }

Saldos

GET /wallet/balances Saldo de todos os ativos

🔒Requer token

{
  "status": true,
  "data": {
    "balances": {
      "L-BTC":  { "available": 100000000, "locked": 0 },
      "USDt":   { "available": 10000000000, "locked": 0 },
      "DePix":  { "available": 50000000000, "locked": 0 }
    }
  }
}

Gerar Endereço

POST /wallet/address Endereço Liquid para depósito

🔒Requer token

Campo	Tipo		Descrição
asset	string	obrig.	`L-BTC`, `USDt` ou `DePix`

{ "status": true, "data": { "address": "VJLCbLBTk...", "asset": "L-BTC" } }

Transações

GET /wallet/transactions Histórico paginado

🔒Requer token

Query param	Padrão	Descrição
page	1	Página
per_page	20	Itens por página (máx 100)
asset	—	`L-BTC`, `USDt` ou `DePix`
type	—	`deposit` ou `withdrawal`

Saque

POST /wallet/withdraw Cria solicitação de saque on-chain

🔒Requer token

⚠Saques são processados em fila. TXID retornado via webhook ao confirmar.

Campo	Tipo		Descrição
asset	string	obrig.	`L-BTC`, `USDt` ou `DePix`
amount	integer	obrig.	Valor em satoshis
address	string	obrig.	Endereço Liquid de destino
memo	string	—	Referência interna (máx 255 chars)

POST /wallet/withdraw
Authorization: Bearer <token>
Content-Type: application/json

{
  "asset": "L-BTC",
  "amount": 1000000,
  "address": "VJLCbLBTk...",
  "memo": "pagamento-123"
}

// Resposta
{ "status": true, "data": { "withdrawal_id": "uuid", "status": "queued", "fee": 500 } }

Pix — Criar Cobrança

POST /pix/create Gera QR Code Pix e converte para cripto

🔒Requer token

Campo	Tipo		Descrição
amount_brl	number	obrig.	Valor em reais (ex: 150.00)
asset	string	obrig.	`DePix`, `USDt` ou `L-BTC`
description	string	—	Descrição da cobrança
external_id	string	—	ID do seu sistema

{
  "status": true,
  "data": {
    "id": "uuid",
    "pix_copy_paste": "00020126580014BR.GOV.BCB.PIX...",
    "qr_code_base64": "data:image/png;base64,...",
    "amount_brl": 150.00,
    "asset": "DePix",
    "status": "pending",
    "expires_at": "2026-01-01T01:00:00Z"
  }
}

Pix — Status

GET /pix/status/{id} Status de um pagamento

🔒Requer token

Status: pending → confirmed → depix_sent → credited

Casos especiais: after7d (retenção 7 dias), expired, failed

Pix — Taxas

GET /pix/fees Taxas atuais e cotação estimada

🔒Requer token

Webhooks

Eventos disparados: deposit.confirmed · withdrawal.completed · withdrawal.failed · pix.credited

⚠ Sempre valide o header X-COFRI-Signature (HMAC-SHA256) nos webhooks recebidos.

GET /webhooks Lista webhooks cadastrados

🔒Requer token

POST /webhooks Registra endpoint para eventos

🔒Requer token

Campo	Tipo		Descrição
url	string	obrig.	URL HTTPS de destino
events	array	obrig.	Lista de eventos a assinar
secret	string	—	Segredo HMAC (gerado se omitido)

Payload de exemplo

{
  "event": "deposit.confirmed",
  "data": {
    "deposit_id": "uuid", "user_id": "uuid",
    "asset": "L-BTC", "amount": 1000000,
    "txid": "abc123...", "confirmations": 2
  },
  "timestamp": 1779900000
}

DEL /webhooks/{id} Remove webhook

🔒Requer token

Ativos Suportados

Símbolo	Nome	Rede	Precisão	Confirmações
L-BTC	Liquid Bitcoin	Liquid Network	8 casas	2 blocos (~2 min)
USDt	Tether USD (Liquid)	Liquid Network	8 casas	2 blocos (~2 min)
DePix	DePix	Liquid Network	8 casas	2 blocos (~2 min)