APIs Externas

SwapBits integra múltiples APIs de terceros para proveer funcionalidades de exchange, pagos fiat, KYC, blockchain y otros servicios. Cada API tiene un propósito específico y se usa en diferentes microservicios.

---

1. Bybit (Exchange)

Propósito: Exchange de criptomonedas, trading spot, orderbook, precios en tiempo real.

Información General

• Website: https://www.bybit.com
• Documentación: https://bybit-exchange.github.io/docs/
• API Base URL:
  • Producción: https://api.bybit.com
  • WebSocket: wss://stream.bybit.com/v5/public/spot
• SDK: bybit-api (npm)

Configuración

// Variables de entorno
BYBIT_API_KEY=your_api_key
BYBIT_API_SECRET=your_api_secret

Servicios que la Usan

Microservicios con Bybit

• ws-service: WebSocket para precios en tiempo real, orderbook, órdenes privadas
• exchange-service: Ejecución de órdenes de compra/venta
• wallet-service: Consultas de precios y símbolos

Endpoints Principales

• GET /v5/market/tickers - Obtener precios actuales de todos los pares
• GET /v5/market/orderbook - Obtener orderbook de un par
• POST /v5/order/create - Crear orden de compra/venta
• GET /v5/order/realtime - Consultar estado de órdenes
• GET /v5/market/instruments-info - Información de instrumentos/símbolos

WebSocket Topics

// Público
'tickers.{symbol}'         // Precios en tiempo real
'orderbook.50.{symbol}'    // Orderbook de 50 niveles

// Privado (requiere autenticación)
'order'                    // Actualizaciones de órdenes del usuario

---

2. Manteca (Pagos Fiat - Argentina/Brasil)

Propósito: Procesamiento de pagos fiat en Argentina (QR) y Brasil (PIX), conversión ARS/USD.

Información General

• Website: https://manteca.dev
• API Base URL: https://api.manteca.dev
• Documentación: API privada (requiere contacto comercial)

Configuración

// Variables de entorno
MANTECA_API_KEY=your_api_key
MANTECA_WEBHOOK_SECRET=your_webhook_secret
MANTECA_BASE_URL=https://api.manteca.dev

Servicios que la Usan

Microservicios con Manteca

• bank-service: Creación de usuarios Manteca, QR argentino, PIX brasileño
• wallet-service: Pagos PIX y QR para depósitos
• webhook-service: Recepción de webhooks de confirmación de pagos
• ws-service: Obtener tasas de conversión fiat (ARS/USD)

Endpoints Principales

// Usuarios
POST /v1/user/                          // Crear usuario en Manteca
GET /v1/user/{userNumberId}             // Obtener info de usuario

// Pagos PIX (Brasil)
POST /crypto/v2/payment-locks           // Crear payment lock PIX
POST /crypto/v2/synthetics/qr-payment   // Confirmar pago PIX

// QR Argentino
POST /argentina/qr/create               // Crear QR para pago argentino

// Tasas de conversión
GET /crypto/v1/fx/ARS/USD               // Tasa ARS a USD

Webhooks

POST /webhook/manteca  // Endpoint en webhook-service

// Eventos:
- 'user.kyc.approved'           // KYC aprobado
- 'payment.completed'           // Pago completado
- 'payment.lock.unlocked'       // Payment lock liberado

---

3. Bridge (Pagos Fiat - USD/Internacional)

Propósito: Procesamiento de pagos fiat internacionales, cuentas bancarias virtuales, KYC.

Información General

• Website: https://bridge.xyz
• API Base URL: https://api.bridge.xyz/v0
• Documentación: https://docs.bridge.xyz

Configuración

// Variables de entorno
BRIDGE_API_KEY=sk-live-xxxxx  // Producción
// sk-test-xxxxx para testing

Servicios que la Usan

Microservicios con Bridge

• bank-service: Creación de clientes Bridge, KYC, cuentas bancarias
• admin-service: Panel de administración de clientes Bridge
• ws-service: Tasas de conversión EUR/USD (planned)

Endpoints Principales

// Clientes
POST /customers                         // Crear cliente
GET /customers/{id}                     // Obtener info de cliente
PATCH /customers/{id}                   // Actualizar cliente

// KYC
POST /customers/{id}/kyc_links          // Crear link de KYC
GET /customers/{id}/kyc                 // Estado del KYC

