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

# Monitoring

> Track portfolio value, performance history, APR, and deposits

## Overview

Monitoring methods let you inspect the current state of an agent and its historical performance. All methods are called on an [`Agent`](/sdk-reference/agent/overview) instance and are scoped to that agent's smart-account wallet.

## `portfolio()`

```typescript theme={null}
async portfolio(): Promise<AgentInfo>
```

Returns the full current state of the agent, including deposits, withdrawals, status, protocol selection, and key dates.

### Return Type

```typescript theme={null}
interface AgentInfo {
  wallet: Address;
  deposits: Deposit[];
  withdraws?: Withdraw[];
  status: AgentStatus;
  activation_date: string;
  last_deactivation_date?: string;
  last_reactivation_date?: string;
  selected_protocols: string[];
  current_protocols?: string[];
  current_token?: string;
  eoa?: Address;
}
```

### Example

```typescript theme={null}
const info = await agent.portfolio();

console.log('Wallet:', info.wallet);
console.log('Status:', info.status);
console.log('Protocols:', info.selected_protocols.join(', '));
console.log('Activated:', info.activation_date);

for (const deposit of info.deposits) {
  console.log(`Deposit: ${deposit.amount} ${deposit.token_type}`);
}
```

***

## `performance(options?)`

```typescript theme={null}
async performance(
  options?: PerformanceOptions
): Promise<PerformanceChartResponse>
```

Returns historical performance data points for charting portfolio value over time. Each data point includes the date, value, USD value, accrued rewards, and portfolio breakdown.

### Parameters

<ParamField path="from" type="string">
  ISO date string to filter performance data from this date onward. Omit to get all available history.
</ParamField>

### Return Type

```typescript theme={null}
interface PerformanceChartResponse {
  performance: PerformanceData[];
}

interface PerformanceData {
  date: string;
  value: number;
  value_in_usd?: number;
  accrued_rewards?: AccruedRewardsBySymbol;
  portfolio?: Portfolio;
  agent_token_amount?: number;
}
```

Where `Portfolio` is `Record<string, AllocatedValue>` mapping protocol names to their allocation details, and `AccruedRewardsBySymbol` is `Record<string, AccruedRewardsWithValue>` mapping reward token symbols to their locked/unlocked amounts.

### Example

```typescript theme={null}
// Get all performance history
const { performance } = await agent.performance();

for (const point of performance) {
  console.log(`${point.date}: $${point.value_in_usd}`);
}

// Get performance from a specific date
const { performance: recent } = await agent.performance({
  from: '2025-01-01',
});
```

***

## `apr(options?)`

```typescript theme={null}
async apr(options?: AprOptions): Promise<WalletAprResponse>
```

Returns the agent's annualized percentage rate (APR). Optionally specify a date range to compute APR over a specific period. The response can include sub-period breakdowns for detailed analysis.

### Parameters

<ParamField path="startDate" type="string">
  ISO date string for the start of the APR calculation period.
</ParamField>

<ParamField path="endDate" type="string">
  ISO date string for the end of the APR calculation period.
</ParamField>

<ParamField path="useExactEndDate" type="boolean">
  When `true`, uses the exact end date instead of rounding to the nearest period boundary.
</ParamField>

### Return Type

```typescript theme={null}
interface WalletAprResponse {
  apr: number;
  sub_periods?: WalletAprSubPeriod[];
}

interface WalletAprSubPeriod {
  start_date: string;
  end_date: string;
  return_: number;
  initial_value: number;
}
```

### Example

```typescript theme={null}
// Get overall APR
const { apr } = await agent.apr();
console.log(`APR: ${apr}%`);

// Get APR for a specific date range
const result = await agent.apr({
  startDate: '2025-01-01',
  endDate: '2025-06-01',
});
console.log(`Period APR: ${result.apr}%`);

if (result.sub_periods) {
  for (const period of result.sub_periods) {
    console.log(
      `  ${period.start_date} to ${period.end_date}: ` +
      `return=${period.return_}, initial=${period.initial_value}`
    );
  }
}
```

***

## `aprByTokens(period?)`

```typescript theme={null}
async aprByTokens(period?: Period): Promise<AprByTokenResponse>
```

