Portfolio

getBalances

Returns the user's current balances.

If agentId is omitted: retrieves balances across the currently active agents.
If agentId is provided: retrieves balances for the specified agent.

Signature
Example
Example Output

getBalances(
  agentId?: AgentId
): Promise<OwneyBalances | AgentBalance>

const balances = await owney.getBalances();

{
  "totalBalance": "700.20",
  "totalBalanceAsset": "usdc",
  "agentBalances": {
    "zyfai": {
      "smartWallet": "0x...",
      "totalBalance": "700.20",
      "totalBalanceAsset": "usdc",
      "tokens": [
        {
          "chain": "BASE",
          "chainId": 8453,
          "asset": "USDC",
          "amount": "700.20"
        }
      ],
      "positions": [
        {
          "chain": "Base",
          "protocol": "Morpho",
          "protocolId": "84742d74-d676-42cc-a4a3-c4e87d8786be",
          "pool": "Gauntlet USDC Frontier",
          "asset": "USDC",
          "amount": "700.20",
          "apy": 7.41,
          "tvl": 210523.67,
          "liquidity": 210523.67
        }
      ]
    }
  }
}

Parameters

agentId?: AgentId - The agent to retrieve balances for (See AgentId for details). If omitted, retrieves balances for the current active-agent set.

Returns

Promise<OwneyBalances> if agentId is omitted. Includes total balance and a breakdown by active agent.
Promise<AgentBalance> if agentId is provided.

totalBalanceAsset indicates the asset that every totalBalance (top-level and per-agent) is denominated in. It is currently always "usdc".

See OwneyBalances and AgentBalance for details.

getEarnings

Returns the user's on-chain earnings summary.

If agentId is omitted: retrieves earnings across the currently active agents.
If agentId is provided: retrieves earnings for the specified agent.

Requires wallet connection: Yes

Signature
Example
Example Output

getEarnings(
  agentId?: AgentId
): Promise<OwneyEarnings | AgentEarnings>

const earnings = await owney.getEarnings();

{
  "totalEarnings": "51.12",
  "agentEarnings": {
    "zyfai": {
      "smartWallet": "0x...",
      "lifetimeEarnings": 51.12,
      "tokens": [
        {
          "chain": "BASE",
          "chainId": 8453,
          "asset": "USDC",
          "amount": "51.12"
        }
      ]
    }
  }
}

Parameters

agentId?: AgentId - The agent to retrieve earnings for (See AgentId for details). If omitted, retrieves earnings for the current active-agent set.

Returns

Promise<OwneyEarnings> if agentId is omitted. Includes total earnings and a per-agent breakdown.
Promise<AgentEarnings> if agentId is provided.

See OwneyEarnings and AgentEarnings for details.

refreshEarnings

Refreshes earnings for agents whose earnings data may become outdated. Use getEarnings to show the current value immediately, then call refreshEarnings in the background and update the displayed value when it resolves. The SDK determines whether a recalculation is needed.

If agentId is omitted: refreshes earnings across the currently active agents.
If agentId is provided: refreshes earnings for the specified agent.

Requires wallet connection: Yes

Signature
Example

refreshEarnings(
  agentId?: AgentId
): Promise<OwneyEarnings | AgentEarnings>

const current = await owney.getEarnings("zyfai");
displayEarnings(current);

void owney.refreshEarnings("zyfai").then((refreshed) => {
  displayEarnings(refreshed);
});

getAccountApy

Returns weighted account APY for a selected lookback period.

If agentId is omitted: returns the account's total APY plus per-agent APY across the currently active agents.
If agentId is provided: returns APY for the specified agent.

Requires wallet connection: Yes

Signature
Example
Example Output

getAccountApy(
  options: AccountApyOptions
): Promise<OwneyAccountApy | AccountAgentApy>

const apy = await owney.getAccountApy({
  days: "30D"
});

{
  "totalApy": "4.0",
  "agentApy": {
    "zyfai": {
      "walletAddress": "0x...",
      "weightedApyAfterFee": 4.0,
      "weightedApyAfterFeeDetails": {
        "apyPerAsset": {
          "8453": {
            "USDC": 4.2
          }
        }
      }
    }
  },
  "apyByChainAndAsset": {
    "8453": {
      "USDC": 4.2
    }
  }
}

Parameters

options: AccountApyOptions - Required options (See AccountApyOptions for details):
- days: DailyApyDays - Lookback period (for example "7D", "14D", or "30D").
- agentId?: AgentId - Optional agent to query. If omitted, returns weighted account APY across the current active-agent set.

Returns

Promise<OwneyAccountApy> if agentId is omitted.
Promise<AccountAgentApy> if agentId is provided.

weightedApyAfterFeeDetails and apyByChainAndAsset are optional on per-agent results. Aggregated OwneyAccountApy responses also include a top-level apyByChainAndAsset.