// Cuentas
POST /customers/{id}/external_accounts  // Crear cuenta externa
GET /customers/{id}/accounts            // Listar cuentas

// Liquidaciones
POST /customers/{id}/liquidation_addresses  // Crear dirección de liquidación

---

4. Didit (KYC/Verificación de Identidad)

Propósito: Verificación de identidad (KYC) con documentos, selfies y liveness detection.

Información General

• Website: https://didit.me
• API Base URL: https://verification.didit.me/v2
• Documentación: https://docs.didit.me

Configuración

// Variables de entorno
CLIENT_ID_DIDIT=your_client_id
CLIENT_SECRET_DIDIT=your_client_secret

Servicios que la Usan

Microservicios con Didit

• kyc-service: Iniciar sesión KYC, webhook de resultados
• user-service: Obtener datos KYC del usuario
• webhook-service: Recibir webhooks de Didit
• Lambda GetDiditData: Consultar datos de sesión KYC

Endpoints Principales

// Sesiones KYC
POST /session/create                    // Crear sesión de verificación
GET /session/{sessionId}/decision/      // Obtener decisión del KYC
GET /session/{sessionId}/data           // Obtener datos capturados

// Webhooks
POST /webhook/didit  // Endpoint en webhook-service

// Eventos:
- 'session.completed'       // Sesión completada
- 'session.approved'        // KYC aprobado
- 'session.rejected'        // KYC rechazado

---

5. Avenia (Pagos PIX - Brasil)

Propósito: Proveedor alternativo de pagos PIX en Brasil (fallback de Manteca).

Información General

• Website: https://avenia.com.br (o similar)
• API: Información privada (API propietaria)
• Uso: Fallback automático si Manteca falla en PIX

Configuración

// Variables de entorno
AVENIA_API_KEY=your_api_key
AVENIA_API_SECRET=your_api_secret
AVENIA_BASE_URL=https://api.avenia.com

Servicios que la Usan

Microservicios con Avenia

• bank-service: Fallback para pagos PIX si Manteca falla
• wallet-service: Pagos PIX alternativos

Lógica de Fallback

// 1. Intentar con Manteca primero (defecto para PIX)
try {
  result = await createPaymentLockManteca(data);
  provider = 'manteca';
} catch (error) {
  // 2. Si Manteca falla, usar Avenia
  console.log('⚠️ Manteca falló, intentando con Avenia...');
  result = await createPaymentLockAvenia(data);
  provider = 'avenia';
}

Importante

Avenia solo soporta pagos PIX de Brasil. No soporta QR argentino ni otros métodos de pago.

---

6. CoinGecko (Precios & Datos de Mercado)

Propósito: Capitalización de mercado de criptomonedas, precios alternativos.

Información General

• Website: https://www.coingecko.com
• API Base URL: https://api.coingecko.com/api/v3
• Documentación: https://www.coingecko.com/api/documentation
• Plan: Free tier (sin API key necesaria)

Servicios que la Usan

Microservicios con CoinGecko

• ws-service: Obtener capitalización de mercado para tabla de precios

Endpoints Principales

GET /coins/list                         // Lista de todas las coins con IDs
GET /simple/price                       // Precios y market cap de múltiples coins
  ?ids=bitcoin,ethereum
  &vs_currencies=usd
  &include_market_cap=true

Ejemplo de Uso

// Obtener market cap de BTC, ETH, SOL
const response = await axios.get(
  'https://api.coingecko.com/api/v3/simple/price',
  {
    params: {
      ids: 'bitcoin,ethereum,solana',
      vs_currencies: 'usd',
      include_market_cap: true
    }
  }
);

// Respuesta:
// {
//   bitcoin: { usd: 45000, usd_market_cap: 880000000000 },
//   ethereum: { usd: 2500, usd_market_cap: 300000000000 },
//   solana: { usd: 100, usd_market_cap: 45000000000 }
// }

---

7. Blockchain RPCs (Nodos de Blockchain)

Propósito: Interactuar con blockchains para crear wallets, enviar transacciones, consultar balances.

RPCs Usados

Ethereum & EVM Chains

ETHEREUM_RPC=https://eth.llamarpc.com
POLYGON_RPC=https://polygon-rpc.com
BSC_RPC=https://bsc-dataseed.binance.org

Solana

SOLANA_RPC=https://api.mainnet-beta.solana.com

Tron

TRON_RPC=https://api.trongrid.io

