API Docs — DePixfy

Visão Geral

Todos os endpoints da API estão sob o prefixo /api/v1. Toda requisição deve enviar Content-Type: application/json e a chave de autenticação no header X-Api-Key.

💡

O campo amount de cada destinatário é sempre o valor base — exatamente o que o destinatário recebe no Pix. A API retorna na resposta todos os cálculos de taxas e o total de DePix que você precisa depositar.

🧾

As taxas são fixas e não podem ser alteradas via API:

Taxa Eulen: 1,0% (mín. R$ 1,00) por destinatário.
Comissão da plataforma: 1,5% (mín. 1 DePix).

Autenticação

Envie a chave de API no header X-Api-Key em todas as requisições. Alternativamente, use Authorization: Bearer <chave>.

Via header

X-Api-Key: sua_chave_secreta_aqui

Authorization: Bearer sua_chave_secreta_aqui

⚙️

As chaves de API são configuradas pelo administrador do servidor na variável de ambiente EXTERNAL_API_KEYS, no formato chave1:NomePlataforma,chave2:OutraPlataforma. Solicite sua chave ao administrador.

Criar Pedido

POST/api/v1/orders

Cria um novo pedido de pagamento com um ou mais destinatários Pix. Retorna o endereço Liquid para depósito do DePix e todos os valores calculados.

Parâmetros do body

recipientsarrayrequired

Lista de destinatários Pix. Mínimo 1, máximo 25.

recipients[].typestringrequired

Tipo da chave Pix. Valores aceitos: "cpf", "cnpj", "email", "telefone", "aleatoria".

recipients[].keystringrequired

Chave Pix do destinatário (será validada e criptografada no servidor).

recipients[].taxNumberstringoptional

CPF/CNPJ do recebedor. Obrigatório para chaves "email", "telefone" e "aleatoria". Para chaves "cpf" e "cnpj", o servidor reaproveita o próprio valor da key e este campo pode ser omitido.

recipients[].amountnumberrequired

Valor em reais que o destinatário receberá no Pix (valor base). Ex: 100.00 para R$100,00. Mínimo R$10,00.

Exemplos de requisição

Minimal — sem comissão customizada

POST /api/v1/orders
Content-Type: application/json
X-Api-Key: sua_chave_aqui

{
  "recipients": [
    {
      "type": "cpf",
      "key": "123.456.789-00",
      "amount": 100.00
    }
  ]
}

Múltiplos destinatários

{
  "recipients": [
    { "type": "cpf",      "key": "123.456.789-00", "amount": 500.00 },
    { "type": "email",    "key": "joao@email.com",  "taxNumber": "123.456.789-00", "amount": 250.00 },
    { "type": "aleatoria","key": "6e9f7a05-...",    "taxNumber": "12.345.678/0001-90", "amount": 100.00 }
  ]
}

Resposta de sucesso — 200

Resposta

{
  "order": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2026-03-23T14:30:00.000Z",
    "updatedAt": "2026-03-23T14:30:00.000Z",
    "status": "awaiting_deposit",
    "source": {
      "type": "api",
      "apiKeyLabel": "MinhaPlatforma"
    },
    "totals": {
      "totalPixInCents": 10000,
      "estimatedHpmFeeInCents": 100,
      "operationalFeeInCents": 150,
      "totalToCollectInCents": 10250
    },
    "deposit": {
      "address": "lq1qqwd0c9x3u5s9n5rg9q7xge8f4rkns12345...",
      "assetLabel": "DePix",
      "expectedAmountInCents": 10250,
      "expectedAmountInBaseUnits": 10250,
      "qrDataUri": "data:image/png;base64,...",
      "receivedAmountInCents": 0,
      "receivedAmountInBaseUnits": 0,
      "fundedAt": null,
      "lastCheckedAt": null
    },
    "recipients": [
      {
        "id": "recipient-1",
        "pixKeyMasked": "***.456.789-**",
        "pixKeyType": "cpf",
        "payoutAmountInCents": 10000,
        "estimatedFeeInCents": 100,
        "status": "queued",
        "error": null,
        "createdAt": "2026-03-23T14:30:00.000Z",
        "completedAt": null,
        "hpm": {
          "depositAmountInCents": null,
          "payoutAmountInCents": 10000,
          "status": null,
          "expiration": null,
          "receiptUrl": null,
          "receipt": null
        },
        "payout": { "txid": null, "sentAt": null }
      }
    ],
    "capabilities": { "hpmEnabled": true }
  },
  "orderToken": "Ts3xKp9mN2..."
}

