Pular para o conteúdo principal
Esta página é para o outro lado de uma troca do Didit Travel Rule: a VASP contraparte (ou a equipe de engenharia dela) que precisa enviar dados de Travel Rule para uma VASP que usa a Didit, ou recebê-los dela. Tudo o que está documentado aqui é infraestrutura pública operada pela Didit. Você não precisa de uma conta Didit, de uma chave de API nem de qualquer relação comercial com a Didit para interoperar: a integração mais profunda exige apenas HTTPS e JSON.

​
Como a Didit roteia uma transferência

Quando um cliente da Didit envia uma transferência, a Didit tenta estes canais em ordem estrita de prioridade e usa o primeiro que consegue alcançar você:
A Didit não consegue receber uma resposta TRUST e ainda não aceita transferências enviadas a ela por uma rede. Pelo TRUST, a transferência de um cliente da Didit chega até você, mas sua resposta não consegue voltar, e a transferência expira no prazo de confirmação do remetente em vez de ser concluída. Pelo GTR, VERIFYVASP e SYGNA, a Didit lê sua resposta na própria rede, pela resposta dela ou consultando periodicamente o status da transferência.
A tabela acima cobre as transferências que um cliente da Didit envia. Quando você envia uma transferência a um cliente da Didit, a Didit só consegue recebê-la como uma consulta de transferência TRP, assim que o host TRP público da Didit estiver ativo (ele ainda não responde, veja Endpoints TRP), ou, após a liquidação, como um registro de sunrise: hoje, nenhum canal de rede e nenhum canal de e-mail entrega uma transferência de entrada a um cliente da Didit. Os canais de rede (GTR, TRUST, VERIFYVASP, SYGNA) funcionam por meio de uma associação do lado remetente. Hoje, essa precisa ser a associação conectada do próprio cliente da Didit: a Didit ainda não tem associação de plataforma em nenhuma dessas redes e está em processo de onboarding como provedora. O GTR não está incluído por padrão, e o mesmo requisito de associação se aplica às quatro redes. O remetente deve verificar o objeto networks em Obter configurações da Travel Rule: didit significa que a associação da Didit inclui essa aplicação como participante próprio na rede, own significa uma associação conectada do cliente, off significa que o roteamento da plataforma está desativado e unavailable significa que nada pode enviar por essa rede para a aplicação ainda. Até que a Didit tenha uma associação de plataforma, nenhuma rede informa didit. Ativar a Travel Rule não ativa uma associação de rede. Veja Redes da Travel Rule para saber o que cada rede alcança hoje. Se você estiver em uma dessas redes e o cliente da Didit tiver associação própria nela, compartilhe seu identificador de rede com ele e a transferência chegará até você pela rede que você já opera. Pelo SYGNA, sua resposta de permissão conclui ou recusa a transferência: a Didit consulta o status da transferência a cada 5 minutos e também registra https://trp.didit.me/sygna/callbacks/permission/{token}/ como callback de cada requisição de permissão, com um token gerado para aquela transferência. Esse callback fica no host TRP público da Didit, que ainda não atende requisições. Um permission_status igual a ACCEPTED move a transferência do remetente para COMPLETED, e REJECTED a move para COUNTERPARTY_VASP_GENERAL_DECLINE, ou para COUNTERPARTY_MISMATCHED_DATA quando o reject_code é BVRC007 (o nome do beneficiário não corresponde). O callback exige sua assinatura: ele responde 401 com {"status": "INVALID_SIGNATURE"} sem uma assinatura válida, 404 para um token desconhecido e 200 novamente para uma decisão que já aplicou. Sem nenhuma associação em comum, o TRP é o caminho para o qual você deve se preparar: compartilhe seu Travel Address com o cliente da Didit, e as transferências dele chegarão ao seu endpoint TRP. Uma resposta que você dá na resposta à consulta conclui ou recusa a transferência imediatamente; uma resposta que você envia depois ao callback da Didit precisa do host TRP público da Didit, que ainda não está ativo. Quando nenhum dos canais consegue identificar você, a Didit executa mais uma etapa de resolução: atribuição por análise de blockchain. A carteira de destino é resolvida com base em dados de análise de blockchain e, quando é atribuída à sua exchange ou ao seu serviço de custódia, a Didit registra seu nome no diretório de VASPs dela e tenta novamente os canais com ele. Isso significa que você pode ser identificado mesmo quando o remetente não forneceu nada além de um endereço de carteira. As transferências atribuídas só são roteadas automaticamente para você quando sua entrada no diretório tem uma rota: um endpoint TRP verificado, uma listagem em rede ou um contato de conformidade (veja Como entrar no diretório de VASPs da Didit). A cadeia completa de resolução é, portanto: um cliente da Didit que comprovou o controle da carteira (INTERNAL) e o Travel Address que o remetente armazenou para ela, depois os canais de protocolo e de rede e, por fim, a análise de blockchain.

