> ## 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.

# Check Account Status

> Query Nexus deployment information across chains and MEE versions

The `/v1/mee/orchestrator` endpoint queries deployment information for an owner address across multiple chains and MEE versions. Use this to check if users have legacy v2.1.0 deployments that need upgrading, or to retrieve their upgraded account addresses.

## Endpoint

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

## When to Use

<Info>
  This endpoint is primarily useful if you have users with **legacy v2.1.0 deployments** and want to support an upgrade flow. New applications using only v2.2.1 can skip this endpoint entirely.
</Info>

Use this endpoint to:

* Check if a user has existing Nexus deployments
* Determine which accounts need upgrading from v2.1.0 to v2.2.1
* Retrieve `upgradedAddresses` to use with the `accountAddress` parameter in `/v1/quote`

## Request Structure

### Request Body

| Parameter         | Type      | Required | Description                                                            |
| ----------------- | --------- | -------- | ---------------------------------------------------------------------- |
| `ownerAddress`    | string    | Yes      | EOA wallet address to check                                            |
| `chains`          | number\[] | No       | Chain IDs to check. Defaults to all supported chains                   |
| `addressVersions` | string\[] | No       | Filter by version: `['2.1.0']`, `['2.2.1']`, or both. Defaults to both |

### Example Request

```bash theme={null}
curl -X POST https://api.biconomy.io/v1/mee/orchestrator \
  -H "Content-Type: application/json" \
  -d '{
    "ownerAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f7bD2B",
    "chains": [8453, 10]
  }'
```

