Monitoring

Overview

Monitoring methods let you inspect the current state of an agent and its historical performance. All methods are called on an Agent instance and are scoped to that agent’s smart-account wallet.

`portfolio()`

async portfolio(): Promise<AgentInfo>

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

Return Type

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

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?)`

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

string

ISO date string to filter performance data from this date onward. Omit to get all available history.

Return Type

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

// 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?)`

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

string

ISO date string for the start of the APR calculation period.

string

ISO date string for the end of the APR calculation period.

boolean

When true, uses the exact end date instead of rounding to the nearest period boundary.

Return Type

interface WalletAprResponse {
  apr: number;
  sub_periods?: WalletAprSubPeriod[];
}

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

Example

// 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?)`

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

Period

Time period for the APR calculation. Use Period.ALL for the entire history or Period.DAY for daily.

enum Period {
  ALL = 'all',
  DAY = 'day',
}

Return Type

type AprByTokenResponse = AllocatedValue[];

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

Example

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()`

async deposits(): Promise<DepositListResponse>

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

Return Type

interface DepositListResponse {
  deposits: Deposit[];
}

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

Example

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.

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

Use Promise.all to fetch independent data in parallel. This reduces total latency compared to sequential calls.

Next Steps

Lifecycle

Activation, deactivation, and agent state management

Agent Overview

All Agent methods at a glance

Giza Client

Chain-level queries and agent factory methods

SDK Overview

Agent Class

Utilities

Overview

`portfolio()`

Return Type

Example

`performance(options?)`

Parameters

Return Type

Example

`apr(options?)`

Parameters

Return Type

Example

`aprByTokens(period?)`

Parameters

Return Type

Example

`deposits()`

Return Type

Example

Building a Dashboard

Next Steps

Lifecycle

Agent Overview

Giza Client

​Overview

​portfolio()

​Return Type

​Example

​performance(options?)

​Parameters

​Return Type

​Example

​apr(options?)

​Parameters

​Return Type

​Example

​aprByTokens(period?)

​Parameters

​Return Type

​Example

​deposits()

​Return Type

​Example

​Building a Dashboard

​Next Steps

Lifecycle

Agent Overview

Giza Client

Overview

`portfolio()`

Return Type

Example

`performance(options?)`

Parameters

Return Type

Example

`apr(options?)`

Parameters

Return Type

Example

`aprByTokens(period?)`

Parameters

Return Type

Example

`deposits()`

Return Type

Example

Building a Dashboard

Next Steps