Skip to main content

Introduction

The @gizatech/agent-sdk is a TypeScript SDK that provides a simple and type-safe interface for interacting with Giza’s autonomous DeFi yield optimization agents.
The SDK wraps the HTTP API in a convenient TypeScript interface with automatic authentication, type safety, and error handling.

Installation

npm install @gizatech/agent-sdk

Quick Start

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

// Environment variables required:
// GIZA_API_KEY=your-partner-api-key
// GIZA_API_URL=https://partners-backend-1038109371738.europe-west1.run.app
// GIZA_PARTNER_NAME=your-partner-name

const giza = new GizaAgent({
  chainId: Chain.BASE,
});

// Create smart account
const account = await giza.agent.createSmartAccount({
  origin_wallet: '0x...'
});

// Activate agent after user deposits
await giza.agent.activate({
  wallet: account.smartAccountAddress,
  origin_wallet: '0x...',
  initial_token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC
  selected_protocols: ['aave', 'compound', 'moonwell'],
  tx_hash: depositTxHash,
});

// Monitor performance
const performance = await giza.agent.getPerformance({
  wallet: account.smartAccountAddress,
});

SDK Architecture

The SDK is organized into two main modules:

Configuration

The SDK reads configuration from environment variables:
VariableRequiredDescription
GIZA_API_KEYYesYour partner API key
GIZA_API_URLYesGiza backend URL
GIZA_PARTNER_NAMEYesYour partner identifier
Additional options can be passed to the constructor:
const giza = new GizaAgent({
  chainId: Chain.BASE,     // Required: Target blockchain
  timeout: 60000,          // Optional: Request timeout in ms (default: 30000)
  enableRetry: true,       // Optional: Retry failed requests (default: false)
  agentId: 'agent-1',      // Optional: Custom agent ID
});

Supported Chains

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

Chain.BASE          // 8453 - Base Mainnet
Chain.ETHEREUM      // 1 - Ethereum Mainnet
Chain.ARBITRUM      // 42161 - Arbitrum One
Chain.POLYGON       // 137 - Polygon Mainnet
Chain.BASE_SEPOLIA  // 84532 - Base Sepolia (testnet)
Chain.SEPOLIA       // 11155111 - Sepolia (testnet)

Error Handling

The SDK provides typed errors for common failure scenarios:
import { 
  ValidationError, 
  GizaAPIError, 
  TimeoutError, 
  NetworkError 
} from '@gizatech/agent-sdk';

try {
  await giza.agent.activate({...});
} catch (error) {
  if (error instanceof ValidationError) {
    // Invalid input parameters
    console.error('Validation failed:', error.message);
  } else if (error instanceof GizaAPIError) {
    // API returned an error
    console.error(`API Error [${error.statusCode}]:`, error.message);
  } else if (error instanceof TimeoutError) {
    // Request timed out
    console.error('Request timed out:', error.message);
  } else if (error instanceof NetworkError) {
    // Network connectivity issue
    console.error('Network error:', error.message);
  }
}

SDK vs HTTP API

FeatureSDKHTTP API
Type Safety✅ Full TypeScript types❌ Manual typing
Authentication✅ AutomaticManual headers
Error Handling✅ Typed errorsManual parsing
Retries✅ Built-inManual implementation
LanguageTypeScript/JavaScriptAny HTTP client

HTTP API Reference

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

Next Steps