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>
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}`);
}
async performance(
options?: PerformanceOptions
): Promise<PerformanceChartResponse>
Parameters
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;
}
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>
Parameters
ISO date string for the start of the APR calculation period.
ISO date string for the end of the APR calculation period.
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>
Parameters
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>
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