​
Travel addresses

Todo VASP da Didit com a Travel Rule ativada tem um travel address: uma string compacta que começa com ta e codifica a URL do seu endpoint TRP próprio de consulta de transferências. Os clientes da Didit consultam o seu nas configurações da Travel Rule e o compartilham com as contrapartes; quando um cliente da Didit fornece o dele a você, você tem tudo o que é necessário para alcançá-lo via TRP. A codificação segue a convenção de travel address do TRP:
  • Remova o prefixo ta.
  • Decodifique o restante com Base58Check (alfabeto do Bitcoin, checksum double-SHA256).
  • Os bytes decodificados são a URL de consulta sem o esquema; adicione https:// no início.
  • A URL sempre contém o par de consulta t=i (tipo: consulta).
Um travel address da Didit decodificado tem um destes dois formatos:
{profile_uuid} identifica o perfil de VASP hospedado: envie suas consultas de transferência via POST para essa URL e, antes, consulte o endpoint de identidade correspondente para confirmar com quem você está falando. O segundo formato é um travel address por carteira: ele indica uma carteira específica do cliente da Didit (receiving_travel_address no catálogo de endereços dele), de modo que sua consulta chega a essa carteira sem que o cliente precise identificá-la pelo número da conta ou pelo nome do titular. Ele responde 404 assim que a carteira é excluída ou registrada como pertencente a outro VASP.

​
Endpoints TRP

A Didit usa a versão 3.2.1 da API TRP na URL base https://trp.didit.me. Todos os endpoints trocam JSON por HTTPS.
O host TRP público da Didit ainda não disponibiliza estes endpoints. Até que isso aconteça, uma consulta TRP ou uma requisição de identidade destinada a um cliente da Didit não pode ser entregue; esta seção descreve o contrato que o host atenderá quando estiver ativo.
Dois cabeçalhos TRP são relevantes:
  • api-version - a versão do protocolo TRP que você usa, por exemplo 3.2.1. Obrigatório nas consultas e nos dois callbacks.
  • request-identifier - seu id exclusivo para a requisição, devolvido nos cabeçalhos da resposta. Obrigatório nas consultas e nos dois callbacks.
Uma requisição aos endpoints de consulta ou de callback sem os dois cabeçalhos retorna 400. Toda resposta da Didit inclui api-version: 3.2.1 e devolve o seu request-identifier.

​
GET /identity

Retorna a identidade do operador da plataforma. Nenhum cabeçalho é obrigatório.

​
GET /trp/identity//

Retorna a identidade do VASP específico com o qual você está prestes a fazer a troca. Use-a para verificar o nome e o LEI antes de enviar dados pessoais (PII). A Didit faz a mesma verificação no sentido inverso quando é ela quem inicia: se a identidade informada pelo seu endpoint não corresponder ao LEI ou ao nome esperado, a troca é interrompida.
Retorna 404 quando o perfil não existe ou quando a configuração de Travel Rule dele está desativada.

​
POST /trp/inquiries//

