Skip to main content
A transaction moves through up to 4 stages, each controlled by a different band. You only need the stages your integration requires — most use cases need only the first two.

​
Stages

​
1. Query (read band)

Check balances, prices, and fees before deciding to transact.
ToolWhat It Returns
get_balanceNative token balance for one address on one chain
get_all_balancesAll token balances with fiat valuations
get_priceCurrent market price for a token
get_fee_quoteEstimated network fee for a transfer
resolve_assetToken contract address from a symbol or name
get_tx_statusStatus of a submitted transaction
get_tx_historyRecent transactions for an address
No keys involved. No state modified.

​
2. Prepare (prepare band)

Construct an unsigned transaction payload. The blockchain is not touched — this builds the data structure you or the agent will later sign.
ToolOutputUse Case
prepare_transferUnsigned payload (nonce, fee params, calldata)External signing — you sign with your own wallet
prepare_serialized_unsigned_txSigning-ready hex + human-readable reviewOWS signing — feed directly into sign_transaction
prepare_onrampMoonPay widget URLFiat on-ramp to fund a wallet
Token transfers are two-step: First call resolve_asset to get the token contract address, then call the prepare tool with that contract. WalletSuite does not guess token contracts from symbols. Amount handling: Provide either amount (human-readable, e.g., "1.5") or amountWei (smallest units, e.g., "1500000000000000000"). Never both — the server rejects ambiguous input.

​
3. Sign (sign band, OWS only)

Sign the prepared transaction locally using the OWS vault. Requires OWS_ENABLED=true.
ToolWhat It Does
sign_transactionTakes unsigned tx hex, returns signature + recovery ID
get_wallet_addressResolves the local wallet address for a chain
Keys stay in the OWS vault. The MCP server never sees private key material. Policy gates are evaluated before any key is touched. Signing is idempotent — signing the same payload produces the same signature.

​
4. Broadcast (broadcast band, OWS only)

Submit the signed transaction to the blockchain. Once confirmed it cannot be undone.
ToolWhat It Does
send_transactionSigns and broadcasts in one step, returns tx hash
Requirements:
  • confirmBroadcast: true (explicit confirmation)
  • Matching RPC URL configured (OWS_ETHEREUM_RPC_URL or OWS_TRON_RPC_URL)
  • Broadcast band enabled (MCP_BANDS=full)
After broadcast, use get_tx_status to monitor confirmation.

​
External Signing Flow

If you manage your own keys (no OWS): 
1. get_fee_quote        → estimate the cost
2. prepare_transfer     → build unsigned payload
3. Your wallet signs    → (outside WalletSuite)
4. Your infra broadcasts → (outside WalletSuite, or via WalletSuite API)
Use MCP_BANDS=read,prepare. No OWS needed.

​
OWS Local Signing Flow

If you use OWS for end-to-end local signing: 
1. get_fee_quote                    → estimate the cost
2. prepare_serialized_unsigned_tx   → build signing-ready hex + review
3. (Agent presents review to user)
4. sign_transaction                 → OWS signs locally
   OR
   send_transaction                 → OWS signs + broadcasts
5. get_tx_status                    → confirm on-chain
The full flow stays within the MCP session. No browser extension, no QR code, no external wallet. Example conversation: 
User: "Send 1 ETH to 0xdef"

Agent: Prepares the transfer, shows review:
  "Send 1.0 ETH to 0xdef... Estimated fee: 0.002 ETH ($5.40)"

User: "Confirm"

Agent: Signs and broadcasts via send_transaction
  "Sent 1 ETH to 0xdef. Tx: 0xabc... confirmed in block 19234567."

​
Data Flow Diagram

User intent ("Send 1 ETH to 0xdef")
  |
  v
MCP Server
  |
  |-- [1] prepare_serialized_unsigned_tx
  |         |-- POST /api/txs/prepare-sign (backend)
  |         \-- tx-compiler -> unsigned hex + review
  |
  |-- [2] send_transaction
  |         |-- OWS: evaluate policy
  |         |-- OWS: decrypt key, sign, wipe key
  |         |-- OWS: broadcast to chain RPC
  |         \-- return tx hash
  |
  \-- [3] get_tx_status
            |-- GET /api/txs/status/{hash} (backend)
            \-- return confirmed / pending / failed