AI Portal

AI Portal is a prepaid escrow-based API gateway for wallet-authenticated LLM usage. It provides an OpenAI-compatible API with on-chain settlement for AI inference costs.

• server: Handles API requests, user authentication, billing, and manages communication with LLM providers.
• worker: Processes AI inference settlements.

Getting Started

Prerequisites

• Go 1.23+
• PostgreSQL 15+
• ZetaChain RPC endpoint
• golangci-lint v2 (for development)

  go install github.com/golangci/golangci-lint/v2/cmd/[email protected]

Accessing the Private Escrow Contract Repository

The escrow contract sources live in the private github.com/zeta-chain/escrow-contract repository. Configure Go and Git to always use SSH when cloning from github.com/zeta-chain/* to avoid authentication errors:

1. Set GOPRIVATE (note that you can add this to your shell profile):

   export GOPRIVATE=github.com/zeta-chain/*

2. Update your ~/.gitconfig to prefer the SSH remote for GitHub:

   [url "[email protected]:"]
           insteadOf = https://github.com/

Installation

make install

Install only server

make install-server

Install only worker

make install-worker

Configuration

See .env.example for available configuration options. Create .env with based on this file.

Running Tests

make test

Generate API specification and client

make generate

This command regenerates both the Swagger specification in docs and the TypeScript client in typescript.

Run E2E Test

The e2e tests use two configuration files:

• .env.test (committed): All public test configuration values
• .env.test.local (gitignored): Secrets like GITHUB_PAT and optional Privy credentials

Setup:

1. The .env.test file is already in the repository with all public test values
2. Create a .env.test.local file (gitignored) with your secrets:

   # Required for Docker builds (private repos)
   GITHUB_PAT=your_github_pat_here

Authentication coverage:

| E2E test | Authentication | | --- | --- | | chat_completion | Privy JWT (Bearer token) | | chat_completion_stream | Privy JWT (Bearer token) | | embeddings | Privy JWT (Bearer token) | | response_api_chat | Privy JWT (Bearer token) | | response_api_image_gen | Privy JWT (Bearer token) | | chat_completions_image | Privy JWT (Bearer token) | | chat_completion_api_key | API key (X-API-Key) | | chat_completion_stream_api_key | API key (X-API-Key) |

Run E2E tests:

Single command to start everything and run E2E tests:

make test-e2e

This will:

1. Start all Docker services (Anvil, Postgres, Server, Worker)
2. Deploy contracts to Anvil
3. Submit api requests
4. Worker detects contracts and starts processing
5. Verify entries in Postgres DB are created

Running with Frontend

To run the local development environment with the frontend UI:

make localnet-frontend

Note: The frontend image (ai-memoryless-client) must be built first from the ai-memoryless-client repository:

docker build -f apps/web/Dockerfile -t ai-memoryless-client \
  --build-arg NEXT_PUBLIC_API_URL=http://localhost:8080 \
  --build-arg NEXT_PUBLIC_PRIVY_APP_ID=<privy-app-id> \
  .

The frontend will be available at http://localhost:8787.

Deployment

AI Portal is deployed to two environments:

| Environment | URL | Deployment | |-------------|-----|------------| | Dev | https://portal.anuma-dev.ai | Automatic on push to main | | Prod | https://portal.anuma.ai | Manual with version tags |

See INFRASTRUCTURE.md for detailed deployment instructions and CI/CD documentation.