Check Account Status

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

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.

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

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

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);

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'])

Response Structure

Success Response (200)

{
  "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

Address Version vs Nexus Version
isUpgradeNeeded
upgradedAddresses

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)

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.

After upgrading a v2.1.0 account, its address appears in upgradedAddresses:

"upgradedAddresses": {
  "8453": "0xLegacyAddr...",
  "10": "0xLegacyAddr..."
}

Use these addresses with the accountAddress parameter in /v1/quote to execute transactions using the legacy address.

Example Responses

Account Needs Upgrade

User has a v2.1.0 deployment that needs upgrading:

{
  "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": {}
}

Account Already Upgraded

User’s v2.1.0 account has been upgraded to v2.2.1 implementation:

{
  "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..."
  }
}

New User (No Legacy Deployments)

User has no legacy deployments - standard flow applies:

{
  "ownerAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f7bD2B",
  "deployments": [
    {
      "chainId": 8453,
      "chainName": "Base",
      "addressVersion": "2.2.1",
      "address": "0xNewAddr...",
      "isDeployed": false,
      "implementation": null,
      "nexusVersion": null,
      "accountId": null,
      "isUpgradeNeeded": false
    }
  ],
  "upgradedAddresses": {}
}

Integration Pattern

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 to generate an upgrade quote
After upgrading, use the accountAddress parameter in /v1/quote to transact with legacy addresses

Frequently Asked Questions

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.

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.

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.

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.

Migration Guides

API Endpoints

Endpoint

When to Use

Request Structure

Request Body

Example Request

Response Structure

Success Response (200)

Response Fields

Deployment Object Fields

Understanding the Response

Key Concepts

Example Responses

Integration Pattern

Next Steps

Frequently Asked Questions

​Endpoint

​When to Use

​Request Structure

​Request Body

​Example Request

​Response Structure

​Success Response (200)

​Response Fields

​Deployment Object Fields

​Understanding the Response

​Key Concepts

​Example Responses

​Integration Pattern

​Next Steps

​Frequently Asked Questions

Endpoint

When to Use

Request Structure

Request Body

Example Request

Response Structure

Success Response (200)

Response Fields

Deployment Object Fields

Understanding the Response

Key Concepts

Example Responses

Integration Pattern

Next Steps

Frequently Asked Questions