> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gizatech.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> TypeScript SDK for building on Giza autonomous yield agents

## 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.

<Info>
  The SDK wraps the [HTTP API](/api-reference/introduction) in a convenient TypeScript interface with automatic authentication, type safety, and structured error handling.
</Info>

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @gizatech/agent-sdk
  ```

  ```bash bun theme={null}
  bun add @gizatech/agent-sdk
  ```

  ```bash yarn theme={null}
  yarn add @gizatech/agent-sdk
  ```
</CodeGroup>

## Quick Start

```typescript theme={null}
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.

```typescript theme={null}
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 |

```typescript theme={null}
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

```typescript theme={null}
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.

```typescript theme={null}
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         |

<Card title="HTTP API Reference" icon="code" href="/api-reference/introduction">
  For direct HTTP access or non-JavaScript integrations, see the API Reference.
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Giza Client" icon="plug" href="/sdk-reference/giza">
    Client configuration, agent factory methods, and chain-level queries
  </Card>

  <Card title="Agent Class" icon="robot" href="/sdk-reference/agent/overview">
    Wallet-scoped lifecycle, monitoring, withdrawals, and rewards
  </Card>

  <Card title="Optimizer" icon="brain" href="/sdk-reference/optimizer">
    Capital allocation optimization
  </Card>

  <Card title="Quickstart" icon="rocket" href="/developers/quickstart">
    End-to-end integration tutorial
  </Card>
</CardGroup>