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

Quick Start

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.

Configuration

All configuration is passed through the GizaConfig interface. Credentials fall back to environment variables when omitted.
ParameterTypeRequiredDefaultEnv FallbackDescription
chainChainYesTarget blockchain network
apiKeystringNoGIZA_API_KEYPartner API key
partnerstringNoGIZA_PARTNER_NAMEPartner identifier
apiUrlstringNoGIZA_API_URLGiza backend URL
timeoutnumberNo45000HTTP request timeout in ms
enableRetrybooleanNofalseAuto-retry on 5xx and network errors

Supported Chains

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.

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