Skip to main content
WalletSuite is non-custodial by design. We never hold your keys, funds, or signing authority. The MCP server is an orchestration layer — it prepares transactions and enforces policy, but private keys stay with you.

​
Trust Model

ComponentTrust LevelWhat It Can Access
WalletSuite APINo key accessBlockchain data, transaction preparation, fee estimation
MCP ServerNo key accessTool orchestration, input validation, band filtering
OWS VaultTrusted, operator-heldKey generation, AES-256-GCM encrypted storage, signing, policy enforcement
Your LLMNo key accessMCP tool calls and responses only — never sees key material
The trust boundary is not “the server is perfect.” The trust boundary is that key custody and signing stay local, regardless of what happens to the server.

​
Defense in Depth

WalletSuite uses seven layers of security controls:

​
1. Band Filtering

Controls which tools exist in the MCP schema. Tools outside the active band are never registered — the LLM cannot discover or call them. Default is read (7 tools, no signing). See Band Filtering.

​
2. Policy Gates

Controls what signed transactions can do. Declarative rules (chain allowlists, expiry) enforced by OWS before any key material is touched. First denial short-circuits. See Policy Gates.

​
3. Structured Errors

Every error includes a category and code. flow errors include a requiredAction. Agents recover programmatically — no guessing, no silent failures. See Structured Errors.

​
4. Input Validation

Zod schemas validate all tool inputs before they reach the API:
  • Address format checked per chain family (0x-prefixed for EVM, T-prefixed for Tron)
  • Amounts validated as positive numeric strings (no scientific notation)
  • Mutually exclusive fields enforced (amount vs amountWei, never both)
  • Token contracts validated when provided
  • Required fields enforced

​
5. Secret Isolation

Sensitive values are supplied through environment variables, never through tool arguments:
  • WALLETSUITE_API_KEY
  • OWS_PASSPHRASE
  • OWS_AGENT_TOKEN
  • OWS_ETHEREUM_RPC_URL / OWS_TRON_RPC_URL
Secrets stay out of prompt history, tool argument logs, and MCP traffic.

​
6. HTTPS Enforcement

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

​
7. Audit Trail

Every sign_transaction and send_transaction operation appends a receipt to a hash-chained, append-only JSONL log. Each receipt is SHA-256 linked to the previous one, so tampering with any entry invalidates every entry after it. Receipts record the operation, chain, policy decision, and outcome — wallet name is preserved for forensics; sensitive fields are schema-redacted before write. See Audit Trail.

​
Non-Custodial Architecture

User request → MCP Server prepares unsigned tx (no key access)
             → OWS decrypts key from local vault
             → OWS signs the transaction
             → OWS broadcasts via configured RPC
             → Key wiped from memory
At no point does the MCP server or the WalletSuite API access private key material. The key exists in decrypted form only inside OWS during the signing operation, then it is wiped from memory. See Key Management for vault details.

​
Attack Model

If the MCP server is compromised:
  • An attacker does not get private keys (keys are in the OWS vault, not the server)
  • An attacker cannot sign transactions unless OWS is enabled and the signing band is active
  • An attacker cannot broadcast unless the broadcast band is enabled, the RPC URL is configured, and confirmBroadcast=true is passed
The worst case for a compromised server with MCP_BANDS=read is information disclosure (balances, prices, transaction history). No value can be moved.

​
What WalletSuite Does Not Do

  • Store private keys or mnemonics
  • Custody funds
  • Sign transactions on your behalf
  • Move funds without an explicitly enabled signing path and user/policy approval
  • Expose internal orchestration logic

​
Remaining Risks

Non-custodial does not mean zero risk. Important risks that remain with the operator:
  • Enabling broader bands than needed
  • Running on a compromised host
  • Leaking environment secrets (API keys, passphrases, agent tokens)
Mitigation: Keep bands narrow, scope agent tokens with policies, and protect your environment variables.

​
Practical Guidance

Start with these defaults and expand deliberately:
SettingDefaultWhen to Change
MCP_BANDSreadAdd prepare when you need tx construction
OWS_ENABLEDfalseEnable when you need local signing
BroadcastDisabledEnable only after proving the signing flow
PolicyNoneCreate before issuing agent tokens
See Production Checklist for the full pre-go-live validation.