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

# Quickstart

> Install the SDK, create a smart account, and activate an agent

## Overview

This guide walks through the Giza Agent SDK from installation to a running agent. You'll create a smart account, activate an agent, and start yield optimization.

<Note>
  This quickstart focuses on the **Agentic integration** -- Giza handles smart accounts, execution, gas, and optimization. If you have your own execution infrastructure and just want optimization intelligence, see the [IaaS Integration Guide](/developers/guides/iaas-integration).
</Note>

## What Giza Manages vs What You Build

| Giza manages                     | You build            |
| -------------------------------- | -------------------- |
| Smart account creation (ZeroDev) | User interface       |
| Session key management           | Deposit flow         |
| Transaction execution            | Performance display  |
| Gas payment                      | Withdrawal requests  |
| Continuous optimization          | Notification systems |
| Protocol rebalancing             | User authentication  |

## Architecture

```mermaid theme={null}
graph TB
    A[Your Application] --> B[Giza Agent SDK]
    B --> C[Giza Backend API]
    C --> D[Agent Service]
    D --> E[Smart Account]
    E --> F1[Aave]
    E --> F2[Compound]
    E --> F3[Moonwell]
    E --> F4[Other Protocols]

    G[User] -->|Deposit| E
    G -->|Monitor| A
    A -->|Performance Data| G
```

## Prerequisites