See OwneyAccountApy and AccountAgentApy for details.

getAllocationApy

Returns allocation-weighted APY from the user's current portfolio positions.

Each position's pool APY is weighted by the user's position value. If agentId is omitted, positions from all active agents are pooled before the total APY is calculated.

Requires wallet connection: Yes

Signature
Example
Example Output

getAllocationApy(
  options?: { agentId?: AgentId }
): Promise<OwneyAllocationApy>

const allocationApy = await owney.getAllocationApy();

{
  "totalApy": "5.5",
  "apyByChainAndAsset": {
    "8453": {
      "USDC": 5.5
    }
  },
  "agentApy": {
    "zyfai": {
      "totalApy": "5.5",
      "apyByChainAndAsset": {
        "8453": {
          "USDC": 5.5
        }
      }
    }
  }
}

Parameters

options?: { agentId?: AgentId } - Optional agent scope. If omitted, returns allocation APY across the current active-agent set.

Returns

Promise<OwneyAllocationApy> - Position-weighted APY across all selected positions, including per-chain/per-asset and per-agent breakdowns.

See OwneyAllocationApy and AllocationAgentApy for details.

getHistory

Returns transaction history, optionally scoped by asset, date or page size.

If agentId is omitted: retrieves history for the currently active agents.
If agentId is provided: retrieves history for the specified agent.

Requires wallet connection: Yes

Signature
Example
Example Output

getHistory(
  params?: HistoryOptions
): Promise<OwneyAgentHistory>

// History with optional filters
const history = await owney.getHistory({
  filters: {
    limit: 10,
    fromDate: "2026-02-01",
    toDate: "2026-03-05",
  },
});

// Scoped to one asset — use this when the UI shows a single asset at a
// time, so a page can't come back holding only the other one's entries.
const wethHistory = await owney.getHistory({
  filters: { limit: 10, tokenSymbol: "WETH" },
});

{
  "data": [
    {
      "agent": "zyfai",
      "action": "Rebalance",
      "date": "2026-03-02T12:30:00.000Z",
      "oldApy": "0.061",
      "newApy": "0.068",
      "transactions": [
        {
          "txHashes": ["0x..."],
          "chainId": 8453,
          "tokenSymbol": "USDC",
          "amount": "100000000"
        }
      ],
      "rebalanceLog": [
        {
          "fromProtocol": "Aave V3",
          "toProtocol": "Moonwell Blue",
          "tokenSymbol": "USDC",
          "amount": "100.00",
          "status": "success"
        }
      ]
    }
  ],
  "hasMore": false
}

Parameters

params?: HistoryOptions - Optional filters (See HistoryOptions for details).
- agentId?: AgentId - Optional agent filter.
- filters?: HistoryFilters - Optional filters:
  - limit?: number - Maximum entries returned per call. Defaults to 10.
  - cursor?: string - Opaque cursor returned by a previous getHistory() call.
  - fromDate?: string - Start date (inclusive), format YYYY-MM-DD.
  - toDate?: string - End date (inclusive), format YYYY-MM-DD.
  - tokenSymbol?: string - Asset symbol (e.g. "USDC", "WETH") to scope the history to a single asset. Without it a page blends every asset on the active chain, so an integrator showing one asset at a time can receive a page holding none of it. Agents whose backend cannot filter by asset ignore this and return the chain's full history.

Returns

Promise<OwneyAgentHistory> - Transaction history matching the provided filters, including hasMore and an optional nextCursor for pagination (See OwneyAgentHistory for details).

getUserProfile

Returns the authenticated user's profile details.

If agentId is omitted: retrieves the user profile for the currently active agents.
If agentId is provided: retrieves the user profile for the specified agent.

Requires wallet connection: Yes

Signature
Example
Example Output

getUserProfile(
  agentId?: AgentId
): Promise<OwneyUserProfile | AgentUserProfile>

const profile = await owney.getUserProfile();

{
  "agentUserProfile": {
    "zyfai": {
      "address": "0x...",
      "smartWallet": "0x...",
      "chains": [8453],
      "strategy": "conservative",
      "hasActiveSessionKey": true,
      "protocols": ["Aave", "Moonwell"]
    }
  }
}

Parameters

agentId?: AgentId - The agent to retrieve the user profile for (See AgentId for details). If omitted, retrieves the user profile for the current active-agent set.

Returns

Promise<OwneyUserProfile> if agentId is omitted. Includes per-agent user profiles.
Promise<AgentUserProfile> if agentId is provided.

See OwneyUserProfile and AgentUserProfile for details.

getBalances​

getEarnings​

refreshEarnings​

getAccountApy​

getAllocationApy​

getHistory​

getUserProfile​

getBalances

getEarnings

refreshEarnings

getAccountApy

getAllocationApy

getHistory

getUserProfile