> ## 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.

# Arquitetura

> Arquitetura non-custodial: quem guarda as chaves e como cada operação é preparada, aprovada, assinada, executada e registrada

<Warning>
  Rascunho: especificação em definição. Endpoints e campos podem mudar.
</Warning>

## Quem guarda o quê

| Parte | Guarda | Não guarda |
| - | - | - |
| Empresa | Chaves de API, política de alocação, decisão de aprovar | Nada muda na operação de custódia atual |
| Custodiante da empresa | Chaves privadas das carteiras, assinatura das transações | Credenciais da TESA |
| TESA | Endereços públicos, propostas, transações não assinadas, registros | Chaves privadas e transações assinadas |

A API nunca guarda, recebe ou solicita chave privada. A chave de API autentica a integração, mas não assina transações.

## Ciclo de uma operação

Toda operação que move fundos (alocação, rebalanceamento ou resgate) segue cinco etapas: preparar, aprovar, assinar, executar e registrar.

```mermaid theme={null}
sequenceDiagram
  autonumber
  participant E as Empresa (integração)
  participant T as API da TESA
  participant C as Custodiante
  participant R as Rede (Ethereum ou Solana)
  E->>T: POST /resgates ou proposta sugerida pela TESA
  T-->>E: Proposta pendente, com movimentos calculados
  E->>T: POST /.../aprovar (Idempotency-Key, HMAC)
  T-->>E: Transações não assinadas
  E->>C: Envia payload não assinado
  C->>C: Assina com as chaves da empresa
  C->>R: Transmite a transação
  R-->>T: Confirmação on-chain (CCTP, USDY, BUIDL)
  T-->>E: Webhook com hash da transação e posições atualizadas
```

<Steps>
  <Step title="Preparar">
    A TESA monta a operação conforme a política de alocação e devolve uma proposta com os movimentos calculados.
  </Step>

  <Step title="Aprovar">
    A empresa aprova ou rejeita pelo painel ou pela API, com uma chave de escopo `admin`. Sem aprovação, nada é executado.
  </Step>

  <Step title="Assinar">
    As transações não assinadas seguem para a carteira da empresa, em self-custody ou no custodiante qualificado.
  </Step>

  <Step title="Executar">
    As transações assinadas são transmitidas. O USDC circula pelo CCTP da Circle e é alocado em USDY e BUIDL, ou volta para a custódia da empresa no resgate.
  </Step>

  <Step title="Registrar">
    A TESA acompanha a confirmação, atualiza posições e emite webhooks com o hash de cada transação.
  </Step>
</Steps>

## Ambientes

| Ambiente | URL base (proposta) | Uso |
| - | - | - |
| Sandbox | `https://sandbox.api.t3sa.com/v1` | Testes de integração, sem fundos reais |
| Produção | `https://api.t3sa.com/v1` | Operação com o caixa da empresa |

Cada ambiente tem chaves próprias. As URLs acima são propostas e ainda não estão ativas.

## Convenções

* **Formato:** JSON em UTF-8, com campos em `snake_case`.
* **Valores:** montantes em USDC são strings decimais com duas casas (`"842110.00"`), para evitar perda de precisão.
* **Datas:** ISO 8601 em UTC (`2026-09-01T00:00:00Z`).
* **Identificadores:** strings opacas com prefixo por recurso, como `prop_`, `res_` e `cart_`.
* **Paginação:** listas usam cursor, com os parâmetros `limite` e `apos`.

## Versionamento

A versão principal fica no caminho (`/v1`). Mudanças compatíveis, como novos campos ou eventos, entram sem troca de versão, e a integração deve ignorar campos que não reconhece. Mudanças incompatíveis geram uma nova versão principal, com período de convivência anunciado com antecedência. Acompanhe o [changelog](/docs/api/changelog).