Smart contract account (SCA) upgrades

When Circle releases a newer version of the SCA contract, you can upgrade existing wallets to pick up bug fixes and product improvements. The wallet’s address and assets stay the same across an upgrade. You initiate every upgrade yourself. Circle never upgrades wallets on your behalf. MSCA wallets have a single implementation and can’t be upgraded.

Supported migration paths

Source version	Destination version	Contract function
`circle_4337_v1`	`circle_6900_singleowner_v2`	`upgradeToAndCall(address,bytes)`
`circle_6900_singleowner_v1`	`circle_6900_singleowner_v2`	`upgradeTo(address)`

Upgrade an SCA wallet

If your wallet is on circle_4337_v1, complete the prerequisites before upgrading.

Call the endpoint that matches your wallet product:

Developer-controlled: POST /developer/transactions/walletUpgrade
User-controlled: POST /user/transactions/walletUpgrade, then follow the standard challenge approval flow. Identify the wallet with either walletId or walletAddress plus blockchain.

Filter GET /wallets by the scaCore query parameter to list SCA wallets eligible for an upgrade.

The upgrade appears in Circle Console and the transaction APIs as a contract execution transaction. When it reaches COMPLETE, the wallet’s SCA version updates in the responses from GET /wallets/{id} and GET /wallets. Your wallet remains usable during the upgrade transaction.

Prerequisites for `circle_4337_v1`

circle_4337_v1 wallets require these prerequisites before the upgrade endpoint succeeds.

Lazy-deploy the wallet

circle_4337_v1 wallets must be deployed onchain before an upgrade can run. To trigger deployment, initiate any outbound transaction (transfer or contract execution) from the wallet. See account types for background on SCA lazy deployment.

Fund the owner address on testnet

On testnet, fund the wallet’s owner address with native token before the upgrade transaction runs. On mainnet, circle_4337_v1 wallets already received an airdrop that covers the upgrade fee, so you can skip this step.Fetch the owner address using POST /contracts/query:

response = await client.queryContract({
  abiFunctionSignature: "owner()",
  address: "<circle_4337_v1-sca-wallet-address>",
  blockchain: "<wallet-blockchain>",
  abiJson:
    '[{"inputs": [],"name": "owner","outputs": [{"internalType": "address","name": "","type": "address"}],"stateMutability": "view","type": "function"}]',
});

api_instance = smart_contract_platform.InteractApi(scpClient)
try:
    request = smart_contract_platform.ReadContractStateRequest.from_dict({
        "abiFunctionSignature": "owner()",
        "address": "<circle_4337_v1-sca-wallet-address>",
        "blockchain": "<wallet-blockchain>",
        "abiJson": "[{\"inputs\": [],\"name\": \"owner\",\"outputs\": [{\"internalType\": \"address\",\"name\": \"\",\"type\": \"address\"}],\"stateMutability\": \"view\",\"type\": \"function\"}]"
    })
    response = api_instance.query_contract(request)
except smart_contract_platform.ApiException as e:
    print("Exception when calling InteractApi->read_contract: %s\n" % e)

curl --request POST \
  --url https://api.circle.com/v1/w3s/contracts/query \
  --header "Authorization: Bearer $API_KEY" \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
      "abiFunctionSignature": "owner()",
      "address": "<circle_4337_v1-sca-wallet-address>",
      "blockchain": "<wallet-blockchain>",
      "abiJson": "[{\"inputs\": [],\"name\": \"owner\",\"outputs\": [{\"internalType\": \"address\",\"name\": \"\",\"type\": \"address\"}],\"stateMutability\": \"view\",\"type\": \"function\"}]"
    }'

Response:

Response body

{
  "data": {
    "outputData": "0x...",
    "outputValues": ["<owner-address>"]
  }
}

The first entry in outputValues is the owner address. Send it enough native token to cover roughly 300,000 gas. Approximate costs:

ETH-SEPOLIA: 300,000 gas × 30 Gwei ≈ 0.009 ETH
MATIC-AMOY: 300,000 gas × 150 Gwei ≈ 0.045 POL

Contract versions

Use the factory and implementation addresses to verify onchain deployments. Addresses are the same on mainnet and testnet.

Type	Version	Description	Factory address	Implementation address
SCA	`circle_6900_singleowner_v3`	ERC-6900 v0.7, ERC-4337 v0.6. Single owner address; supports batching multiple user operations in one transaction.	`0xf61023061ed45fa9eAC4D2670649cE1FD37ce536`	`0xD206aC7fEf53d83ED4563E770b28Dba90D0D9eC8`
MSCA	`circle_6900_v1`	ERC-6900 v0.7, ERC-4337 v0.7. Any ownership type (single owner, multiple owners, passkeys, multisig); supports batching multiple user operations in one transaction.	`0x0000000DF7E6c9Dc387cAFc5eCBfa6c3a6179AdD`	`0xA70F1296869DA9D7CB69578123F21888E6dB2B62`

Because MSCA wallets are proxy contracts, block explorers display the wallet address’s contract name as ERC1967Proxy rather than UpgradeableMSCA.

How upgrades work

SCA and MSCA wallets use the ERC-1967 proxy pattern. The proxy contract at your wallet address delegates calls to a separate implementation contract that holds the actual logic. An upgrade points the proxy at a new implementation address, which is why the wallet address stays the same. The upgrade endpoint executes one of these functions on the proxy:

upgradeTo(address)
upgradeToAndCall(address,bytes)

Wallets

Gas fees

Compliance

Contracts

Smart contract account (SCA) upgrades

Supported migration paths

Upgrade an SCA wallet

Prerequisites for `circle_4337_v1`

Contract versions

How upgrades work

​Supported migration paths

​Upgrade an SCA wallet

​Prerequisites for circle_4337_v1

​Contract versions

​How upgrades work

Supported migration paths

Upgrade an SCA wallet

Prerequisites for `circle_4337_v1`

Contract versions

How upgrades work