Withdrawals

Overview

The Agent class provides methods for withdrawing funds, monitoring withdrawal status, and querying fees and limits. Withdrawals come in two forms:

Partial withdrawal: Specify an amount to withdraw while the agent stays active.
Full withdrawal: Omit the amount to deactivate the agent and transfer all funds back to the origin wallet.

withdraw()

Initiate a withdrawal from the agent’s smart account.

Signature

withdraw(amount?: string): Promise<WithdrawResponse>

Parameters

string

Token amount to withdraw, in the token’s smallest unit (e.g., '500000000' for 500 USDC with 6 decimals). When omitted, the agent is fully deactivated and all funds are transferred to the origin wallet.

Returns

Promise<WithdrawResponse> — the response type depends on the withdrawal mode:

Full withdrawal (no amount): Returns FullWithdrawResponse with a confirmation message. The agent begins deactivation.
Partial withdrawal (amount provided): Returns PartialWithdrawResponse with details of the withdrawn tokens.

Response Types

type WithdrawResponse =
  | FullWithdrawResponse
  | PartialWithdrawResponse;

interface FullWithdrawResponse {
  message: string;
}

interface PartialWithdrawResponse {
  date: string;
  amount: number;
  value: number;
  withdraw_details: WithdrawDetail[];
}

interface WithdrawDetail {
  token: string;
  amount: string;
  value: number;
  value_in_usd: number;
  principal_amount?: number;
  yield_amount?: number;
  fee_amount?: number;
  tx_hash?: string;
  block_number?: number;
}

Examples

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

const giza = new Giza({ chain: Chain.BASE });
const agent = giza.agent('0xYourSmartAccountAddress');

// Withdraw 500 USDC (6 decimals)
const result = await agent.withdraw('500000000');

if ('withdraw_details' in result) {
  for (const detail of result.withdraw_details) {
    console.log(`${detail.token}: ${detail.amount}`);
    console.log(`  USD value: $${detail.value_in_usd}`);
    console.log(`  Principal: ${detail.principal_amount}`);
    console.log(`  Yield: ${detail.yield_amount}`);
  }
}

// Full withdrawal: deactivates agent and transfers all funds
const result = await agent.withdraw();

if ('message' in result) {
  console.log(result.message);
}

// Poll until deactivation completes
const finalStatus = await agent.waitForDeactivation({
  interval: 5000,
  timeout: 300000,
  onUpdate: (status) => {
    console.log('Status:', status);
  },
});

console.log('Deactivated:', finalStatus.status);

status()

Get the current status of the agent, including activation and deactivation dates.

Signature

status(): Promise<WithdrawalStatusResponse>

Returns

Promise<WithdrawalStatusResponse>

WithdrawalStatusResponse Type

interface WithdrawalStatusResponse {
  status: AgentStatus;
  wallet: Address;
  activation_date: string;
  last_deactivation_date?: string;
  last_reactivation_date?: string;
}

Examples

const info = await agent.status();

console.log('Status:', info.status);
console.log('Wallet:', info.wallet);
console.log('Activated:', info.activation_date);

if (info.last_deactivation_date) {
  console.log('Last deactivated:', info.last_deactivation_date);
}

waitForDeactivation()

Poll the agent status until it reaches DEACTIVATED. This is used after calling withdraw() without an amount (full withdrawal) to wait for the deactivation process to complete.

Signature

waitForDeactivation(
  options?: WaitForDeactivationOptions
): Promise<WithdrawalStatusResponse>

Parameters

WaitForDeactivationOptions

Polling configuration.

number

Polling interval in milliseconds. Defaults to 5000 (5 seconds). Must be greater than 0.

number

Maximum time to wait in milliseconds. Defaults to 300000 (5 minutes). Must be greater than 0. Throws TimeoutError if exceeded.

(status: AgentStatus) => void

Callback invoked on each poll with the current agent status. Use this to update a progress UI.

Returns

Promise<WithdrawalStatusResponse> — resolves when the agent reaches DEACTIVATED status.

Errors

