Transaction Lifecycle

A transaction moves through up to four stages. Which stages an agent can reach is its execution level — the server-owned tool profile bound to the agent and the token scopes it holds. A tool outside that surface is never registered in the schema, so a lower-level agent cannot reach a higher stage.

Read stages touch no key. Every sign or broadcast intent clears the policy engine before any MPC share is released — a denied intent produces no signature, so it cannot be signed by anyone.

Stages

1. Query — R0 Read (`read`)

Check balances, prices, and fees before deciding to transact.

Tool	What It Returns
`get_balance`	Native token balance for one address on one chain
`get_all_balances`	All token balances with fiat valuations
`get_price`	Current market price for a token
`get_fee_quote`	Estimated network fee for a transfer
`resolve_asset`	Token contract address from a symbol or name
`get_tx_status`	Status of a submitted transaction
`get_tx_history`	Recent transactions for an address

No keys involved. No state modified.

2. Prepare — R1 Prepare (`prepare`)

Construct an unsigned transaction payload. The blockchain is not touched — this builds the data structure you or the agent will later sign.

Tool	Output	Use Case
`prepare_transfer`	Unsigned payload (nonce, fee params, calldata)	External BYO signing — you route the payload to your own signer
`prepare_serialized_unsigned_tx`	Signing-ready hex + human-readable review	Feed directly into `sign_transaction`
`prepare_onramp`	Fiat on-ramp widget URL	Fund a wallet with fiat

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 — R2 Execute (`execute` · `wallets:sign`)

Sign the prepared transaction. Signing runs through non-custodial MPC threshold signing — no full key ever assembled.

Tool	What It Does
`sign_transaction`	Takes unsigned tx hex, returns the signature
`get_wallet_address`	Resolves the wallet address for a chain

The policy engine is evaluated before any signature is produced. A denied intent is never signed. Signing is idempotent — signing the same payload produces the same signature.

4. Broadcast — R2 Execute (`execute` · `wallets:sign`)

Submit the signed transaction to the blockchain.

Tool	What It Does
`send_transaction`	Signs and broadcasts in one step, returns tx hash

Requirements:

confirmBroadcast: true — explicit confirmation
The agent holds the Execute level (wallets:sign scope) and the intent clears the policy engine

Once confirmed, a broadcast cannot be undone. After broadcast, use get_tx_status to monitor confirmation.

MPC Signing Flow

The end-to-end sequence that the Sign and Broadcast stages follow in a single MCP session:

get_fee_quote                    → estimate the cost
prepare_serialized_unsigned_tx   → build signing-ready hex + review
(Agent presents review to user, or auto-confirms within policy)
sign_transaction                 → policy clears, then MPC co-sign (WalletSuite share + customer share)
   OR
   send_transaction                 → policy clears, then MPC co-sign + broadcast
get_tx_status                    → confirm on-chain

The runtime is hosted — no signing infrastructure for your team to operate. Custody of the two shares is described in the trust model. 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
Hosted MCP runtime
  |
  |-- [1] prepare_serialized_unsigned_tx
  |         \-- build unsigned hex + human-readable review
  |
  |-- [2] send_transaction
  |         |-- Policy engine: evaluate intent (allow / deny)
  |         |-- On allow: MPC co-sign across two shares (no full key assembled)
  |         |-- Broadcast to chain
  |         \-- return tx hash
  |
  \-- [3] get_tx_status
            \-- return confirmed / pending / failed

Execution Levels

Which stages an agent can reach — tool profile plus token scopes.

Policy Gates

What the sign and broadcast stages are allowed to do.

Token Exchange

How scopes and tool profile reach the agent as a short-lived token.

Tool Reference

Full input/output schemas for every tool.

​Stages

​1. Query — R0 Read (read)

​2. Prepare — R1 Prepare (prepare)

​3. Sign — R2 Execute (execute · wallets:sign)

​4. Broadcast — R2 Execute (execute · wallets:sign)

​MPC Signing Flow

​Data Flow Diagram

​Related

Execution Levels

Policy Gates

Token Exchange

Tool Reference

Stages

1. Query — R0 Read (`read`)

2. Prepare — R1 Prepare (`prepare`)

3. Sign — R2 Execute (`execute` · `wallets:sign`)

4. Broadcast — R2 Execute (`execute` · `wallets:sign`)

MPC Signing Flow

Data Flow Diagram

Related