Skip to main content

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.

​
Overview

This guide walks through the Giza Agent SDK from installation to a running agent. You’ll create a smart account, activate an agent, and start yield optimization.
This quickstart focuses on the Agentic integration — Giza handles smart accounts, execution, gas, and optimization. If you have your own execution infrastructure and just want optimization intelligence, see the IaaS Integration Guide.

​
What Giza Manages vs What You Build

Giza managesYou build
Smart account creation (ZeroDev)User interface
Session key managementDeposit flow
Transaction executionPerformance display
Gas paymentWithdrawal requests
Continuous optimizationNotification systems
Protocol rebalancingUser authentication

​
Architecture

​
Prerequisites

Check your version: node --versionDownload from nodejs.org if needed.
The SDK is built for TypeScript. JavaScript works too, but without type safety.
You’ll need:
  • GIZA_API_KEY - Your partner API key
  • GIZA_API_URL - Giza backend URL
  • GIZA_PARTNER_NAME - Your partner identifier

Get API Keys

Request API keys from Giza teams.

​
Installation

npm install @gizatech/agent-sdk

​
Environment Setup

Create a .env file in your project root:
.env
GIZA_API_KEY=...
GIZA_API_URL=...
GIZA_PARTNER_NAME=...
Never commit your .env file to version control! Add it to .gitignore.

​
Complete Integration Flow

​
Step 1: Initialize the SDK

import { Giza, Chain } from '@gizatech/agent-sdk';

// Initialize once, reuse throughout your app
const giza = new Giza({
  chain: Chain.BASE,
  timeout: 60000,      // Optional: 60s timeout
  enableRetry: true,   // Optional: retry failed requests
});

​
Step 2: Create a Smart Account

Generate a smart account for your user. This is where they’ll deposit funds. 
async function onboardUser(userWallet: `0x${string}`) {
  const agent = await giza.createAgent(userWallet);

  console.log('Smart Account:', agent.wallet);
  console.log('Deposit funds to this address');

  return agent;
}
The smart account address is deterministic - calling giza.createAgent with the same EOA always returns the same address.

​
Step 3: Get Available Protocols

Check which DeFi protocols are available for the token you want to optimize: 
const USDC_BASE = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';

const { protocols } = await giza.protocols(USDC_BASE);

console.log('Available protocols:', protocols);
// ['aave', 'compound', 'moonwell', 'fluid', ...]

​
Step 4: User Deposits Funds

1

User sends tokens to smart account

User transfers USDC (or supported token) to the agent.wallet address from Step 2.
2

Wait for confirmation

Wait for the transaction to be confirmed on-chain.
// Example: User deposits via your UI
const depositTxHash = await userWallet.sendTransaction({
  to: agent.wallet,
  value: parseUnits('1000', 6), // 1000 USDC (6 decimals)
});

​
Step 5: Activate the Agent

After the user deposits, activate the agent to start optimization: 
await agent.activate({
  owner: userWallet,
  token: USDC_BASE,
  protocols: ['aave', 'compound', 'moonwell'],
  txHash: depositTxHash,
  constraints: [
    {
      kind: 'min_protocols',
      params: { min_protocols: 2 } // Always diversify
    }
  ]
});
Once activated, the agent automatically:
  • Monitors APRs across selected protocols
  • Rebalances capital for optimal yield
  • Handles all gas costs internally
  • Continues optimizing until deactivated

​
Step 6: Monitor Performance

Track the agent’s performance: 
// Get current portfolio status
const info = await agent.portfolio();

console.log('Status:', info.status);

// Get APR
const { apr } = await agent.apr();

console.log(`Current APR: ${apr.toFixed(2)}%`);

// Get performance history
const { performance } = await agent.performance();

performance.forEach(point => {
  console.log(`${point.date}: $${point.value_in_usd}`);
});

​
Step 7: Withdraw Funds

Users can withdraw partially or fully at any time: 
// Withdraw everything and deactivate agent
await agent.withdraw();

// Wait for completion
await agent.waitForDeactivation({
  interval: 5000,
  timeout: 300000,
  onUpdate: (status) => console.log('Status:', status),
});

​
Additional Operations

​
Top-Up Active Agent

await agent.topUp(newDepositTxHash);

​
Update Protocols

await agent.updateProtocols(['aave', 'compound', 'moonwell', 'fluid']);

​
Manual Rebalance

await agent.run();

​
Multi-Chain Management

Run agents on multiple chains simultaneously: 
import { Giza, Chain } from '@gizatech/agent-sdk';

const baseGiza = new Giza({ chain: Chain.BASE });
const arbGiza = new Giza({ chain: Chain.ARBITRUM });

const baseAgent = await baseGiza.createAgent(userWallet);
const arbAgent = await arbGiza.createAgent(userWallet);

const [baseApr, arbApr] = await Promise.all([
  baseAgent.apr(),
  arbAgent.apr(),
]);

console.log('Base APR:', baseApr.apr);
console.log('Arbitrum APR:', arbApr.apr);

​
Constraint-Based Risk Management

Use constraints to control agent behavior: 
await agent.activate({
  owner: userWallet,
  token: USDC,
  protocols: ['aave', 'compound', 'moonwell', 'fluid'],
  txHash: depositTxHash,
  constraints: [
    // Diversify across at least 3 protocols
    { kind: 'min_protocols', params: { min_protocols: 3 } },
    // Cap newer protocol at 30%
    {
      kind: 'max_amount_per_protocol',
      params: { protocol: 'fluid', max_ratio: 0.3 },
    },
    // No dust allocations
    { kind: 'min_amount', params: { min_amount: '100000000' } },
  ],
});

​
Error Handling

Wrap SDK calls in try-catch blocks: 
import { ValidationError, GizaAPIError, TimeoutError } from '@gizatech/agent-sdk';

try {
  const agent = await giza.createAgent(userWallet);
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Invalid input:', error.message);
  } else if (error instanceof GizaAPIError) {
    console.error('API error:', error.statusCode, error.message);
  } else if (error instanceof TimeoutError) {
    console.error('Request timed out');
  }
}

Error Handling Guide

Error types, retry patterns, and user-friendly messages

​
Next Steps

Architecture

Understand smart accounts, agents, and protocols

SDK Reference

Explore all SDK methods

API Reference

HTTP API documentation

IaaS Integration

Use Optimizer with your own infrastructure