Documentation › Components › Coordinator API
Back to Components

Coordinator API

FastAPI service for job submission, miner registration, and receipt management with SQLite persistence

● Live

Overview

The Coordinator API is the central orchestration layer that manages job distribution between clients and miners in the AITBC network. It handles job submissions, miner registrations, and tracks all computation receipts.

Key Features

  • Job submission and tracking
  • Miner registration and heartbeat monitoring
  • Receipt management and verification
  • User management with wallet-based authentication
  • SQLite persistence with SQLModel ORM
  • Comprehensive API documentation with OpenAPI

Architecture

The Coordinator API follows a clean architecture with separation of concerns for domain models, API routes, and business logic.

API Layer

FastAPI routers for clients, miners, admin, and users

Domain Models

SQLModel definitions for jobs, miners, receipts, users

Business Logic

Service layer handling job orchestration

Persistence

SQLite database with Alembic migrations

API Reference

The Coordinator API provides RESTful endpoints for all major operations.

Client Endpoints

POST /v1/client/jobs

Submit a new computation job

GET /v1/client/jobs/{job_id}/status

Get job status and progress

GET /v1/client/jobs/{job_id}/receipts

Retrieve computation receipts

Miner Endpoints

POST /v1/miner/register

Register as a compute provider

POST /v1/miner/heartbeat

Send miner heartbeat

GET /v1/miner/jobs

Fetch available jobs

POST /v1/miner/result

Submit job result

User Management

POST /v1/users/login

Login or register with wallet

GET /v1/users/me

Get current user profile

GET /v1/users/{user_id}/balance

Get user wallet balance

Exchange Endpoints

POST /v1/exchange/create-payment

Create Bitcoin payment request

GET /v1/exchange/payment-status/{id}

Check payment status

Authentication

The API uses API key authentication for clients and miners, and session-based authentication for users.

API Keys

X-Api-Key: your-api-key-here

Session Tokens

X-Session-Token: sha256-token-here

Example Request

curl -X POST "https://aitbc.bubuit.net/api/v1/client/jobs" \
  -H "X-Api-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "job_type": "llm_inference",
    "parameters": {...}
  }'

Configuration

The Coordinator API can be configured via environment variables.

Environment Variables

# Database
DATABASE_URL=sqlite:///coordinator.db

# API Settings
API_HOST=0.0.0.0
API_PORT=8000

# Security
SECRET_KEY=your-secret-key
API_KEYS=key1,key2,key3

# Exchange
BITCOIN_ADDRESS=tb1qxy2...
BTC_TO_AITBC_RATE=100000

Deployment

The Coordinator API runs in a Docker container with nginx proxy.

Docker Deployment

# Build image
docker build -t aitbc-coordinator .

# Run container
docker run -d \
  --name aitbc-coordinator \
  -p 8000:8000 \
  -e DATABASE_URL=sqlite:///data/coordinator.db \
  -v $(pwd)/data:/app/data \
  aitbc-coordinator

Systemd Service

# Start service
sudo systemctl start aitbc-coordinator

# Check status
sudo systemctl status aitbc-coordinator

# View logs
sudo journalctl -u aitbc-coordinator -f

Interactive API Documentation

Interactive API documentation is available via Swagger UI and ReDoc.