Comprar Cripto

Toda compra de criptoactivos en XGate se realiza exclusivamente con el saldo en Reales (BRL) de la propia empresa directamente de la tesorería de XGate. XGate debita el valor en BRL del saldo corporativo y transfiere los tokens adquiridos directamente a la billetera de destino de la empresa indicada en la llamada, sin intermediación de custodia.

Endpoint

Método: POST

URL del Endpoint
https://api.xgateglobal.com/crypto/purchases

Solicitud (Request)

Headers Obligatorios

Header	Valor	Descripción
`Authorization`	`Bearer <su_token>`	El token JWT obtenido al inicio de sesión.

Modalidades de Compra

La compra con el saldo BRL de la empresa puede solicitarse de manera puntual (directamente en este endpoint) o programarse como una instrucción adicional vinculada a la confirmación de un depósito Pix vía POST /deposit:

Con Cotización (Saldo BRL)
A Mercado (Saldo BRL)
Instrucción Adicional en Pix (POST /deposit)

Compra utilizando el precio garantizado por 30 segundos obtenido mediante una cotización previa (quoteId). El activo, la red y el monto se derivan de la cotización.

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

Compra instantánea debitando el saldo BRL disponible al precio vigente en el momento de la ejecución. Los campos asset, network y amount son obligatorios.

{
  "externalId": "orden-7782",
  "asset": "USDT",
  "network": "TRON",
  "amount": "1500.00",
  "addressId": "66f1a2b3c4d5e6f70819****"
}

Puede crear un cobro Pix en POST /deposit y adjuntar el objeto purchase como una instrucción adicional.

Tan pronto como el Pix es pagado y acreditado en el saldo de la empresa, su empresa compra el criptoactivo directamente de la tesorería de XGate con el saldo disponible:

{
  "amount": 1500.00,
  "customerId": "6a1a379e1fe9bfd92d2f****",
  "currency": {
    "_id": "6728f0a2cba3ac9ea300****",
    "name": "BRL",
    "type": "PIX",
    "symbol": "R$"
  },
  "purchase": {
    "asset": "USDT",
    "network": "POLYGON",
    "address": "0xf73345519993edc1006388b5596100d2dd51****"
  },
  "externalId": "orden-7783"
}

Body de la Solicitud Directa (`POST /crypto/purchases`)

Campo	Tipo	Obligatorio	Descripción
`externalId`	`string`	Sí	Identificador de la compra en su sistema. 1 a 128 caracteres ASCII imprimibles, sin `/` y sin iniciar con `$`. Único por empresa.
`address`	`string`	Uno de ambos	Dirección de la billetera externa de destino de la empresa, compatible con la red (sin memo/tag).
`addressId`	`string`	Uno de ambos	ID de dirección preregistrada en el panel (`buy.addresses[].addressId` de Opciones).
`quoteId`	`string`	Modo con cotiz.	ID de la cotización obtenida previamente. No puede enviarse junto con `asset`, `network` o `amount`.
`asset`, `network`, `amount`	`string`	Modo a mercado	Activo (`USDT`/`USDC`), red y total en BRL debitado del saldo corporativo (cadena con 2 decimales).

Idempotencia mediante externalId

Mismo externalId + mismo cuerpo → 200 OK devolviendo el registro de la compra ya procesada.
Mismo externalId + cuerpo diferente → 409 EXTERNAL_ID_CONFLICT.

Respuestas (Responses)

Éxito (201 Created)

Se devuelve una vez que el monto ha sido debitado del saldo corporativo y comienza la ejecución (estado EXECUTING):

{
  "id": "6710c2f4a1b2c3d4e5f6****",
  "externalId": "orden-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: Estado inicial únicamente cuando se programa como instrucción adicional asociada a un depósito Pix (channel = "DEPOSIT"), mientras el Pix aguarda pago.
Sin aprobación automática (buy.autoApproval = false): la compra entra a la cola de aprobación de XGate (PENDING_APPROVAL). El precio y el monto se mantienen fijos.
Con aprobación automática: la orden avanza directamente al despacho on-chain hasta DELIVERED.
En DELIVERED, el hash de la transacción pública en la blockchain se entrega en delivery.txHash.
En REJECTED, en caso de no concretarse la compra, el valor en BRL se reembolsa íntegramente al saldo corporativo (rejection.refunded = true).

Realice seguimiento mediante Consultar Compra o a través de los Webhooks de Compra (purchase.*).

Objeto de la compra

Campo	Tipo	Descripción
`id`	`string`	ID de la compra en XGate.
`externalId`	`string`	ID de la compra en su sistema.
`status`	`string`	`PENDING_PAYMENT` · `EXECUTING` · `PENDING_APPROVAL` · `DELIVERED` · `REJECTED` · `EXPIRED`.
`channel`	`string`	Origen de la instrucción: `API` (POST directo), `DASHBOARD` (panel) o `DEPOSIT` (compra tras confirmación de Pix).
`asset`, `network`, `address`	`string`	Destino de los activos cripto en la red.
`amount`	`string` \| `null`	Total en BRL debitado del saldo corporativo de la empresa.
`rate`	`string` \| `null`	Precio de 1 unidad del activo en BRL (8 decimales), fijado en la ejecución, con el margen incluido.
`cryptoAmount`	`string` \| `null`	Cantidad bruta de cripto adquirida (`amount ÷ rate`, 6 decimales).
`networkFee`	`string` \| `null`	Costo del gas de red deducido del envío final.
`deliveredAmount`	`string` \| `null`	Total efectivamente entregado en la billetera externa: `cryptoAmount − networkFee`.
`quoteId`	`string` \| `null`	Cotización garantizada utilizada (devuelve `null` en compras a mercado).
`depositId`	`string` \| `null`	ID del depósito de origen, cuando se originó tras confirmación de Pix (`channel = "DEPOSIT"`).
`approval`	`object`	`required` (`boolean`), `decision` (`APPROVED` \| `REJECTED` \| `AUTO` \| `null`), `decidedAt`.
`delivery`	`object`	`status` (`WAITING_APPROVAL` · `QUEUED` · `SUBMITTED` · `CONFIRMING` · `CONFIRMED` · `null`), `txHash`, `confirmedAt`.
`rejection`	`object` \| `null`	Detalles de rechazo: `reason`, `message` y `refunded`.
`executedAt`, `createdAt`	`string`	Registros de fecha y hora en formato ISO 8601 (UTC).

Erros Comunes

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

Integración

Node.js

const axios = require("axios");

(async () => {
    const email = "su_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. Obtener cotización garantizada por 30s
        const quote = await axios.post(`${url_api}/crypto/quotes`, {
            asset: "USDT",
            network: "TRON",
            amount: "1500.00"
        }, { headers });

        // 2. Ejecutar compra de cripto directamente de la tesorería de XGate con el saldo BRL de la empresa
        const { data } = await axios.post(`${url_api}/crypto/purchases`, {
            externalId: "orden-7781",
            quoteId: quote.data.quoteId,
            address: "TQn9Y2khEsLJW1ChVWFMSMeRDow5Kc****"
        }, { headers });

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

Endpoint​

Solicitud (Request)​

Headers Obligatorios​

Modalidades de Compra​

Body de la Solicitud Directa (POST /crypto/purchases)​

Respuestas (Responses)​

Éxito (201 Created)​

Ciclo de vida​

Objeto de la compra​

Erros Comunes​

Integración​