Transactions

Transactions in Tholos follow a structured lifecycle with built-in governance. Every transaction requires creation, approval, signing, and broadcasting — with the specific flow depending on whether the vault is Standard or Flex.

Transaction types

Type	Description	Use case
Transfer	Send native tokens or ERC-20/SPL tokens	Payments, treasury movements
Message	Sign an arbitrary message	Off-chain signatures, authentication
Contract interaction	Call a smart contract function	DeFi, governance, staking
ERC-20 approve	Set a token spending allowance	DEX approvals, protocol interactions
Swap	Token swap via integrated DEX routing	Trading, rebalancing
Raw	Submit a pre-built raw transaction	Advanced or custom use cases

Transaction states

Every transaction moves through a defined state machine:

DRAFT → SUBMITTED → SUCCEEDED
                  → FAILED
                  → CANCELLED
                  → EXPIRED

State	Description
Draft	Transaction has been created but not yet submitted for approval
Submitted	Transaction is awaiting approval from vault signers
Succeeded	Transaction was signed, broadcast, and confirmed on-chain
Failed	Transaction failed during signing or broadcast
Cancelled	Transaction was explicitly rejected or cancelled
Expired	Transaction was not approved within the allowed time window

Lifecycle

Flex vault flow

1. Create — an Initiator (or higher role) creates a transaction
2. Approve — Signers review and approve or reject the transaction. A threshold number of approvals is required.
3. Sign — once the approval threshold is met, the server automatically signs using MPC
4. Broadcast — the signed transaction is broadcast to the blockchain network
5. Confirm — the transaction is confirmed on-chain and the state updates to Succeeded

Standard vault flow

1. Create — a vault member creates a transaction
2. Join signing ceremony — all signers connect to the MPC signing room
3. Sign — each signer contributes their key share to produce the signature via the MPC protocol
4. Broadcast — the signed transaction is broadcast to the blockchain network
5. Confirm — the transaction is confirmed on-chain

Note

Standard vaults require all signers to be online simultaneously for the signing ceremony. Flex vaults decouple approval from signing, allowing asynchronous workflows.

Policy evaluation

For Flex vaults, transactions are evaluated against active policies before they can be submitted. Policies can enforce rules like:

• Spending limits (per-transaction or cumulative)
• Allowed destination addresses (whitelist)
• Required cooldown periods between transactions
• Additional signer requirements for high-value transfers

Creating a transaction

# Transfer ETH
curl -X POST https://api.tholos.app/transaction/transfer \
  -H "Authorization: Bearer $THOLOS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vaultId": 123,
    "chain": "ethereum",
    "to": "0xRecipientAddress...",
    "amount": "1000000000000000000",
    "tokenAddress": null
  }'

See the Send a Transaction guide for a complete walkthrough.

Fee estimation

Before submitting a transaction, you can estimate the network fee:

curl -X POST https://api.tholos.app/transaction/estimate-fee \
  -H "Authorization: Bearer $THOLOS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vaultId": 123, "chain": "ethereum", "to": "0x...", "amount": "1000000000000000000"}'

Key API endpoints

Operation	Method	Endpoint
Create transfer	POST	/transaction/transfer
Create message signing	POST	/transaction/message
Create contract interaction	POST	/transaction/contract-interaction
Create ERC-20 approve	POST	/transaction/erc20-approve
Create swap	POST	/transaction/swap
Create raw transaction	POST	/transaction/raw
Get transaction	GET	/transaction/{id}
Approve transaction	POST	/transaction/{id}/approve
Reject transaction	POST	/transaction/{id}/reject
Estimate fee	POST	/transaction/estimate-fee
Get challenge	GET	/transaction/{id}/challenge