Pular para o conteúdo principal

Comprar Cripto

Toda compra de criptoativos na XGate é realizada exclusivamente com o saldo em Reais (BRL) da própria empresa. A XGate debita o valor em BRL do saldo corporativo e transfere os tokens adquiridos diretamente para a carteira de destino da empresa informada na chamada, sem intermediação de custódia.

Endpoint​

  • Método: POST
URL do Endpoint
https://api.xgateglobal.com/crypto/purchases

Requisição​

Headers Obrigatórios​

HeaderValorDescrição
AuthorizationBearer <seu_token>O token JWT obtido no login.

Como Comprar Cripto​

A compra com o saldo BRL da empresa pode ser solicitada de forma avulsa (diretamente nesta rota) ou programada como uma instrução adicional vinculada à confirmação de um depósito Pix via POST /deposit:

Compra utilizando o preço garantido por 30 segundos obtido através de uma cotação prévia (quoteId). O ativo, a rede e o valor são derivados da cotação.

{
  "externalId": "pedido-7781",
  "quoteId": "l3m8Qm1n0pV2cXk5dY9sTg4hWz7aB6eR1uJ0****",
  "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5Kc****"
}

Body da Chamada Direta (POST /crypto/purchases)​

CampoTipoObrigatórioDescrição
externalIdstringSimIdentificador da compra no seu sistema. 1 a 128 caracteres ASCII imprimíveis, sem / e sem começar com $. Único por empresa.
addressstringUm dos doisEndereço da carteira externa de destino da empresa, compatível com a rede (sem memo/tag).
addressIdstringUm dos doisID de endereço pré-cadastrado no painel (buy.addresses[].addressId de Opções).
quoteIdstringForma com cotaçãoID da cotação obtida previamente. Não pode ser enviado em conjunto com asset, network ou amount.
asset, network, amountstringForma a mercadoAtivo (USDT/USDC), rede e valor em BRL a ser debitado do saldo (string com 2 casas decimais).
Idempotência pelo externalId
  • Mesmo externalId + mesmo corpo → 200 OK retornando o registro da compra já processada.
  • Mesmo externalId + corpo diferente → 409 EXTERNAL_ID_CONFLICT.

Respostas (Responses)​

Sucesso (201 Created)​

Retornado após o valor ser debitado do saldo corporativo e a execução ser iniciada (status EXECUTING):

{
  "id": "6710c2f4a1b2c3d4e5f6****",
  "externalId": "pedido-7781",
  "status": "EXECUTING",
  "channel": "API",
  "asset": "USDT",
  "network": "TRON",
  "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5Kc****",
  "amount": "1500.00",
  "rate": "5.45400000",
  "cryptoAmount": "275.027502",
  "networkFee": "0.012000",
  "deliveredAmount": "275.015502",
  "quoteId": "l3m8Qm1n0pV2cXk5dY9sTg4hWz7aB6eR1uJ0****",
  "depositId": null,
  "approval": { "required": true, "decision": null, "decidedAt": null },
  "delivery": {
    "status": "WAITING_APPROVAL",
    "txHash": null,
    "confirmedAt": null
  },
  "rejection": null,
  "executedAt": "2026-10-13T14:03:40.512Z",
  "createdAt": "2026-10-13T14:03:40.204Z",
  "updatedAt": "2026-10-13T14:03:40.512Z"
}

Ciclo de vida​

(PENDING_PAYMENT)* ──► EXECUTING ──► PENDING_APPROVAL ──► DELIVERED
                           │                │
                           └────────────────┴──────────► REJECTED
  • *PENDING_PAYMENT: Status inicial apenas quando a ordem foi programada como instrução adicional vinculada a um depósito Pix (channel = "DEPOSIT"), enquanto o Pix ainda aguarda pagamento.
  • Sem aprovação automática (buy.autoApproval = false): a compra aguarda liberação na fila de compliance da XGate (PENDING_APPROVAL). O valor e a cotação permanecem congelados.
  • Com aprovação automática: a ordem prossegue imediatamente para despacho on-chain até DELIVERED.
  • Em DELIVERED, o hash da transação pública na blockchain é disponibilizado em delivery.txHash.
  • Em REJECTED, caso a compra não possa ser finalizada, o valor em BRL é estornado integralmente para o saldo da empresa (rejection.refunded = true).