TimeoutError: Thrown if the timeout is exceeded before the agent is deactivated. The agent may still be deactivating; call status() to check.
ValidationError: Thrown if interval or timeout is not a positive number.

Examples

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

try {
  const finalStatus = await agent.waitForDeactivation({
    interval: 3000,
    timeout: 600000, // 10 minutes
    onUpdate: (status) => {
      console.log(`Current status: ${status}`);
    },
  });

  console.log('Agent deactivated at:', finalStatus.last_deactivation_date);
} catch (error) {
  if (error instanceof TimeoutError) {
    console.log('Still deactivating, check again later');
    const current = await agent.status();
    console.log('Current status:', current.status);
  }
}

fees()

Get the fee information for the agent’s smart account.

Signature

fees(): Promise<FeeResponse>

Returns

Promise<FeeResponse>

FeeResponse Type

interface FeeResponse {
  percentage_fee: number;
  fee: number;
}

Examples

const feeInfo = await agent.fees();

console.log(`Fee percentage: ${feeInfo.percentage_fee}%`);
console.log(`Fee amount: ${feeInfo.fee}`);

limit()

Get the withdrawal limit for a given origin wallet (EOA).

Signature

limit(eoa: Address): Promise<LimitResponse>

Parameters

Address

required

The origin wallet address (0x-prefixed hex string) to check the limit for.

Returns

Promise<LimitResponse>

LimitResponse Type

interface LimitResponse {
  limit: number;
}

Examples

const originWallet = '0xYourOriginWalletAddress' as const;
const limitInfo = await agent.limit(originWallet);

console.log(`Withdrawal limit: ${limitInfo.limit}`);

Complete Withdrawal Flow

This example shows a complete withdrawal flow: checking fees, performing a full withdrawal, and waiting for completion.

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

const giza = new Giza({ chain: Chain.BASE });
const agent = giza.agent('0xYourSmartAccountAddress');

// 1. Check fees before withdrawing
const feeInfo = await agent.fees();
console.log(`Withdrawal fee: ${feeInfo.percentage_fee}%`);

// 2. Check current status
const currentStatus = await agent.status();
console.log(`Agent is: ${currentStatus.status}`);

// 3. Initiate full withdrawal
const result = await agent.withdraw();
console.log('Withdrawal initiated');

// 4. Wait for deactivation
try {
  const finalStatus = await agent.waitForDeactivation({
    interval: 5000,
    timeout: 300000,
    onUpdate: (status) => {
      console.log(`  -> ${status}`);
    },
  });
  console.log('Withdrawal complete:', finalStatus.status);
} catch (error) {
  if (error instanceof TimeoutError) {
    console.log('Withdrawal still processing...');
  } else {
    throw error;
  }
}

After a full withdrawal, the agent is deactivated. To use the agent again, you must re-activate it with agent.activate().

SDK Overview

Agent Class

Utilities

Withdrawals

Overview

withdraw()

Signature

Parameters

Returns

Response Types

Examples

status()

Signature

Returns

WithdrawalStatusResponse Type

Examples

waitForDeactivation()

Signature

Parameters

Returns

Errors

Examples

fees()

Signature

Returns

FeeResponse Type

Examples

limit()

Signature

Parameters

Returns

LimitResponse Type

Examples

Complete Withdrawal Flow

​Overview

​withdraw()

​Signature

​Parameters

​Returns

​Response Types

​Examples

​status()

​Signature

​Returns

​WithdrawalStatusResponse Type

​Examples

​waitForDeactivation()

​Signature

​Parameters

​Returns

​Errors

​Examples

​fees()

​Signature

​Returns

​FeeResponse Type

​Examples

​limit()

​Signature

​Parameters

​Returns

​LimitResponse Type

​Examples

​Complete Withdrawal Flow

Overview

withdraw()

Signature

Parameters

Returns

Response Types

Examples

status()

Signature

Returns

WithdrawalStatusResponse Type

Examples

waitForDeactivation()

Signature

Parameters

Returns

Errors

Examples

fees()

Signature

Returns

FeeResponse Type

Examples

limit()

Signature

Parameters

Returns

LimitResponse Type

Examples

Complete Withdrawal Flow