Convert API

La Convert API le permite intercambiar entre las divisas que mantiene en el saldo de su comercio al precio de mercado actual — el mismo motor que impulsa la pestaña Swap del panel del comercio, ahora disponible desde su backend.

Obtener cotización de conversión

{
  "state": 0,
  "result": {
    "success": true,
    "from_currency": "BTC",
    "to_currency": "USDT",
    "amount_type": "from",
    "from_amount": "0.01000000",
    "to_amount": "947.86690000",
    "effective_rate": "94786.69000000",
    "from_amount_usd": "947.87",
    "to_amount_usd": "947.87"
  }
}

curl -X POST https://api.2328.io/api/v1/convert/price \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Ejecutar conversión

{
  "state": 0,
  "result": {
    "id": 12345,
    "type": "manual",
    "status": "completed",
    "from_currency": "BTC",
    "to_currency": "USDT",
    "from_amount": "0.01000000",
    "requested_from_amount": "0.01000000",
    "refund_amount": null,
    "to_amount": "947.86690000",
    "exchange_rate": "94786.69000000",
    "fee_amount": "0.00000000",
    "from_amount_usd": "947.87",
    "to_amount_usd": "947.87",
    "processed_at": "2026-01-20T15:30:24Z",
    "created_at": "2026-01-20T15:30:22Z"
  }
}

curl -X POST https://api.2328.io/api/v1/convert \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Errores

Ante un fallo, la respuesta tiene state: 1 y un error_code — compartido por /v1/convert/price y /v1/convert:

🔴 422 / 400 · application/json

{
  "state": 1,
  "error_code": "amount_too_small",
  "errors": {
    "amount": "Amount is too small for this conversion. Please increase the amount and try again."
  }
}

Conversión automática de pagos entrantes

Auto-convert es una configuración de proyecto para pagos entrantes invoice y créditos de billetera estática. Se configura en el panel de merchant, no agregando campos a /v1/payment. Cada regla selecciona una o más monedas de origen y una moneda objetivo.

Cuando la conversión se complete, la información del pago y merchant webhooks pueden incluir:

{
  "payment_amount": "0.14800000",
  "merchant_amount": "0.146520000000000000",
  "payer_currency": "XMR",
  "convert": {
    "to_currency": "USDT",
    "commission": "0.09000000",
    "rate": "323.21000000",
    "amount": "47.262015740000000000"
  }
}

Los dominios de cantidad están intencionalmente separados:

• payment_amount — lo que se detectó en la cadena en la moneda de pago de origen;
• merchant_amount — la cantidad neta de origen atribuible a merchant antes de la conversión;
• convert.amount — la cantidad acreditada en convert.to_currency;
• convert.rate y convert.commission — el resultado de la conversión ejecutada, no un precio que deba recalcular localmente.

Fallo de Auto-convert y fallback

La conversión ocurre después de recibir el pago en blockchain. La disponibilidad en el mercado, tamaños mínimos de orden, límites de precisión, tiempos de espera del intercambio y liquidez ejecutable insuficiente pueden retrasar o impedir la conversión.

• Los depósitos por debajo del mínimo global/proyecto omiten la canalización de conversión y acreditan la moneda de origen.
• Los fallos transitorios pueden reintentarse de manera asincrónica.
• Depósitos grandes o no comerciables pueden volver al crédito en moneda de origen después de que se agote la política de retry.
• Por lo tanto, un pago puede ser válido incluso cuando la conversión deseada a la moneda objetivo no haya ocurrido.

Su integración debe persistir primero el pago verificado, luego conciliar la moneda realmente acreditada a partir de la información de pago, el bloque opcional convert y los saldos merchant. No bloquee el reconocimiento del pago webhook mientras espera a sus propios sistemas de análisis o notificación.

Pruebas de aceptación Auto-convert

Pruebe al menos: conversión directa exitosa, conversión puente/multi-hop, dust por debajo del mínimo, retry transitorio, fallback a la moneda de origen, pago insuficiente, pago excesivo, webhook duplicado, convert faltante y reconciliation después de un timeout ambiguo.

Casos límite de conversión manual

• /v1/convert/price es una vista previa indicativa; el movimiento del mercado puede cambiar el resultado de la ejecución.
• amount_type: from corrige la solicitud del lado de origen, mientras que amount_type: to solicita un monto del lado de destino. No altere el significado al presentar la interfaz de confirmación.
• Un par sin un mercado directo puede ser enrutado a través de una moneda intermedia. Si solo una parte se completa, partially_completed informa el crédito intermedio.
• Si una llamada de ejecución excede el tiempo de espera, concilie antes de reintentar. Una orden de mercado puede ejecutarse incluso cuando se pierde su respuesta HTTP.
• Trate failed como un estado para conciliar, no como permiso para aplicar una entrada de balance compensatoria local; la plataforma posee la contabilidad de débitos/reembolsos.