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

# Architecture

> How AIUSD works across human interfaces, AI agents, custody, and trading execution.

## Overview

AIUSD is a trading platform built for both human users and AI agents. Humans can use AIUSD through first-party interfaces and chat-based experiences. AI agents can use [AIUSD Skills](/skills) (either the direct MCP-based skill or the natural language skill) or connect directly through the [MCP Hub API](/api). All paths converge on the same execution platform.

At a high level, the platform combines four layers:

* User and agent interfaces
* A shared orchestration layer for intent handling
* Core services for balances, custody, and trading
* On-chain execution and institutional custody

<Note>
  This page explains the platform at a high level. It intentionally omits sensitive implementation details such as key derivation formulas, signing paths, wallet inventories, and internal operational thresholds.
</Note>

## Shared platform for humans and AI agents

```mermaid theme={null}
flowchart LR
    H[Human users] --> UI[AIUSD interfaces]
    A[AI agents] --> SK[AIUSD Skill / NL Skill]
    A --> MCP[MCP Hub API]
    UI --> ORCH[Shared platform]
    SK --> ORCH
    MCP --> ORCH
    ORCH --> L[Ledger and custody services]
    ORCH --> T[TIM trading execution]
    T --> C[Supported chains and venues]
```

The key design choice is that human users and AI agents do not use separate trading systems. They use different entry points, but they rely on the same account model, custody controls, and execution infrastructure.

## Core components

| Component                  | Role                                                                                                                  |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| User interfaces            | Serve human users through web and chat-style experiences                                                              |
| `AIUSD Skills`             | Let external AI agents access the platform through packaged integrations (direct MCP skill or natural language skill) |
| `MCP Hub`                  | Exposes a tool surface for balances, funding, and trading                                                             |
| Ledger                     | Tracks AIUSD balances, staking balances, and movement between reserve and trading contexts                            |
| TIM                        | Interprets trading intent and routes execution to the right chain and venue                                           |
| Relayer and chain adapters | Handle chain-specific transaction execution                                                                           |
| Indexers and monitoring    | Detect deposits, observe on-chain state, and support operational controls                                             |
| `CEFFU`                    | Holds reserve assets in institutional custody                                                                         |

## Account model

The platform separates identity, reserve custody, and trading execution.

| Account type            | Purpose                                                            |
| ----------------------- | ------------------------------------------------------------------ |
| Login wallet            | Proves user identity during authentication                         |
| Deposit address         | Receives supported stablecoin deposits into the AIUSD system       |
| Trading account         | Holds tradable on-chain assets and executes user-authorized trades |
| Hot wallet              | Supports operational transfers and fulfillment                     |
| `CEFFU` custody account | Holds reserve assets backing liquid AIUSD                          |
| `CEFFU` staking account | Holds reserve assets backing staked AIUSD                          |

Two boundaries matter:

* `AIUSD ledger balances` are ledger liabilities inside the reserve model
* `On-chain trading balances` are execution balances outside the AIUSD reserve model until they are converted back through ledger operations

This separation lets the platform support natural-language trading without confusing reserve assets with active trading positions.

## Custody and reserve management

Reserve assets are managed in `CEFFU` custody. Liquid reserves and staked reserves are separated at the custody layer.

```mermaid theme={null}
flowchart LR
    D[User stablecoin deposits] --> DA[Deposit addresses]
    DA --> CW[CEFFU custody]
    CW --> HW[Hot wallets]
    CW --> SW[CEFFU staking]
    CW --> TA[Per-user trading accounts]
    SW --> Y[Yield strategy layer]
    TA --> EX[On-chain trading execution]
```

The custody model is designed around clear fund boundaries:

* Liquid AIUSD reserves are held in `CEFFU` custody
* Staked reserves are isolated in `CEFFU` staking
* Hot wallets support operational movement and fulfillment
* Trading accounts are used for execution, not for reserve backing

We run continuous reconciliation and operational monitoring across custody balances, ledger state, and execution flows. This architecture doc does not expose internal reconciliation procedures.

## How intent becomes execution

The same execution model supports a human asking for a trade and an AI agent fulfilling that trade on the user’s behalf.

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant U as Human or AI agent
    participant E as UI, Skills, or MCP client
    participant M as MCP Hub / orchestration
    participant L as Ledger
    participant T as TIM
    participant X as Chains and venues

    U->>E: Express trading intent
    E->>M: Submit authenticated request
    M->>L: Read balances and account state
    alt Funding or gas is needed
        M->>L: Move funds or ensure gas
    end
    M->>T: Submit trading intent
    T->>X: Execute on the target chain or venue
    X-->>T: Return transaction result
    T-->>M: Return execution status
    M-->>E: Return result and updated state
```

In practice, the flow is:

1. The user authenticates with a wallet-based identity flow.
2. The platform reads the user’s ledger balances and trading-account balances.
3. If needed, the platform moves value into the correct execution context.
4. `TIM` executes the trading intent on the destination chain or venue.
5. The platform returns execution status and updated balances.

This model is especially important for AI agents. Agents can use `AIUSD Skills` or the `MCP Hub API` directly to fulfill user trading intents without bypassing the platform’s custody and balance controls.

## Security model

The platform uses a wallet-based identity model and a separate trading-account control model.

* A user’s login wallet proves identity
* Per-user trading accounts are deterministically mapped from authenticated user identity inside a secure key-management boundary
* The application does not store those signing keys as plaintext in the application database
* Signing and execution occur through controlled service boundaries

This approach lets the platform give users persistent trading accounts while avoiding a simple “private key in database” design.

## Design principles

* One platform for both human users and AI agents
* Clear separation between reserve custody and trading execution
* Natural-language intent as the user-facing interaction model
* Shared backend controls for funding, gas, execution, and monitoring
* High-level transparency without exposing sensitive implementation details