Authentication

Overview

The Giza API uses API key authentication. Authenticated endpoints require two headers on each request.

Required Headers

X-Partner-API-Key: your-api-key
X-Partner-Name: your-partner-name

Example Request

curl -X POST "https://partners-backend-1038109371738.europe-west1.run.app/api/v1/8453/wallets" \
  -H "Content-Type: application/json" \
  -H "X-Partner-API-Key: your-api-key" \
  -H "X-Partner-Name: your-partner-name" \
  -d '{
    "wallet": "0x1234567890abcdef1234567890abcdef12345678",
    "eoa": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    "initial_token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "selected_protocols": ["aave", "compound", "moonwell"]
  }'

Obtaining API Credentials

Contact Giza

Reach out to the Giza team to request partner access.

Request Access

Visit gizatech.xyz to get started

Receive Credentials

You’ll receive:

API Key: A unique key for authentication
Partner Name: Your registered partner identifier
Backend URL: The API endpoint URL

Configure Environment

Store credentials securely as environment variables:

.env

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

Authentication Scopes

Different endpoints require different authentication levels:

Public Endpoints (No Auth Required)

These endpoints can be called without authentication:

Endpoint	Description
`GET /api/v1/healthcheck`	Health check
`GET /api/v1/chains`	List supported chains
`GET /api/v1/{chain_id}/tokens`	List supported tokens
`GET /api/v1/{chain_id}/{token}/protocols`	Get protocol information
`GET /api/v1/{chain_id}/wallets/{wallet}`	Get wallet information (read-only)
`GET /api/v1/{chain_id}/stats`	Get statistics

Authenticated Endpoints

These endpoints require API key authentication:

Endpoint	Description
`POST /api/v1/{chain_id}/wallets`	Activate wallet
`POST /api/v1/{chain_id}/wallets/{wallet}:deactivate`	Deactivate wallet
`POST /api/v1/{chain_id}/wallets/{wallet}:withdraw`	Withdraw funds
`POST /api/v1/{chain_id}/wallets/{wallet}:run`	Trigger agent run
`POST /api/v1/{chain_id}/wallets/{wallet}:top-up`	Top up wallet
`POST /api/v1/{chain_id}/wallets/{wallet}:claim-rewards`	Claim rewards
`PUT /api/v1/{chain_id}/wallets/{wallet}/protocols`	Update protocols
`POST /api/v1/optimizer/{chain_id}/optimize`	Optimize allocation

Error Responses

Invalid or Missing API Key

{
  "detail": "Invalid or missing API key"
}

HTTP Status: 401 Unauthorized

Access Denied

{
  "detail": "Access denied"
}

HTTP Status: 403 Forbidden This occurs when:

Trying to access another partner’s wallet
API key is inactive
Partner doesn’t have permission for the operation

Security Best Practices

Never expose your API key in client-side code! Always make API calls from your backend server.

Store credentials securely

Use environment variables, not hardcoded strings
Never commit .env files to version control
Use a secrets manager in production (AWS Secrets Manager, HashiCorp Vault, etc.)

Rotate keys periodically

Contact Giza to regenerate your API key if:

You suspect it’s been compromised
An employee with access leaves your organization
As part of regular security hygiene

Use HTTPS only

Always use HTTPS when making API requests. Never send API keys over unencrypted connections.

Implement server-side calls

Make all authenticated API calls from your backend:

// ✅ Good: Server-side API call
// pages/api/activate.ts (Next.js)
export default async function handler(req, res) {
  const response = await fetch('https://api.giza.../wallets', {
    headers: {
      'X-Partner-API-Key': process.env.GIZA_API_KEY,
      'X-Partner-Name': process.env.GIZA_PARTNER_NAME,
    },
    body: req.body,
  });
  res.json(await response.json());
}

// ❌ Bad: Client-side API call (exposes key!)
// Don't do this in frontend code
fetch('https://api.giza.../wallets', {
  headers: {
    'X-Partner-API-Key': 'exposed-key', // NEVER DO THIS
  },
});

Using with the SDK

The TypeScript SDK handles authentication automatically:

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

// SDK reads from environment variables:
// - GIZA_API_KEY
// - GIZA_PARTNER_NAME
// - GIZA_API_URL

const giza = new Giza({
  chain: Chain.BASE,
});

// Authentication headers are added automatically
const agent = await giza.createAgent('0x...');
await agent.activate({...});

SDK Overview

We recommend using the SDK for simplified authentication

Next Steps

Activate Wallet

Create your first agent

Get Protocols

Discover available protocols

API Overview

Agents

Protocols

Optimizer

Statistics

Rewards

Support

Authentication

Overview

Required Headers

Example Request

Obtaining API Credentials

Request Access

Authentication Scopes

Public Endpoints (No Auth Required)

Authenticated Endpoints

Error Responses

Invalid or Missing API Key

Access Denied

Security Best Practices

Using with the SDK

SDK Overview

Next Steps

Activate Wallet

Get Protocols

​Overview

​Required Headers

​Example Request

​Obtaining API Credentials

Request Access

​Authentication Scopes

​Public Endpoints (No Auth Required)

​Authenticated Endpoints

​Error Responses

​Invalid or Missing API Key

​Access Denied

​Security Best Practices

​Using with the SDK

SDK Overview

​Next Steps

Activate Wallet

Get Protocols

Overview

Required Headers

Example Request

Obtaining API Credentials

Authentication Scopes

Public Endpoints (No Auth Required)

Authenticated Endpoints

Error Responses

Invalid or Missing API Key

Access Denied

Security Best Practices

Using with the SDK

Next Steps