{ "openapi": "3.0.0", "paths": { "/api/v1/config/public": { "get": { "operationId": "ConfigRegistryController_getPublicConfig", "summary": "Get public platform configuration", "description": "Returns non-sensitive configuration for frontend sync (tier definitions, pricing, thresholds).", "parameters": [], "responses": { "200": { "description": "Public configuration object", "content": { "application/json": { "schema": { "type": "object", "example": { "tiers.free.monthlyCredits": 10, "tiers.pro.monthlyCredits": 100, "tiers.pro.priceMonthlyUsd": 15, "credits.topUpPacks": [ { "credits": 50, "priceUsd": 5 }, { "credits": 200, "priceUsd": 15 }, { "credits": 1000, "priceUsd": 50 } ], "leaderboard.pioneer.taskPoints": 10 } } } } } }, "tags": [ "config" ] } }, "/api/v1/credits/balance/{operatorId}": { "get": { "operationId": "CreditLedgerController_getBalance", "summary": "Get credit balance for an operator (self only)", "parameters": [ { "name": "operatorId", "required": true, "in": "path", "description": "Operator ID — must match authenticated session", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Credit balance details" } }, "tags": [ "credits" ], "security": [ { "bearer": [] } ] } }, "/api/v1/stripe/checkout/subscription": { "post": { "operationId": "StripeController_checkoutSubscription", "summary": "Create a Stripe Checkout session for Pro subscription ($15/mo)", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSubscriptionDto" } } } }, "responses": { "200": { "description": "Returns Stripe Checkout URL" }, "503": { "description": "Stripe not configured" } }, "tags": [ "Stripe" ] } }, "/api/v1/stripe/checkout/topup": { "post": { "operationId": "StripeController_checkoutTopup", "summary": "Create a Stripe Checkout session for a credit top-up pack", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutTopupDto" } } } }, "responses": { "200": { "description": "Returns Stripe Checkout URL" } }, "tags": [ "Stripe" ] } }, "/api/v1/stripe/portal": { "post": { "operationId": "StripeController_createPortal", "summary": "Create a Stripe Customer Portal session for subscription management", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalDto" } } } }, "responses": { "201": { "description": "" } }, "tags": [ "Stripe" ] } }, "/api/v1/leaderboard/agents": { "get": { "operationId": "LeaderboardController_getAgentRankings", "summary": "Get top 50 agents ranked by ARI, VCI, CQ, or composite score", "parameters": [ { "name": "sort", "required": false, "in": "query", "description": "Ranking dimension", "schema": { "enum": [ "ari", "vci", "cq", "score" ], "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Max results (1-100)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Agent rankings with trust level and score breakdown" } }, "tags": [ "Leaderboard" ] } }, "/api/v1/leaderboard/agents/{agentId}/rank": { "get": { "operationId": "LeaderboardController_getAgentRank", "summary": "Get rank and scores for a specific agent", "parameters": [ { "name": "agentId", "required": true, "in": "path", "description": "Agent fingerprint ID", "schema": { "type": "string" } } ], "responses": { "404": { "description": "Agent not found" } }, "tags": [ "Leaderboard" ] } }, "/api/v1/leaderboard/operators": { "get": { "operationId": "LeaderboardController_getOperatorRankings", "summary": "Get top 50 operators ranked by Fleet Commander Index (FCI)", "parameters": [ { "name": "sort", "required": false, "in": "query", "schema": { "enum": [ "fci", "tasks" ], "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Leaderboard" ] } }, "/api/v1/leaderboard/pioneers": { "get": { "operationId": "LeaderboardController_getPioneerRankings", "summary": "Get top 50 operators ranked by Beta Pioneer Points", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Leaderboard" ] } }, "/api/v1/leaderboard/pioneers/events": { "get": { "operationId": "LeaderboardController_getPioneerEvents", "summary": "Get point event history for an operator (public, ordered desc)", "parameters": [ { "name": "operatorId", "required": true, "in": "query", "description": "Operator cuid", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Max results (1-200)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List of PioneerPointEvent rows ordered by createdAt desc" } }, "tags": [ "Leaderboard" ] } }, "/api/v1/auth/me": { "get": { "operationId": "AuthController_getMe", "summary": "Return the current authenticated operator profile", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "auth" ], "security": [ { "bearer": [] } ] } }, "/api/v1/operator/kill-switch": { "patch": { "operationId": "AuthController_setKillSwitch", "summary": "Persist kill-switch state (G3 fix — was local state only)", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "auth" ], "security": [ { "bearer": [] } ] } }, "/api/v1/operator/guardrails": { "patch": { "operationId": "AuthController_setGuardrails", "summary": "Persist guardrail config (CV-3 fix — was ephemeral)", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "auth" ], "security": [ { "bearer": [] } ] } }, "/api/v1/operator/export": { "get": { "operationId": "AuthController_exportData", "summary": "Export all operator data as JSON (G4 — data portability)", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "auth" ], "security": [ { "bearer": [] } ] } }, "/api/v1/fingerprints/{agentId}": { "get": { "operationId": "FingerprintController_getFingerprint", "summary": "Get fingerprint for a specific agent", "parameters": [ { "name": "agentId", "required": true, "in": "path", "description": "Agent fingerprint ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent fingerprint with ARI, VCI, CQ and centroid" }, "404": { "description": "Agent not found" } }, "tags": [ "Fingerprints" ], "security": [ { "x-api-key": [] } ] } }, "/api/v1/fingerprints": { "get": { "operationId": "FingerprintController_listFingerprints", "summary": "List agent fingerprints sorted by ARI, VCI, or CQ", "parameters": [ { "name": "sort", "required": false, "in": "query", "schema": { "enum": [ "ari", "vci", "cq", "driftScore" ], "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Fingerprints" ], "security": [ { "x-api-key": [] } ] } }, "/api/v1/operator/dashboard": { "get": { "operationId": "OperatorController_getDashboard", "summary": "Get dashboard overview (stats, credits, agent count)", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "operator" ], "security": [ { "bearer": [] } ] } }, "/api/v1/operator/tasks": { "get": { "operationId": "OperatorController_getTasks", "summary": "Get recent tasks", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "operator" ], "security": [ { "bearer": [] } ] } }, "/api/v1/operator/keys": { "get": { "operationId": "OperatorController_listKeys", "summary": "List API keys (redacted)", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "operator" ], "security": [ { "bearer": [] } ] }, "post": { "operationId": "OperatorController_createKey", "summary": "Generate a new API key", "parameters": [], "responses": { "201": { "description": "" } }, "tags": [ "operator" ], "security": [ { "bearer": [] } ] } }, "/api/v1/operator/keys/{keyId}": { "delete": { "operationId": "OperatorController_revokeKey", "summary": "Revoke an API key", "parameters": [ { "name": "keyId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "operator" ], "security": [ { "bearer": [] } ] } }, "/api/v1/operator/billing": { "get": { "operationId": "OperatorController_getBilling", "summary": "Get credit balance and transaction history", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "operator" ], "security": [ { "bearer": [] } ] } }, "/api/v1/operator/wallet": { "post": { "operationId": "OperatorController_connectWallet", "summary": "Connect Base Account wallet", "parameters": [], "responses": { "201": { "description": "" } }, "tags": [ "operator" ], "security": [ { "bearer": [] } ] } }, "/api/v1/operator/compliance": { "get": { "operationId": "OperatorController_getCompliance", "summary": "Get compliance certificates (PRO/ENTERPRISE)", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "operator" ], "security": [ { "bearer": [] } ] } }, "/api/v1/operator/compliance/generate": { "post": { "operationId": "OperatorController_generateCompliance", "summary": "Generate a new compliance certificate on demand", "parameters": [], "responses": { "201": { "description": "" } }, "tags": [ "operator" ], "security": [ { "bearer": [] } ] } }, "/api/v1/public/stats": { "get": { "operationId": "PublicController_getStats", "summary": "Platform-wide stats (total tasks, agents, operators)", "parameters": [], "responses": { "200": { "description": "Platform statistics", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalTasks": { "type": "number" }, "totalOperators": { "type": "number" }, "totalAgents": { "type": "number" }, "avgLatencyMs": { "type": "number" }, "verificationRate": { "type": "number" } } } } } } }, "tags": [ "public" ] } }, "/api/v1/public/leaderboard": { "get": { "operationId": "PublicController_getLeaderboard", "summary": "Agent leaderboard (top agents by composite score)", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Max results (default 20)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "tags": [ "public" ] } }, "/api/v1/public/proof/{cid}": { "get": { "operationId": "PublicController_getProof", "summary": "View a proof receipt by IPFS CID", "parameters": [ { "name": "cid", "required": true, "in": "path", "description": "IPFS CID of the proof receipt", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "public" ] } }, "/v1/prior/claim": { "post": { "operationId": "PriorController_uploadPriorClaim", "summary": "Upload context payload or JSON to PRIOR IPFS", "parameters": [], "requestBody": { "required": true, "description": "File upload (multipart) or JSON payload", "content": { "multipart/form-data": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "string" } } } }, "responses": { "201": { "description": "" } }, "tags": [ "prior" ] } }, "/v1/logs": { "get": { "operationId": "WorkerLogsController_queryLogs", "summary": "Query worker logs from on-chain events", "description": "Fetches IntentExecuted events from ShadowVault, hydrates log content from IPFS. Pagination is block-range-based (fromBlock/toBlock), not offset-based.", "parameters": [ { "name": "fromBlock", "required": false, "in": "query", "description": "Start block number", "schema": { "type": "string" } }, { "name": "toBlock", "required": false, "in": "query", "description": "End block number", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Max results (default: 50)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Worker Logs" ] } }, "/v1/logs/{cid}": { "get": { "operationId": "WorkerLogsController_getLogByCid", "summary": "Fetch a single worker log from IPFS", "description": "Retrieves the full WorkerLogEntry JSON from Pinata IPFS gateway by CID.", "parameters": [ { "name": "cid", "required": true, "in": "path", "description": "IPFS CID of the log entry", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Worker Logs" ] } }, "/api/pipeline/events": { "get": { "operationId": "PipelineEventsController_getEvents", "summary": "Get recent pipeline events", "description": "Returns the most recent pipeline events from the Client Zero trade execution pipeline. Events include job acceptance, processing, LLM inference, IPFS pinning, and on-chain settlement.", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Max events to return (default: 20, max: 100)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Pipeline Events" ] } }, "/v1/intent": { "post": { "operationId": "IntentController_submitIntent", "summary": "Submit a compute intent for the AgentChain network", "parameters": [], "requestBody": { "required": true, "description": "JSON intent payload with bounty amount", "content": { "application/json": { "schema": { "type": "object", "properties": { "payload": { "type": "object", "description": "The compute task data" }, "bounty": { "type": "string", "description": "USDC bounty amount as decimal string (6 decimals)" }, "requiredCollateral": { "type": "string", "description": "Shadow Vault v3: required collateral in USDC (optional, 0 = default)" } }, "required": [ "payload", "bounty" ] } } } }, "responses": { "201": { "description": "Intent queued for settlement" }, "400": { "description": "Missing required fields" }, "413": { "description": "Payload exceeds 2MB limit" } }, "tags": [ "intent" ], "security": [ { "bearer": [] } ] } }, "/api/v1/tasks": { "get": { "operationId": "TaskController_listTasks", "summary": "List tasks (paginated)", "description": "Returns a paginated list of tasks with optional filters by status, taskType, or operatorId.", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number (default: 1)", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Items per page (default: 20, max: 100)", "schema": { "type": "number" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by status (COMPLETED, FAILED, PROCESSING)", "schema": { "type": "string" } }, { "name": "taskType", "required": false, "in": "query", "description": "Filter by task type (general, code, analysis, creative, trade_signal)", "schema": { "type": "string" } }, { "name": "operatorId", "required": false, "in": "query", "description": "Filter by operator ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated task list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "taskType": { "type": "string" }, "status": { "type": "string" }, "agentId": { "type": "string" }, "model": { "type": "string", "nullable": true }, "provider": { "type": "string", "nullable": true }, "latencyMs": { "type": "number", "nullable": true }, "ipfsCid": { "type": "string", "nullable": true }, "stateRoot": { "type": "string", "nullable": true }, "verificationStatus": { "type": "string", "nullable": true }, "verificationScore": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true } } } }, "total": { "type": "number" }, "page": { "type": "number" }, "limit": { "type": "number" }, "totalPages": { "type": "number" } } } } } } }, "tags": [ "tasks" ] } }, "/api/v1/tasks/{id}": { "get": { "operationId": "TaskController_getTask", "summary": "Get task by ID", "description": "Returns a single task summary by its ID.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Task ID (cuid)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task found" }, "404": { "description": "Task not found" } }, "tags": [ "tasks" ] } }, "/api/v1/tasks/submit": { "post": { "operationId": "TaskController_submitTask", "summary": "Submit a task for execution", "description": "Full 8-stage pipeline: guardrail → credit → compute → verify → anchor → receipt", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt", "taskType", "agentId" ], "properties": { "prompt": { "type": "string", "description": "The prompt/instruction for the LLM", "example": "Analyze the sentiment of the following text: \"Bitcoin is looking bullish today\"" }, "taskType": { "type": "string", "enum": [ "general", "code", "analysis", "creative", "trade_signal" ], "description": "Type of task", "example": "analysis" }, "agentId": { "type": "string", "description": "Agent fingerprint ID (unique per agent)", "example": "agent-alpha-001" }, "metadata": { "type": "object", "description": "Optional metadata for the task" } } } } } }, "responses": { "200": { "description": "Task executed — provenance receipt returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" }, "status": { "type": "string", "enum": [ "COMPLETED", "UNMETERED", "GUARDRAIL_BLOCKED", "INSUFFICIENT_CREDITS", "COMPUTE_FAILED", "OUTPUT_BLOCKED" ] }, "agentId": { "type": "string" }, "model": { "type": "string" }, "provider": { "type": "string" }, "latencyMs": { "type": "number" }, "output": { "type": "string" }, "ipfsCid": { "type": "string" }, "stateRoot": { "type": "string" }, "verificationStatus": { "type": "string" }, "verificationScore": { "type": "number" } } } } } }, "400": { "description": "Invalid request body or guardrail block" }, "401": { "description": "Missing or invalid JWT" } }, "tags": [ "tasks" ], "security": [ { "bearer": [] } ] } }, "/api/v1/faucet/usdc": { "post": { "operationId": "FaucetController_drip", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaucetDripDto" } } } }, "responses": { "200": { "description": "" } } } } }, "info": { "title": "AgentChain & PRIOR API", "description": "The centralized gateway for the decentralized compute network.", "version": "1.0", "contact": {} }, "tags": [], "servers": [], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http" } }, "schemas": { "CheckoutSubscriptionDto": { "type": "object", "properties": {} }, "CheckoutTopupDto": { "type": "object", "properties": {} }, "PortalDto": { "type": "object", "properties": {} }, "FaucetDripDto": { "type": "object", "properties": {} } } } }