Campos importantes da resposta

order.idstring

UUID único do pedido. Use para consultar o status.

order.statusstring

Status inicial sempre será "awaiting_deposit".

order.totals.totalPixInCentsnumber

Soma dos valores base de todos os destinatários (em centavos).

order.totals.estimatedHpmFeeInCentsnumber

Taxa HPM/Eulen total estimada (fixa, imutável). Em centavos.

order.totals.operationalFeeInCentsnumber

Comissão da plataforma que ficará retida na carteira intermediária. Em centavos.

order.totals.totalToCollectInCentsnumber

Total de DePix que o usuário deve depositar no endereço abaixo. Em centavos.

order.deposit.addressstring

Endereço Liquid para depósito do DePix.

order.deposit.expectedAmountInCentsnumber

Valor exato a depositar em centavos (= totalToCollectInCents).

order.deposit.qrDataUristring

QR Code em base64 para exibir ao usuário.

orderTokenstring

Token de acesso ao pedido. Guarde para uso como alternativa de autenticação via X-Order-Token.

Consultar Pedido

GET/api/v1/orders/:orderId

Retorna o estado atualizado de um pedido. Cada chamada dispara internamente a reconciliação de depósito e de confirmações Eulen — use polling a cada 15–30 segundos enquanto aguarda o depósito ou a confirmação dos pagamentos.

🔑

Só é possível consultar pedidos criados pela mesma API key. Pedidos de outras plataformas retornam 404.

📄

Quando o Eulen/HPM confirma o saque, a API baixa o PDF temporário antes da expiração e passa a servir o comprovante por uma URL própria estável. Para baixar, faça GET order.recipients[].hpm.receiptUrl usando a mesma X-Api-Key do pedido.

Resposta de sucesso — 200 (pedido concluído)

Resposta — status: completed

{
  "order": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "totals": { ... },
    "deposit": {
      "receivedAmountInCents": 10250,
      "fundedAt": "2026-03-23T14:32:10.000Z",
      ...
    },
    "processing": {
      "startedAt": "2026-03-23T14:32:11.000Z",
      "finishedAt": "2026-03-23T14:33:45.000Z",
      "broadcastAmountInCents": 10100,
      "actualPlatformRetainedInCents": 150,
      ...
    },
    "recipients": [
      {
        "id": "recipient-1",
        "status": "completed",
        "completedAt": "2026-03-23T14:33:45.000Z",
        "hpm": {
          "depositAmountInCents": 10100,
          "payoutAmountInCents": 10000,
          "status": "sent",
          "receiptUrl": "/api/v1/orders/550e8400-e29b-41d4-a716-446655440000/recipients/recipient-1/receipt",
          "receipt": {
            "available": true,
            "status": "stored",
            "archivedAt": "2026-03-23T14:33:46.000Z",
            "contentType": "application/pdf",
            "sizeBytes": 38124,
            "sha256": "b7f2..."
          }
        },
        "payout": { "txid": "a1b2c3d4...", "sentAt": "2026-03-23T14:33:20.000Z" }
      }
    ]
  }
}

Campos importantes na fase de processamento

order.processing.broadcastAmountInCentsnumber

Valor total já enviado ao Eulen (em centavos).

order.processing.actualPlatformRetainedInCentsnumber

Valor efetivamente retido na carteira intermediária (comissão realizada).

order.recipients[].statusstring

