Saltar al contenido principal

Bridge - Cuentas Virtuales

Endpoints para crear y consultar cuentas bancarias virtuales (USD) y cuentas IBAN (EUR) en Bridge, con conversión automática a stablecoins en Base.

🏦 Cuentas bancarias para on-ramp (Bridge)

Bridge permite crear cuentas bancarias virtuales para recibir transferencias fiat. Al acreditar los fondos, se convierten automáticamente a stablecoins (USDC/EURC) y se depositan en la wallet del usuario en la red Base.

1) Crear Cuenta Virtual (USD)​

POST/bridge/virtual-accounts

Crea una cuenta virtual (USD) para recibir transferencias bancarias y convertir a USDC en Base

📋 Parámetros

sourceCurrencystringrequerido

Moneda origen (ej: usd)

📤 Respuesta

{
"success": true,
"data": {
  "id": "va_123456",
  "account_number": "1234567890",
  "routing_number": "123456789",
  "source": {
    "currency": "usd"
  },
  "destination": {
    "currency": "usdc",
    "payment_rail": "base",
    "address": "0x26818c85192ddf841e98d6d7f5ac64e4f50a2f44"
  },
  "status": "active"
},
"message": "Cuenta virtual USD creada exitosamente"
}

Headers:

Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

Body:

{
  "sourceCurrency": "usd"
}

Customer no activo (404)

{
  "message": "El usuario no tiene un customer activo en Bridge",
  "error": "Not Found",
  "statusCode": 404
}

2) Crear Cuenta IBAN (EUR)​

POST/bridge/iban-account

Crea una cuenta IBAN (EUR) para recibir transferencias SEPA y convertir a EURC en Base

📤 Respuesta

{
"success": true,
"data": {
  "id": "iban_123456",
  "iban": "DE89370400440532013000",
  "bic": "COBADEFFXXX",
  "source": {
    "currency": "eur"
  },
  "destination": {
    "currency": "eurc",
    "payment_rail": "base",
    "address": "0x26818c85192ddf841e98d6d7f5ac64e4f50a2f44"
  },
  "status": "active"
},
"message": "Cuenta IBAN (EUR) creada exitosamente"
}

Headers:

Authorization: Bearer <JWT_TOKEN>

3) Obtener Cuentas Virtuales​

GET/bridge/virtual-accounts

Obtiene todas las cuentas virtuales del usuario

📤 Respuesta

{
"success": true,
"data": {
  "virtual_accounts": [
    {
      "id": "va_123456",
      "account_number": "1234567890",
      "routing_number": "123456789",
      "source": {
        "currency": "usd"
      },
      "destination": {
        "currency": "usdc",
        "payment_rail": "base"
      },
      "status": "active"
    }
  ]
},
"message": "Cuentas virtuales obtenidas exitosamente"
}

Headers:

Authorization: Bearer <JWT_TOKEN>

💳 Tipos de Cuentas​

Cuenta Virtual USD

  • Moneda: USD
  • Account Number: 10 dígitos
  • Routing Number: 9 dígitos
  • Destino: USDC en Base
  • Uso: Recibir transferencias bancarias USD

Cuenta IBAN EUR

  • Moneda: EUR
  • IBAN: Formato estándar europeo
  • BIC/SWIFT: Código bancario
  • Destino: EURC en Base
  • Uso: Recibir transferencias SEPA

🔄 Flujo de Conversión​

USD → USDC

  1. Cliente envía USD a la cuenta virtual
  2. Bridge detecta la transferencia
  3. Conversión automática a USDC
  4. Depósito de USDC en wallet del usuario (Base)

EUR → EURC

  1. Cliente envía EUR vía SEPA al IBAN
  2. Bridge detecta la transferencia
  3. Conversión automática a EURC
  4. Depósito de EURC en wallet del usuario (Base)

🏦 Detalles Bancarios​

Cuenta Virtual USD​

{
  "account_number": "1234567890",
  "routing_number": "123456789",
  "bank_name": "Bridge Financial",
  "account_type": "Checking"
}

Cuenta IBAN EUR​

{
  "iban": "DE89370400440532013000",
  "bic": "COBADEFFXXX",
  "bank_name": "Bridge Europe",
  "account_holder": "Bridge Financial Services"
}

📍 Payment Rails​

Base Network

  • USDC y EURC en Base
  • Red: Ethereum Layer 2
  • Confirmaciones estimadas: ~2–5 minutos

Otras redes (futuro)

  • Ethereum Mainnet
  • Polygon
  • Arbitrum

📊 Estados de Cuenta​

Estados principales

  • active - Cuenta activa y funcional
  • pending - En proceso de activación
  • suspended - Suspendida temporalmente
  • closed - Cerrada permanentemente

Validaciones / requisitos

  • Customer verificado requerido
  • Límites diarios y mensuales
  • Compliance KYC/AML

💰 Límites y Comisiones​

Límites estándar

  • Diario: $10,000 USD / €10,000 EUR
  • Mensual: $50,000 USD / €50,000 EUR
  • Por transferencia: $500 - $25,000

Comisiones

  • Transferencias entrantes: gratis
  • Conversión: 0.1% – 0.5%
  • Fees de red: variables según red

⚠️ Errores Comunes​

Errores típicos

  • 404 Not Found: Customer no activo en Bridge
  • 400 Bad Request: Moneda no soportada
  • 409 Conflict: Cuenta ya existe para esa moneda
  • 403 Forbidden: Límites excedidos

📝 Notas Importantes​

Consideraciones

  • Se requiere customer verificado antes de crear cuentas
  • Cada usuario puede tener una cuenta por moneda
  • Las cuentas se crean instantáneamente, pero pueden tardar en activarse
  • Depósitos se procesan automáticamente 24/7
  • Los fondos se convierten automáticamente a crypto al recibirse