> ## Documentation Index
> Fetch the complete documentation index at: https://docs.walletsuite.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Transaction Lifecycle
> End-to-end flow from intent to broadcast — query, prepare, sign, send.
A transaction moves through up to four stages. Which stages an agent can reach is its [execution level](/ai-agents/execution-levels) — 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](/core-concepts/policy-gates) before any [MPC share](/security/overview#trust-model) 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](/security/overview#trust-model) — 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](/core-concepts/policy-gates) 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](/core-concepts/policy-gates)
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:
```
1. get_fee_quote → estimate the cost
2. prepare_serialized_unsigned_tx → build signing-ready hex + review
3. (Agent presents review to user, or auto-confirms within policy)
4. sign_transaction → policy clears, then MPC co-sign (WalletSuite share + customer share)
OR
send_transaction → policy clears, then MPC co-sign + broadcast
5. 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](/security/overview#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
```
## Related
Which stages an agent can reach — tool profile plus token scopes.
What the sign and broadcast stages are allowed to do.
How scopes and tool profile reach the agent as a short-lived token.
Full input/output schemas for every tool.