Status individual de cada destinatário: "queued" → "quoted" → "funding_sent" → "completed" | "failed".

order.recipients[].hpm.receiptUrlstring

URL estável da própria API para baixar o PDF arquivado. Requer a mesma X-Api-Key do pedido.

order.recipients[].hpm.receiptobject

Metadata do comprovante arquivado: disponibilidade, hash, tamanho, MIME type e data de arquivamento.

order.recipients[].payout.txidstring

ID da transação Liquid enviada ao Eulen.

Status do Pedido

Fluxo típico: awaiting_deposit → processing_payouts → awaiting_hpm_confirmation → completed

awaiting_deposit

Aguardando depósitoPedido criado. Aguardando DePix no endereço de depósito.

processing_payouts

Processando pagamentosDepósito recebido. Enviando DePix ao Eulen para cada destinatário.

awaiting_hpm_confirmation

Aguardando confirmação EulenDePix enviado ao Eulen. Aguardando confirmação dos Pix.

completed

ConcluídoTodos os pagamentos Pix foram confirmados com sucesso.

completed_with_errors

Concluído com errosPelo menos um destinatário falhou. Verifique recipients[].error.

deposit_confirmed

Depósito confirmadoDepósito recebido mas HPM não configurado (modo manual).

manual_review

Revisão manualCotação HPM excedeu o saldo coletado. Requer intervenção do administrador.

expired

ExpiradoNenhum depósito recebido dentro do prazo configurado (padrão: 30 min).

Status dos destinatários (recipients[].status)

queued

Na filaAguardando processamento.

quoted

Cotação obtidaEulen retornou o endereço Liquid e o valor a enviar.

funding_sent

DePix enviadoTransação Liquid enviada ao Eulen.

completed

Pix confirmadoEulen confirmou o envio do Pix.

failed

FalhouEulen retornou erro. Verifique recipients[].error.

Tipos de Chave Pix

type	Descrição	Exemplo de key
`cpf`	CPF (11 dígitos)	123.456.789-00 ou 12345678900
`cnpj`	CNPJ (14 dígitos)	12.345.678/0001-99
`email`	E-mail	pagamento@empresa.com.br
`telefone`	Celular com DDI +55	+5511999887766
`aleatoria`	Chave aleatória (UUID)	6e9f7a05-1234-4abc-8def-000102030405

Erros

Todas as respostas de erro seguem o formato:

Formato de erro

{
  "error": "Chave de API invalida."
}

HTTP	Causa
`400`	Dados inválidos no body (tipo de chave, valor, formato)
`401`	API key ausente ou inválida
`404`	Pedido não encontrado ou pertencente a outra plataforma
`405`	Método HTTP não permitido
`413`	Body da requisição excede o limite (padrão: 32 KB)
`429`	Limite de requisições excedido — aguarde e tente novamente
`500`	Erro interno do servidor
`502`	Falha na comunicação com a Eulen ou a rede Liquid
`503`	Servidor mal configurado (variáveis de ambiente ausentes)

Módulo Swap

O módulo Swap permite converter DePix diretamente para criptoativos como SOL, BTC, ETH, USDC e outros — tudo via API, com autenticação por X-Api-Key. O fluxo é: listar ativos → obter cotação → criar conversão → monitorar status.

💡

A cotação obtida em /api/v1/swap/quote é estimada — o valor final depende das taxas de mercado no momento em que a conversão for processada. A taxa da plataforma é descontada sobre o valor bruto depositado.

Listar Ativos Disponíveis

GET/api/v1/swap/assets

Retorna a lista de criptoativos disponíveis para conversão e suas redes suportadas. Use o parâmetro scope=all para listar todos os ativos (em vez dos populares).

Parâmetros de query (opcionais)

scopestringoptional

Filtra o conjunto de ativos retornados. "popular" (padrão) — ativos mais usados. "all" — todos os ativos suportados pela BTSE.

Exemplo

Requisição e resposta

GET /api/v1/swap/assets
X-Api-Key: sua_chave_aqui

