Skip to main content
WalletSuite’s security model has three orthogonal axes:
AxisMembers
Surface (how you integrate)MCP server · SDK · REST API
Signing layer (where keys live)MPC 2-of-2 (DKLS23) · External BYO (KMS / HSM / multisig - SDK or REST)
Cross-cutting controlsBands · Policy gates · Audit trail · Structured errors · Input validation · Secret isolation · HTTPS

​
Trust Model

ComponentLayerHolds keys?What it can access
WalletSuite REST APISurfaceNoBlockchain data, transaction preparation, fee estimation
MCP ServerSurfaceNoTool orchestration, input validation, band filtering
SDK (@walletsuite/wallet-sdk)SurfaceNoTyped client; signer-agnostic
WalletSuite MPC ShareSigning1 of 2 DKLS23 sharesThreshold signature share; policy enforcement
Customer MPC ShareSigning1 of 2 DKLS23 sharesStored on customer infrastructure, encrypted at rest; never reaches WalletSuite
External Signer (BYO)SigningCustomer-managedKMS / HSM / multisig - outside WalletSuite
Your LLMCallerNoMCP tool calls and responses only
Trust boundary: no single party ever holds enough to sign alone, regardless of which surface initiates the request.

​
Defense in Depth

​
1. Band Filtering · MCP only

Tools outside the active band are never registered in the MCP schema — the LLM cannot discover or call them. Default is read. SDK and REST API have no equivalent: they expose their full surface to whatever code holds the API key. See Band Filtering.

​
2. Policy Gates · Signing layer

Declarative rules (destination allowlists, value caps, rate limits) enforced at the signing layer before any signature is produced. Same gates apply whether the call comes from MCP, SDK, or REST. See Policy Gates.

​
3. Structured Errors · MCP + SDK

Every error includes a category and code. flow errors include a requiredAction. Agents recover programmatically. See Structured Errors.

​
4. Input Validation · All surfaces

Zod schemas (MCP/SDK) and request validators (REST) check inputs before they reach the API:
  • Address format per chain family (0x-prefixed for EVM, T-prefixed for Tron)
  • Amounts as positive numeric strings (no scientific notation)
  • Mutually exclusive fields (amount vs amountWei)
  • Token contracts validated when provided

​
5. Secret Isolation · All surfaces

Sensitive values are supplied through environment variables, never through tool arguments or request bodies:
  • WALLETSUITE_API_KEY
  • WALLETSUITE_PASSPHRASE (when the server holds the customer key share)
Secrets stay out of prompt history, tool argument logs, and MCP traffic.

​
6. HTTPS Enforcement · All surfaces

All external URLs are validated as HTTPS. HTTP is allowed only for localhost in development. Applies to the backend API, chain RPCs, and MoonPay widget URLs.

​
7. Audit Trail · Signing layer

Every sign_transaction and send_transaction operation appends a receipt to a hash-chained, append-only JSONL log written by the server core - tamper-evident, local to your deployment, and exportable to your SIEM. See Audit Trail.

​
Surface-Specific Notes

​
MCP server

  • Bands constrain tool visibility per agent role
  • Tool arguments carry only wallet identifiers, chain ids, and unsigned tx hex — never key material
  • Closed-source orchestration; trust is enforced architecturally, not via source review

​
SDK

  • Signer-agnostic: composes with MPC or external (KMS/HSM/multisig/local key)
  • No bands - the SDK exposes its full surface to whatever code imports it
  • Typed errors share the category / code taxonomy with MCP

​
REST API

  • Stateless HTTPS with x-api-key header
  • Same input validation and structured error envelope as the SDK
  • Customer brings the signer (External BYO) or routes signing through MCP

​
Non-Custodial Architecture

​
MPC 2-of-2 (DKLS23)

Any surface (MCP/SDK/REST) → prepare unsigned tx (no key access)
                           → Signing layer evaluates policy
                           → Customer share signs
                           → WalletSuite share signs
                           → Combined threshold signature → broadcast
                           → Neither party ever held a full key
No full private key ever exists. Both shares are required to produce a signature, and neither party can sign alone. See Key Management.

​
Attack Model

MCP server compromised:
  • No full key is exposed - no full key ever exists
  • Signing requires the customer share plus the sign band
  • Broadcast requires the broadcast band and confirmBroadcast=true
WalletSuite-side MPC share compromised:
  • Attacker has 1 of 2 shares — cannot produce a valid signature without the customer share
  • Internal access is M-of-N gated and audit-logged
Customer-side MPC share compromised:
  • Attacker has 1 of 2 shares — cannot produce a valid signature without WalletSuite’s share
  • Policy gates are still evaluated on every co-signing request
Read-only deployment (MCP_BANDS=read): Worst case is information disclosure (balances, prices, transaction history). No value can be moved.

​
What WalletSuite Does Not Do

  • Hold a full private key (1 of 2 DKLS23 shares only)
  • Custody funds
  • Sign transactions alone - both shares are required
  • Move funds without an enabled signing band and user/policy approval

​
Remaining Risks

Non-custodial does not mean zero risk. Operator-side risks:
  • Enabling broader bands than needed (MCP)
  • Running on a compromised host
  • Leaking environment secrets (API keys)
Mitigation: Keep bands narrow, attach policies to the signing layer, protect environment variables.

​
Practical Guidance

SettingDefaultWhen to change
MCP_BANDSreadAdd prepare when you need tx construction
BroadcastDisabledEnable only after proving the signing flow
PolicyNoneAttach to the signing layer before enabling sign
See Production Checklist.