Skip to main content
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

ParameterTypeRequiredDescription
ownerAddressstringYesEOA wallet address to check
chainsnumber[]NoChain IDs to check. Defaults to all supported chains
addressVersionsstring[]NoFilter 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);

​
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

FieldTypeDescription
ownerAddressstringThe queried EOA address
deploymentsarrayArray of deployment info for each chain/version combination
upgradedAddressesobjectChain ID to address mapping for upgraded v2.1.0 accounts

​
Deployment Object Fields

FieldTypeDescription
chainIdnumberChain ID
chainNamestringHuman-readable chain name
addressVersionstringMEE version used to derive this address (2.1.0 or 2.2.1)
addressstringNexus smart account address
isDeployedbooleanWhether the account has code deployed
implementationstring | nullCurrent implementation contract address
nexusVersionstring | nullCurrent implementation version (2.1.0, 2.2.1, or null)
accountIdstring | nullAccount identifier (e.g., biconomy.nexus.1.2.0)
isUpgradeNeededbooleanTrue if deployed with v2.1.0 implementation and needs upgrade

​
Understanding the Response

​
Key Concepts

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)

​
Example Responses

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

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