Overview

Introduction

The @gizatech/agent-sdk is a TypeScript SDK for managing Giza DeFi yield optimization agents. It provides a resource-oriented, type-safe interface and handles authentication, request retries, pagination, and error handling.

The SDK wraps the HTTP API in a convenient TypeScript interface with automatic authentication, type safety, and structured error handling.

Installation

npm install @gizatech/agent-sdk

bun add @gizatech/agent-sdk

yarn add @gizatech/agent-sdk

Quick Start

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

// Credentials fall back to GIZA_API_KEY, GIZA_PARTNER_NAME, GIZA_API_URL env vars
const giza = new Giza({ chain: Chain.BASE });

// Create a smart-account agent for a user's EOA
const agent = await giza.createAgent('0xYourEOA...');

// Activate the agent after the user deposits USDC
await agent.activate({
  owner: '0xYourEOA...',
  token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base
  protocols: ['aave', 'compound'],
  txHash: '0xDepositTxHash...',
});

// Check the current APR
const { apr } = await agent.apr();
console.log(`Current APR: ${apr}%`);

SDK Architecture

The SDK follows a resource-oriented design with two primary classes:

Giza — the top-level client. Handles configuration, authentication, and chain-level queries (protocols, tokens, stats, optimizer). It also acts as a factory for Agent instances.
Agent — a wallet-scoped handle bound to a single smart-account address. All agent lifecycle, monitoring, withdrawal, rewards, and protocol operations live here. You never pass a wallet address to individual methods because the Agent already knows it.

The typical flow is:

Create a Giza client with your chain and credentials.
Obtain an Agent via giza.createAgent(eoa), giza.getAgent(eoa), or giza.agent(wallet).
Call methods on the Agent instance for all wallet-scoped operations.

const giza = new Giza({ chain: Chain.BASE });

// Three ways to get an Agent handle:
const agent1 = await giza.createAgent('0xEOA...');    // new smart account
const agent2 = await giza.getAgent('0xEOA...');       // existing smart account
const agent3 = giza.agent('0xSmartAccount...');        // known address, no API call

Configuration

All configuration is passed through the GizaConfig interface. Credentials fall back to environment variables when omitted.

Parameter	Type	Required	Default	Env Fallback	Description
`chain`	`Chain`	Yes	—	—	Target blockchain network
`apiKey`	`string`	No	—	`GIZA_API_KEY`	Partner API key
`partner`	`string`	No	—	`GIZA_PARTNER_NAME`	Partner identifier
`apiUrl`	`string`	No	—	`GIZA_API_URL`	Giza backend URL
`timeout`	`number`	No	`45000`	—	HTTP request timeout in ms
`enableRetry`	`boolean`	No	`false`	—	Auto-retry on 5xx and network errors

const giza = new Giza({
  chain: Chain.BASE,
  apiKey: 'your-api-key',       // or set GIZA_API_KEY
  partner: 'your-partner',      // or set GIZA_PARTNER_NAME
  apiUrl: 'https://api.gizatech.xyz', // or set GIZA_API_URL
  timeout: 60000,
  enableRetry: true,
});

Supported Chains

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

Chain.ETHEREUM       // 1     - Ethereum Mainnet
Chain.POLYGON        // 137   - Polygon Mainnet
Chain.BASE           // 8453  - Base Mainnet
Chain.ARBITRUM       // 42161 - Arbitrum One
Chain.SEPOLIA        // 11155111 - Sepolia Testnet
Chain.BASE_SEPOLIA   // 84532 - Base Sepolia Testnet
Chain.DEVNET         // -1    - Development Network

Error Handling

The SDK provides a typed error hierarchy so you can handle failures precisely:

Error Class	When It Occurs
`ValidationError`	Invalid input parameters (bad address format, missing fields)
`GizaAPIError`	API returned an HTTP error (includes `statusCode` and `message`)
`TimeoutError`	Request exceeded the configured timeout
`NetworkError`	Network connectivity failure (DNS, connection refused)

All errors extend the base GizaError class.

import {
  ValidationError,
  GizaAPIError,
  TimeoutError,
  NetworkError,
} from '@gizatech/agent-sdk';

try {
  await agent.activate({ /* ... */ });
} 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('Timed out:', error.message);
  } else if (error instanceof NetworkError) {
    console.error('Network failure:', error.message);
  }
}

SDK vs HTTP API

Feature	SDK	HTTP API
Type Safety	Full TypeScript types	Manual typing
Authentication	Automatic via config/env	Manual headers
Error Handling	Typed error classes	Manual response parsing
Retries	Built-in (opt-in)	Manual implementation
Pagination	Async-iterable `Paginator`	Manual page tracking
Language	TypeScript / JavaScript	Any HTTP client

HTTP API Reference

For direct HTTP access or non-JavaScript integrations, see the API Reference.

Next Steps

Giza Client

Client configuration, agent factory methods, and chain-level queries

Agent Class

Wallet-scoped lifecycle, monitoring, withdrawals, and rewards

Optimizer

Capital allocation optimization

Quickstart

End-to-end integration tutorial

SDK Overview

Agent Class

Utilities

Introduction

Installation

Quick Start

SDK Architecture

Configuration

Supported Chains

Error Handling

SDK vs HTTP API

HTTP API Reference

Next Steps

Giza Client

Agent Class

Optimizer

Quickstart

​Introduction

​Installation

​Quick Start

​SDK Architecture

​Configuration

​Supported Chains

​Error Handling

​SDK vs HTTP API

HTTP API Reference

​Next Steps

Giza Client

Agent Class

Optimizer

Quickstart

Introduction

Installation

Quick Start

SDK Architecture

Configuration

Supported Chains

Error Handling

SDK vs HTTP API

Next Steps