Weights sit with the signers, and the threshold rule sits inside the account.
A weighted Smart Wallet needs several signers to agree before it acts. Each signer holds a weight, and their combined weight must clear the account's own threshold whenever the weighted validator is the account's only authorisation path.
The weighted validator checks that threshold on chain, inside the account itself, not in a process beside it. Review every installed validator, since another one can authorise a different signing path. Fees stay separate from authority: the organisation's paymaster can pay the network fee for an instruction the account has already approved, so no signer has to hold funds for fees.
Reconfiguring the account is itself an instruction. With only the weighted validator installed, changing the signer set or the threshold has to clear the current threshold first, the same as any other call. The account's code is shared: the directory administrator can replace it for every account at once.
Why an account needs a rule of its own
A weighted Smart Wallet stops any signer whose weight is below the threshold from moving the account's assets alone. A tenant sets how many signers must agree and how much each one's approval counts for, and the account itself checks that agreement before anything executes. The rule for who may act, and how much weight they need, sits in the same account that holds the assets.
An ordinary account on a chain is a private key: whoever holds it can move everything the account holds, at any hour, with no second party in the room. Institutions answer that risk with maker-checker: a maker proposes and a checker authorises. That discipline usually lives in the process around the key, outside the account. A Smart Wallet moves the requirement inside the account: signers hold weights, and an instruction executes only when the weight behind it reaches the threshold.
The account contract holds the signer set and does the arithmetic itself, so no platform process can approve an instruction the signers did not. Adding a signer or lowering the threshold is an instruction that must clear the current threshold first, so the existing signers must agree to any widening. The account's code is the one part that sits outside the signers' control, as How it works and what it covers explains.
The account also separates the fee from the authority. The organisation's paymaster, funded from the organisation's deposit at the EntryPoint, can pay the network fee for an instruction the account has already authorised, so no signer's key has to hold the chain's native token. The paymaster gains no say over what executes. Gas sponsorship explains who pays on each network and how the organisation funds it.
Every operation across an asset's Asset Lifecycle, from issuance through servicing to redemption, reaches the chain as a transaction some account sent. A Smart Wallet is one way that account decides what counts as authorised, at every stage.
Why the check runs in the account
The alternative to a rule the account enforces is a rule enforced by whatever produces the account's signature. A managed custody provider or an internal approval process can require the same number of sign-offs before it releases a signature. That check runs off chain, in a system separate from the account, so the account has no way to confirm that every signature it later accepts passed through it. Whoever still holds a key the account accepts can produce a valid signature outside that process entirely.
A Smart Wallet closes that gap by moving the check onto the account itself. The threshold lives on the validator module the account installs, so the account counts the signing weight behind every instruction itself, before it executes anything, whichever key or provider produced each signature. Compliance rules, role grants, and the audit trail already name the account's address, and the threshold check runs at that same address, so there is no second system for those records to reconcile against.
Running a Smart Wallet day to day
Once a Smart Wallet is live, an operations team keeps its signer set current as people join and leave, and keeps the gas reserves funded. Without funded reserves, instructions never reach the chain.
You create the account with its signers and the threshold, either directly through the API, where every signer starts at weight 1, or by staffing it through Multisig's draft, invite, and finalise flow, where each seat carries its own weight. A configuration that could never execute anything is refused at creation: a repeated signer address, or a threshold higher than the sum of the weights.
The threshold trades control against convenience. A higher threshold needs more signers to agree before anything moves, including a change to the signer set itself, so it limits what one compromised signer can do, while requiring more signing weight to remain available. A lower threshold keeps things moving with fewer people, at the cost of concentrating effective control in whichever few signers reliably show up. A seat whose weight alone reaches the threshold can act alone. Give the signers whose sign-off is mandatory enough weight that nothing passes without them, and check which signer losses would stop the account reaching the threshold. A mandatory signer must also be available for any repair of the signer set.
Changing the set afterwards follows one rule: a change is an instruction like any other, so the account approves it at the threshold in force. Removing a signer therefore needs the remaining signers to agree, and a removal that would leave their weights short of the threshold is refused when you request it.
An instruction that arrives without enough weight waits as a pending approval. The account would refuse it, so the platform does not submit it. The other signers see the approval on the wallet's Approvals tab, under Shared accounts in the Console sidebar, and co-sign it before an expiry the platform sets from the deployment's approval deadline. Custody Approval, the pending-decision record that tracks each instruction until co-signers resolve it, covers that queue. On the API an approval reads pending while it collects weight and threshold-reached once the weight is met. It then reads submitted and ends as landed, rejected or expired.
Smart wallets, the Console's wallet type for this execution route, need two gas reserves, and each holds back different work when it runs short.
The submission reserve is the organisation's own bundler wallet. It pays to get any instruction on the chain and is always required: when it empties, instructions stall for every participant. Watch it with the bundler balance read, which reports that reserve's live native balance so a gas manager can fund it before it stalls anything.
The sponsorship reserve is the organisation's paymaster deposit, the funds the organisation keeps at the EntryPoint to pay for sponsored operations. It matters only on a network whose gas payer is Paymaster-paid. When it runs short, sponsored instructions wait for a top-up, and they fail with the gas required error if the network's funding window, the time a paused write waits for funds, closes first. A sponsored instruction does not fall back to paying from the account's own balance. Runway is the signal for this reserve: the platform adds the paymaster, bundler and refund splitter balances and divides the total by the bundler's average daily gas cost over the last seven days, and the Console shows the result in days. How gas is paid and funded covers both reserves.
An instruction clears the account's own weight check first, then the fee question decides who pays, and can still block execution if no payer is available.
How it works and what it covers
A Smart Wallet is a contract account under ERC-4337, the account-abstraction standard. Instructions reach it as signed intents, UserOperation objects that hold a signature, rather than raw transactions. A shared entry-point contract validates each intent and then calls the account to execute it, and the platform's bundler, the off-chain service that batches many participants' intents into one on-chain submission, submits those batches to that entry point. The smart wallet user operations guide lists the REST and JSON-RPC routes that send and track those intents.
The account is modular, following ERC-7579, the modular-account standard. Validation is not compiled into the account: it is a module the account installs. A single-signer account installs a plain signature validator. A weighted account installs a validator that stores each signer's weight and the threshold and compares the collected weight against it. An account can hold up to sixteen validators at once, and cannot be left with none.
Each account is a light proxy that reads its code from the platform directory, the on-chain registry of DALP implementations, on every call. The accounts share that code and none of their state. The directory administrator upgrades every account at once by pointing the directory at a new implementation. No account's signers can choose or refuse that upgrade, and no account can upgrade itself.
An account created with an on-chain identity also gets a recovery module with the platform guardian as its only guardian, at a 72-hour delay. The platform guardian is an address the deployment names when it sets up the account factory. On a single-owner account the guardian can name a replacement owner key, and the replacement takes effect 72 hours later unless the current owner cancels it first. A weighted validator records no single owner, so guardian recovery cannot change a weighted account's signers. The set-guardians and cancel-recovery changes clear the threshold like any other.
The weighted validator answers “may this actor manage this account directly” with no, always, for every actor. Adding a signer, removing one, or moving the threshold therefore has to arrive as an instruction the account validates like any other, which means through the threshold. That restriction holds only when another installed validator does not authorise direct management.
Whether a participant's writes leave from their own key or from their Smart Wallet is an organisation-level setting, not a per-request choice. Flipping it changes which address the chain sees as the actor, so on-chain state written for a participant, such as identity registrations and role grants, follows the address that wrote it. A participant created as key-only, or as account-only, keeps its own route either way. The setting governs the rest.
The integration contract
On the API, a Smart Wallet is one object with its address, its installed validators, its signers and their weights, and its threshold. You create the account once, read it from the indexed record, and change its signer set and threshold through separate queued writes.
Creation through the API takes the participant, the network, the signer addresses and the threshold. Every signer joins at weight 1, so the threshold must lie between 1 and the number of signers. The request is rejected before anything starts when an address repeats or is not a valid EVM address, when the threshold cannot be reached, or when the participant holds no active custody account on that network. A participant with no Smart Wallet address recorded on that network, which is the case in an organisation that does not route writes through Smart Wallets, is refused with 404 before anything starts. On a deployment with the Self-custody module switched off, more than one signer or a threshold higher than 1 is refused with 403 MULTISIG_NOT_ENABLED. When only the organisation has switched the module off, the same request is refused with 403 platform.module.DISABLED, which names the module in data.module. The participant's custody account on that network carries at most one Smart Wallet, and a create completes the one already recorded there: it links that wallet to the custody account and changes no signer. A signer set or threshold the recorded wallet does not already hold is refused with 409 CUSTODY_ before anything starts. Change signers through signer management instead. The platform records the signer set and threshold of the first create call it accepts for that participant and network. A later call that repeats them, in any order or letter case, returns the same request, and a call that names a different signer set or threshold is refused with 409 CUSTODY_, whether the first wallet is still being created or already exists. A signer set with different weights comes from the Multisig draft flow, where each seat carries its own weight.
Creation is a queued write, not a synchronous one. The response carries a request identifier and the status accepted, which tells you the platform took the request, not that the account exists. Follow the request at GET /api/. While the account is being created, it answers 202 with state: "running" and a statusUrl, which is also sent as Location. Once the account exists, it answers 200 with the Smart Wallet, as the wallet read does. A creation that ended without an account answers 409 CUSTODY_. Only the participant that made the request can read it, and only a caller who holds the account or a weighted seat on it gets the 200.
Reads split into two kinds, and the difference decides what you may conclude. The account, its signers and its approvals come from the indexed record and never query the chain, so a change you queued a moment ago is absent there until it is indexed. The gas-status read combines the account's indexed native balance with the network's live gas price, and answers empty for a zero balance, low for a balance below the cost of 500,000 gas at the current maximum fee, or funded. It returns no amount and says nothing about sponsorship. Only a caller who holds the account or a weighted seat on it can read it.
A signer added after creation joins at weight 1, and a signer removed and then re-added returns at weight 1. A separate set-signer-weight change gives it another weight, and like every change to the account it has to clear the current threshold. The account's mutation route takes add-signer, remove-signer, set-threshold, set-signer-weight, install-module, uninstall-module, set-guardians and cancel-recovery changes. The API reference lists the exact routes.
Controls and evidence
A Smart Wallet is a preventive control at the point of execution. The account validates the collected signer weight before it does anything, so an instruction below the threshold is refused before it executes. The enforcement point is the account contract itself, on chain.
The signer set, the weights and the threshold are on-chain state, and the check runs where the assets are. No signer and no other account can widen the control, provided the weighted validator is the only validator installed. The directory administrator's implementation upgrade is the one change that does not pass through the threshold. The account grants direct access to any actor that any one of its installed validators authorises, so a single-signer validator left in place beside the weighted one would hand its own recorded owner that same direct path. With only the weighted validator installed, it refuses direct management outright, so a change to the signer set, to the threshold, or to which validators are installed, has to clear the threshold in force first. The same fence covers identity claims made on the account, which must arrive through the account rather than from one signer acting alone.
Attribution is the second control the account provides. The party on chain is the account, whichever signer's key produced a signature, so transfer restrictions, role checks and the audit trail all name one address you already govern.
Evidence has two halves. On chain: the signer set, the weights, the threshold, and each amendment to them, with the transaction that made it. On the platform: each pending approval with the weight it required, the weight it collected, and every collected signature with its signer, its weight and its time.
A Smart Wallet is not transfer compliance. The threshold check runs first, during validation. The asset's own rules run later, inside the transfer, and the asset contract enforces them, so a fully approved instruction can still be rejected there. Transfer-Path Compliance is that separate control.
Frequently asked questions
How is this different from a multi-signature vault?
No separate vault contract holds assets on behalf of an account. The account itself is the multi-signature arrangement: assets sit in it directly, and the threshold applies to everything it does, not only to withdrawals from a special-purpose contract. That also means there is no second address to reconcile and no bridge step between the account you configure and the account that holds the assets. See Multisig for how a weighted account like this one gets staffed, through a draft, invites, and one finalise step.
What happens if a signer loses their key?
The remaining signers remove that signer and add a replacement, which is an instruction like any other, so it needs their combined weight to reach the threshold. If the lost signer's weight was necessary to reach the threshold, the remaining signers cannot pass any instruction at all, including the one that would repair the signer set. Guardian recovery cannot help a weighted account either, because it replaces the owner of a single-owner validator and a weighted validator has none. Plan for this when you set the weights: give the account enough signers that no single lost key blocks the threshold.
Can the fee sponsor change or block what I do?
The sponsor cannot change it. A sponsorship ticket, the authorisation the paymaster checks, names the account and a hash of the exact call it covers, together with a deadline and a fee ceiling. Changing one argument puts the instruction outside the authorisation, and a fee above the ceiling falls outside it too. On a Paymaster-paid network, an instruction the paymaster cannot sponsor fails as blocked by policy, and the account does not pay the fee for it instead. The platform decides whether to issue a ticket, so a signer whose account holds no native balance depends on the organisation's sponsorship being funded and on. An instruction that waits on an unfunded sponsorship reserve resumes once the reserve is topped up within the network's funding window.
Can an organisation switch back from smart wallets to key wallets?
Smart wallets is the Console's wallet type for routing an organisation's on-chain work through Smart Wallets and the sponsored-fee path instead of through participants' own keys. The setting is organisation-wide and one-way: once it is on, the platform does not accept turning it off. On-chain state written for a participant, such as identity registrations and role grants, follows the address that wrote it, so switching back would strand what was already written from the account.
Can a weighted account also keep the single-signer validator installed?
Yes, but doing so reopens the direct-management path the weighted validator closes: the account authorises any actor that any one of its validators authorises, as covered under Controls and evidence. Remove the single-signer validator once the weighted one is in place, or never install one, if the threshold should be the only way in.