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

# Architecture

> Non-custodial architecture: who holds the keys and how each operation is prepared, approved, signed, executed and recorded

<Warning>
  Draft: specification in progress. Endpoints and fields may change.
</Warning>

## Who holds what

| Party | Holds | Does not hold |
| - | - | - |
| Company | API keys, allocation policy, the decision to approve | Nothing changes in its current custody operation |
| Company's custodian | Wallet private keys, transaction signing | TESA credentials |
| TESA | Public addresses, proposals, unsigned transactions, records | Private keys and signed transactions |

The API never stores, receives or requests a private key. The API key authenticates the integration but does not sign transactions.

## Lifecycle of an operation

Every operation that moves funds (allocation, rebalancing or redemption) goes through five steps: prepare, approve, sign, execute and record.

```mermaid theme={null}
sequenceDiagram
  autonumber
  participant E as Company (integration)
  participant T as TESA API
  participant C as Custodian
  participant R as Network (Ethereum or Solana)
  E->>T: POST /resgates or proposal suggested by TESA
  T-->>E: Pending proposal, with calculated movements
  E->>T: POST /.../aprovar (Idempotency-Key, HMAC)
  T-->>E: Unsigned transactions
  E->>C: Sends unsigned payload
  C->>C: Signs with the company's keys
  C->>R: Broadcasts the transaction
  R-->>T: On-chain confirmation (CCTP, USDY, BUIDL)
  T-->>E: Webhook with transaction hash and updated positions
```

<Steps>
  <Step title="Prepare">
    TESA builds the operation according to the allocation policy and returns a proposal with the calculated movements.
  </Step>

  <Step title="Approve">
    The company approves or rejects it in the dashboard or through the API, with an `admin` scope key. Without approval, nothing is executed.
  </Step>

  <Step title="Sign">
    The unsigned transactions go to the company's wallet, in self-custody or with the qualified custodian.
  </Step>

  <Step title="Execute">
    The signed transactions are broadcast. USDC moves through Circle's CCTP and is allocated to USDY and BUIDL, or returns to the company's custody on redemption.
  </Step>

  <Step title="Record">
    TESA tracks the confirmation, updates positions and sends webhooks with the hash of each transaction.
  </Step>
</Steps>

## Environments

| Environment | Base URL (proposed) | Use |
| - | - | - |
| Sandbox | `https://sandbox.api.t3sa.com/v1` | Integration testing, with no real funds |
| Production | `https://api.t3sa.com/v1` | Operations with the company's cash |

Each environment has its own keys. The URLs above are proposals and are not live yet.

## Conventions

* **Format:** UTF-8 JSON, with `snake_case` fields.
* **Amounts:** USDC amounts are decimal strings with two decimal places (`"842110.00"`), to avoid loss of precision.
* **Dates:** ISO 8601 in UTC (`2026-09-01T00:00:00Z`).
* **Identifiers:** opaque strings with a per-resource prefix, such as `prop_`, `res_` and `cart_`.
* **Pagination:** lists use a cursor, with the `limite` and `apos` parameters.

## Versioning

The major version is in the path (`/v1`). Backward-compatible changes, such as new fields or events, ship without a version change, and your integration should ignore fields it does not recognize. Breaking changes create a new major version, with a coexistence period announced in advance. Follow the [changelog](/docs/en/api/changelog).