Panorama de la API

Panorama de la API

Estado: Limitado

La API del marketplace de T-Suite es la API que usan las propias aplicaciones web de Libertum. Todavía no es un producto público con soporte: no hay una referencia OpenAPI publicada y mantenida, y las rutas y los campos pueden cambiar entre versiones. Esta página sirve para entender la forma de la API; cualquier integración debe acordarse con Libertum antes de construir sobre ella. Está prevista una referencia OpenAPI pública.

Ruta base y hosts

Todas las rutas de la API del marketplace se sirven bajo la ruta base:

/marketplace/v1

en el host de la API de T-Suite del despliegue correspondiente. El host se entrega como parte de un acuerdo de integración.

Las peticiones y respuestas son JSON sobre HTTPS, salvo la subida de archivos (multipart) y el stream de notificaciones en tiempo real (Server-Sent Events).

Grupos de rutas

Grupo	Prefijo	Autenticación
Cuenta	registro, inicio de sesión, verificación de códigos y restablecimiento de contraseña en la raíz de la ruta base	Ninguna (estas rutas crean la sesión)
Autenticadas	/auth/...	Token de acceso del usuario — véase Autenticación
Otros grupos autenticados	órdenes, dividendos y gestión de suscripciones tienen sus propios prefijos	Token de acceso del usuario
Públicas	/public/...	Ninguna — datos de solo lectura que ya son públicos, más algunos flujos protegidos por token
API para desarrolladores de stablecoins	/api/stablecoin/v1	API key del emisor
API de Funds	/api/funds/v1	Clave de API de Funds con alcances o credenciales de cliente OAuth

La mayoría de las rutas de producto bajo /auth/... también pasan por la puerta de onboarding, y los productos de pago comprueban además el módulo de suscripción.

Grupos de recursos

Los principales grupos de recursos, por área de producto. Es un mapa, no una referencia de endpoints.

Inversión y ofertas

Grupo de recursos	Propósito
Ofertas	Crear, configurar, desplegar y listar ofertas; documentos de la oferta; listados Coming Soon e interés
Órdenes	Órdenes de suscripción primaria y sus medios de pago (tarjeta, transferencia bancaria, USDC/USDT vía Escrow en EVM, RLUSD/USDC en XRPL, saldo de custodia)
Acuerdos	Plantillas de acuerdos, especímenes de firma del inversor, firma, PDFs ejecutados y registros de auditoría
Dividendos	Distribuciones de dividendos a los tenedores de tokens
Transferencias	Solicitudes de transferencia de tokens y el diario de transferencias
Mercado secundario (P2P)	Libro de órdenes entre pares para tokens listados
Redenciones	Ventanas de redención, solicitudes de redención y cuentas de pago del inversor
Gobernanza	Propuestas y votación de inversores
Estados de cuenta del inversor	Resumen del inversor y feed combinado de transacciones
Tenencias	Las tenencias de tokens de un usuario

Cuentas y facturación

Grupo de recursos	Propósito
Perfil y seguridad	Perfil, contraseña, autenticación de dos factores y códigos de respaldo, cierre de sesión
KYC / KYB	Sesiones y estado de verificación de identidad (vía SumSub)
Suscripciones	Catálogo de planes y módulos, checkout, cambios de plan, add-ons, portal de facturación
Equipo del emisor	Invitar a miembros del equipo y gestionar roles
Facturación y pagos del emisor	Facturas del emisor, configuración de pagos, cuentas bancarias y métodos de pago guardados
Wallets vinculadas	Wallets externas que el usuario ha conectado
Restricciones por país	La lista gris y la lista negra de países de la plataforma
Soporte	Tickets de soporte y disputas

Wallets y pagos

Grupo de recursos	Propósito
Custodian Wallet	Saldos, datos de depósito, direcciones de retiro guardadas y retiros
Tesorería de gas	Saldo prepagado de gas y cobros de comisiones de red de las transacciones de custodia
T-Pay	Rampa fiat de entrada/salida vía Bridge.xyz (disponibilidad limitada)

Distribución, estructuración y otros productos

Grupo de recursos	Propósito
Distribution Hub	CRM de inversores, matching con IA, campañas, pipeline, comunicaciones y funciones de Libby AI
Hosting	Solicitudes de hosting entre marketplaces y el Ecosystem Directory
Structuring	Proyectos de Structuring, intake, investigación, generación de documentos, artefactos y enlaces de revisión para invitados
Funds	Operadores de administración de fondos, fondos y clases de participación, paquetes de NAV, suscripciones y reembolsos, mercados privados, conciliación, asientos, medidas de cumplimiento, integraciones y órdenes de fondos de los inversores
Token Import	Importación de tokens existentes, listas de titulares, roles y cesión del control a Libertum
Stablecoin Studio	Configuración de stablecoins, órdenes de emisión y redención, y el portal de minters
Whitelabel	Branding del tenant y configuración del dominio propio
Asset Management	Activos, portafolios, clientes, órdenes de trabajo, etiquetas, elementos de cumplimiento, reportes y migración
Notificaciones	Notificaciones en la app y el stream en tiempo real — véase Tiempo real y webhooks
Acreditación	Solicitudes de acreditación de inversores, evidencias y decisiones de revisión
Plataforma XRPL	Cuentas de plataforma XRPL, credenciales, autorización de trust lines y reservas para las ofertas XRPL activas

