> ## Documentation Index
> Fetch the complete documentation index at: https://t3sa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Arquitectura

> Arquitectura no custodial: quién tiene las claves y cómo se prepara, aprueba, firma, ejecuta y registra cada operación

> [!WARNING]
>
> Borrador: especificación en curso. Los endpoints y campos pueden cambiar.

## Quién tiene qué

| Parte | Tiene | No tiene |
| - | - | - |
| Empresa | Claves de API, política de asignación, la decisión de aprobar | Nada cambia en su operación de custodia actual |
| Custodio de la empresa | Claves privadas de las billeteras, firma de transacciones | Credenciales de TESA |
| TESA | Direcciones públicas, propuestas, transacciones sin firmar, registros | Claves privadas y transacciones firmadas |

La API nunca almacena, recibe ni solicita una clave privada. La clave de API autentica la integración, pero no firma transacciones.

## Ciclo de vida de una operación

Toda operación que mueve fondos (asignación, rebalanceo o rescate) pasa por cinco etapas: preparar, aprobar, firmar, ejecutar y registrar.

```mermaid theme={null}
sequenceDiagram
  autonumber
  participant E as Empresa (integración)
  participant T as API de TESA
  participant C as Custodio
  participant R as Red (Ethereum o Solana)
  E->>T: POST /resgates, POST /propostas o regla de la política cumplida
  T-->>E: Propuesta pendiente, con los movimientos calculados
  E->>T: POST /.../aprovar (Idempotency-Key, HMAC)
  T-->>E: Transacciones sin firmar
  E->>C: Envía el payload sin firmar
  C->>C: Firma con las claves de la empresa
  C->>R: Transmite la transacción
  R-->>T: Confirmación on-chain (CCTP, USDY, BUIDL)
  T-->>E: Webhook con el hash de la transacción y las posiciones actualizadas
```

**1. Preparar**

El software arma la operación según la política de asignación definida por la empresa, cuando se cumple una de sus reglas o a solicitud de la integración, y devuelve una propuesta con los movimientos calculados.

**2. Aprobar**

La empresa la aprueba o la rechaza en el panel o por la API, con una clave de alcance `admin`. Sin aprobación, no se ejecuta nada.

**3. Firmar**

Las transacciones sin firmar van a la billetera de la empresa, en autocustodia o con el custodio autorizado en su jurisdicción.

**4. Ejecutar**

Las transacciones firmadas se transmiten. El USDC se mueve por el CCTP de Circle y se asigna a USDY y BUIDL, o regresa a la custodia de la empresa en el caso de un rescate.

**5. Registrar**

TESA sigue la confirmación, actualiza las posiciones y envía webhooks con el hash de cada transacción.

## Entornos

| Entorno | URL base (propuesta) | Uso |
| - | - | - |
| Sandbox | `https://sandbox.api.t3sa.com/v1` | Pruebas de integración, sin fondos reales |
| Producción | `https://api.t3sa.com/v1` | Operaciones con la caja de la empresa |

Cada entorno tiene sus propias claves. Las URL de arriba son propuestas y todavía no están activas.

## Convenciones

* **Formato:** JSON en UTF-8, con campos en `snake_case`.
* **Montos:** los montos en USDC son cadenas decimales con dos decimales (`"842110.00"`), para evitar pérdida de precisión.
* **Fechas:** ISO 8601 en UTC (`2026-09-01T00:00:00Z`).
* **Identificadores:** cadenas opacas con un prefijo por recurso, como `prop_`, `res_` y `cart_`.
* **Paginación:** las listas usan cursor, con los parámetros `limite` y `apos`.

## Versionado

La versión mayor va en la ruta (`/v1`). Los cambios compatibles hacia atrás, como nuevos campos o eventos, se publican sin cambiar de versión, y su integración debe ignorar los campos que no reconozca. Los cambios incompatibles crean una nueva versión mayor, con un período de coexistencia anunciado con anticipación. Siga el [changelog](https://t3sa.com/docs/es/api/changelog.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.