Acompanhe as atualizações de status em Consultar Compra ou por meio dos Webhooks de Compra (purchase.*).

Objeto da compra​

CampoTipoDescrição
idstringID da compra na XGate.
externalIdstringID da compra no seu sistema.
statusstringPENDING_PAYMENT · EXECUTING · PENDING_APPROVAL · DELIVERED · REJECTED · EXPIRED.
channelstringOrigem da instrução: API (POST direto), DASHBOARD (painel) ou DEPOSIT (compra disparada após confirmação de Pix).
asset, network, addressstringDestino dos ativos cripto na rede.
amountstring | nullTotal em BRL debitado do saldo corporativo da empresa.
ratestring | nullPreço de 1 unidade do ativo em BRL (8 casas decimais), fixado na execução, com a margem já embutida.
cryptoAmountstring | nullQuantidade bruta de cripto adquirida (amount ÷ rate, 6 casas decimais).
networkFeestring | nullCusto do gás de rede deduzido da quantidade final enviada.
deliveredAmountstring | nullTotal efetivamente entregue na carteira externa: cryptoAmount − networkFee.
quoteIdstring | nullCotação garantida utilizada (retorna null na compra a mercado).
depositIdstring | nullID do depósito de origem, quando a compra foi disparada após confirmação do Pix (channel = "DEPOSIT").
approvalobjectrequired (boolean), decision (APPROVED | REJECTED | AUTO | null), decidedAt.
deliveryobjectstatus (WAITING_APPROVAL · QUEUED · SUBMITTED · CONFIRMING · CONFIRMED · null), txHash, confirmedAt.
rejectionobject | nullDetalhes em caso de recusa: reason, message e refunded.
executedAt, createdAtstringRegistros de data e hora em padrão ISO 8601 (UTC).

Erros Comuns​

StatusReason
400VALIDATION_FAILED, AMOUNT_MUST_BE_STRING, CONFLICTING_FIELDS
401UNAUTHORIZED
403PERMISSION_DENIED, COMPANY_BLOCKED, ALLOWED_IPS_REQUIRED, CLIENT_IP_NOT_ALLOWED, BUY_DISABLED
404SAVED_ADDRESS_NOT_FOUND, QUOTE_NOT_FOUND
409EXTERNAL_ID_CONFLICT, QUOTE_EXPIRED, QUOTE_ALREADY_USED
422ASSET_NOT_SUPPORTED, NETWORK_NOT_SUPPORTED, AMOUNT_BELOW_MIN, AMOUNT_ABOVE_MAX, ADDRESS_INVALID_FOR_NETWORK, INSUFFICIENT_BALANCE, PRICE_UNSTABLE
429RATE_LIMITED, DAILY_CAP_EXCEEDED, OUTFLOW_HOURLY_CAP_EXCEEDED
503PRICE_STALE, NETWORK_FEE_UNAVAILABLE, CRYPTO_TEMPORARILY_UNAVAILABLE, SERVICE_OVERLOADED

Integração​

const axios = require("axios");

(async () => {
    const email = "seu_email@dominio.com";
    const password = "**************";

    try {
        const url_api = "https://api.xgateglobal.com";
        const login = await axios.post(`${url_api}/auth/token`, { email, password });
        const headers = { "Authorization": `Bearer ${login.data.token}` };

        // 1. Obter cotação com preço garantido por 30s
        const quote = await axios.post(`${url_api}/crypto/quotes`, {
            asset: "USDT",
            network: "TRON",
            amount: "1500.00"
        }, { headers });

        // 2. Executar compra debitando do saldo BRL da empresa
        const { data } = await axios.post(`${url_api}/crypto/purchases`, {
            externalId: "pedido-7781",
            quoteId: quote.data.quoteId,
            address: "TQn9Y2khEsLJW1ChVWFMSMeRDow5Kc****"
        }, { headers });

        console.log("ID da Compra:", data.id, "Status:", data.status);
    } catch (error) {
        console.log(error.response?.data?.reason, error.response?.data?.message);
    }
})();