Envia uma consulta de transferência. Você é o VASP remetente e o cliente da Didit é o VASP beneficiário.
Nesta via, os ativos são identificados por DTI, e um DTI identifica um token em uma única blockchain. Hoje a Didit mapeia BTC (4H95J0R2X), ETH (X9J9K872S) e USDC em nove redes, e outros ativos são adicionados ao longo do tempo. Consulte Identificadores de ativos TRP para ver a lista completa. Uma consulta com um DTI que a Didit não reconhece ainda é aceita e apresentada ao VASP beneficiário com o DTI como código do ativo. Uma resposta 200 significa que a consulta foi aceita para processamento; 400 significa cabeçalhos TRP ausentes ou corpo inválido, 404 significa que o perfil (ou a carteira de um endereço por carteira) é desconhecido ou está desativado, e 422 significa que a requisição usa uma extensão TRP: a Didit não oferece suporte a nenhuma, então um cabeçalho api-extensions ou uma chave extensions no corpo é recusado. Reenviar o mesmo request-identifier é idempotente: a consulta original é reutilizada em vez de duplicada. Em seguida, a Didit cria a transferência de entrada na aplicação do cliente e a resolve com base no catálogo de endereços de carteiras e na política do cliente. Ela identifica o beneficiário pela carteira indicada em um Travel Address por carteira; caso contrário, pelo primeiro endereço de carteira em IVMS101.beneficiary.accountNumber; ou, sem nenhum, pelo nome em beneficiaryPersons[0].naturalPerson comparado às entradas de carteiras verificadas do cliente. A resposta 200 traz a resposta quando a Didit pode fornecê-la imediatamente:
  • {"approved": {"address": "...", "callback": "..."}} quando a consulta foi aprovada automaticamente. A Didit não envia essa aprovação também ao seu callback.
  • {"rejected": "NOT_ENOUGH_COUNTERPARTY_DATA: inquiry carries no beneficiary identification"} quando a consulta não indica nem o beneficiário nem um endereço de carteira; por isso, sempre inclua os dois.
  • {"version": "3.2.1"} quando a decisão depende do cliente da Didit. A resolução chega depois, como um POST para a sua URL de callback, com um dos dois corpos abaixo.
A aprovação pode ser automática (quando o VASP beneficiário ativa a aceitação automática e o beneficiário corresponde a uma entrada de carteira verificada na blockchain do ativo) ou ocorrer após uma revisão manual ou uma prova de propriedade da carteira do lado do beneficiário; portanto, considere um possível atraso entre a consulta e a resolução. Uma consulta nunca corresponde a uma carteira que o cliente da Didit registrou como sendo de outro VASP, e o nome do seu VASP em originatingVASP é o que o cliente da Didit vê como VASP remetente da transferência. A Didit não define prazo para uma consulta que você envia, e um cliente da Didit que a cancela não envia nenhuma rejeição a você; por isso, aplique seu próprio timeout. Depois de receber uma aprovação e transmitir a transferência on-chain, encerre a troca enviando um POST para a URL approved.callback que você recebeu:
Em vez disso, envie { "canceled": "reason" } para a mesma URL se você interromper a transferência. txid muda a transferência do lado do beneficiário para FINISHED; canceled a muda para CANCELLED. Os dois callbacks respondem 204 após o processamento, 404 para um token desconhecido ou para uma transferência que não está mais aguardando esse callback, e 400 para um corpo que não contém nenhum dos dois campos do callback.

​
Como resolver as consultas que a Didit envia para você

