Security Architecture
How WalletSuite enforces non-custodial boundaries, scopes agent access with band filtering, and creates tamper-evident audit trails.
Last updated: April 2026
Non-custodial architecture
WalletSuite never holds, stores, or transmits your private keys. The REST API returns unsigned transaction payloads — you sign with your own key material, on your own infrastructure.
With OWS (Open Wallet Standard) enabled on the MCP Server, keys are derived locally via BIP-39/BIP-44 and stored in an AES-256-GCM encrypted vault on your device. Keys are decrypted in process memory only for the duration of a signing operation, then wiped. Neither the MCP Server nor the API ever access the vault — key material stays entirely within your control.
The core principle is prepare ≠ sign ≠ broadcast. Each boundary is explicit and enforced by a different component. No single component in the stack holds the full chain of custody.
MCP Server
no key access
API
no key access
OWS Vault
user-controlled
RPC
user-configured
What happens if a component is compromised?
MCP Server compromised
Attacker cannot sign — server has no key access. Band filtering limits which tools are even visible.
Mitigated by designWalletSuite API compromised
Attacker gets read-only chain data (balances, fees). No signing capability, no key material.
Mitigated by designOWS Vault compromised (self-hosted)
Attacker needs the vault passphrase. Keys are AES-256-GCM encrypted at rest, never plaintext on disk.
Encryption barrierRPC endpoint compromised
Attacker can see or delay broadcast transactions. Cannot forge signatures or access keys.
Read-only exposureBand filtering MCP Server
Band filtering is a 4-tier access control system. Each band — read, prepare, sign, broadcast — is cumulative. An agent configured at the prepare band can access read and prepare tools, but nothing above.
Enforcement happens at server startup: tools above the band cap are not registered in the MCP tool registry. The agent cannot see or call them. This is not a runtime permission check — the tools do not exist for that session. Configure per agent role: an analytics agent gets read, a trading bot gets sign.
Query chain state
get_balance, get_transactions, get_fees
Construct unsigned tx
prepare_transfer, prepare_onramp
Detached signing
sign_transaction (OWS vault)
Submit to chain
send_transaction (user RPC)
The only wallet MCP server with infrastructure-enforced tool isolation.
Band filtering in the glossarySpend governance MCP Server
Band filtering decides what an agent can call. Spend governance decides whether a specific operation should proceed — and under what rules.
Policy + Agent Key
Evaluated together inside OWS, before any key access. The agent key carries the policy set — both are validated in the same call. A mismatch rejects the request.
Policy rules
- Per-transaction spend limit
- Daily aggregate cap
- Chain allowlist
- Counterparty screeningBeta
Credential
- Scoped to one wallet
- Bound to one policy set
- Expires on a configurable window
If any rule rejects, signing never happens. Every pass, reject, and revocation is recorded
Runtime validation
Every backend response is schema-validated (Zod) before reaching the agent. Malformed or tampered data never influences decisions. The 6-category error taxonomy gives agents machine-parseable recovery instructions.
Audit trail MCP Server
Every signing and broadcast attempt is logged as a structured JSONL event. Each event includes a SHA-256 hash of the previous event, forming a tamper-evident chain.
Fields captured: operation type, agent identity, wallet address, chain, timestamp, band, policy evaluation result, and the hash link to the previous event.
The hash chain means you can independently verify that no event was inserted, modified, or deleted after the fact — without trusting WalletSuite infrastructure. Logs are exportable in JSON format for ingestion into your SIEM, compliance tooling, or archival storage.
Data & encryption
Applies to both the REST API and MCP Server.
In transit
HTTPS enforced on all endpoints (localhost exempt for dev). Database connections require SSL.
At rest
OWS vault encrypted with AES-256-GCM. Database storage encrypted.
Key material
Never plaintext on disk, never transmitted over the network. Decrypted in-memory only during signing.
API authentication
API key required for all mutating endpoints. Rate limiting enforced per key.
Logging
Operation labels only — no URLs or wallet addresses in logs. Error messages never expose internal state.
Deployment
MCP Server — Self-hosted
Runs on your infrastructure. OWS vault keeps keys local — they never leave your network. Chain data is served by the WalletSuite API.
MCP Server — Hosted
Fully managed by WalletSuite. Same band filtering, same policy gates, same audit trail — without the infrastructure overhead.
The REST API is available independently for teams that manage their own signing. It returns unsigned transaction payloads across all supported chains.
Deployment documentation (opens in new tab)Compliance
Formal certifications are in progress. Today, WalletSuite’s security posture is built on non-custodial architecture, infrastructure-enforced governance, and a tamper-evident audit trail.
Responsible disclosure
If you discover a security vulnerability, please report it directly. Do not open a public GitHub issue.
We will:
We do not currently operate a bug bounty program.