Skip to main content

​
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

​
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:
  1. Create a Giza client with your chain and credentials.
  2. Obtain an Agent via giza.createAgent(eoa), giza.getAgent(eoa), or giza.agent(wallet).
  3. 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.
ParameterTypeRequiredDefaultEnv FallbackDescription
chainChainYes——Target blockchain network
apiKeystringNo—GIZA_API_KEYPartner API key
partnerstringNo—GIZA_PARTNER_NAMEPartner identifier
apiUrlstringNo—GIZA_API_URLGiza backend URL
timeoutnumberNo45000—HTTP request timeout in ms
enableRetrybooleanNofalse—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 ClassWhen It Occurs
ValidationErrorInvalid input parameters (bad address format, missing fields)
GizaAPIErrorAPI returned an HTTP error (includes statusCode and message)
TimeoutErrorRequest exceeded the configured timeout
NetworkErrorNetwork 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

FeatureSDKHTTP API
Type SafetyFull TypeScript typesManual typing
AuthenticationAutomatic via config/envManual headers
Error HandlingTyped error classesManual response parsing
RetriesBuilt-in (opt-in)Manual implementation
PaginationAsync-iterable PaginatorManual page tracking
LanguageTypeScript / JavaScriptAny 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