Buscar Carteira Crypto

Este endpoint retorna as carteiras de criptomoedas associadas a um cliente específico.

Utilize esta rota para obter as chaves públicas de depósito (publicKey) e verificar quais redes (blockchainNetworks) (ex: Polygon, Solana) e ativos (assets) (ex: USDT, USDC) estão disponíveis para cada endereço.

Endpoint

Método: GET

URL do Endpoint
https://api.xgateglobal.com/crypto/customer/CLIENT_ID/wallet

Importante

O campo CLIENT_ID se refere ao ID do cliente, se ainda não criou, você pode cria-lo a partir da página de criar clientes.

Comportamento Assíncrono (Recomendação de Retry)

Ao solicitar as carteiras de um cliente pela primeira vez, a blockchain iniciará a geração dos endereços em segundo plano.

Durante esses segundos de criação, a API responderá com a mensagem: "Wait a few seconds, we are provisioning your wallet addresses".

Recomendação Técnica: Certifique-se de que sua aplicação utiliza uma lógica de async/await com retry (polling). Configure o seu código para repetir a requisição de 3 a 5 vezes, com um intervalo de 1 a 5 segundos entre as tentativas, até que o array com a publicKey definitiva seja retornado. Você encontra um exemplo prático dessa implementação no final desta página.

Testar Integração

Utilize o formulário abaixo para listar as carteiras de um cliente.

👛

Testar: Listar Carteira Crypto

Requisição

É necessário enviar o Header de autenticação e passar o ID do Cliente na URL.

Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	`Bearer <seu_token>`	O token JWT obtido no login.

Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
`CLIENT_ID`	`string`	Sim	O `_id` do cliente que você deseja consultar.

Respostas (Responses)

Sucesso (200 OK)

Retorna um array com as carteiras geradas, as criptomoedas aceitas e a rede que deve ser utilizada para receber depósitos.

[
  {
    "publicKey": "0xda4e37a068a2fed2c******************",
    "blockchainNetworks": [
      "Polygon",
      "Ethereum"
    ],
    "assets": [
      "USDC",
      "USDT"
    ]
  },
  {
    "publicKey": "EGJCs2ZDNFksfZH******************",
    "blockchainNetworks": [
      "Solana"
    ],
    "assets": [
      "USDT",
      "USDC"
    ]
  },
  {
    "publicKey": "TNWraJD8jp3TK******************",
    "blockchainNetworks": [
      "Tron"
    ],
    "assets": [
      "USDT"
    ]
  }
]

Importante

Depósitos de origem crypto não aparecem na aba depósitos da Dashboard até que sejam concluídas (Pagas).

Risco de Perda de Fundos e Fraudes

USDT ou USDC: A XGate processa exclusivamente depósitos em Tether (USDT) e USD Coin (USDC). O envio de outras criptomoedas (como Bitcoin, Ethereum nativo, TRX, etc.) resultará na perda irreversível do valor.
Rede Correta: O depósito deve ser feito obrigatoriamente através de uma das redes listadas na nossa API (ex: ERC-20, Solana ou Polygon). O envio por redes não suportadas causará a perda total dos fundos.
Alerta de Fraude ("Flash Tokens"): Cuidado com golpistas que enviam tokens falsos imitando os originais (conhecidos como "Flash USDT" ou "Flash USDC"). Essas moedas falsas aparecem na carteira, mas não têm valor real e não podem ser transacionadas. Sempre valide pelo contrato inteligente (smart contract) se o token depositado é o oficial da Tether ou da Circle antes de liberar o saldo para o seu cliente final.

Erros Comuns

Status	Mensagem	Motivo Provável
401	`Unauthorized`	• Token inválido ou expirado. • Header inválido ou não informado. • IP não permitido.
404	`Not Found`	Cliente não encontrado.
500	`Internal Server Error`	Erro interno de servidor. Entrar em contato com suporte.

Como usar

As informações entregues nesta rota são o Endereço (publicKey), as Redes Suportadas (blockchainNetworks) e os Ativos Aceitos (assets). Elas serão utilizadas sempre que você ou seu cliente final desejar realizar um depósito em criptomoedas.

Cada objeto do array representa um formato de endereço específico que pode suportar uma ou mais redes e um ou mais ativos em paralelo:

