Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vultlocal.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Quickstart Guide

This guide will help you set up and run OLIVE locally using Docker Compose.

​
Prerequisites

  • Docker and Docker Compose installed
  • At least 4GB of available memory
  • Git to clone the repository

​
Setup

​
1. Clone the Repository

git clone https://github.com/EmmanuelKeifala/olive.git
cd olive

​
2. Configure Environment

Copy the example environment file and configure your settings: 
cp .env.example .env
Edit .env with your configuration: 
# Database
DATABASE_URL=postgres://user:password@localhost:5432/olive

# JWT Secret (generate a strong secret)
JWT_SECRET=your-secure-jwt-secret-minimum-32-chars

# OpenAI (for agent-ts)
OPENAI_API_KEY=sk-...

# AWS S3 (for KYC document storage)
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_S3_BUCKET_NAME=olive-kyc-documents
AWS_REGION=us-east-1

​
3. Start Services

docker compose up -d --build gateway wallet-core agent

​
4. Verify Health

curl http://localhost:8080/health
Expected response: 
{
  "service": "gateway",
  "version": "1.0.0",
  "healthy": true,
  "wallet_core": {
    "healthy": true,
    "version": "1.0.0"
  }
}

​
Your First API Call

​
Check Balance

curl -X GET "http://localhost:8080/api/v1/balance/user123" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Create a Payment

curl -X POST "http://localhost:8080/api/v1/payments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user123",
    "recipient": "merchant456",
    "amount": 5000,
    "currency": "SLE",
    "memo": "Payment for goods"
  }'

​
Service Ports

ServicePortProtocol
Gateway8080HTTP/REST
Agent8000HTTP/REST
Wallet-Core50051gRPC
PostgreSQL5432TCP

​
Viewing Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f gateway
docker compose logs -f wallet-core
docker compose logs -f agent

​
Stopping Services

docker compose down

​
Next Steps

Subscriber Registration

Learn how to register users and complete KYC

API Reference

Explore all available endpoints

Agent-TS

Set up the WhatsApp conversational agent

Security

Configure authentication and TLS