Returns APR data broken down by token allocation. Each entry includes the current value, USD value, and base/total APR for that allocation.

### Parameters

<ParamField path="period" type="Period">
  Time period for the APR calculation. Use `Period.ALL` for the entire history or `Period.DAY` for daily.
</ParamField>

```typescript theme={null}
enum Period {
  ALL = 'all',
  DAY = 'day',
}
```

### Return Type

```typescript theme={null}
type AprByTokenResponse = AllocatedValue[];

interface AllocatedValue {
  value: number;
  value_in_usd: number;
  base_apr?: number;
  total_apr?: number;
}
```

### Example

```typescript theme={null}
import { Period } from '@gizatech/agent-sdk';

const allocations = await agent.aprByTokens(Period.ALL);

for (const alloc of allocations) {
  console.log(
    `Value: ${alloc.value} ($${alloc.value_in_usd}), ` +
    `Base APR: ${alloc.base_apr}%, Total APR: ${alloc.total_apr}%`
  );
}
```

***

## `deposits()`

```typescript theme={null}
async deposits(): Promise<DepositListResponse>
```

Returns all deposits made to the agent's smart account.

### Return Type

```typescript theme={null}
interface DepositListResponse {
  deposits: Deposit[];
}

interface Deposit {
  amount: number;
  token_type: string;
  date?: string;
  tx_hash?: string;
  block_number?: number;
}
```

### Example

```typescript theme={null}
const { deposits } = await agent.deposits();

let total = 0;
for (const deposit of deposits) {
  console.log(
    `${deposit.date}: ${deposit.amount} ${deposit.token_type} ` +
    `(tx: ${deposit.tx_hash})`
  );
  total += deposit.amount;
}
console.log(`Total deposited: ${total}`);
```

***

## Building a Dashboard

This example shows how to combine monitoring methods to build a portfolio dashboard view.

```typescript theme={null}
import { Giza, Chain, Period } from '@gizatech/agent-sdk';

const giza = new Giza({ chain: Chain.BASE });
const agent = await giza.getAgent('0xUserEOA...');

// Fetch all data in parallel
const [info, perf, aprData, tokenAprs, depositList] =
  await Promise.all([
    agent.portfolio(),
    agent.performance({ from: '2025-01-01' }),
    agent.apr(),
    agent.aprByTokens(Period.ALL),
    agent.deposits(),
  ]);

// Agent overview
console.log('=== Agent Dashboard ===');
console.log(`Wallet: ${info.wallet}`);
console.log(`Status: ${info.status}`);
console.log(`Active since: ${info.activation_date}`);
console.log(`Protocols: ${info.selected_protocols.join(', ')}`);

// APR summary
console.log(`\nOverall APR: ${aprData.apr}%`);

// Token allocation breakdown
console.log('\n--- Allocation Breakdown ---');
for (const alloc of tokenAprs) {
  console.log(
    `  Value: $${alloc.value_in_usd.toFixed(2)} | ` +
    `Base APR: ${alloc.base_apr?.toFixed(2)}% | ` +
    `Total APR: ${alloc.total_apr?.toFixed(2)}%`
  );
}

// Recent performance (last 5 data points)
console.log('\n--- Recent Performance ---');
const recent = perf.performance.slice(-5);
for (const point of recent) {
  console.log(`  ${point.date}: $${point.value_in_usd?.toFixed(2)}`);
}

// Deposit history
console.log('\n--- Deposits ---');
for (const dep of depositList.deposits) {
  console.log(
    `  ${dep.date}: ${dep.amount} ${dep.token_type}`
  );
}
```

<Tip>
  Use `Promise.all` to fetch independent data in parallel. This reduces total latency compared to sequential calls.
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Lifecycle" icon="arrows-spin" href="/sdk-reference/agent/lifecycle">
    Activation, deactivation, and agent state management
  </Card>

  <Card title="Agent Overview" icon="robot" href="/sdk-reference/agent/overview">
    All Agent methods at a glance
  </Card>

  <Card title="Giza Client" icon="plug" href="/sdk-reference/giza">
    Chain-level queries and agent factory methods
  </Card>
</CardGroup>