// Resposta
{
  "assets": [
    { "symbol": "SOL",  "name": "Solana",        "networks": ["SOLANA", "SPL"] },
    { "symbol": "BTC",  "name": "Bitcoin",        "networks": ["BITCOIN"] },
    { "symbol": "ETH",  "name": "Ethereum",       "networks": ["ETHEREUM", "ARBITRUM", "BASE"] },
    { "symbol": "USDC", "name": "USD Coin",       "networks": ["SOLANA", "ETHEREUM", "BASE"] },
    { "symbol": "USDT", "name": "Tether",         "networks": ["TRX", "ETHEREUM", "SOLANA"] }
  ],
  "scope": "popular"
}

Campos da resposta

assetsarray

Lista de ativos disponíveis.

assets[].symbolstring

Ticker do ativo (ex: SOL, BTC).

assets[].namestring

Nome completo do ativo.

assets[].networksarray

Redes disponíveis para saque (ex: SOLANA, BITCOIN).

scopestring

Escopo aplicado: "popular" ou "all".

Obter Cotação

GET/api/v1/swap/quote

Retorna as taxas de câmbio atuais e, opcionalmente, calcula todos os valores da conversão para um montante específico. Útil para exibir ao usuário antes de criar a ordem.

Parâmetros de query

destAssetstringrequired

Ticker do ativo de destino (ex: SOL, BTC, ETH, USDC).

destNetworkstringrequired

Rede de saque (ex: SOLANA, BITCOIN, ETHEREUM). Deve ser uma das redes retornadas em /swap/assets.

amountInCentsnumberoptional

Valor em centavos de DePix para calcular a conversão estimada. Omita para obter apenas as taxas.

Exemplo

Requisição

GET /api/v1/swap/quote?destAsset=SOL&destNetwork=SOLANA&amountInCents=10000
X-Api-Key: sua_chave_aqui

Resposta

{
  "sourceAsset": "DEPIX",
  "destAsset": "SOL",
  "destNetwork": "SOLANA",
  "availableNetworks": ["SOLANA", "SPL"],
  "usdtBrlRate": 5.87,
  "usdtBrlRateBase": 5.75,
  "destAssetUsdtRate": 148.32,
  "platformFeeRate": 0.01,
  "platformMinFeeInCents": 100,
  "swapMinAmountInCents": 1000,
  "swapMaxAmountInCents": 50000000,
  "destWithdrawFee": 0.002,
  "destWithdrawMin": 0.0345,
  "amountInCents": 10000,
  "platformFeeInCents": 100,
  "netAmountInCents": 9900,
  "usdtAmount": 1.6867,
  "estimatedDestAmount": 0.011279,
  "disclaimer": "Cotacao estimada. O valor final pode variar conforme as condicoes de mercado no momento da conversao."
}

Campos da resposta

usdtBrlRatenumber

Taxa DePix/USDT aplicada (com spread). Quantos reais por 1 USDT.

destAssetUsdtRatenumber

Preço do ativo de destino em USDT (1 SOL = X USDT).

platformFeeRatenumber

Taxa percentual da plataforma (ex: 0.01 = 1%).

platformMinFeeInCentsnumber

Taxa mínima da plataforma em centavos.

swapMinAmountInCentsnumber

Valor mínimo aceito para criar uma conversão (em centavos).

swapMaxAmountInCentsnumber

Valor máximo aceito para criar uma conversão (em centavos).

destWithdrawFeenumber

Taxa de saque da BTSE para a rede informada (em unidades do ativo destino).

destWithdrawMinnumber

Saldo mínimo necessário para saque (inclui buffer de 15%).

platformFeeInCentsnumber

Taxa da plataforma calculada para amountInCents (null se não informado).

netAmountInCentsnumber

Valor líquido após desconto da taxa da plataforma (em centavos).

usdtAmountnumber

Equivalente em USDT do valor líquido.

estimatedDestAmountnumber

