Skip to main content
WalletSuite MCP is designed to be useful without taking custody of your keys or exposing more capability than necessary. In wallets, the core trust question is who controls the keys. With WalletSuite MCP, the user controls the keys through the local OWS vault.
WalletSuite MCP is non-custodial. We never hold your keys or funds. Signing happens locally via OWS with policy controls.

​
Trust model

WalletSuite MCP keeps the orchestration core private and replaces source-code visibility with three explicit architectural guarantees: Non-custodial by design. The server never stores or transmits private keys. A fresh install uses only the WalletSuite API key — no local signing, no broadcast. Enabling OWS keeps keys in an encrypted vault on the host you control; signing stays under user or policy control. Architecture transparency. The prepare → sign → broadcast flow is publicly documented. Responsibilities between WalletSuite MCP, the WalletSuite API, OWS, and the caller are explicit. Policy boundaries for signing are stated in Policy Gates. Minimal public surface. WalletSuite exposes the npm package, Docker image, MCP tool interfaces, and these docs. Internal orchestration details that aren’t required for safe integration are not disclosed.

​
How signing works

WalletSuite MCP separates transaction preparation from signing: 
User or AI host -> WalletSuite MCP -> prepare transaction
User or AI host -> OWS on the operator's host -> sign locally
Signed transaction -> chain RPC -> broadcast
WalletSuite MCP prepares and orchestrates. OWS performs local signing. Wallet keys remain on the host that runs OWS — your infrastructure, never WalletSuite’s.

​
Separation of responsibilities

ComponentResponsibility
WalletSuite MCPMCP orchestration and tool exposure
WalletSuite APIwallet data, prices, balances, and transfer preparation
OWSlocal key storage and local signing
User or policy ownerfinal approval of sensitive actions

​
Policy-based signing

OWS adds the signing control layer. In owner mode:
  • the user controls signing directly through the local vault passphrase
  • wallet creation is available
In agent mode:
  • signing uses a pre-created scoped OWS token
  • the current default WalletSuite MCP policy limits signing to the allowed chains in that wallet policy and an expiry window
  • policy denial blocks the signing request before the key is used
This means WalletSuite MCP can prepare and route requests, but the final signing boundary still sits inside OWS.

​
What WalletSuite does not do

WalletSuite does not:
  • store private keys
  • custody funds
  • sign transactions on your behalf
  • move funds without an enabled signing path and explicit approval

​
Attack model

If WalletSuite MCP is misconfigured or compromised on its own:
  • an attacker still does not get your private keys
  • an attacker still cannot sign transactions unless local OWS signing is enabled and reachable
  • an attacker still cannot broadcast through send_transaction unless the broadcast band is enabled, the RPC URL is configured, and the request is explicitly confirmed
This matters because the trust boundary is not “the server is perfect.” The trust boundary is that key custody and signing stay local.

​
What WalletSuite does not control

WalletSuite does not control:
  • the contents of your local OWS vault
  • the approval decision to sign when OWS is configured for local signing
  • the host where the vault, environment variables, and MCP server run
Those boundaries stay with the user or operator.

​
What risks still exist

Non-custodial does not mean zero risk. Important remaining risks are:
  • enabling broader bands than you need
  • approving or automating a transaction you did not inspect carefully
  • running on a compromised host
  • leaking environment secrets such as API keys, passphrases, or agent tokens
The mitigation is to keep bands narrow, use OWS deliberately, scope agent tokens, and review destructive actions carefully.

​
Bands control tool exposure

WalletSuite MCP exposes tools through bands:
BandWhat it allows
readbalances, prices, fee quotes, asset resolution, transaction status and history
preparetransaction-preparation tools
signlocal wallet lookup and detached signing through OWS
broadcastlocal sign-and-send through OWS
The default is read. This matters because the best security control for AI tooling is often not a runtime warning. It is not exposing a more powerful tool in the first place.

​
Why the default should stay narrow

Read-only tools answer many wallet questions without creating transfer payloads or exposing any signing surface. A safe rollout pattern is:
  1. start with read
  2. move to read,prepare only when you need transaction preparation
  3. add sign only when you are ready to manage a local OWS wallet
  4. add broadcast only when you are ready to execute on-chain actions

​
Detached signing vs local broadcast

sign_transaction and send_transaction are intentionally separate.

​
sign_transaction

Use this when you want detached signing of raw unsigned transaction hex. This is still sensitive, but it does not submit anything on-chain by itself.

​
send_transaction

Use this only for explicit user-approved broadcasts. send_transaction is the destructive path because it signs and broadcasts the transaction. WalletSuite MCP requires:
  • the broadcast band
  • confirmBroadcast=true
  • the matching RPC URL for the selected chain

​
Secrets stay out of tool arguments

Sensitive values are supplied through environment variables, not through tool arguments. Examples:
  • WALLETSUITE_API_KEY
  • OWS_PASSPHRASE
  • OWS_AGENT_TOKEN
  • OWS_ETHEREUM_RPC_URL
  • OWS_TRON_RPC_URL
This keeps secrets out of normal user prompts and out of tool argument history.

​
Local signing boundaries

When OWS is enabled:
  • keys stay local
  • signing happens inside OWS
  • the MCP tool surface only receives wallet names, chain ids, and raw unsigned transaction hex where applicable
WalletSuite MCP does not expose mnemonics or private keys through the tool responses.

​
Verifiable audit trail

Every sign_transaction and send_transaction call appends a structured JSON receipt to a local log file at ~/.walletsuite/audit-trail.jsonl (override with WALLETSUITE_AUDIT_PATH). Receipts are linked by a SHA-256 hash chain: each entry records the previous entry’s hash, so tampering with any line invalidates every line after it. Secrets are redacted before write (API keys, mnemonics, bearer tokens) and transaction hex is truncated. The audit trail is local by default — it stays on the host that runs the MCP server, under operator control, and can be shipped to a SIEM or archived on a schedule. See Audit Trail for the full receipt schema, hash-chain verification, and SIEM integration guidance.

​
Why WalletSuite MCP is closed-source

WalletSuite MCP is distributed as a product surface through the published npm package and Docker image, while the core implementation remains private. Trust comes from:
  • non-custodial architecture
  • local signing boundaries
  • explicit capability controls through bands and OWS modes
  • clear operational documentation
Closed source does not change the custody model: WalletSuite still does not hold your keys.

​
Practical guidance

Use these defaults unless you have a reason not to:
  • MCP_BANDS=read for a new install
  • no OWS on day one
  • no broadcast until the local signing flow is proven
If you need more capability later, add it deliberately instead of enabling the entire surface at once.