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

# getPositions

Retrieve the current active DeFi positions and idle balances for the user across all configured chains. This method provides a view of the user's positions, including deployed capital and latent funds.

For a more accurate and detailed portfolio view, see [getPortfolio](/docs/sdk/api/get-portfolio).

## Signature

```typescript theme={null}
getPositions(): Promise<PortfolioResponse>
```

## Parameters

| Parameter     | Type               | Required | Description                           |
| ------------- | ------------------ | -------- | ------------------------------------- |
| `userAddress` | `string`           | ✅        | User's EOA address                    |
| `chainId`     | `SupportedChainId` | ❌        | Optional: Filter by specific chain ID |

## Returns

A comprehensive breakdown of the user's assets, separated into active positions and idle (stale) balances.

## Return Type

```typescript theme={null}
interface PortfolioResponse {
    success: boolean;
    userAddress: string;
    portfolio: Portfolio;
}

interface Portfolio {
    user?: string;
    eoa?: Address;
    chains?: number[];
    strategy?: string;
    smartWallet?: Address;
    positions?: PositionSlot[];
    hasActiveSessionKey?: boolean;
    hasBalance?: boolean;
    newSessionKeyAvailable?: boolean;
    contracts?: Address[];
    omniAccount?: boolean;
    crosschainStrategy?: boolean;
    staleBalances?: staleBalances[];
    splitting?: boolean;
    minSplits?: number;
    executorProxy?: boolean;
    assetTypeSettings?: AssetTypeSettings;
}


interface AssetTypeSettings {
  [assetType: string]: {
    rebalanceStrategy?: string;
    autocompounding?: boolean;
    crosschainStrategy?: boolean;
    splitting?: boolean;
    minSplits?: number;
    chains?: number[];
    autoSelectProtocols?: boolean;
    protocols?: string[];
  };
}

interface PositionSlot {
    chain?: string;
    protocol_id?: string;
    protocol_name?: string;
    protocol_icon?: string;
    pool?: string;
    token_id?: string;
    token_symbol?: string;
    token_icon?: string;
    amount?: string;
    underlyingAmount?: string;
    pool_apy?: number;
    pool_tvl?: number;
    liquidity?: number;
}

interface staleBalances {
    chainId: number;
    tokenSymbol: string;
    balance: string;
    isPending: boolean;
}
```

## Portfolio Calculation

To calculate the total **Portfolio Value**, you must consider both active and idle funds:

<Info title="Portfolio Formula">
  **Total Portfolio Value** = Active Positions + Stale Balances
</Info>

* **`positions`**: Represents capital that has been successfully deployed by the Zyfai agent into liquidity pools or vaults. These assets are actively earning yield.
* **`staleBalances`**: Represents "latent" funds that are sitting in the user's **Safe Smart Wallet** but have not yet been allocated to a strategy (e.g., recently deposited funds or funds awaiting the next rebalance cycle).

## Example

```typescript theme={null}
const response = await sdk.getPositions();
const portfolio = response.portfolio;

console.log(`Smart Wallet: ${portfolio.smartWallet}`);

// List active yield-earning positions
portfolio.positions?.forEach(p => {
  console.log(`${p.protocol_name} (${p.chain}): ${p.underlyingAmount} ${p.token_symbol} @ ${p.pool_apy}% APY`);
});

// List idle funds awaiting deployment
portfolio.staleBalances?.forEach(b => {
  console.log(`Idle on Chain ${b.chainId}: ${b.balance} ${b.tokenSymbol}`);
});
```

## Notes

* The `underlyingAmount` is provided in the token's least decimal units.
* `staleBalances` are automatically picked up by the agent during the next optimization/rebalance window.