Quantidade estimada do ativo de destino que será recebida, já descontada a taxa de saque.

Criar Conversão

POST/api/v1/swap

Cria uma nova ordem de conversão DePix → cripto. Retorna o endereço Liquid para depósito do DePix e o token de acesso da ordem.

⚠️

O endereço de destino (destAddress) é criptografado e nunca é retornado nas consultas posteriores — apenas uma versão mascarada. Guarde-o antes de criar a ordem.

Parâmetros do body

amountInCentsnumberrequired

Valor em centavos de DePix a converter. Deve estar dentro dos limites retornados pelo endpoint de cotação.

destAssetstringrequired

Ticker do ativo de destino (ex: SOL, BTC, ETH). Deve ser um ativo suportado.

destNetworkstringrequired

Rede de saque (ex: SOLANA, BITCOIN, ETHEREUM). Deve ser válida para o ativo informado.

destAddressstringrequired

Endereço da carteira de destino na rede informada. Validado por regex conforme a rede.

Exemplo

Requisição

POST /api/v1/swap
Content-Type: application/json
X-Api-Key: sua_chave_aqui

{
  "amountInCents": 10000,
  "destAsset": "SOL",
  "destNetwork": "SOLANA",
  "destAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
}

Resposta

{
  "swapOrder": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2026-03-31T10:00:00.000Z",
    "updatedAt": "2026-03-31T10:00:00.000Z",
    "status": "pending",
    "source": { "type": "api" },
    "quote": {
      "amountInCents": 10000,
      "destAsset": "SOL",
      "destNetwork": "SOLANA",
      "usdtBrlRate": 5.87,
      "destAssetUsdtRate": 148.32,
      "estimatedDestAmount": 0.011279,
      "platformFeeInCents": 100,
      "platformFeeRate": 0.01,
      "netAmountInCents": 9900,
      "usdtAmount": 1.6867,
      "quotedAt": "2026-03-31T10:00:00.000Z",
      "disclaimer": "Cotacao estimada..."
    },
    "deposit": {
      "address": "lq1qqwd0c9x3u5s9n5rg9q7xge8f4rkns12345...",
      "assetId": "ce091c998b83c78bb71a632313ba3...",
      "assetLabel": "DePix",
      "expectedAmountInCents": 10000,
      "expectedAmountInBaseUnits": 10000,
      "receivedAmountInCents": 0,
      "receivedAmountInBaseUnits": 0,
      "fundedAt": null,
      "lastCheckedAt": null
    },
    "destination": {
      "destAsset": "SOL",
      "destNetwork": "SOLANA",
      "destAddressMasked": "9WzDXw...AWWM"
    },
    "sideswap": { "swapTxid": null, "swappedAt": null, "usdtReceivedSat": null },
    "btse": { "usdtConfirmedAt": null, "convertedAmount": null, "withdrawalSentAt": null },
    "processing": {
      "startedAt": null,
      "finishedAt": null,
      "lastAttemptAt": null,
      "nextAttemptAt": null,
      "phase": null
    }
  },
  "swapToken": "Ts3xKp9mN2bVqFzR..."
}

Campos importantes da resposta

swapOrder.idstring

UUID único da conversão. Use para consultar o status.

swapOrder.statusstring

Status inicial sempre será "pending".

swapOrder.deposit.addressstring

Endereço Liquid para depósito do DePix.

swapOrder.deposit.expectedAmountInCentsnumber

Valor exato a depositar em centavos (= amountInCents).

swapOrder.quote.estimatedDestAmountnumber

Quantidade estimada do ativo de destino. O valor real pode variar conforme o mercado.

swapTokenstring

Token de acesso à ordem. Guarde para referência.

Consultar Conversão

GET/api/v1/swap/:swapId

Retorna o estado atual de uma conversão. Faça polling a cada 15–30 segundos enquanto o status for não-terminal (não for completed, failed ou expired).

🔑

Só é possível consultar conversões criadas pela mesma API key. Ordens de outras plataformas retornam 404.

