Giza Client

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)

Creates a new SDK client. See the GizaConfig reference for all available options.

config

GizaConfig

required

Configuration object specifying the target chain and credentials.

The constructor validates all inputs and resolves environment variable fallbacks. It throws a 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)

If neither the config field nor the environment variable is set, the constructor throws a 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

Returns an 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).

wallet

Address

required

The smart-account wallet address (0x-prefixed hex string).

Returns: Agent

const agent = giza.agent('0x1234567890abcdef1234567890abcdef12345678');
const info = await agent.portfolio();

`createAgent(eoa)`

async createAgent(eoa: Address): Promise<Agent>

Creates a new smart account for the given externally-owned account (EOA) and returns an Agent bound to the new smart-account address.

eoa

Address

required

The user’s externally-owned account address.

Returns: 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>

Looks up an existing smart account by EOA and returns an Agent bound to it. Use this when the smart account was created previously and you need to recover the handle.

eoa

Address

required

The user’s externally-owned account address.

Returns: Promise<Agent>

const agent = await giza.getAgent('0xUserEOA...');
const portfolio = await agent.portfolio();

`getSmartAccount(eoa)`

async getSmartAccount(eoa: Address): Promise<SmartAccountInfo>

Returns full smart-account metadata (address, backend wallet, origin wallet, chain) without creating an Agent handle. Useful when you need the raw account data.

eoa

Address

required

The user’s externally-owned account address.

Returns: 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>

Returns the list of active protocol names available for a given token on the current chain.

token

Address

required

The token contract address.

Returns: 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>

Returns supply data for each protocol supporting the given token.

token

Address

required

The token contract address.

Returns: 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>

Returns all supported tokens on the current chain with their metadata (address, symbol, decimals, balance, price). Returns: 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>

Returns aggregate statistics for the current chain: total balance, deposits, users, transactions, APR, and liquidity distribution. Returns: 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>

Returns the total value locked on the current chain. Returns: 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>

Computes optimal capital allocation across protocols for a given token and capital amount. Returns the allocation plan, action steps, and execution-ready calldata.

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>

Returns the API health status, version, and server time.

const health = await giza.health();
console.log(`API version: ${health.version}, status: ${health.message}`);

`getApiConfig()`

async getApiConfig(): Promise<GlobalConfigResponse>

Returns the global API configuration, including minimum withdrawal thresholds, optimizer settings, and per-chain configuration.

const config = await giza.getApiConfig();
console.log(`Min withdraw: $${config.min_withdraw_usd}`);

`chains()`

async chains(): Promise<ChainsResponse>

Returns the list of supported chain IDs.

const { chain_ids } = await giza.chains();
console.log('Supported chains:', chain_ids);

Accessors

`getChain()`

getChain(): Chain

Returns the Chain enum value configured on this client.

`getApiUrl()`

getApiUrl(): string

Returns the resolved API base URL.

Next Steps

Agent Class

Wallet-scoped lifecycle, monitoring, and operations

Optimizer

Capital allocation optimization

Overview

SDK architecture and configuration reference

Quickstart

End-to-end integration tutorial

SDK Overview

Agent Class

Utilities

Giza Client

Overview

Constructor

Environment Variable Fallback

Agent Factory Methods

`agent(wallet)`

`createAgent(eoa)`

`getAgent(eoa)`

`getSmartAccount(eoa)`

Chain-Level Queries

`protocols(token)`

`protocolSupply(token)`

`tokens()`

`stats()`

`tvl()`

Optimizer

`optimize(options)`

System

`health()`

`getApiConfig()`

`chains()`

Accessors

`getChain()`

`getApiUrl()`

Next Steps

Agent Class

Optimizer

Overview

Quickstart

SDK Overview

Agent Class

Utilities

​Overview

​Constructor

​Environment Variable Fallback

​Agent Factory Methods

​agent(wallet)

​createAgent(eoa)

​getAgent(eoa)

​getSmartAccount(eoa)

​Chain-Level Queries

​protocols(token)

​protocolSupply(token)

​tokens()

​stats()

​tvl()

​Optimizer

​optimize(options)

​System

​health()

​getApiConfig()

​chains()

​Accessors

​getChain()

​getApiUrl()

​Next Steps

Agent Class

Optimizer

Overview

Quickstart

Overview

Constructor

Environment Variable Fallback

Agent Factory Methods

`agent(wallet)`

`createAgent(eoa)`

`getAgent(eoa)`

`getSmartAccount(eoa)`

Chain-Level Queries

`protocols(token)`

`protocolSupply(token)`

`tokens()`

`stats()`

`tvl()`

Optimizer

`optimize(options)`

System

`health()`

`getApiConfig()`

`chains()`

Accessors

`getChain()`

`getApiUrl()`

Next Steps