{ "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": 100, "tiers.pro.monthlyCredits": 1000, "tiers.pro.priceMonthlyUsd": 15, "credits.topUpPacks": [ { "credits": 500, "priceUsd": 5 }, { "credits": 2000, "priceUsd": 15 }, { "credits": 10000, "priceUsd": 50 } ], "leaderboard.pioneer.taskPoints": 25, "leaderboard.pioneer.explorerThreshold": 500, "leaderboard.pioneer.founderThreshold": 25000 } } } } } }, "tags": [ "config" ] } }, "/api/v1/compute": { "post": { "operationId": "ComputeOverflowController_enqueueOverflow", "summary": "Enqueue compute overflow job (key pool exhausted)", "parameters": [], "responses": { "202": { "description": "Job queued. Subscribe to /api/v1/compute/:jobId/status for SSE." } }, "tags": [ "compute-overflow" ], "security": [ { "bearer": [] }, { "x-api-key": [] } ] } }, "/api/v1/compute/{jobId}/status": { "get": { "operationId": "ComputeOverflowController_sseJobStatus", "summary": "SSE stream for overflow job status", "parameters": [ { "name": "jobId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "compute-overflow" ], "security": [ { "bearer": [] }, { "x-api-key": [] } ] } }, "/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/auth/me": { "get": { "operationId": "AuthController_getMe", "summary": "Return the current authenticated operator profile", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorProfileDto" } } } } }, "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": { "get": { "operationId": "AuthController_getGuardrails", "summary": "Get current and pending guardrail config", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "auth" ], "security": [ { "bearer": [] } ] }, "patch": { "operationId": "AuthController_setGuardrails", "summary": "Queue guardrail config update — 30s activation delay, 10s write rate limit", "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": [] } ] } }, "/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" ], "security": [ { "x-api-key": [] }, { "bearer": [] } ] } }, "/api/v1/operator/dashboard": { "get": { "operationId": "OperatorController_getDashboard", "summary": "Get dashboard overview (stats, credits, agent count)", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardStatsDto" } } } } }, "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": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyRecordDto" } } } } } }, "tags": [ "operator" ], "security": [ { "bearer": [] } ] }, "post": { "operationId": "OperatorController_createKey", "summary": "Generate a new API key", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKeyDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreatedDto" } } } } }, "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": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponseDto" } } } } }, "tags": [ "operator" ], "security": [ { "bearer": [] } ] } }, "/api/v1/operator/billing": { "get": { "operationId": "OperatorController_getBilling", "summary": "Get credit balance and transaction history", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingDataDto" } } } } }, "tags": [ "operator" ], "security": [ { "bearer": [] } ] } }, "/api/v1/operator/wallet/nonce": { "get": { "operationId": "OperatorController_getWalletNonce", "summary": "Get EIP-712 wallet bind challenge nonce (step 1 of 2)", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletNonceDto" } } } } }, "tags": [ "operator" ], "security": [ { "bearer": [] } ] } }, "/api/v1/operator/wallet": { "post": { "operationId": "OperatorController_bindWallet", "summary": "Bind Base wallet with EIP-712 signature proof (step 2 of 2)", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletBindDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletBindResultDto" } } } } }, "tags": [ "operator" ], "security": [ { "bearer": [] } ] } }, "/api/v1/operator/compliance": { "get": { "operationId": "OperatorController_getCompliance", "summary": "Get compliance certificates (PRO/ENTERPRISE)", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ComplianceCertDto" } } } } } }, "tags": [ "operator" ], "security": [ { "bearer": [] } ] } }, "/api/v1/operator/compliance/generate": { "post": { "operationId": "OperatorController_generateCompliance", "summary": "Generate a new compliance certificate on demand", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceCertDto" } } } } }, "tags": [ "operator" ], "security": [ { "bearer": [] } ] } }, "/api/v1/operator/tos/status": { "get": { "operationId": "OperatorController_getTosStatus", "summary": "Get ToS acceptance status", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TosStatusDto" } } } } }, "tags": [ "operator" ], "security": [ { "bearer": [] } ] } }, "/api/v1/operator/tos/accept": { "post": { "operationId": "OperatorController_acceptTos", "summary": "Accept Terms of Service (creates IPFS attestation + system task)", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TosAcceptDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TosAcceptResultDto" } } } } }, "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/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" ] } }, "/api/v1/public/agent/{agentId}/passport": { "get": { "operationId": "PublicController_getPassport", "summary": "Agent Passport — public identity, trust, and x402 block status", "parameters": [ { "name": "agentId", "required": true, "in": "path", "description": "Agent fingerprint ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent passport with trust metrics and defense stack status", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string" }, "trustLevel": { "type": "string" }, "ari": { "type": "number" }, "vci": { "type": "number" }, "cq": { "type": "number" }, "driftScore": { "type": "number" }, "totalTasks": { "type": "number" }, "verifiedTasks": { "type": "number" }, "enrolledAt": { "type": "string", "format": "date-time" }, "lastActiveAt": { "type": "string", "format": "date-time", "nullable": true }, "x402": { "type": "object", "properties": { "blocked": { "type": "boolean" }, "reason": { "type": "string", "nullable": true }, "walletChecked": { "type": "string", "nullable": true }, "rateLimitMax": { "type": "number", "description": "Max x402 tasks/hour for this wallet" }, "rateLimitRemaining": { "type": "number", "nullable": true, "description": "Remaining tasks in current window (null if Redis unavailable)" }, "rateLimitResetMs": { "type": "number", "nullable": true, "description": "Milliseconds until rate limit window resets" }, "rateLimitResetUnix": { "type": "number", "nullable": true, "description": "Unix timestamp (seconds) when window resets — aligns with X-RateLimit-Reset" } } } } } } } } }, "tags": [ "public" ] } }, "/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 (Master Key or Operator JWT)", "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" ], "security": [ { "bearer": [] }, { "x-api-key": [] } ] } }, "/api/v1/attestations/{taskId}": { "get": { "operationId": "AttestationController_getByTaskId", "parameters": [ { "name": "taskId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } } } }, "/api/v1/attestations/uid/{attestationUid}": { "get": { "operationId": "AttestationController_getByUid", "parameters": [ { "name": "attestationUid", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } } } }, "/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)" }, "modelCid": { "type": "string", "description": "EPIC 9.3 Fat Intent: Ollama model tag (e.g. \"gemma3:12b\"). Optional — worker falls back to OLLAMA_MODEL env var." } }, "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": [] } ] } }, "/v1/intent/tasks/pending": { "get": { "operationId": "IntentController_getPendingTask", "summary": "Fetch oldest pending tasks for MPC worker", "parameters": [], "responses": { "200": { "description": "Pending intent returned" }, "204": { "description": "No pending intents" } }, "tags": [ "intent" ] } }, "/v1/intent/task/{cid}": { "get": { "operationId": "IntentController_getTaskByCid", "summary": "Fetch signed intent metadata by IPFS CID (on-chain listener mode)", "parameters": [ { "name": "cid", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signed intent descriptor returned" }, "404": { "description": "No intent found for this CID" } }, "tags": [ "intent" ] } }, "/v1/intent/report": { "post": { "operationId": "IntentController_reportCompletion", "summary": "Worker reports task completion with on-chain taskId (EIP-191 attested)", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "payloadCid", "onChainTaskId", "stateRoot", "workerAddress" ], "properties": { "payloadCid": { "type": "string", "description": "IPFS CID of the original intent payload" }, "onChainTaskId": { "type": "string", "description": "uint256 taskId from TaskMarket" }, "stateRoot": { "type": "string", "description": "SHA-256 state root of the compute output" }, "output": { "type": "string", "description": "Raw compute output (truncated for verification)" }, "workerAddress": { "type": "string", "description": "Worker EOA or smart account address" }, "operatorId": { "type": "string", "description": "Operator who submitted the original intent" }, "taskType": { "type": "string", "description": "Task type for verification routing" } } } } } }, "responses": { "200": { "description": "Task record created and verification enqueued" } }, "tags": [ "intent" ] } }, "/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" } }, { "name": "agentId", "required": false, "in": "query", "description": "Filter by agent ID (for agent detail pipeline feed)", "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 }, "verificationProof": { "type": "string", "nullable": true, "description": "TX hash from on-chain verification anchor" }, "verificationBasescanUrl": { "type": "string", "nullable": true }, "attestationUid": { "type": "string", "nullable": true, "description": "EAS Omni-Stamp UID (bytes32 hex)" }, "easscanUrl": { "type": "string", "nullable": true, "description": "EASScan deep link" }, "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", "evm-action" ], "description": "Type of task. Use evm-action for deterministic EVM state verification.", "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" }, "model": { "type": "string", "description": "Model slug from the whitelist (e.g. \"llama-3.3-70b\"). Defaults to llama-3.3-70b if omitted. Ignored for evm-action type.", "example": "llama-3.3-70b" }, "evmPayload": { "type": "object", "description": "Required when taskType is evm-action. EVM action payload for deterministic verification.", "properties": { "actionId": { "type": "string", "description": "bytes32 hex — unique action identifier" }, "agentId": { "type": "string", "description": "Agent wallet address (0x...)" }, "preStateRoot": { "type": "string", "description": "bytes32 hex — EVM state root before action" }, "transactions": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string", "description": "Contract address (0x...)" }, "calldata": { "type": "string", "description": "ABI-encoded calldata (0x...)" }, "value": { "type": "string", "description": "Wei value as decimal string" }, "slippageBps": { "type": "string", "description": "Slippage tolerance in basis points" } } } }, "effectClaimHash": { "type": "string", "description": "bytes32 hex — claimed effect hash" } } } } } } } }, "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" }, "verificationProof": { "type": "string", "nullable": true, "description": "TX hash from on-chain verification anchor" }, "verificationBasescanUrl": { "type": "string", "nullable": true }, "attestationUid": { "type": "string", "nullable": true, "description": "EAS Omni-Stamp UID (bytes32 hex)" }, "easscanUrl": { "type": "string", "nullable": true, "description": "EASScan deep link" } } } } } }, "400": { "description": "Invalid request body" }, "401": { "description": "Missing or invalid JWT" }, "418": { "description": "Guardrail or output policy blocked this task. Your operator config is the wall — check maxCreditsPerDay, maxTasksPerHour, or allowedTaskTypes." } }, "tags": [ "tasks" ], "security": [ { "bearer": [] } ] } }, "/api/v1/approvals": { "get": { "operationId": "ApprovalController_list", "summary": "List approval requests", "description": "Returns pending approval requests for the authenticated operator. Filter by decision status (PENDING, APPROVED, DENIED, EXPIRED). Defaults to PENDING. Auto-expires stale approvals past their TTL.", "parameters": [ { "name": "decision", "required": false, "in": "query", "description": "Filter by decision status: PENDING, APPROVED, DENIED, EXPIRED (default: PENDING)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of approval requests", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Approval request ID" }, "taskId": { "type": "string", "description": "Associated task ID" }, "agentId": { "type": "string", "description": "Agent that submitted the action" }, "actionType": { "type": "string", "example": "spend_control" }, "operation": { "type": "string", "example": "invoice_payment" }, "target": { "type": "string", "description": "Counterparty or resource" }, "requestedValue": { "type": "number", "example": 12000, "nullable": true }, "currency": { "type": "string", "example": "USDC", "nullable": true }, "triggerPolicy": { "type": "string", "example": "human_approval_threshold" }, "triggerReason": { "type": "string", "example": "$12,000 exceeds auto-approve limit of $5,000" }, "decision": { "type": "string", "enum": [ "PENDING", "APPROVED", "DENIED", "EXPIRED" ] }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true } } } } } } }, "401": { "description": "Missing or invalid authentication" } }, "tags": [ "Approval Queue" ], "security": [ { "x-api-key": [] }, { "bearer": [] } ] } }, "/api/v1/approvals/count": { "get": { "operationId": "ApprovalController_count", "summary": "Get pending approval count", "description": "Returns the number of pending approval requests for the authenticated operator. Used by dashboard sidebar badges and SDK polling.", "parameters": [], "responses": { "200": { "description": "Pending approval count", "content": { "application/json": { "schema": { "type": "object", "properties": { "pending": { "type": "number", "example": 3, "description": "Number of pending approvals" } } } } } } }, "tags": [ "Approval Queue" ], "security": [ { "x-api-key": [] }, { "bearer": [] } ] } }, "/api/v1/approvals/{id}": { "get": { "operationId": "ApprovalController_findOne", "summary": "Get approval request detail", "description": "Returns the full detail of a single approval request, including policy evaluations, evidence artifacts, and resolution state. Only accessible to the owning operator.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Approval request ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Approval request detail" }, "403": { "description": "Not your approval request" }, "404": { "description": "Approval request not found" } }, "tags": [ "Approval Queue" ], "security": [ { "x-api-key": [] }, { "bearer": [] } ] }, "patch": { "operationId": "ApprovalController_resolve", "summary": "Resolve an approval request", "description": "Approve or deny a pending approval request. If approved, the gateway resumes the full task pipeline (stages 2–8: credit debit → compute → IPFS → fingerprint → receipt). If denied, the task is marked FAILED and no credits are consumed. Both JWT and API key authentication are supported — enabling programmatic resolution from SDKs and scripts without the dashboard.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Approval request ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Resolution payload", "content": { "application/json": { "schema": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "approved", "denied" ], "description": "Approval decision" }, "note": { "type": "string", "description": "Optional note explaining the decision (e.g. \"Verified invoice with finance team\")" } } } } } }, "responses": { "200": { "description": "Approval resolved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "decision": { "type": "string", "enum": [ "approved", "denied" ] }, "taskId": { "type": "string" }, "receipt": { "type": "object", "description": "Full task receipt (only present when approved)" } } } } } }, "400": { "description": "Invalid decision value" }, "403": { "description": "Not your approval request" }, "404": { "description": "Approval request not found" } }, "tags": [ "Approval Queue" ], "security": [ { "x-api-key": [] }, { "bearer": [] } ] } }, "/api/v1/approvals/{id}/callback": { "post": { "operationId": "ApprovalController_registerCallback", "summary": "Register approval webhook callback", "description": "Register a one-shot callback URL for a specific approval request. When resolved, AgentChain POSTs the result with dual-signature headers: `x-agentchain-signature` (HMAC-SHA256 for web2 verification) and `x-agentchain-eip712-sig` (EIP-712 for crypto-native verification). The callback fires once and is then deleted. Primary use case: Trigger.dev `wait.forToken()` integration for zero-cost checkpoint-resume approval flows.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Approval request ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Callback registration payload", "content": { "application/json": { "schema": { "type": "object", "required": [ "callbackUrl" ], "properties": { "callbackUrl": { "type": "string", "format": "uri", "description": "URL to receive the webhook POST when the approval is resolved", "example": "https://api.trigger.dev/wait/token/abc123" } } } } } }, "responses": { "201": { "description": "Callback registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "registered": { "type": "boolean", "example": true }, "approvalId": { "type": "string" } } } } } }, "403": { "description": "Not your approval request" }, "404": { "description": "Approval request not found" } }, "tags": [ "Approval Queue" ], "security": [ { "x-api-key": [] }, { "bearer": [] } ] } }, "/api/v1/agents/register": { "post": { "operationId": "AgentsController_register", "summary": "Register a new agent", "description": "Atomic: creates API key + pre-seeds fingerprint row. Returns plain API key (shown once).", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "displayName", "capabilities" ], "properties": { "displayName": { "type": "string", "example": "prod-sentiment-analyzer" }, "description": { "type": "string", "example": "Processes Farcaster sentiment for trading signals" }, "capabilities": { "type": "array", "items": { "type": "string" }, "example": [ "sentiment_analysis", "general" ] }, "model": { "type": "string", "example": "llama3:70b" }, "agentVersion": { "type": "string", "example": "1.0.0" } } } } } }, "responses": { "201": { "description": "Agent registered. API key returned once — store securely." } }, "tags": [ "Agents" ], "security": [ { "bearer": [] } ] } }, "/api/v1/agents": { "get": { "operationId": "AgentsController_listAgents", "summary": "List all agents for the authenticated operator", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "Agents" ], "security": [ { "bearer": [] } ] } }, "/api/v1/agents/{agentId}": { "get": { "operationId": "AgentsController_getAgent", "summary": "Get agent detail (wizard resume + detail page)", "parameters": [ { "name": "agentId", "required": true, "in": "path", "description": "Agent ID (agent__)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Agents" ], "security": [ { "bearer": [] } ] }, "patch": { "operationId": "AgentsController_updateAgent", "summary": "Update agent metadata", "description": "Update mutable agent fields: displayName, description, capabilities, model. Validates capabilities against allowed task types.", "parameters": [ { "name": "agentId", "required": true, "in": "path", "description": "Agent ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "example": "Updated Agent Name" }, "description": { "type": "string", "example": "Updated description" }, "capabilities": { "type": "array", "items": { "type": "string" }, "example": [ "evm_action", "spend_control" ] }, "model": { "type": "string", "example": "llama3:70b" } } } } } }, "responses": { "200": { "description": "Updated agent record." }, "400": { "description": "Invalid capabilities or agent is archived." } }, "tags": [ "Agents" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "AgentsController_archiveAgent", "summary": "Archive an agent (soft-delete)", "description": "Sets archivedAt on the agent and revokes the associated API key. Archived agents are excluded from list queries and cannot be updated.", "parameters": [ { "name": "agentId", "required": true, "in": "path", "description": "Agent ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Agent archived successfully." } }, "tags": [ "Agents" ], "security": [ { "bearer": [] } ] } }, "/api/v1/agents/{agentId}/test-run": { "post": { "operationId": "AgentsController_testRun", "summary": "Fire a canonical test task for this agent", "description": "Used by wizard Step 5 and the persistent agent detail test panel. Uses the agent's primary capability and canonical test prompt.", "parameters": [ { "name": "agentId", "required": true, "in": "path", "description": "Agent ID", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskType": { "type": "string", "description": "Override task type (defaults to agent primary capability)" }, "prompt": { "type": "string", "description": "Override prompt (defaults to canonical test prompt)" } } } } } }, "responses": { "201": { "description": "Task created and enqueued for pipeline processing." }, "422": { "description": "Guardrail blocked — prompt injection, banned topic, prompt too long, or task type not allowed." }, "429": { "description": "Rate limit exceeded — max tasks/hour or max credits/day." } }, "tags": [ "Agents" ], "security": [ { "bearer": [] } ] } }, "/api/v1/registry/agents/{agentId}/agent-card.json": { "get": { "operationId": "RegistryController_getAgentCard", "summary": "Get ERC-8004 agent card (public, no auth)", "description": "Returns the machine-readable agent-card.json for the given agent. Used by ERC-8004 discovery clients, other agents, and platform integrations. No authentication required — this is a public registry endpoint.", "parameters": [ { "name": "agentId", "required": true, "in": "path", "description": "Agent ID (agent__)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "ERC-8004 agent card JSON" }, "404": { "description": "Agent not found" } }, "tags": [ "Registry" ] } }, "/api/v1/registry/agents": { "get": { "operationId": "RegistryController_listPublicAgents", "summary": "List all registered agents (public directory)", "description": "Returns a list of all agents with their agent-card URIs and basic metadata. No authentication required.", "parameters": [], "responses": { "200": { "description": "Array of agent card summaries" } }, "tags": [ "Registry" ] } }, "/api/v1/faucet/usdc": { "post": { "operationId": "FaucetController_drip", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaucetDripDto" } } } }, "responses": { "200": { "description": "" } } } }, "/api/v1/settlement/actions": { "get": { "operationId": "SettlementController_listActions", "summary": "List agent actions", "description": "Returns agent actions with verification status, settlement state, and policy evaluations.", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "verificationStatus", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "settlementStatus", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "tool", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "agentId", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated action list" } }, "tags": [ "settlement" ] } }, "/api/v1/settlement/actions/{id}": { "get": { "operationId": "SettlementController_getAction", "summary": "Get action by ID", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "0x-prefixed action hash", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Action with full policy evaluations" }, "404": { "description": "Action not found" } }, "tags": [ "settlement" ] } }, "/api/v1/settlement/settlements": { "get": { "operationId": "SettlementController_listSettlements", "summary": "List settlements", "description": "Returns settlement records with release conditions and dispute references.", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "rail", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated settlement list" } }, "tags": [ "settlement" ] } }, "/api/v1/settlement/settlements/{id}": { "get": { "operationId": "SettlementController_getSettlement", "summary": "Get settlement by ID", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Settlement with evidence chain" }, "404": { "description": "Settlement not found" } }, "tags": [ "settlement" ] } }, "/api/v1/settlement/disputes": { "get": { "operationId": "SettlementController_listDisputes", "summary": "List disputes", "description": "Returns active and resolved disputes from BisectionCourt.", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "phase", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated dispute list" } }, "tags": [ "settlement" ] } }, "/api/v1/settlement/disputes/{id}": { "get": { "operationId": "SettlementController_getDispute", "summary": "Get dispute by ID", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Dispute with phase timeline" }, "404": { "description": "Dispute not found" } }, "tags": [ "settlement" ] } }, "/api/v1/settlement/policies": { "get": { "operationId": "SettlementController_listPolicies", "summary": "List registered policies", "description": "Returns policies from the AgentPolicy on-chain registry.", "parameters": [], "responses": { "200": { "description": "Policy list" } }, "tags": [ "settlement" ] } }, "/api/v1/settlement/stats": { "get": { "operationId": "SettlementController_getStats", "summary": "Settlement aggregate stats", "description": "Returns 30-day totals: released, held, disputed, avg settlement time, verification rate.", "parameters": [], "responses": { "200": { "description": "Settlement stats object" } }, "tags": [ "settlement" ] } }, "/api/v1/settlement/userop": { "post": { "operationId": "SettlementController_submitUserOp", "summary": "Submit a UserOperation", "description": "Constructs and submits an ERC-4337 UserOperation through the bundler RPC, routed through the AgentPolicyPaymaster for gas sponsorship. The paymaster validates policy compliance before sponsoring.", "parameters": [], "responses": { "200": { "description": "UserOp submission result with hash and receipt" } }, "tags": [ "settlement" ] } }, "/api/v1/settlement/userop/status": { "get": { "operationId": "SettlementController_getUserOpStatus", "summary": "UserOp pipeline status", "description": "Returns whether the ERC-4337 pipeline is initialized and ready.", "parameters": [], "responses": { "200": { "description": "Pipeline status" } }, "tags": [ "settlement" ] } }, "/api/v1/settlement/session/digest": { "post": { "operationId": "SettlementController_computeSessionDigest", "summary": "Compute EIP-712 session key digest", "description": "Returns the EIP-712 typed data hash that the owner (cold wallet) must sign to authorize the server's session key for a specific TaskMarket. The owner signs this digest offline and caches it on the server.", "parameters": [], "responses": { "200": { "description": "Session digest and grant parameters" } }, "tags": [ "settlement" ] } }, "/api/v1/settlement/session/status": { "get": { "operationId": "SettlementController_getSessionStatus", "summary": "Session key status", "description": "Returns the current session key address and configuration.", "parameters": [], "responses": { "200": { "description": "Session key info" } }, "tags": [ "settlement" ] } }, "/api/v1/evm/guard": { "post": { "operationId": "V2EvmController_guard", "summary": "Pre-transaction guard: policy evaluation + signed receipt (E1)", "tags": [ "evm" ], "security": [ { "bearer": [] }, { "x-api-key": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Guard decision and signed receipt" }, "400": { "description": "Validation error" }, "503": { "description": "Receipt signing not configured" } } } }, "/api/v1/policies/hash": { "post": { "operationId": "V2PoliciesController_postHash", "summary": "Hash policy body (JCS) — parity with SDK", "tags": [ "policies" ], "security": [ { "bearer": [] }, { "x-api-key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "policyHash, canonical, coreVersion" } } } }, "/api/v1/policies": { "get": { "operationId": "V2PoliciesController_list", "summary": "List policies", "tags": [ "policies" ], "security": [ { "bearer": [] }, { "x-api-key": [] } ], "responses": { "200": { "description": "Policy list" } } }, "post": { "operationId": "V2PoliciesController_create", "summary": "Create policy", "tags": [ "policies" ], "security": [ { "bearer": [] }, { "x-api-key": [] } ], "responses": { "200": { "description": "Policy created" } } } }, "/api/v1/policies/{policyId}/versions": { "get": { "operationId": "V2PoliciesController_listVersions", "summary": "List policy version hashes", "tags": [ "policies" ], "security": [ { "bearer": [] }, { "x-api-key": [] } ], "parameters": [ { "name": "policyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chainId", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Version rows" } } } }, "/api/v1/policies/{policyId}": { "get": { "operationId": "V2PoliciesController_getOne", "summary": "Get current policy", "tags": [ "policies" ], "security": [ { "bearer": [] }, { "x-api-key": [] } ], "parameters": [ { "name": "policyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chainId", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Policy detail" } } }, "patch": { "operationId": "V2PoliciesController_update", "summary": "Append a new policy snapshot", "tags": [ "policies" ], "security": [ { "bearer": [] }, { "x-api-key": [] } ], "parameters": [ { "name": "policyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chainId", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Updated policy" } } } }, "/api/v1/receipts/verify": { "post": { "operationId": "V2ReceiptsController_postVerify", "summary": "Verify signed receipt (signature vs digest)", "tags": [ "receipts" ], "security": [ { "bearer": [] }, { "x-api-key": [] } ], "responses": { "200": { "description": "valid flag" } } } }, "/api/v1/receipts/{receiptId}": { "get": { "operationId": "V2ReceiptsController_getOne", "summary": "Get receipt by id", "tags": [ "receipts" ], "security": [ { "bearer": [] }, { "x-api-key": [] } ], "parameters": [ { "name": "receiptId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Receipt" } } } }, "/api/v1/receipts/{receiptId}/execution": { "post": { "operationId": "V2ReceiptsController_postExecution", "summary": "Report client execution (issued → executed)", "tags": [ "receipts" ], "security": [ { "bearer": [] }, { "x-api-key": [] } ], "parameters": [ { "name": "receiptId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated receipt" } } } } }, "info": { "title": "AgentChain & PRIOR API", "description": "The centralized gateway for the decentralized compute network.", "version": "1.0", "contact": {} }, "tags": [], "servers": [ { "url": "https://api.agentchain.cloud", "description": "Production" } ], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http" }, "x-api-key": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "schemas": { "AgentRankDto": { "type": "object", "properties": { "agentId": { "type": "string" }, "rank": { "type": "number" }, "ari": { "type": "number" }, "vci": { "type": "number" }, "cq": { "type": "number" }, "score": { "type": "number" }, "trustLevel": { "type": "string", "enum": [ "QUARANTINE", "PROBATIONARY", "PROVISIONAL", "STANDARD", "TRUSTED" ] }, "totalTasks": { "type": "number" } }, "required": [ "agentId", "rank", "ari", "vci", "cq", "score", "trustLevel", "totalTasks" ] }, "OperatorRankDto": { "type": "object", "properties": { "operatorId": { "type": "string" }, "rank": { "type": "number" }, "fci": { "type": "number" }, "totalTasks": { "type": "number" }, "githubLogin": { "type": "string" } }, "required": [ "operatorId", "rank", "fci", "totalTasks" ] }, "PioneerRankDto": { "type": "object", "properties": { "operatorId": { "type": "string" }, "rank": { "type": "number" }, "points": { "type": "number" }, "tier": { "type": "string", "enum": [ "FREE", "PRO", "ENTERPRISE" ] }, "githubLogin": { "type": "string" } }, "required": [ "operatorId", "rank", "points", "tier" ] }, "PioneerPointEventDto": { "type": "object", "properties": { "id": { "type": "string" }, "operatorId": { "type": "string" }, "points": { "type": "number" }, "reason": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "operatorId", "points", "reason", "createdAt" ] }, "OperatorProfileDto": { "type": "object", "properties": { "id": { "type": "string" }, "githubLogin": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "email": { "type": "string" }, "tier": { "type": "string", "enum": [ "FREE", "PRO", "ENTERPRISE" ] }, "tierOverride": { "type": "string", "enum": [ "FREE", "PRO", "ENTERPRISE" ], "nullable": true }, "effectiveTier": { "type": "string", "enum": [ "FREE", "PRO", "ENTERPRISE" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "SUSPENDED", "BANNED" ] }, "flags": { "type": "object" }, "walletAddress": { "type": "string", "nullable": true }, "firstTaskAt": { "type": "string", "nullable": true }, "hasApiKey": { "type": "boolean" }, "pioneerPoints": { "type": "number" } }, "required": [ "id", "githubLogin", "tier", "tierOverride", "effectiveTier", "status", "hasApiKey" ] }, "FingerprintDto": { "type": "object", "properties": { "agentId": { "type": "string" }, "trustLevel": { "type": "string", "enum": [ "QUARANTINE", "PROBATIONARY", "PROVISIONAL", "STANDARD", "TRUSTED" ] }, "ari": { "type": "number" }, "vci": { "type": "number" }, "cq": { "type": "number", "nullable": true }, "driftScore": { "type": "number", "nullable": true }, "totalTasks": { "type": "number" }, "verifiedTasks": { "type": "number" }, "successfulTasks": { "type": "number" }, "compliantTasks": { "type": "number" }, "centroidMean": { "type": "array", "items": { "type": "number" } }, "centroidCount": { "type": "number" }, "lastActiveAt": { "type": "string", "nullable": true } }, "required": [ "agentId", "trustLevel", "ari", "vci", "totalTasks", "verifiedTasks", "centroidMean", "centroidCount" ] }, "FingerprintListDto": { "type": "object", "properties": { "agentId": { "type": "string" }, "trustLevel": { "type": "string", "enum": [ "QUARANTINE", "PROBATIONARY", "PROVISIONAL", "STANDARD", "TRUSTED" ] }, "ari": { "type": "number" }, "vci": { "type": "number" }, "cq": { "type": "number" }, "driftScore": { "type": "number" }, "totalTasks": { "type": "number" }, "verifiedTasks": { "type": "number" }, "centroidMean": { "type": "array", "items": { "type": "number" } }, "lastActiveAt": { "type": "string", "nullable": true } }, "required": [ "agentId", "trustLevel", "ari", "vci", "cq", "driftScore", "totalTasks", "verifiedTasks", "centroidMean" ] }, "FingerprintListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FingerprintListDto" } }, "count": { "type": "number" } }, "required": [ "data", "count" ] }, "DashboardStatsDto": { "type": "object", "properties": { "creditsRemaining": { "type": "number" }, "creditsTotal": { "type": "number" }, "creditsResetDays": { "type": "number" }, "tasksThisMonth": { "type": "number" }, "tasksTrend": { "type": "number" }, "verificationRate": { "type": "number" }, "verificationTrend": { "type": "number" }, "avgLatencyMs": { "type": "number" }, "latencyTrend": { "type": "number" }, "agentCount": { "type": "number" } }, "required": [ "creditsRemaining", "creditsTotal", "creditsResetDays", "tasksThisMonth", "tasksTrend", "verificationRate", "verificationTrend", "avgLatencyMs", "latencyTrend", "agentCount" ] }, "ApiKeyRecordDto": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string", "nullable": true, "description": "User-defined label" }, "keyPrefix": { "type": "string", "example": "ac_ab12...cd34", "description": "Prefix for display — never the full key" }, "rateLimitRpm": { "type": "number", "description": "Requests per minute limit" }, "lastUsedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "isTestKey": { "type": "boolean", "description": "True for system-generated diagnostic test keys — excluded from tier limit count" }, "testUsesRemaining": { "type": "number", "nullable": true, "description": "Remaining uses for test keys; null for production keys" } }, "required": [ "id", "label", "keyPrefix", "rateLimitRpm", "lastUsedAt", "createdAt", "isTestKey", "testUsesRemaining" ] }, "CreateKeyDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Production", "description": "Human-readable label for this API key" } }, "required": [ "name" ] }, "ApiKeyCreatedDto": { "type": "object", "properties": { "plainKey": { "type": "string", "description": "Plain-text key — shown ONCE, never returned again" }, "keyId": { "type": "string" }, "keyPrefix": { "type": "string", "example": "ac_ab12...cd34" } }, "required": [ "plainKey", "keyId", "keyPrefix" ] }, "SuccessResponseDto": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] }, "CreditBalanceDto": { "type": "object", "properties": { "id": { "type": "string" }, "operatorId": { "type": "string" }, "balance": { "type": "number" }, "monthlyAllocation": { "type": "number" }, "lastResetAt": { "type": "string" } }, "required": [ "id", "operatorId", "balance", "monthlyAllocation", "lastResetAt" ] }, "BillingDataDto": { "type": "object", "properties": { "balance": { "$ref": "#/components/schemas/CreditBalanceDto" } }, "required": [ "balance" ] }, "WalletNonceDto": { "type": "object", "properties": { "nonce": { "type": "string", "description": "UUID challenge nonce — single-use, sign and POST back immediately" }, "operatorId": { "type": "string", "description": "Operator ID to embed in the EIP-712 struct" }, "domain": { "type": "string", "description": "EIP-712 domain name", "example": "AgentChain" }, "chainId": { "type": "number", "description": "EIP-712 chainId — 8453 for Base Mainnet", "example": 8453 } }, "required": [ "nonce", "operatorId", "domain", "chainId" ] }, "WalletBindDto": { "type": "object", "properties": { "walletAddress": { "type": "string", "description": "Base wallet address (0x...) — must be the signer of the EIP-712 payload", "example": "0x6a8CB7fd38dB93f9679466ab42CDca8D5951f5a9" }, "signature": { "type": "string", "description": "EIP-712 signature produced by signTypedData over { wallet, operatorId, nonce }", "example": "0xabc123..." }, "nonce": { "type": "string", "description": "UUID nonce issued by GET /api/v1/operator/wallet/nonce — single-use, rotated after bind", "example": "3f87ab12-4c90-4e1d-b3d2-0e1234567890" } }, "required": [ "walletAddress", "signature", "nonce" ] }, "WalletBindResultDto": { "type": "object", "properties": { "walletAddress": { "type": "string", "description": "Bound wallet address" }, "firstBind": { "type": "boolean", "description": "True if this is the first bind (pioneer points awarded)" }, "pointsAwarded": { "type": "number", "description": "Pioneer points awarded (config-driven, default 250 on first bind, 0 on rebind)" } }, "required": [ "walletAddress", "firstBind", "pointsAwarded" ] }, "ComplianceCertDto": { "type": "object", "properties": { "id": { "type": "string" }, "operatorId": { "type": "string" }, "issuedAt": { "type": "string" }, "expiresAt": { "type": "string", "nullable": true }, "certHash": { "type": "string" }, "tier": { "type": "string", "enum": [ "PRO", "ENTERPRISE" ] } }, "required": [ "id", "operatorId", "issuedAt", "certHash", "tier" ] }, "TosStatusDto": { "type": "object", "properties": { "accepted": { "type": "boolean", "description": "Whether the operator has accepted the current ToS" }, "acceptedAt": { "type": "string", "nullable": true }, "version": { "type": "string", "nullable": true }, "ipfsCid": { "type": "string", "nullable": true } }, "required": [ "accepted" ] }, "TosAcceptDto": { "type": "object", "properties": { "version": { "type": "string", "description": "ToS version string (e.g. \"2026-03-27\")", "example": "2026-03-27" } }, "required": [ "version" ] }, "TosAcceptResultDto": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "ipfsCid": { "type": "string", "nullable": true, "description": "IPFS CID of the ToS acceptance attestation" }, "taskId": { "type": "string", "description": "ID of the system task recording this acceptance" }, "acceptedAt": { "type": "string" } }, "required": [ "accepted", "ipfsCid", "taskId", "acceptedAt" ] }, "FaucetDripDto": { "type": "object", "properties": {} } } } }