<AccordionGroup>
  <Accordion title="Node.js 18+">
    Check your version: `node --version`

    Download from [nodejs.org](https://nodejs.org/) if needed.
  </Accordion>

  <Accordion title="TypeScript Project">
    The SDK is built for TypeScript. JavaScript works too, but without type safety.
  </Accordion>

  <Accordion title="Giza API Credentials">
    You'll need:

    * `GIZA_API_KEY` - Your partner API key
    * `GIZA_API_URL` - Giza backend URL
    * `GIZA_PARTNER_NAME` - Your partner identifier

    <Card title="Get API Keys" icon="key" href="https://docs.google.com/forms/d/e/1FAIpQLScuKxm2JybRaxj3dUYLR_BYXUdCPDYV9BGW5PC-8g0K_7ZKXg/viewform?usp=publish-editor">
      Request API keys from Giza teams.
    </Card>
  </Accordion>
</AccordionGroup>

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

## Environment Setup

Create a `.env` file in your project root:

```bash .env theme={null}
GIZA_API_KEY=...
GIZA_API_URL=...
GIZA_PARTNER_NAME=...
```

<Warning>
  Never commit your `.env` file to version control! Add it to `.gitignore`.
</Warning>

## Complete Integration Flow

### Step 1: Initialize the SDK

```typescript theme={null}
import { Giza, Chain } from '@gizatech/agent-sdk';

// Initialize once, reuse throughout your app
const giza = new Giza({
  chain: Chain.BASE,
  timeout: 60000,      // Optional: 60s timeout
  enableRetry: true,   // Optional: retry failed requests
});
```

### Step 2: Create a Smart Account

Generate a smart account for your user. This is where they'll deposit funds.

```typescript theme={null}
async function onboardUser(userWallet: `0x${string}`) {
  const agent = await giza.createAgent(userWallet);

  console.log('Smart Account:', agent.wallet);
  console.log('Deposit funds to this address');

  return agent;
}
```

<Tip>
  The smart account address is **deterministic** - calling `giza.createAgent` with the same EOA always returns the same address.
</Tip>

### Step 3: Get Available Protocols

Check which DeFi protocols are available for the token you want to optimize:

```typescript theme={null}
const USDC_BASE = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';

const { protocols } = await giza.protocols(USDC_BASE);

console.log('Available protocols:', protocols);
// ['aave', 'compound', 'moonwell', 'fluid', ...]
```

### Step 4: User Deposits Funds

<Steps>
  <Step title="User sends tokens to smart account">
    User transfers USDC (or supported token) to the `agent.wallet` address from Step 2.
  </Step>

  <Step title="Wait for confirmation">
    Wait for the transaction to be confirmed on-chain.
  </Step>
</Steps>

```typescript theme={null}
// Example: User deposits via your UI
const depositTxHash = await userWallet.sendTransaction({
  to: agent.wallet,
  value: parseUnits('1000', 6), // 1000 USDC (6 decimals)
});
```

### Step 5: Activate the Agent

After the user deposits, activate the agent to start optimization:

```typescript theme={null}
await agent.activate({
  owner: userWallet,
  token: USDC_BASE,
  protocols: ['aave', 'compound', 'moonwell'],
  txHash: depositTxHash,
  constraints: [
    {
      kind: 'min_protocols',
      params: { min_protocols: 2 } // Always diversify
    }
  ]
});
```

<Info>
  Once activated, the agent automatically:

  * Monitors APRs across selected protocols
  * Rebalances capital for optimal yield
  * Handles all gas costs internally
  * Continues optimizing until deactivated
</Info>

### Step 6: Monitor Performance

Track the agent's performance:

```typescript theme={null}
// Get current portfolio status
const info = await agent.portfolio();

console.log('Status:', info.status);

// Get APR
const { apr } = await agent.apr();

console.log(`Current APR: ${apr.toFixed(2)}%`);

// Get performance history
const { performance } = await agent.performance();

performance.forEach(point => {
  console.log(`${point.date}: $${point.value_in_usd}`);
});
```

### Step 7: Withdraw Funds

Users can withdraw partially or fully at any time:

<Tabs>
  <Tab title="Full Withdrawal">
    ```typescript theme={null}
    // Withdraw everything and deactivate agent
    await agent.withdraw();

    // Wait for completion
    await agent.waitForDeactivation({
      interval: 5000,
      timeout: 300000,
      onUpdate: (status) => console.log('Status:', status),
    });
    ```
  </Tab>

  <Tab title="Partial Withdrawal">
    ```typescript theme={null}
    // Withdraw specific amount, agent stays active
    await agent.withdraw('500000000'); // 500 USDC (6 decimals)
    // Agent continues optimizing remaining balance
    ```
  </Tab>
</Tabs>

## Additional Operations

### Top-Up Active Agent

```typescript theme={null}
await agent.topUp(newDepositTxHash);
```

### Update Protocols

```typescript theme={null}
await agent.updateProtocols(['aave', 'compound', 'moonwell', 'fluid']);
```

### Manual Rebalance

```typescript theme={null}
await agent.run();
```

## Multi-Chain Management

Run agents on multiple chains simultaneously:

```typescript theme={null}
import { Giza, Chain } from '@gizatech/agent-sdk';

const baseGiza = new Giza({ chain: Chain.BASE });
const arbGiza = new Giza({ chain: Chain.ARBITRUM });

const baseAgent = await baseGiza.createAgent(userWallet);
const arbAgent = await arbGiza.createAgent(userWallet);

const [baseApr, arbApr] = await Promise.all([
  baseAgent.apr(),
  arbAgent.apr(),
]);

console.log('Base APR:', baseApr.apr);
console.log('Arbitrum APR:', arbApr.apr);
```

## Constraint-Based Risk Management

Use [constraints](/developers/architecture/constraints) to control agent behavior:

```typescript theme={null}
await agent.activate({
  owner: userWallet,
  token: USDC,
  protocols: ['aave', 'compound', 'moonwell', 'fluid'],
  txHash: depositTxHash,
  constraints: [
    // Diversify across at least 3 protocols
    { kind: 'min_protocols', params: { min_protocols: 3 } },
    // Cap newer protocol at 30%
    {
      kind: 'max_amount_per_protocol',
      params: { protocol: 'fluid', max_ratio: 0.3 },
    },
    // No dust allocations
    { kind: 'min_amount', params: { min_amount: '100000000' } },
  ],
});
```

## Error Handling

Wrap SDK calls in try-catch blocks:

```typescript theme={null}
import { ValidationError, GizaAPIError, TimeoutError } from '@gizatech/agent-sdk';

try {
  const agent = await giza.createAgent(userWallet);
} 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('Request timed out');
  }
}
```

<Card title="Error Handling Guide" icon="shield-exclamation" href="/developers/guides/error-handling">
  Error types, retry patterns, and user-friendly messages
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Architecture" icon="building" href="/developers/architecture/overview">
    Understand smart accounts, agents, and protocols
  </Card>

  <Card title="SDK Reference" icon="code" href="/sdk-reference/overview">
    Explore all SDK methods
  </Card>

  <Card title="API Reference" icon="server" href="/api-reference/introduction">
    HTTP API documentation
  </Card>

  <Card title="IaaS Integration" icon="brain" href="/developers/guides/iaas-integration">
    Use Optimizer with your own infrastructure
  </Card>
</CardGroup>