📊 Portal de Leitura sobre Seus Usuários (Participant Portal)

Status: rollout gradual. Esta funcionalidade está sendo habilitada progressivamente por participante. Se PARTICIPANT_PORTAL_FEATURE_DISABLED for retornado, ainda não está ativa para sua conta — fale com seu gerente de conta para solicitar acesso.

Esta página detalha os endpoints de somente leitura que seu backend usa para consultar status, saldo e transações dos usuários vinculados à sua conta — com a mesma credencial de participante (client_id/client_secret) que você já usa em POST /auth/api-key.

🔒 Regra de Segurança: Essa credencial é de leitura para dados de usuário. Ela nunca aciona Pix, Swap ou saque cripto em nome de um usuário — isso não é uma limitação temporária, é uma decisão de arquitetura permanente. Recomendamos testar isso ativamente no seu processo de QA: chamar POST /pix/withdraw ou POST /swap/execute com sua credencial de participante deve sempre ser rejeitado.

1. Listar Usuários Vinculados

curl "https://api.dexkey.finance/v1/participant/users?page=1&pageSize=20" \
  -H "Authorization: Bearer $TOKEN"

Paginação obrigatória — pageSize tem teto de 50, mesmo se você pedir mais.

{
  "data": [
    { "userId": "550e8400-e29b-41d4-a716-446655440000", "status": "ACTIVE", "accountStatus": "FULL", "kycStatus": "APPROVED", "createdAt": "2026-01-10T12:00:00.000Z" },
    { "userId": "660e8400-e29b-41d4-a716-446655440001", "status": "ACTIVE", "accountStatus": "BASIC", "kycStatus": null, "createdAt": "2026-01-15T09:00:00.000Z" }
  ],
  "total": 2,
  "page": 1,
  "pageSize": 20
}

2. Detalhe Básico de um Usuário

curl https://api.dexkey.finance/v1/participant/users/{userId} \
  -H "Authorization: Bearer $TOKEN"

Mesmo formato de um item da lista acima.

3. Saldo (cache de 30s)

curl https://api.dexkey.finance/v1/participant/users/{userId}/balance \
  -H "Authorization: Bearer $TOKEN"

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountCode": "550e8400-e29b-41d4-a716-446655440000",
  "balances": [
    {
      "currency": "BTC",
      "amount": "920",
      "formatted": "0.00000920 BTC",
      "brlValue": "35", "brlFormatted": "R$ 0,35",
      "usdValue": "7", "usdFormatted": "US$ 0.07",
      "eurValue": "6", "eurFormatted": "€ 0,06"
    }
  ],
  "consolidated": {
    "brlValue": "150035", "brlFormatted": "R$ 1.500,35",
    "usdValue": "29507", "usdFormatted": "US$ 295.07",
    "eurValue": "27206", "eurFormatted": "€ 272,06"
  },
  "isActive": true,
  "updatedAt": "2026-01-20T12:30:00.000Z"
}

amount de cada moeda vem na menor unidade; use

formatted (ou os *Formatted em fiat) para exibição.

4. Transações (cache de 30s) — Conciliação Diária

curl "https://api.dexkey.finance/v1/participant/users/{userId}/transactions?startDate=2026-01-20T00:00:00Z&endDate=2026-01-20T23:59:59Z&limit=50" \
  -H "Authorization: Bearer $TOKEN"

Query param	Descrição
`startDate` / `endDate`	ISO 8601 — filtra por período
`type`	Tipo de transação (ex: `CRYPTO_SWAP`, `TRANSFER_INTERNAL`, `PENDING_TRANSFER`)
`status`	Status (ex: `COMPLETED`)
`currency`	Filtra por moeda
`page` / `limit`	Paginação — atenção: aqui o parâmetro é `limit`, não `pageSize` (esse nome é só do endpoint de listar usuários, seção 1). Máximo 100 por página.

{
  "data": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "type": "CRYPTO_SWAP",
      "status": "COMPLETED",
      "amount": "1900609",
      "formattedAmount": "1.900609 USDC",
      "currency": "USDC",
      "totalFee": "9500",
      "participantFee": "4200",
      "netAmount": "1891109",
      "netAmountFormatted": "1.891109 USDC",
      "swapDetails": {
        "fromCurrency": "BRT",
        "toCurrency": "USDC",
        "rate": "0.195775"
      },
      "createdAt": "2026-01-20T10:00:00.000Z",
      "completedAt": "2026-01-20T10:00:05.000Z",
      "user": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Nome do Usuário" }
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}

Reconciliação de fee e câmbio: totalFee, participantFee (sua própria comissão),netAmount e — para swaps — swapDetails.rate/fromCurrency/toCurrency já vêm nesse retorno. O único campo omitido é platformFee (a comissão da própria Ether),que é sempre null para credenciais de participante — o resto da estrutura é a mesma usada internamente pelo nosso painel admin.

⚠️ Atenção — campo user dentro de cada transação: ele não é garantidamente o usuário que você consultou na URL. Em TRANSFER_INTERNAL, PENDING_TRANSFER e PENDING_TRANSFER_EXPIRY (transferências P2P), esse campo mostra a contraparte da movimentação — que pode ser um usuário de outro participante, ou de nenhum, já que transferências P2P no DEX não são restritas a usuários do mesmo participante. O único dado garantidamente seu é o {userId} que você informou na URL: é sobre ele que a lista inteira é filtrada, mesmo que a contraparte mostrada em cada linha não seja. Não trate user como "dado do seu cliente" automaticamente.

O Que Essa Visão NÃO Mostra

Documentos de KYC, CPF ou qualquer outro dado sensível — só status da conta, status resumido do KYC, saldo e transações. Consultar um usuário que não é seu retorna 403.

Limites

30 requisições por minuto por participante, em todos os endpoints desta página.

Erros Específicos

Código	Situação
`PARTICIPANT_PORTAL_USER_OUT_OF_SCOPE`	O `userId` consultado não pertence a você (`403`)
`PARTICIPANT_PORTAL_USER_NOT_FOUND`	O `userId` informado não existe (`404`)
`PARTICIPANT_PORTAL_FEATURE_DISABLED`	Funcionalidade ainda não habilitada para o seu participante (`403`)
`PARTICIPANT_PORTAL_CONTEXT_REQUIRED`	O token usado não é uma credencial de participante válida (`403`)

Construir o Aplicativo do Seu Cliente (Front-end)

Integração de Backend Corporativo (Participante B2B)