Exemplo

Requisição e resposta (completed)

GET /api/v1/swap/550e8400-e29b-41d4-a716-446655440000
X-Api-Key: sua_chave_aqui

// Resposta — status: completed
{
  "swapOrder": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "quote": { ... },
    "deposit": {
      "receivedAmountInCents": 10000,
      "fundedAt": "2026-03-31T10:02:15.000Z",
      ...
    },
    "sideswap": {
      "swapTxid": "a1b2c3d4e5f6...",
      "swappedAt": "2026-03-31T10:03:00.000Z",
      "usdtReceivedSat": 168670000
    },
    "btse": {
      "usdtConfirmedAt": "2026-03-31T10:04:00.000Z",
      "convertedAmount": 0.011279,
      "withdrawalSentAt": "2026-03-31T10:05:30.000Z"
    },
    "processing": {
      "startedAt": "2026-03-31T10:02:16.000Z",
      "finishedAt": "2026-03-31T10:06:00.000Z",
      "phase": "done"
    }
  }
}

Campos de progresso

swapOrder.deposit.receivedAmountInCentsnumber

Valor de DePix já recebido no endereço de depósito.

swapOrder.deposit.fundedAtstring

Timestamp em que o depósito foi detectado (null até confirmação).

swapOrder.sideswap.swapTxidstring

TXID da conversão DePix→USDT no SideSwap.

swapOrder.sideswap.usdtReceivedSatnumber

USDT recebido em satoshis (8 casas decimais).

swapOrder.btse.usdtConfirmedAtstring

Timestamp de confirmação do USDT na BTSE.

swapOrder.btse.convertedAmountnumber

Quantidade de ativo de destino obtida na conversão (valor final).

swapOrder.btse.withdrawalSentAtstring

Timestamp em que o saque foi enviado ao endereço de destino.

Status da Conversão

Fluxo típico: pending → swapping_depix_to_usdt → sending_usdt_to_btse → waiting_btse_deposit → converting → withdrawing → completed

pending

Aguardando depósitoOrdem criada. Aguardando recebimento de DePix no endereço de depósito.

swapping_depix_to_usdt

Convertendo DePix → USDTDepósito recebido. Realizando swap de DePix para USDT via SideSwap.

sending_usdt_to_btse

Enviando USDT à BTSEUSDT obtido. Transferindo para o endereço de depósito na BTSE.

waiting_btse_deposit

Aguardando confirmação BTSEUSDT enviado. Aguardando a BTSE confirmar o recebimento.

converting

Convertendo na BTSEUSDT confirmado. Executando a conversão para o ativo de destino.

withdrawing

Realizando saqueConversão executada. Enviando o ativo de destino para o endereço informado.

completed

ConcluídoSaque confirmado. O ativo foi enviado ao endereço de destino com sucesso.

failed

FalhouOcorreu um erro durante o processamento. Contate o suporte.

expired

ExpiradoNenhum depósito recebido dentro do prazo configurado.

manual_review

Revisão manualSituação inesperada que requer intervenção do administrador.

DePixfy API v1 — Taxas Eulen padrão: 1,0% (mín. R$ 1,00) · Comissão padrão: 1,5% (mín. 1 DePix)

Documentação da API

Visão Geral

Autenticação

Criar Pedido

Parâmetros do body

Exemplos de requisição

Resposta de sucesso — 200

Campos importantes da resposta

Consultar Pedido

Resposta de sucesso — 200 (pedido concluído)

Campos importantes na fase de processamento

Status do Pedido

Status dos destinatários (recipients[].status)

Tipos de Chave Pix

Erros

Listar Ativos Disponíveis

Parâmetros de query (opcionais)

Exemplo

Campos da resposta

Obter Cotação

Parâmetros de query

Exemplo

Campos da resposta

Criar Conversão

Parâmetros do body

Exemplo

Campos importantes da resposta

Consultar Conversão

Exemplo

Campos de progresso

Status da Conversão