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 exposureSecurity diligence
Most SOC 2 Type II controls ask one question: can an employee access customer data? In self-hosted deployments, the answer isn’t “no” — it’s “there is no customer data on our systems.” Keys, signed transactions, and the audit trail live on your infrastructure, not ours. That’s a categorical guarantee, not a policy promise.
Employee access
No WalletSuite employee can access your keys, signed transactions, or audit trail in self-hosted deployments. This isn’t a policy — it’s architectural. Keys live in the OWS vault on your infrastructure; signing happens on your infrastructure; the audit trail is written to your disk. We never see any of it.
Prompt injection as a threat model
Band filtering is a prompt-injection defense, not just access control. Tools outside the configured band are never registered with the MCP client. An agent compromised by a malicious prompt cannot call what it cannot see — it can’t invent a tool to broadcast a transaction if broadcast is outside its band.
What else to verify
Trust boundary diagram: §01. Threat scenarios: §01. Audit trail mechanics: §05. Build hygiene: §07. Full enforcement mechanics and build pipeline in the security documentation (opens in new tab).
Band 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
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.
Ship with security built in
Policy-gated signing, band filtering, and audit trails — ready in under 15 minutes.