Overview
The Giza class is the primary entry point of the SDK. It manages authentication, HTTP transport, and chain-scoped configuration. Use it to create Agent handles, query protocol data, run the optimizer, and check system health.
import { Giza, Chain } from '@gizatech/agent-sdk';
const giza = new Giza({
chain: Chain.BASE,
// apiKey, partner, apiUrl fall back to env vars
});
Constructor
new Giza(config: GizaConfig)
Configuration object specifying the target chain and credentials.
ValidationError if any required credential is missing or if the chain ID is invalid.
Environment Variable Fallback
When a credential is omitted from the constructor config, the SDK reads the corresponding environment variable:
| Config Field | Environment Variable | Required |
|---|
apiKey | GIZA_API_KEY | Yes (via config or env) |
partner | GIZA_PARTNER_NAME | Yes (via config or env) |
apiUrl | GIZA_API_URL | Yes (via config or env) |
ValidationError with a message indicating which value is missing.
Agent Factory Methods
These methods create or retrieve Agent handles bound to a specific smart-account wallet address.
agent(wallet)
agent(wallet: Address): Agent
Agent handle for a known smart-account address without making any API call. Use this when you already have the smart-account address stored (for example, from a previous createAgent call).
The smart-account wallet address (0x-prefixed hex string).
Agent
const agent = giza.agent('0x1234567890abcdef1234567890abcdef12345678');
const info = await agent.portfolio();
createAgent(eoa)
async createAgent(eoa: Address): Promise<Agent>
Agent bound to the new smart-account address.
The user’s externally-owned account address.
Promise<Agent> — the Agent is bound to the newly created smart-account address.
const agent = await giza.createAgent('0xUserEOA...');
console.log('Smart account:', agent.wallet);
getAgent(eoa)
async getAgent(eoa: Address): Promise<Agent>
Agent bound to it. Use this when the smart account was created previously and you need to recover the handle.
The user’s externally-owned account address.
Promise<Agent>
const agent = await giza.getAgent('0xUserEOA...');
const portfolio = await agent.portfolio();
getSmartAccount(eoa)
async getSmartAccount(eoa: Address): Promise<SmartAccountInfo>
Agent handle. Useful when you need the raw account data.
The user’s externally-owned account address.
Promise<SmartAccountInfo>
interface SmartAccountInfo {
smartAccountAddress: Address;
backendWallet: Address;
origin_wallet: Address;
chain: Chain;
}
const account = await giza.getSmartAccount('0xUserEOA...');
console.log('Smart account:', account.smartAccountAddress);
console.log('Backend wallet:', account.backendWallet);
Chain-Level Queries
These methods query data scoped to the chain configured on the Giza client.
protocols(token)
async protocols(token: Address): Promise<ProtocolsResponse>
The token contract address.
Promise<ProtocolsResponse> — { protocols: string[] }
const USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
const { protocols } = await giza.protocols(USDC);
console.log('Available protocols:', protocols);
// ['aave', 'compound', 'moonwell', ...]
protocolSupply(token)
async protocolSupply(token: Address): Promise<ProtocolsSupplyResponse>
The token contract address.
Promise<ProtocolsSupplyResponse>
const supply = await giza.protocolSupply(
'0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
);
for (const p of supply.protocols) {
console.log(`${p.protocol}: ${p.supply}`);
}
tokens()
async tokens(): Promise<TokensResponse>
Promise<TokensResponse> — { tokens: TokenInfo[] }
const { tokens } = await giza.tokens();
for (const token of tokens) {
console.log(`${token.symbol}: ${token.address}`);
}
stats()
async stats(): Promise<Statistics>
Promise<Statistics>
const stats = await giza.stats();
console.log(`Total users: ${stats.total_users}`);
console.log(`Total APR: ${stats.total_apr}%`);
tvl()
async tvl(): Promise<TVLResponse>
Promise<TVLResponse> — { tvl: number }
const { tvl } = await giza.tvl();
console.log(`TVL: $${tvl}`);
Optimizer
The optimizer provides capital allocation recommendations. See the Optimizer reference for full documentation.
optimize(options)
async optimize(options: OptimizeOptions): Promise<OptimizeResponse>
const result = await giza.optimize({
token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
capital: '1000000000', // in token smallest unit
protocols: ['aave', 'compound'],
currentAllocations: { aave: '500000000', compound: '500000000' },
});
console.log('Optimal allocations:', result.optimization_result.allocations);
System
health()
async health(): Promise<HealthcheckResponse>
const health = await giza.health();
console.log(`API version: ${health.version}, status: ${health.message}`);
getApiConfig()
async getApiConfig(): Promise<GlobalConfigResponse>
const config = await giza.getApiConfig();
console.log(`Min withdraw: $${config.min_withdraw_usd}`);
chains()
async chains(): Promise<ChainsResponse>
const { chain_ids } = await giza.chains();
console.log('Supported chains:', chain_ids);
Accessors
getChain()
Returns the Chain enum value configured on this client.
getApiUrl()
Returns the resolved API base URL.
Next Steps