Endereço (`publicKey`)	Redes (`blockchainNetworks`)	Ativos Disponíveis (`assets`)
Formato EVM (`0x...`)	`Polygon`, `Ethereum`	`USDT`, `USDC`
Formato Solana	`Solana`	`USDT`, `USDC`
Formato Tron (`T...`)	`Tron`	`USDT`

O fluxo para o usuário final deve ser estruturado da seguinte forma:

Seleção do Ativo: O usuário escolhe se deseja depositar USDT ou USDC.
Seleção da Rede: O sistema exibe as redes aceitas (blockchainNetworks) com base no ativo escolhido.
Exibição do Endereço: O sistema exibe a chave pública (publicKey) correspondente à combinação selecionada.
Envio dos Fundos: O usuário vai até a corretora ou carteira externa dele e envia o ativo escolhido, utilizando obrigatoriamente uma das redes listadas, para o endereço fornecido.

⚠️ Regras Críticas de Depósito

Para garantir a segurança dos fundos, o desenvolvedor deve exibir avisos claros no front-end para o usuário final:

Risco de Perda de Fundos e Fraudes

USDT ou USDC: A XGate processa exclusivamente depósitos em Tether (USDT) e USD Coin (USDC). O envio de outras criptomoedas (como Bitcoin, Ethereum nativo, TRX, etc.) resultará na perda irreversível do valor.
Rede Correta: O depósito deve ser feito obrigatoriamente através de uma das redes listadas na nossa API (ex: ERC-20, Solana ou Polygon). O envio por redes não suportadas causará a perda total dos fundos.
Alerta de Fraude ("Flash Tokens"): Cuidado com golpistas que enviam tokens falsos imitando os originais (conhecidos como "Flash USDT" ou "Flash USDC"). Essas moedas falsas aparecem na carteira, mas não têm valor real e não podem ser transacionadas. Sempre valide pelo contrato inteligente (smart contract) se o token depositado é o oficial da Tether ou da Circle antes de liberar o saldo para o seu cliente final.

Exemplo de Aplicação (UX)

Ao integrar essa rota, recomendamos que sua interface mostre as informações de forma clara e atrelada ao endereço específico gerado. Por exemplo:

💰 Ativos Aceitos: USDT ou USDC

🌐 Redes Suportadas (para este endereço): Ethereum (ERC-20), Polygon

📍 Endereço de Depósito: 0xda4e37a068a2fed2c****************** 📋 (Botão Copiar)

⚠️ Atenção: Envie apenas os ativos listados acima usando as redes indicadas. O envio de outras moedas ou o uso de redes incorretas resultará na perda irreversível dos fundos.

Integração

Node.js

O exemplo de integração utiliza a biblioteca Axios em Node.js.

Instalando Axios:

npm install axios

Exemplo Javascript:

const axios = require("axios");

// Função auxiliar para aguardar 2 segundos (2000ms)
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

(async () => {
  const email = "your_email@domain.com";
  const password = "**********";
  const customerId = "************";
  const url_api = "https://api.xgateglobal.com";

  try {
    // 1. Autenticação na API
    const login = await axios.post(`${url_api}/auth/token`, { email, password });
    const token = login.data.token;

    // 2. Função recursiva com retry para buscar ou gerar a carteira
    async function getWalletWithRetry(count = 0) {
      const { data } = await axios.get(`${url_api}/crypto/customer/${customerId}/wallet`, {
        headers: {
          "Authorization": `Bearer ${token}`
        }
      });

      // Se a API retornar a mensagem de provisionamento, aguarda 2 segundos e tenta de novo (máximo 3 vezes)
      if (
        data?.message === "Wait a few seconds, we are provisioning your wallet addresses" &&
        count < 3
      ) {
        console.log(`Carteira em criação. Tentativa ${count + 1} de 3... Aguardando 2 segundos.`);
        await sleep(2000);
        return getWalletWithRetry(count + 1);
      }

      return data;
    }

    console.log("Iniciando busca da carteira...");
    const wallet = await getWalletWithRetry();
    console.log("Resultado final da carteira:", wallet);

  } catch (error) {
    console.log("Erro na execução:", error.response?.data?.message || error.message);
  }
})();

Endpoint​

Testar Integração​

Testar: Listar Carteira Crypto

Requisição​

Headers Obrigatórios​

Parâmetros de URL​

Respostas (Responses)​

Sucesso (200 OK)​

Erros Comuns​

Como usar​

⚠️ Regras Críticas de Depósito​

Exemplo de Aplicação (UX)​

Integração​