# Coordinator API - AITBC Documentation FastAPI service for job submission, miner registration, and receipt management. SQLite persistence with comprehensive endpoints. ● 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 ### GPU Marketplace Endpoints `POST /v1/marketplace/gpu/register` Register a GPU on the marketplace `GET /v1/marketplace/gpu/list` List available GPUs (filter by available, model, price, region) `GET /v1/marketplace/gpu/{gpu_id}` Get GPU details `POST /v1/marketplace/gpu/{gpu_id}/book` Book a GPU for a duration `POST /v1/marketplace/gpu/{gpu_id}/release` Release a booked GPU `GET /v1/marketplace/gpu/{gpu_id}/reviews` Get reviews for a GPU `POST /v1/marketplace/gpu/{gpu_id}/reviews` Add a review for a GPU `GET /v1/marketplace/orders` List marketplace orders `GET /v1/marketplace/pricing/{model}` Get pricing for a GPU model ### Payment Endpoints `POST /v1/payments` Create payment for a job `GET /v1/payments/{payment_id}` Get payment details `GET /v1/jobs/{job_id}/payment` Get payment for a job `POST /v1/payments/{payment_id}/release` Release payment from escrow `POST /v1/payments/{payment_id}/refund` Refund payment `GET /v1/payments/{payment_id}/receipt` Get payment receipt ### Governance Endpoints `POST /v1/governance/proposals` Create a governance proposal `GET /v1/governance/proposals` List proposals (filter by status) `GET /v1/governance/proposals/{proposal_id}` Get proposal details `POST /v1/governance/vote` Submit a vote on a proposal `GET /v1/governance/voting-power/{user_id}` Get voting power for a user `GET /v1/governance/parameters` Get governance parameters `POST /v1/governance/execute/{proposal_id}` Execute an approved proposal ### Explorer Endpoints `GET /v1/explorer/blocks` List recent blocks `GET /v1/explorer/transactions` List recent transactions `GET /v1/explorer/addresses` List address summaries `GET /v1/explorer/receipts` List job receipts ### 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 ```http X-Api-Key: your-api-key-here ``` ### Session Tokens ```http X-Session-Token: sha256-token-here ``` ### Example Request ```bash 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 ```bash # 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 ```bash # 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 ```bash # 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](https://aitbc.bubuit.net/api/docs) - [ReDoc](https://aitbc.bubuit.net/api/redoc) - [OpenAPI Spec](https://aitbc.bubuit.net/api/openapi.json) ## Data Models ### Job ```json { "id": "uuid", "client_id": "string", "job_type": "llm_inference", "parameters": {}, "status": "pending|running|completed|failed", "created_at": "timestamp", "updated_at": "timestamp" } ``` ### Miner ```json { "id": "uuid", "address": "string", "endpoint": "string", "capabilities": [], "status": "active|inactive", "last_heartbeat": "timestamp" } ``` ### Receipt ```json { "id": "uuid", "job_id": "uuid", "miner_id": "uuid", "result": {}, "proof": "string", "created_at": "timestamp" } ``` ## Error Handling The API returns standard HTTP status codes with detailed error messages: ```json { "error": { "code": "INVALID_JOB_TYPE", "message": "The specified job type is not supported", "details": {} } } ``` ## Rate Limiting API endpoints are rate-limited to prevent abuse: - Client endpoints: 100 requests/minute - Miner endpoints: 1000 requests/minute - User endpoints: 60 requests/minute ## Monitoring The Coordinator API exposes metrics at `/metrics` endpoint: - `api_requests_total` - Total API requests - `api_request_duration_seconds` - Request latency - `active_jobs` - Currently active jobs - `registered_miners` - Number of registered miners ## Security - All sensitive endpoints require authentication - API keys should be kept confidential - HTTPS is required in production - Input validation on all endpoints - SQL injection prevention via ORM