Architecture - WalletSuite

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 for positioning and Choose your surface 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.

  ① 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. Signing is non-custodial MPC threshold signing — 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.

Tool Handler Layer

Maps MCP tool calls to service operations. Each handler:

Validates input using Zod schemas (address format, amount, chain)
Calls the service layer
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 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. 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 and 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 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

​System Context

​Design Principle

​Component Layers

​MCP Runtime

​Tool Handler Layer

​Service Layer

​Boundary of Responsibility

​Signing Models

​What the Platform Does Not Do