Quando um cliente da Didit inicia uma transferência para você via TRP, a Didit:
  1. Busca /identity na raiz do host da sua URL de consulta (https://{your-host}/identity) e verifica se o nome e o LEI informados correspondem ao que o cliente espera. Quando a rota vem do diretório da Didit, o seu /identity deve informar o LEI dessa entrada do diretório.
  2. Envia via POST uma consulta de transferência para a sua URL de consulta, com o mesmo formato de corpo descrito acima: asset.dti, um amount em unidades base como número JSON, um callback e o payload IVMS101.
Apenas uma resposta 2xx conta como entregue. Uma 3xx é recusada, porque redirecionamentos não são seguidos, e qualquer outra resposta é registrada na linha do tempo da transferência do cliente com o seu código de status, por exemplo refused by counterparty (HTTP 403): .... As duas chamadas levam os dois cabeçalhos TRP, e a Didit não segue redirecionamentos HTTP nelas, então sirva /identity e a URL de consulta diretamente. Se /identity estiver inacessível, não informar nenhum LEI ou informar um LEI diferente quando o cliente tiver fornecido um, ou informar um nome que não corresponda, a Didit para antes de enviar a consulta e a transferência do cliente passa para COUNTERPARTY_VASP_NOT_REACHABLE. Se, em seguida, o POST da consulta falhar ou o seu endpoint responder com status 4xx ou 5xx, a transferência também passa para COUNTERPARTY_VASP_NOT_REACHABLE. O callback dessa consulta aponta para o endpoint de resolução da Didit (/trp/callbacks/resolution/{token}/). Responda enviando via POST os mesmos corpos de resolução que a Didit usa: { "approved": { "address": "...", "callback": "..." } } para aprovar (o seu callback é onde a Didit vai enviar a confirmação on-chain), ou { "rejected": "reason" } para recusar. Envie os dois cabeçalhos TRP junto. A Didit responde 204 quando a requisição é processada, 404 quando a transferência não está mais aguardando uma resolução e 400 para uma aprovação sem address ou cujo callback não seja uma URL http(s) pública que a Didit vá chamar. Após a aprovação, a transferência na Didit passa para COMPLETED; assim que o cliente informa o hash on-chain, a Didit envia via POST { "txid": "..." } para o callback de confirmação que você forneceu (ou { "canceled": "reason" } se a transferência for cancelada antes).
Os tokens de callback são segredos destinados a uma única finalidade e impossíveis de adivinhar, gerados por transferência: trate as URLs de retorno completas como confidenciais e observe que uma resolução só é aceita enquanto a transferência ainda estiver aguardando uma.

​
Acesso por e-mail

Se nenhum canal de protocolo alcançar você e o cliente da Didit tiver fornecido o seu e-mail de conformidade, a Didit recorre ao e-mail: o seu contato de conformidade recebe uma mensagem com o nome do VASP remetente e um link seguro de acesso de uso único. Não é preciso conta, chave de API nem integração: o token do link é a autenticação. Ao abrir o link, você vê a troca pendente; a API subjacente (que a página hospedada chama em seu nome) é pública:
amount é o decimal armazenado sem alterações, por isso traz as 18 casas decimais completas.
decision é accept ou decline; ao aceitar, informe o nome do beneficiário conforme consta nos seus registros para que a parte remetente possa fazer a correspondência de nomes, ou envie a sua resposta IVMS 101 completa como ivms_response, cujo nome de beneficiário passa então a prevalecer. Ao recusar, você pode informar um decline_reason (data_mismatch, not_our_customer, wallet_not_hosted, sanctions, risk_appetite, jurisdiction, insufficient_data ou other) e um decline_detail de até 512 caracteres, obrigatório para other. Uma aceitação sem beneficiary_name é registrada como divergência quando o remetente forneceu um nome de beneficiário, a menos que o remetente tenha desativado a correspondência de nomes. A resposta é o {"status": "..."} resultante: COMPLETED quando os nomes correspondem, COUNTERPARTY_MISMATCHED_DATA quando não correspondem, ou COUNTERPARTY_VASP_GENERAL_DECLINE após uma recusa. Você pode responder uma única vez, enquanto a transferência estiver aguardando você: depois da sua resposta, depois do cancelamento da transferência ou depois do prazo de confirmação, os dois endpoints retornam 410, e um token desconhecido retorna 404. A requisição mostra os campos do remetente que ele compartilha e um ivms_request IVMS 101, no idioma da sua jurisdição, e você recebe lembretes 72, 24 e 6 horas antes do prazo enquanto não tiver respondido.

​
Sunrise: transferências liquidadas antes da troca

Quando uma transferência chega à carteira de um cliente da Didit antes de qualquer troca de Travel Rule, porque não havia um rede compartilhada na época, os dados ainda podem ser entregues após a liquidação. Envie ao cliente da Didit (a sua contraparte beneficiária) o payload de Travel Rule pelo seu canal habitual e peça que ele o registre; ele deve chamar POST /v3/travel-rule/inbound/ com a blockchain do depósito, o txid, o endereço da carteira, o valor, a moeda e os seus dados de remetente. Inclua a identidade do seu VASP (nome, LEI e travel address) como originating_vasp nesse payload, para que os registros da transferência do cliente da Didit indiquem quem enviou o depósito. Essa informação fica nessa transferência e nunca cria nem altera a sua entrada no diretório. O LEI deve ser um LEI válido de 20 caracteres e o travel address deve ser válido; caso contrário, o registro é rejeitado.

​
Como entrar no diretório de VASPs da Didit

A Didit mantém um diretório de VASPs que o roteamento de saída dos seus clientes consulta. As entradas vêm destas fontes:
  • O registro provisório da ESMA de prestadores de serviços de criptoativos sob o MiCA, lido toda semana: seu nome, LEI e Estado-membro de origem, se você estiver listado nele.
  • O diretório público da TRISA, lido toda semana: quem você é, seu país e sua listagem na TRISA.
  • O registro global de LEI, que preenche seu LEI, outras denominações legais e o país.
  • A atribuição de análise de blockchain, quando uma carteira de destino é identificada como pertencente à sua exchange ou ao seu serviço de custódia: a Didit adiciona ou associa sua entrada e mantém o nome atribuído como alias.
  • A equipe da Didit, que faz a curadoria das entradas: identificadores de roteamento e listagens em redes que ela verificou, contatos de conformidade, aliases e marcas com suas entidades.
O que um cliente da Didit informa sobre você, como um originating_vasp em um registro sunrise ou um travel address em uma transferência, fica na transferência desse cliente e nunca altera sua entrada. As consultas de transferência que você envia a um cliente da Didit também não criam nem atualizam sua entrada. Sua entrada roteia uma transferência até você quando contém um endpoint TRP verificado, uma listagem em uma rede que o remetente pode usar ou um contato de conformidade para o fallback por e-mail. Um endereço de conformidade em um dos seus próprios domínios que responde a uma requisição pelo link de resposta passa a ser um contato que todos os clientes da Didit podem usar. Enquanto sua entrada não tiver uma rota, um cliente da Didit só chega até você com os campos que envia em cada transferência: seu travel address, seu identificador de rede (counterparty_gtr_vasp_code, counterparty_trust_membership_id, counterparty_verifyvasp_id ou counterparty_sygna_vasp_code) ou seu e-mail de conformidade (counterparty_vasp_email). Para estar acessível hoje, compartilhe seu travel address, identificador de rede ou e-mail de conformidade com os clientes da Didit com quem você trabalha.

​
Checklist para VASPs de contraparte

  • Você já opera TRP: compartilhe seu travel address e seu LEI com o cliente da Didit. As transferências de BTC, ETH e USDC dele chegam ao seu endpoint como consultas TRP padrão. Responda na própria resposta à consulta: uma resposta posterior exige o host TRP público da Didit, que ainda não está ativo.
  • Você está na GTR, na TRUST ou na VerifyVASP: compartilhe seu identificador de rede. As transferências chegam por essa rede quando o cliente da Didit tem a própria associação nela. A Didit lê sua resposta da GTR ou da VerifyVASP pela rede, mas não uma resposta da TRUST, então publique também um endpoint TRP quando uma troca pela TRUST precisar ser concluída. Redes de Travel Rule informa quando isso muda.
  • Você está na Sygna Bridge: compartilhe seu código de VASP da Sygna. Quando o cliente da Didit tem a própria associação na Sygna, sua resposta de permissão conclui ou recusa a transferência assim que a Didit a lê por polling.
  • Você ainda não tem um canal de protocolo: informe ao cliente da Didit um e-mail de conformidade monitorado. Você receberá links de retirada e poderá responder pela página hospedada, sem nenhuma integração.
  • Uma transferência já foi liquidada: entregue os dados por meio de registro sunrise, via o cliente da Didit.
  • Você também quer originar transferências para VASPs da Didit: peça à sua contraparte o travel address dela, disponível nas configurações de Travel Rule da Didit, e siga POST /trp/inquiries assim que o host TRP público da Didit estiver ativo.

​
Próximas etapas

Travel Rule

O produto voltado ao cliente: ciclo de vida, configurações, redes e a API /v3/.

Widget de propriedade de carteira

Como as provas de propriedade do lado do beneficiário são coletadas quando a carteira é autocustodiada.

Registro Sunrise

Registro de dados da Travel Rule para depósitos que já foram liquidados on-chain.

Webhooks

Como os clientes da Didit acompanham cada transição do intercâmbio do lado deles.
Última modificação em 1 de novembro de 2026