Back to Components

# Coordinator API

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

● Live
System Flow: See the complete system flow diagram to understand how the coordinator API fits into the overall AITBC architecture.

## 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.

- Swagger UI
- ReDoc
- OpenAPI Spec