<CodeGroup>
  ```typescript TypeScript theme={null}
  const orchestratorResponse = await fetch('https://api.biconomy.io/v1/mee/orchestrator', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      ownerAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f7bD2B',
      chains: [8453, 10]  // Optional: Base and Optimism
    })
  }).then(r => r.json());

  // Check if any deployments need upgrade
  const needsUpgrade = orchestratorResponse.deployments.some(d => d.isUpgradeNeeded);
  ```

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

  response = requests.post(
      'https://api.biconomy.io/v1/mee/orchestrator',
      headers={'Content-Type': 'application/json'},
      json={
          'ownerAddress': '0x742d35Cc6634C0532925a3b844Bc9e7595f7bD2B',
          'chains': [8453, 10]
      }
  )

  orchestrator_data = response.json()
  needs_upgrade = any(d['isUpgradeNeeded'] for d in orchestrator_data['deployments'])
  ```
</CodeGroup>

## Response Structure

### Success Response (200)

```json theme={null}
{
  "ownerAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f7bD2B",
  "deployments": [
    {
      "chainId": 8453,
      "chainName": "Base",
      "addressVersion": "2.1.0",
      "address": "0xLegacyAddr...",
      "isDeployed": true,
      "implementation": "0xOldImpl...",
      "nexusVersion": "2.1.0",
      "accountId": "biconomy.nexus.1.0.0",
      "isUpgradeNeeded": true
    },
    {
      "chainId": 8453,
      "chainName": "Base",
      "addressVersion": "2.2.1",
      "address": "0xNewAddr...",
      "isDeployed": false,
      "implementation": null,
      "nexusVersion": null,
      "accountId": null,
      "isUpgradeNeeded": false
    }
  ],
  "upgradedAddresses": {}
}
```

### Response Fields

| Field               | Type   | Description                                                 |
| ------------------- | ------ | ----------------------------------------------------------- |
| `ownerAddress`      | string | The queried EOA address                                     |
| `deployments`       | array  | Array of deployment info for each chain/version combination |
| `upgradedAddresses` | object | Chain ID to address mapping for upgraded v2.1.0 accounts    |

### Deployment Object Fields

| Field             | Type           | Description                                                   |
| ----------------- | -------------- | ------------------------------------------------------------- |
| `chainId`         | number         | Chain ID                                                      |
| `chainName`       | string         | Human-readable chain name                                     |
| `addressVersion`  | string         | MEE version used to derive this address (`2.1.0` or `2.2.1`)  |
| `address`         | string         | Nexus smart account address                                   |
| `isDeployed`      | boolean        | Whether the account has code deployed                         |
| `implementation`  | string \| null | Current implementation contract address                       |
| `nexusVersion`    | string \| null | Current implementation version (`2.1.0`, `2.2.1`, or null)    |
| `accountId`       | string \| null | Account identifier (e.g., `biconomy.nexus.1.2.0`)             |
| `isUpgradeNeeded` | boolean        | True if deployed with v2.1.0 implementation and needs upgrade |

## Understanding the Response

### Key Concepts

<Tabs>
  <Tab title="Address Version vs Nexus Version">
    **Address Version** (`addressVersion`): The MEE version used to *derive* the address. Different versions derive different addresses for the same owner.

    **Nexus Version** (`nexusVersion`): The actual implementation version running at that address. An account derived with v2.1.0 can be *upgraded* to run v2.2.1 implementation.

    ```
    addressVersion: "2.1.0"  →  Address derived using v2.1.0 formula
    nexusVersion: "2.2.1"    →  Currently running v2.2.1 implementation (upgraded)
    ```
  </Tab>

  <Tab title="isUpgradeNeeded">
    The `isUpgradeNeeded` field is `true` when:

    * Account is deployed (`isDeployed: true`)
    * Running v2.1.0 implementation (`nexusVersion: "2.1.0"`)

    After upgrading, this becomes `false` even though `addressVersion` remains `2.1.0`.
  </Tab>

  <Tab title="upgradedAddresses">
    After upgrading a v2.1.0 account, its address appears in `upgradedAddresses`:

    ```json theme={null}
    "upgradedAddresses": {
      "8453": "0xLegacyAddr...",
      "10": "0xLegacyAddr..."
    }
    ```

    Use these addresses with the `accountAddress` parameter in `/v1/quote` to execute transactions using the legacy address.
  </Tab>
</Tabs>

## Example Responses

<AccordionGroup>
  <Accordion title="Account Needs Upgrade">
    User has a v2.1.0 deployment that needs upgrading:

    ```json theme={null}
    {
      "ownerAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f7bD2B",
      "deployments": [
        {
          "chainId": 8453,
          "chainName": "Base",
          "addressVersion": "2.1.0",
          "address": "0xLegacyAddr...",
          "isDeployed": true,
          "implementation": "0xOldImpl...",
          "nexusVersion": "2.1.0",
          "accountId": "biconomy.nexus.1.0.0",
          "isUpgradeNeeded": true
        }
      ],
      "upgradedAddresses": {}
    }
    ```
  </Accordion>

  <Accordion title="Account Already Upgraded">
    User's v2.1.0 account has been upgraded to v2.2.1 implementation:

    ```json theme={null}
    {
      "ownerAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f7bD2B",
      "deployments": [
        {
          "chainId": 8453,
          "chainName": "Base",
          "addressVersion": "2.1.0",
          "address": "0xLegacyAddr...",
          "isDeployed": true,
          "implementation": "0xLatestImpl...",
          "nexusVersion": "2.2.1",
          "accountId": "biconomy.nexus.1.2.0",
          "isUpgradeNeeded": false
        }
      ],
      "upgradedAddresses": {
        "8453": "0xLegacyAddr..."
      }
    }
    ```
  </Accordion>

  <Accordion title="New User (No Legacy Deployments)">
    User has no legacy deployments - standard flow applies:

    ```json theme={null}
    {
      "ownerAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f7bD2B",
      "deployments": [
        {
          "chainId": 8453,
          "chainName": "Base",
          "addressVersion": "2.2.1",
          "address": "0xNewAddr...",
          "isDeployed": false,
          "implementation": null,
          "nexusVersion": null,
          "accountId": null,
          "isUpgradeNeeded": false
        }
      ],
      "upgradedAddresses": {}
    }
    ```
  </Accordion>
</AccordionGroup>

## Integration Pattern

```typescript theme={null}
async function checkUserStatus(ownerAddress: string) {
  // 1. Query deployment 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());

  // 2. Check if upgrade is needed
  const deploymentsNeedingUpgrade = nexusInfo.deployments.filter(d => d.isUpgradeNeeded);

  if (deploymentsNeedingUpgrade.length > 0) {
    return {
      status: 'needs_upgrade',
      chainsToUpgrade: deploymentsNeedingUpgrade.map(d => d.chainId)
    };
  }

  // 3. User is ready - return upgraded addresses for use in /quote
  return {
    status: 'ready',
    accountAddress: nexusInfo.upgradedAddresses
  };
}
```

## Next Steps

* If accounts need upgrading, use the [Upgrade endpoint](/supertransaction-api/endpoints/upgrade) to generate an upgrade quote
* After upgrading, use the `accountAddress` parameter in [/v1/quote](/supertransaction-api/endpoints/quote) to transact with legacy addresses

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Which MEE versions are supported?">
    The orchestrator endpoint currently supports two versions:

    * **v2.1.0** - Legacy version (accounts that may need upgrading)
    * **v2.2.1** - Current version (all new deployments)

    Only these two versions can be queried via the `addressVersions` parameter.
  </Accordion>

  <Accordion title="Do I need to use this endpoint for new applications?">
    No. If you're building a new application without existing users on v2.1.0, you can skip this endpoint entirely. The standard `/v1/quote` → `/v1/execute` flow will automatically use v2.2.1.
  </Accordion>

  <Accordion title="Can I cache the response?">
    Yes. You can cache `upgradedAddresses` in memory or local storage to avoid repeated API calls. The upgrade status only changes when a user explicitly upgrades their account.
  </Accordion>

  <Accordion title="Which chains are supported?">
    The orchestrator endpoint supports all MEE-enabled chains. Common chain IDs:

    * **Base**: `8453`
    * **Optimism**: `10`
    * **Polygon**: `137`
    * **Arbitrum**: `42161`
    * **World Chain**: `480`

    For a complete list, see [Supported Chains](/contracts-and-audits/supported-chains).
  </Accordion>
</AccordionGroup>