# Smart wallet multisig thresholds

Source: https://docs.settlemint.com/docs/developers/developer-guides/api-integration/smart-wallet-thresholds
Update and validate the approval threshold for a DALP smart wallet that uses weighted multisig signing.



Smart wallet thresholds define how much signer weight must approve a multisig
operation before the wallet can execute it. The threshold API changes that value
on an existing smart wallet with an installed weighted multisig validator. For
co-signer participation on pending operations, see [Smart wallet
approvals](/docs/developers/developer-guides/api-integration/smart-wallet-approvals).

The threshold is a weighted approval value, not a signer count. A smart wallet
with signer weights of `3`, `2`, and `1` can use threshold `4`, which means the
signer with weight `3` must approve with at least one other signer.

## Prerequisites [#prerequisites]

Before sending the update:

* Use credentials for the wallet owner. Co-signers approve pending operations
  through the multisig approval flow.
* Confirm the smart wallet has an installed weighted multisig validator.
* Read the wallet's signer configuration with
  `GET /api/v2/smart-wallets/{address}/signers`.
* Choose a threshold that can be met by the configured signer weights.

Request validation accepts `threshold` only when it is a decimal string from `1`
through `18446744073709551615` (`2^64-1`). A threshold that cannot be reached by
the configured signer weights is rejected by the wallet operation rather than by
initial request validation, so track the transaction result before retrying.

## Quickstart [#quickstart]

Submit the update with a wallet-owner credential:

```bash
curl -X PUT https://your-platform.example.com/api/v2/smart-wallets/0x1234567890AbcdEF1234567890aBcdef12345678/threshold \
  -H "X-Api-Key: YOUR_DALP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{
    "threshold": "4"
  }'
```

The endpoint submits an asynchronous blockchain mutation. Treat the response as
the start of an on-chain operation: persist the returned status information and
poll the status URL when the response includes one. If confirmation times out,
check transaction status before retrying the same threshold update.

Co-signers do not call this endpoint directly. They approve pending multisig
operations through the multisig approval flow.

## Endpoint reference [#endpoint-reference]

The threshold endpoint sets the multisig approval threshold for a smart wallet.

`PUT /api/v2/smart-wallets/{address}/threshold`

### Path parameters [#path-parameters]

| Parameter | Type             | Description                   |
| --------- | ---------------- | ----------------------------- |
| `address` | Ethereum address | Smart wallet contract address |

### Request body [#request-body]

| Field       | Type   | Required | Description                                                                                                                               |
| ----------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `threshold` | string | Yes      | Positive decimal integer string from `1` through `18446744073709551615`. Choose a value that can be met by the configured signer weights. |

### Authorisation [#authorisation]

Only the wallet owner can call this endpoint. Co-signers use the multisig
approval flow to approve operations that require their signature weight.

### Response [#response]

Threshold updates use the blockchain mutation response shape. Depending on the
request preference and execution timing, the API returns one of these responses:

| Shape                                | Fields                                 | Use it for                                                                                                                                          |
| ------------------------------------ | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Accepted for asynchronous processing | `transactionId`, `status`, `statusUrl` | Persist the transaction ID and poll `statusUrl` until the operation reaches a terminal state.                                                       |
| Completed mutation                   | `data`, `meta.txHashes`, `links`       | Persist the updated wallet data and transaction hashes. The same transaction hashes are also emitted through `X-Transaction-Hash` response headers. |

When you send `Prefer: respond-async`, the response includes a
`Preference-Applied` header for the accepted preference.

### Behaviour [#behaviour]

* The endpoint targets smart wallets with an installed weighted multisig
  validator.
* The platform submits the threshold change as an account-abstraction operation
  against the wallet's multisig validator.
* Synchronous request validation checks the smart wallet address, positive
  decimal-string format, and `uint64` bounds.
* The owner-only check runs before the blockchain mutation is submitted.
* A threshold that exceeds available signer weight is not a valid multisig
  configuration. Track that failure through the transaction status instead of
  expecting pre-submission rejection.

### Error cases [#error-cases]

| Case                          | What it means                                                                      | Next step                                                                                                             |
| ----------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Wallet cannot be resolved     | The platform cannot find the smart wallet for the caller's organization and chain. | Verify the address, chain context, and indexer state before retrying.                                                 |
| Caller is not the owner       | The authenticated participant is not allowed to change this setting.               | Use the owner credential, or have co-signers approve pending operations through the approval flow instead.            |
| Multisig validator is missing | The wallet does not have the weighted multisig validator installed.                | Install or use a wallet configured for weighted multisig before changing this value.                                  |
| Invalid threshold value       | The value is not a decimal string from `1` through `18446744073709551615`.         | Send a positive decimal string inside the supported range.                                                            |
| Transaction fails             | The mutation was accepted but the account-abstraction operation did not complete.  | Poll the status URL, inspect the terminal status, and only retry after confirming the prior operation will not apply. |

## Related operations [#related-operations]

* Use `GET /api/v2/smart-wallets/{address}/signers` to inspect signer weights
  before choosing a threshold.
* Use `GET /api/v2/smart-wallets/{address}/approvals` to list pending multisig
  approvals for a wallet.
* Use `POST /api/v2/smart-wallets/{address}/approvals/{userOpHash}/sign` when a
  co-signer needs to sign a pending approval.

## Related [#related]

* [Developer guides](/docs/developers/developer-guides)
* [Smart wallet approvals](/docs/developers/developer-guides/api-integration/smart-wallet-approvals)
* [Organization system scope](/docs/developers/developer-guides/api-integration/organization-system-scope)