> ## Documentation Index
> Fetch the complete documentation index at: https://docs.biconomy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade Legacy Account

> Generate an upgrade quote for accounts with v2.1.0 deployments

The `/v1/mee/upgrade` endpoint generates an upgrade quote for Nexus accounts running v2.1.0 implementation. Execute the returned quote via `/v1/execute` to upgrade the account to v2.2.1 while preserving the original address.

## Endpoint

```
POST https://api.biconomy.io/v1/mee/upgrade
```

## When to Use

<Info>
  Use this endpoint only for users with **existing v2.1.0 deployments** that need upgrading. New users automatically get v2.2.1 accounts.
</Info>

<Tip>
  **For legacy EOA (Fusion) mode users**, upgrade is optional. In EOA mode, Nexus acts as a pass-through only, so there are typically no funds remaining in the old Nexus account.

  You have two options:

  1. **Rescue dust (optional)**: If users have small residual funds in their old Nexus and you want to help them recover these, build a separate rescue flow that uses address override to upgrade the old Nexus and sweep funds back to their EOA. After rescue, users should proceed with the default v2.2.1 account.

  2. **Ignore dust**: Simply use the normal flow without any special handling—it will automatically default to the latest v2.2.1 Nexus.
</Tip>

The upgrade flow is:

1. Check account status via [/v1/mee/orchestrator](/supertransaction-api/endpoints/orchestrator) to identify accounts needing upgrade
2. Generate an upgrade quote via this endpoint
3. Sign and execute the quote via [/v1/execute](/supertransaction-api/endpoints/execute)
4. Use the legacy address with `accountAddress` parameter in future [/v1/quote](/supertransaction-api/endpoints/quote) requests

## Request Structure

### Request Body

| Parameter      | Type      | Required | Description                                                         |
| -------------- | --------- | -------- | ------------------------------------------------------------------- |
| `ownerAddress` | string    | Yes      | EOA wallet address                                                  |
| `mode`         | string    | Yes      | Execution mode: `eoa` or `smart-account` (not `eoa-7702`)           |
| `chainIds`     | number\[] | Yes      | Chain IDs where accounts should be upgraded                         |
| `feeToken`     | object    | No       | Token for gas payment. If not specified, uses sponsorship (gasless) |
| `simulate`     | boolean   | No       | Simulate before execution (default: `true`)                         |

<Warning>
  The `eoa-7702` mode is **not supported** for upgrades. Use `eoa` or `smart-account` mode instead.
</Warning>

<Info>
  **Signature Format**: Upgrade transactions use **personal message signing** (`eth_sign`), not EIP-712 typed data. This is because the upgrade operates on v2.1.0 accounts which use the legacy signing format. After upgrading, future transactions will use EIP-712 typed data.
</Info>

### Fee Token Object

```json theme={null}
"feeToken": {
  "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "chainId": 8453
}
```

### Example Request

```bash theme={null}
curl -X POST https://api.biconomy.io/v1/mee/upgrade \
  -H "Content-Type: application/json" \
  -d '{
    "ownerAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f7bD2B",
    "mode": "smart-account",
    "chainIds": [8453],
    "feeToken": {
      "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "chainId": 8453
    }
  }'
```

<CodeGroup>
  ```typescript TypeScript theme={null}
  const upgradeQuote = await fetch('https://api.biconomy.io/v1/mee/upgrade', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      ownerAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f7bD2B',
      mode: 'smart-account',
      chainIds: [8453],
      feeToken: {
        address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', // USDC on Base
        chainId: 8453
      }
    })
  }).then(r => r.json());

  // Sign the upgrade quote
  const signature = await walletClient.signMessage({
    message: upgradeQuote.payloadToSign[0].message,
    account
  });

  // Execute the upgrade
  const result = await fetch('https://api.biconomy.io/v1/execute', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      ...upgradeQuote,
      payloadToSign: [{ ...upgradeQuote.payloadToSign[0], signature }]
    })
  }).then(r => r.json());
  ```

  ```python Python theme={null}
  import requests

  # Get upgrade quote
  upgrade_response = requests.post(
      'https://api.biconomy.io/v1/mee/upgrade',
      headers={'Content-Type': 'application/json'},
      json={
          'ownerAddress': '0x742d35Cc6634C0532925a3b844Bc9e7595f7bD2B',
          'mode': 'smart-account',
          'chainIds': [8453],
          'feeToken': {
              'address': '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
              'chainId': 8453
          }
      }
  )

  upgrade_quote = upgrade_response.json()

  # Sign and execute...
  ```
</CodeGroup>

## Response Structure

### Success Response (200)

The response follows the standard quote format with an additional `upgradeDetails` field:

```json theme={null}
{
  "ownerAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f7bD2B",
  "fee": {
    "amount": "150000",
    "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "chainId": 8453
  },
  "quoteType": "simple",
  "quote": {
    "hash": "0x...",
    "node": "0x...",
    "commitment": "0x...",
    "paymentInfo": {...},
    "userOps": [...]
  },
  "payloadToSign": [
    {
      "signablePayload": {...},
      "metadata": {...}
    }
  ],
  "upgradeDetails": [
    {
      "chainId": 8453,
      "addressVersion": "2.1.0",
      "address": "0xLegacyAddr...",
      "nexusVersion": "2.1.0",
      "targetVersion": "2.2.1"
    }
  ]
}
```

### Response Fields

| Field            | Type   | Description                                      |
| ---------------- | ------ | ------------------------------------------------ |
| `ownerAddress`   | string | Owner wallet address                             |
| `fee`            | object | Execution fee details                            |
| `quoteType`      | string | Signature type (typically `simple` for upgrades) |
| `quote`          | object | Quote details for execution                      |
| `payloadToSign`  | array  | Payloads requiring signatures                    |
| `upgradeDetails` | array  | Details about accounts being upgraded            |