Las rutas públicas cubren datos que ya son visibles en páginas públicas — una vista pública de la oferta y su historial de NAV, las listas de restricciones por país, el branding del tenant, la comisión de la plataforma, el autorregistro de inversores del Distribution Hub, y la página de revisión para invitados de Structuring que el abogado externo abre desde un enlace compartido.

Metadatos de tokens. Los metadatos de los tokens ERC-721 se sirven en una ruta separada y permanente fuera de /marketplace/v1, porque esa URL queda escrita en los contratos de los tokens y nunca debe cambiar. Solo resuelve para ofertas ERC-721 aprobadas y desplegadas.

Formato de respuesta

Las respuestas usan un único sobre:

{
  "message": "Mensaje legible",
  "status": 200,
  "data": { },
  "error": false
}

• error es true ante cualquier fallo, y status repite el código de estado HTTP.
• data lleva el contenido en caso de éxito. En algunos fallos lleva detalles legibles por máquina — por ejemplo requiresOnboarding y missingStep de la puerta de onboarding, o reason y moduleId de una comprobación de suscripción.
• Las decisiones deben basarse en status y en los campos de data, no en el texto de message, que puede cambiar.

Excepciones: el stream en tiempo real envía Server-Sent Events, y los metadatos de tokens devuelven metadatos ERC-721 en bruto, sin el sobre.

Códigos de estado

Estado	Cuándo aparece
200 / 201	Éxito
400	La validación falló o la petición no está permitida en el estado actual
401	Token de acceso ausente, inválido o caducado, o una sesión que ha terminado
402	La cuenta no tiene el módulo de suscripción que exige este producto. data.reason indica el caso (por ejemplo, sin suscripción frente a una suscripción vencida que ahora es de solo lectura) y data.moduleId indica el módulo que hay que añadir
403	Sesión iniciada pero sin permiso: paso de 2FA pendiente, onboarding incompleto, rol o persona incorrectos, o cuenta bloqueada
404	No se encontró la ruta o el recurso
409	Conflicto con datos existentes, como un duplicado
429	Se alcanzó el límite de tasa
500	Error inesperado del servidor
503	Una dependencia, como el almacén de sesiones, no está disponible temporalmente — se debe reintentar con backoff

Los productos que hoy responden 402 incluyen Distribution Hub, las funciones de Libby AI, Structuring y Stablecoin Studio. Cuando vence la suscripción del titular de un espacio de trabajo de Structuring, todas las rutas de Structuring responden 402 al titular, a los miembros y a los invitados hasta que vuelve a estar activa.

Límites de tasa

Hay límites de tasa en rutas sensibles concretas — por ejemplo, la solicitud de códigos de verificación de retiros, la página pública de revisión de Structuring y la API para desarrolladores de stablecoins (300 peticiones por minuto por cliente). Al alcanzar un límite, la API responde 429; donde aplican, los límites se anuncian en las cabeceras estándar RateLimit-*. Los clientes deben esperar y reintentar en lugar de saturar una ruta.

API para desarrolladores de Stablecoin Studio

Estado: Limitado

Los emisores de Stablecoin Studio cuentan con una pequeña API para desarrolladores, de solo lectura, en /api/stablecoin/v1:

• Autenticación: una API key del emisor, creada y revocada en la página Developer de Stablecoin Studio, enviada como token Bearer o en una cabecera de API key.
• Alcance: cada key lee solo los datos de su propio emisor — tokens, órdenes de emisión, órdenes de redención y uso de la API — además de una comprobación de conectividad.
• Sin escrituras: crear órdenes de emisión y otros cambios siguen en la app de Stablecoin Studio.
• Facturación: el uso de la API se mide por emisor; la facturación del uso de la API para desarrolladores llegará próximamente.

API de Funds

Estado: Disponible — para operadores de Funds

Los administradores de fondos de Funds disponen de su propia API pública en /api/funds/v1, bajo la misma ruta base:

• Especificación: OpenAPI 3.1, servida en /api/funds/v1/openapi.json. El SDK de TypeScript, la CLI tsuite y el servidor MCP se basan en la misma especificación.
• Autenticación: una clave de API creada en Funds → Integrations con alcances (por ejemplo, funds:read, dealing:read, dealing:write) y, opcionalmente, limitada a determinados fondos; o credenciales de cliente OAuth. Una clave creada para otra persona queda pendiente hasta que esa persona la acepta, y solo ella ve el secreto. Sin clave, la API responde 401; una clave sin el alcance necesario se rechaza con un error de alcance insuficiente.
• Escrituras idempotentes: envíe una cabecera Idempotency-Key. Repetir una solicitud con la misma clave devuelve el resultado original (con Idempotent-Replayed: true); reutilizar la clave con un cuerpo distinto se rechaza.
• Sin aprobaciones: no existe ningún endpoint que apruebe nada. Las aprobaciones, y todo lo que mueve dinero, siguen en manos de personas en T-Suite.
• Webhooks: entregas firmadas a endpoints https públicos, con las cabeceras T-Suite-Event-Type, T-Suite-Event-Id y T-Suite-Signature (t=…,v1=…), ping, pausa/reanudación y reenvío. Entre los eventos están nav.published, dealing_run.approved y order.settled.

Referencia OpenAPI

Está prevista una referencia OpenAPI pública y mantenida para la API del marketplace (la API de Funds ya publica su propia especificación OpenAPI 3.1). Hasta que se publique, esta página es la descripción de referencia de la forma de la API, y el detalle a nivel de endpoint se solicita a Libertum como parte de un acuerdo de integración.