Skip to main content
PATCH
/
api
/
v1
/
smart-accounts
/
{smart_account_address}
Update smart account settings
curl --request PATCH \
  --url https://developer-api.squads.so/api/v1/smart-accounts/{smart_account_address} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-squads-network: <x-squads-network>' \
  --data '
{
  "smart_account_signers": [
    {
      "address": "<string>",
      "permissions": [
        "CAN_INITIATE"
      ]
    }
  ],
  "threshold": 123,
  "admin_address": "<string>",
  "transaction_signers": [
    "<string>"
  ],
  "fee_config": {
    "currency": "<string>",
    "payer_address": "<string>",
    "self_managed_fees": false
  }
}
'
{
  "transaction": "<string>",
  "fee": {
    "amount": "<string>",
    "amount_decimal": "<string>",
    "currency": "<string>",
    "sol_equivalent": {
      "amount": "<string>",
      "amount_decimal": "<string>"
    }
  }
}
Update the configuration of an existing Smart Account, including signers, threshold, and optional settings.

​
Key Concepts

  • Partial Updates: Only specify the fields you want to modify
  • Transaction Signing: Changes require signatures from current authorized signers or the admin address
  • Validation Rules: Updates must maintain valid signer and threshold requirements

​
Update Modes

​
Standard Mode

In standard mode (without admin), updates require:
  • Meeting the current threshold requirement
  • Multiple signers can approve the transaction
  • When updating smart_account_signers, you must provide the complete desired state
  • To unset a field, set it to an empty string "" or 0
Example request: 
PATCH /api/v1/smart-accounts/{address}
{
  "smart_account_signers": [
    {
      "address": "existing1...",
      "permissions": ["CAN_INITIATE", "CAN_VOTE", "CAN_EXECUTE"]
    },
    {
      "address": "existing2...",
      "permissions": ["CAN_VOTE", "CAN_EXECUTE"]
    },
    {
      "address": "new_signer...",
      "permissions": ["CAN_VOTE", "CAN_EXECUTE"]
    }
  ],
  "threshold": 2,
  "transaction_signers": ["current1...", "current2..."]
}

​
Admin Mode

When a smart account has an admin address set, only that address can modify settings using admin mode:
  • Must use the admin=true query parameter
  • Only the admin address should be in transaction_signers
Example admin request: 
PATCH /api/v1/smart-accounts/{address}?admin=true
{
  "smart_account_signers": [
    {
      "address": "signer1...",
      "permissions": ["CAN_INITIATE", "CAN_VOTE", "CAN_EXECUTE"]
    },
    {
      "address": "signer2...",
      "permissions": ["CAN_VOTE", "CAN_EXECUTE"]
    }
  ],
  "threshold": 2,
  "transaction_signers": ["admin_address"] // Must be only the admin address
}

​
Understanding Updates

​
Modifying Fields

  • Adding/Updating Fields: Include the field with its new value
  • Removing Optional Fields: Set the field value to "" or 0 to remove it
  • Required Fields: Cannot be set to "" or 0 (will return validation error)
Example removing admin_address: 
{
  "admin_address": ""
}
Only the admin address can remove the admin address.

​
Validation Rules

​
Signer Configuration

  1. Must always maintain:
    • At least one signer with CAN_INITIATE permission
    • Enough signers with CAN_VOTE permission to meet threshold
    • At least one signer with CAN_EXECUTE permission
  2. Invalid configurations: 
{
  "smart_account_signers": [
    // ❌ Missing CAN_INITIATE permission
    {
      "address": "signer1...",
      "permissions": ["CAN_VOTE", "CAN_EXECUTE"]
    }
  ]
}

​
Threshold Requirements

  • Must be greater than 0
  • Must not exceed number of signers with CAN_VOTE permission
  • Changes require meeting current threshold for signing

​
Admin Mode Requirements

  • Only admin address can be in transaction_signers
  • Must use admin=true query parameter
  • Updates are atomic - all succeed or all fail

​
Important Notes

  • Changes only take effect after transaction settlement
  • Required fields cannot be removed:
    • smart_account_signers (must maintain minimum permissions)
    • threshold (must be > 0)
  • Admin can remove itself by setting admin_address to ""

​
Fee Configuration

The fee_config object controls how transaction fees are paid:
  • When self_managed_fees is true: The payer_address becomes both the rent payer and transaction fee payer. The currency field is ignored.
  • When self_managed_fees is false or not set: Uses gas abstraction with the specified currency (sol, usdc, or usdt) and payer_address.

Authorizations

​
Authorization
string
header
required

UUID-based API key provided by Squads

Headers

​
x-squads-network
enum<string>
required

Specifies the network for the API request

Available options:
mainnet,
devnet

Path Parameters

​
smart_account_address
string
required

The address of the smart account

Query Parameters

​
admin
boolean

When true, indicates that the update is being performed by the smart account admin (configured in the admin_address field)

Body

application/json
​
smart_account_signers
object[]

List of signers and their permissions. At least one signer must have CAN_INITIATE permission.

​
threshold
integer<uint32>

Number of CAN_VOTE signatures required for transaction approval. Must not exceed the number of signers with CAN_VOTE permission.

​
admin_address
string

Admin address. When set, only this address can modify account settings using the admin query parameter.

​
transaction_signers
string[]

List of signers for this update transaction. In admin mode, this must contain only the admin address. In normal mode, must meet the account's threshold requirement.

​
fee_config
object

Response

Smart account updated successfully

​
transaction
string
​
fee
object