### Upgrade Details Object

| Field            | Type   | Description                                        |
| ---------------- | ------ | -------------------------------------------------- |
| `chainId`        | number | Chain ID of the account being upgraded             |
| `addressVersion` | string | Always `2.1.0` (legacy address derivation version) |
| `address`        | string | The address being upgraded                         |
| `nexusVersion`   | string | Current implementation version (`2.1.0`)           |
| `targetVersion`  | string | Target implementation version (`2.2.1`)            |

## Error Responses

### 400 Bad Request

<Tabs>
  <Tab title="NO_UPGRADE_NEEDED">
    No v2.1.0 deployments found that need upgrading on specified chains:

    ```json theme={null}
    {
      "code": "NO_UPGRADE_NEEDED",
      "message": "No accounts require upgrading on the specified chains"
    }
    ```

    **Solution**: Check the account status via `/v1/mee/orchestrator` first to confirm upgrade is needed.
  </Tab>

  <Tab title="INVALID_CHAIN">
    Invalid or unsupported chain ID:

    ```json theme={null}
    {
      "code": "INVALID_CHAIN",
      "message": "Chain ID 999999 is not supported"
    }
    ```

    **Solution**: Use a [supported chain ID](/contracts-and-audits/supported-chains).
  </Tab>

  <Tab title="INVALID_MODE">
    Unsupported execution mode for upgrades:

    ```json theme={null}
    {
      "code": "BAD_REQUEST",
      "message": "eoa-7702 mode is not supported for upgrades"
    }
    ```

    **Solution**: Use `eoa` or `smart-account` mode instead.
  </Tab>
</Tabs>

## Complete Upgrade Flow

Here's the complete flow for upgrading legacy accounts:

```typescript theme={null}
async function upgradeLegacyAccount(ownerAddress: string, walletClient: WalletClient) {
  // Step 1: Check account status
  const nexusInfo = await fetch('https://api.biconomy.io/v1/mee/orchestrator', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ ownerAddress })
  }).then(r => r.json());

  // Step 2: Identify chains needing upgrade
  const chainsToUpgrade = nexusInfo.deployments
    .filter(d => d.isUpgradeNeeded)
    .map(d => d.chainId);

  if (chainsToUpgrade.length === 0) {
    console.log('No upgrade needed');
    return nexusInfo.upgradedAddresses;
  }

  // Step 3: Generate upgrade quote
  const upgradeQuote = await fetch('https://api.biconomy.io/v1/mee/upgrade', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      ownerAddress,
      mode: 'smart-account',
      chainIds: chainsToUpgrade,
      feeToken: {
        address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', // USDC on Base
        chainId: 8453
      }
    })
  }).then(r => r.json());

  // Step 4: Sign the upgrade quote
  const payload = upgradeQuote.payloadToSign[0];
  const signature = await walletClient.signMessage({
    message: payload.signablePayload.message,
    account: walletClient.account
  });

  // Step 5: Execute the upgrade
  const result = await fetch('https://api.biconomy.io/v1/execute', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      ...upgradeQuote,
      payloadToSign: [{ ...payload, signature }]
    })
  }).then(r => r.json());

  console.log('Upgrade submitted:', result.supertxHash);
  console.log('Track at:', `https://meescan.biconomy.io/details/${result.supertxHash}`);

  // Step 6: Fetch updated status to get upgraded addresses
  const updatedInfo = await fetch('https://api.biconomy.io/v1/mee/orchestrator', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ ownerAddress })
  }).then(r => r.json());

  return updatedInfo.upgradedAddresses;
}
```

## After Upgrade

Once the upgrade is complete:

1. **Store the upgraded addresses** - Save `upgradedAddresses` for future use, or query the [/v1/mee/orchestrator](/supertransaction-api/endpoints/orchestrator) endpoint anytime to retrieve this info
2. **Use `accountAddress` parameter** - Pass the legacy address in `/v1/quote` requests

```typescript theme={null}
// After upgrade, use the legacy address in quote requests
const quote = await fetch('https://api.biconomy.io/v1/quote', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    ownerAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f7bD2B',
    mode: 'smart-account',
    composeFlows: [...],
    accountAddress: {
      '8453': '0xLegacyAddr...'  // Use the upgraded legacy address
    }
  })
}).then(r => r.json());
```

<Warning>
  The `eoa-7702` mode is **not supported** for upgrades yet and will be supported in the future. Use `eoa` or `smart-account` mode instead.
</Warning>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I upgrade multiple chains at once?">
    Yes. Pass multiple chain IDs in the `chainIds` array:

    ```json theme={null}
    {
      "chainIds": [8453, 10, 137]
    }
    ```

    All upgrades will be batched into a single supertransaction.
  </Accordion>

  <Accordion title="What versions are supported for upgrade?">
    Currently, only upgrading from **v2.1.0** to **v2.2.1** is supported:

    * **v2.1.0** - Legacy version (source)
    * **v2.2.1** - Current version (target)
  </Accordion>

  <Accordion title="Is the upgrade reversible?">
    No. Once upgraded to v2.2.1, accounts cannot be downgraded. However, this is generally not needed as v2.2.1 is backward compatible.
  </Accordion>
</AccordionGroup>

## Next Steps

* Learn about [using upgraded accounts with accountAddress](/supertransaction-api/endpoints/quote#account-address-override)
* Check [supported chains](/contracts-and-audits/supported-chains)
* Explore [execution modes](/supertransaction-api/execution-modes/choose-execution-mode)