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

# Architecture

> How the hosted WalletSuite platform composes MCP, SDK, and REST over one policy engine and one MPC signing layer.

WalletSuite is a **hosted platform**. WalletSuite operates the MCP runtime, tools, and financial execution controls — there is no server to run. Three surfaces reach the one platform: **MCP** (agents), **SDK** (code), **REST API** (any language). All three compose the **same policy engine** and the **same MPC signing layer**, and share the audit trail, structured errors, input validation, secret isolation, and HTTPS enforcement.

This is the layer that gives every AI agent a financial identity — see [Overview](/ai-agents/overview) for positioning and [Choose your surface](/ai-agents/choose-your-setup) for the five ways to reach the platform.

## System Context

An agent connects by authorizing with its key to get a short-lived token, then calls the hosted endpoint with that token. The key stays on your server and never reaches the model — see [Connect your agent](/ai-agents/token-exchange).

```
  ① Authorize (once per token)

     agent key ──authorize──▶ WalletSuite ──▶ short-lived token

  ② Request path (every call, token attached)

     Your app / agent ──MCP · SDK · REST──▶ Hosted WalletSuite platform ──▶ WalletSuite APIs ──▶ Blockchain
     (your model)     ◀─────────────────── MCP runtime → policy engine        (data plane)        (multi-chain)
                            responses         → MPC signing layer
```

Inside the platform, the MCP runtime proposes, the deterministic policy engine authorizes, and the MPC signing layer completes — the proposer/authorizer/completer split defined in [Agents and Authority](/core-concepts/agents-and-authority). Signing is non-custodial MPC threshold signing — [trust model](/security/overview#trust-model).

## Design Principle

Every MCP tool maps to a user outcome, not a REST endpoint. The runtime orchestrates multiple API calls behind a single tool when needed. A token transfer, for example, resolves the asset first and then prepares the transaction — the agent handles this as two clear steps, not raw API calls.

## Component Layers

### MCP Runtime

WalletSuite operates the hosted MCP endpoint. Agents connect over HTTPS with a short-lived token; the runtime handles MCP protocol communication, session affinity, and dispatch to the tool handlers. Nothing is installed or self-operated — see [Connect your agent](/ai-agents/token-exchange).

### Tool Handler Layer

Maps MCP tool calls to service operations. Each handler:

1. Validates input using Zod schemas (address format, amount, chain)
2. Calls the service layer
3. Returns a structured MCP response or a structured error

Which tools exist for an agent is set by its server-owned **tool profile** and granted scopes. Tools outside that profile are never registered in the MCP schema — the model cannot discover or call them. That is the prompt-injection boundary. See [Execution Levels](/ai-agents/execution-levels) for how the effective tool surface is computed.

### Service Layer

Shared business logic behind the tool handlers:

| Service                  | Responsibility                                                                                                                          |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| **WalletSuiteApiClient** | Typed HTTP client for the REST API — retry, timeout, response envelope unwrapping                                                       |
| **MPC**                  | Threshold share orchestration; the fully-managed cosigner holds one share, the customer holds the other; policy-gated threshold signing |
| **TxCompiler**           | Converts API prepare-sign responses into signing-ready unsigned transaction hex                                                         |
| **On-ramp**              | Builds a hosted fiat on-ramp widget URL (`prepare_onramp` tool)                                                                         |
| **AuditTrail**           | Hash-chained JSONL receipt log for sign and broadcast operations — tamper-evident, append-only                                          |

## Boundary of Responsibility

| Component            | Owns                                                                                    | Does Not Own                                                                                |
| -------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| **MCP Runtime**      | Tool schema, input validation, error mapping, tool-profile scoping                      | Blockchain interaction, caching, chain-specific tx construction, the authorization decision |
| **Policy Engine**    | The allow/deny decision on every signing intent, decision records                       | Signature production, transaction preparation                                               |
| **MPC Signing**      | Key-share orchestration, threshold signature, sign and broadcast                        | Transaction preparation, the authorization decision, MCP protocol                           |
| **WalletSuite API**  | Chain interaction, fee estimation, tx simulation, broadcast, caching, volume tracking   | LLM integration, tool discovery, signing                                                    |
| **You (integrator)** | Your model/framework, holding the agent's key server-side, user confirmation, wallet UI | The MCP runtime, signing infra, API orchestration, fee calculation                          |

## Signing Models

All three surfaces compose the same **policy engine** and the same **MPC threshold signing** layer. Signing is non-custodial — no full private key ever exists. See the [trust model](/security/overview#trust-model).

**External BYO** signing (KMS / HSM / multisig / custodian) stays available through the SDK and REST — the customer manages the key entirely, outside WalletSuite. WalletSuite can prepare for an external signer but never signs with it, so grant such an agent the **R1 · Prepare** level (the `prepare` tool profile, `wallets:sign` withheld) and route the unsigned payload to your signer outside WalletSuite. See [Execution Levels](/ai-agents/execution-levels) and [Bring your own signer](/sdk/end-to-end-token-transfer-flow#bring-your-own-signer).

## What the Platform Does Not Do

* Hold a full private key (one of two shares only, both required to sign)
* Let the model authorize — the deterministic [policy engine](/core-concepts/policy-gates) decides, with no LLM in the path
* Expose internal orchestration logic (tools map to outcomes, not implementation details)
* Move funds without a signing scope and a passing policy decision