Bridge cross-chain

Todos os endpoints exigem Authorization: Bearer <token> e o header x-client-id: <seu Client_ID> — o tenant id é o mesmo valor do Client_ID do OAuth (detalhes); sem ele a chamada falha com 400 MISSING_CLIENT_ID. Produto CRYPTO_BRIDGE — precisa estar habilitado para a conta, senão 403 PRODUCT_NOT_ENABLED.

Visão geral

A API de Bridge permite mover um ativo de uma carteira custodial do tenant (rede de origem EVM) para uma carteira de destino em outra rede EVM.

• Redes de origem aceitas: ETHEREUM, POLYGON, BSC.
• Redes de destino: ver a tabela abaixo (informe o destinationChainId).
• Assíncrono: a execute retorna assim que a transferência é iniciada; a chegada no destino é confirmada depois — consulte o status.

Fluxo:

1. Cotar (POST /v1/crypto/bridge/quote) — retorna o valor a debitar, a taxa, o valor estimado no destino e a validade da cotação (quoteId).
2. Executar (POST /v1/crypto/bridge/execute) — inicia a transferência. Retorna operationId.
3. Acompanhar (GET /v1/crypto/bridge/status/{operationId}) até FILLED (ou REFUNDED/FAILED).

Redes de destino suportadas

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

A rota (origem → destino, para o ativo escolhido) é validada no momento da cotação. Ativos suportados: USDC, USDT.

---

POST /v1/crypto/bridge/quote

Cota a transferência sem mover fundos. A carteira de origem (fromAddress) deve pertencer ao 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	Descrição
fromAddress	Carteira custodial de origem (do tenant).
amount	Valor a transferir, em unidades humanas do ativo.
asset	Ativo a mover (USDC ou USDT).
originNetwork	ETHEREUM | POLYGON | BSC.
destinationChainId	chainId de destino (ver tabela).
destinationWallet	Carteira de destino — deve estar na whitelist do 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

Executa uma cotação válida (a cotação tem validade curta). Debita o tenant e inicia a transferência para o destino.

Request Body:

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

Response 200:

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

Estados possíveis: PENDING → SWEPT → APPROVED → DEPOSITED → FILLED. Terminais de exceção: EXPIRED, REFUNDED, FAILED.

---

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

Retorna o estado atual da operação e, quando disponível, o hash de recebimento no destino.

Response 200:

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

---

GET /v1/crypto/bridge/operations

Lista as operações de bridge do tenant.

Query params: status (opcional), limit, offset.

Response 200: array de operações no mesmo shape do status.

---

Notas

• Devolução: se a transferência não for concluída na rede de destino, os fundos são devolvidos automaticamente à carteira de origem.
• Idempotência: reenviar execute com o mesmo quoteId não duplica a transferência.
• Limites: cada rota tem valor mínimo e máximo — valores fora da faixa são rejeitados na cotação.