Bridge cross-chain

Todos los endpoints requieren Authorization: Bearer <token> y están acotados al tenant (clientId) resuelto desde OAuth. Producto CRYPTO_BRIDGE — debe estar habilitado para la cuenta.

Visión general

La API de Bridge mueve un activo desde una billetera custodial del tenant (red de origen EVM) hacia una billetera de destino en otra red EVM.

• Redes de origen aceptadas: ETHEREUM, POLYGON, BSC.
• Redes de destino: ver la tabla abajo (envíe el destinationChainId).
• Asíncrono: execute retorna en cuanto se inicia la transferencia; la llegada al destino se confirma después — consulte el estado.

Flujo:

1. Cotizar (POST /v1/crypto/bridge/quote) — retorna el monto a debitar, la tarifa, el monto estimado en destino y la validez de la cotización (quoteId).
2. Ejecutar (POST /v1/crypto/bridge/execute) — inicia la transferencia. Retorna operationId.
3. Seguir (GET /v1/crypto/bridge/status/{operationId}) hasta FILLED (o REFUNDED/FAILED).

Redes de destino soportadas

Red	destinationChainId
Ethereum	1
Optimism	10
BNB Smart Chain	56
Polygon	137
Base	8453
Arbitrum One	42161

La ruta (origen → destino, para el activo elegido) se valida al momento de cotizar. Activos soportados: USDC, USDT.

---

POST /v1/crypto/bridge/quote

Cotiza la transferencia sin mover fondos. La billetera de origen (fromAddress) debe pertenecer al tenant.

Headers:

Header	Value
Authorization	Bearer <token>
Content-Type	application/json

Request Body:

{
  "fromAddress": "0x89f423567c2648BB828c3997f60c47b54f57Fa6e",
  "amount": "100.0",
  "asset": "USDT",
  "originNetwork": "POLYGON",
  "destinationChainId": 8453,
  "destinationWallet": "0xabc0000000000000000000000000000000000123",
  "userId": "user-123"
}

Campo	Descripción
fromAddress	Billetera custodial de origen (del tenant).
amount	Monto a transferir, en unidades humanas del activo.
asset	Activo a mover (USDC o USDT).
originNetwork	ETHEREUM | POLYGON | BSC.
destinationChainId	chainId de destino (ver tabla).
destinationWallet	Billetera de destino — debe estar en la whitelist del tenant.

Response 200:

{
  "quoteId": "b1f2c3d4-...-q",
  "amountDebited": "100.0",
  "fee": "0.512206",
  "estimatedOutput": "99.487794",
  "estimatedFillTimeSec": 2,
  "expiresAt": "2026-07-01T12:34:56.000Z"
}

---

POST /v1/crypto/bridge/execute

Ejecuta una cotización válida (la cotización tiene validez corta). Debita al tenant e inicia la transferencia hacia el destino.

Request Body:

{
  "quoteId": "b1f2c3d4-...-q"
}

Response 200:

{
  "operationId": "a1b2c3d4-...-op",
  "status": "DEPOSITED",
  "depositId": "998877"
}

Estados posibles: PENDING → SWEPT → APPROVED → DEPOSITED → FILLED. Terminales de excepción: EXPIRED, REFUNDED, FAILED.

---

GET /v1/crypto/bridge/status/{operationId}

Retorna el estado actual de la operación y, cuando esté disponible, el hash de recepción en destino.

{
  "operationId": "a1b2c3d4-...-op",
  "status": "FILLED",
  "depositId": "998877",
  "depositTxHash": "0x...",
  "fillTxHash": "0x...",
  "destinationChainId": 8453,
  "outputAmount": "99.487794"
}

---

GET /v1/crypto/bridge/operations

Lista las operaciones de bridge del tenant. Query params: status (opcional), limit, offset.

---

Notas

• Devolución: si la transferencia no se completa en la red de destino, los fondos se devuelven automáticamente a la billetera de origen.
• Idempotencia: reenviar execute con el mismo quoteId no duplica la transferencia.
• Límites: cada ruta tiene un monto mínimo y máximo — valores fuera del rango se rechazan al cotizar.