Bitcoin

# BlockCypher API
https://api.blockcypher.com/v1/btc/main

Avalanche

# Avalanche API (api.avax.network)

Otros

• Litecoin: Custom RPC
• Dogecoin: Custom RPC
• Cardano: Custom RPC
• Polkadot: Custom RPC
• TON: Custom RPC
• XRP Ledger: Custom RPC

Servicios que los Usan

Lambda Functions

Todas las Lambda functions de creación de wallets (CreateWallet*) usan RPCs:

• CreateWalletEvm - Ethereum, Polygon, BSC, etc.
• CreateWalletSol - Solana
• CreateWalletTrx - Tron
• CreateWalletBtc - Bitcoin
• CreateWalletLtc - Litecoin
• CreateWalletDog - Dogecoin
• CreateWalletAvalanche - Avalanche
• CreateWalletCadano - Cardano
• CreateWalletPolkadot - Polkadot
• CreateWalletTon - TON
• CreateWalletXrpl - XRP Ledger

---

8. AWS Services (Infraestructura)

Aunque no son APIs externas tradicionales, SwapBits usa varios servicios de AWS:

AWS Lambda

// Lambda invocations desde microservicios
await lambdaService.call('CreateWalletEvm', { ... });
await lambdaService.call('SendHotWalletGlobal', { ... });
await lambdaService.call('GetDiditData', { sessionId });

AWS Secrets Manager

// Cargar secrets al iniciar servicios
await loadSecrets('production/env');
await loadSecrets('hash/config');
await loadSecrets('withdrawal/global/config');

AWS S3

• Almacenamiento de documentos KYC
• Imágenes de perfil de usuarios

---

Resumen de Integraciones

API	Microservicios	Propósito	Region/Geo
Bybit	ws-service, exchange-service, wallet-service	Trading, precios, orderbook	Global
Manteca	bank-service, wallet-service, webhook-service, ws-service	Pagos fiat AR/BR, PIX, QR	Argentina, Brasil
Bridge	bank-service, admin-service	Pagos internacionales, KYC, cuentas bancarias	Global
Didit	kyc-service, user-service, webhook-service, Lambda	KYC, verificación de identidad	Global
Avenia	bank-service, wallet-service	Fallback para PIX	Brasil
CoinGecko	ws-service	Market cap, precios	Global
Blockchain RPCs	Lambda Functions	Wallets, transacciones blockchain	Global

---

Observación

Redundancia y Fallbacks:

• PIX (Brasil): Manteca → Avenia (fallback automático)
• QR (Argentina): Solo Manteca (sin fallback)
• Precios crypto: Bybit (primario) + CoinGecko (market cap)
• Blockchains: Múltiples RPCs (public + private según necesidad)

API Keys: Todas las API keys se almacenan en AWS Secrets Manager (production/env) y se cargan al iniciar cada microservicio.

---

Monitoreo de APIs

Health Checks

Cada microservicio valida la conectividad con sus APIs al iniciar:

async onModuleInit() {
  // Verificar conectividad con APIs externas
  await this.checkBybitConnection();
  await this.checkMantecaConnection();
  await this.checkBridgeConnection();
}

Rate Limits

Rate Limits Conocidos

• Bybit: 120 requests/min (API REST), ilimitado (WebSocket con auth)
• CoinGecko: 10-50 calls/min (Free tier)
• Manteca: Custom (depende del plan comercial)
• Bridge: Custom (depende del plan comercial)
• Didit: Custom (depende del plan comercial)

Error Handling

// Patrón de retry con exponential backoff
async function callExternalAPI(attempt = 1): Promise<any> {
  try {
    return await apiClient.call();
  } catch (error) {
    if (attempt < 3) {
      await sleep(1000 * attempt); // 1s, 2s, 3s
      return callExternalAPI(attempt + 1);
    }
    throw new Error('API call failed after 3 attempts');
  }
}

---

Próximos Pasos

Para agregar una nueva API externa al sistema:

1. Crear servicio NestJS en docker/packages/services/ o dentro del microservicio
2. Configurar variables en AWS Secrets Manager (production/env)
3. Implementar cliente HTTP con axios o fetch
4. Agregar error handling y retry logic
5. Documentar endpoints usados en este archivo
6. Configurar webhooks (si aplica) en webhook-service
7. Agregar tests de integración

---

Última actualización: Octubre 2025