{"openapi":"3.0.3","info":{"title":"BIOS x402 Service","version":"0.1.0","description":"Payment proxy for the BIOS Deep Research API, powered by the x402 protocol.\n\nThis service wraps the BIOS deep-research endpoints with crypto micro-payments using USDC on Base. Payments are verified upfront but only settled once the research job completes.\n\n## How it works\n\n1. **Start a research job** — `POST /api/deep-research/start` with an x402 `PAYMENT-SIGNATURE` header. The payment is verified but not settled yet.\n2. **Poll for results** — `GET /api/deep-research/{conversationId}` with an `X-SIWX` header (SIWE wallet signature). Only the wallet that paid can access results.\n3. **On-demand settlement** — When polling a completed job, the payment is settled immediately and results returned. A background cron also handles batch settlement.\n4. **Timeout handling** — If the payment window expires before completion, the conversation enters `timeout` status. A new payment is required to retrieve results.\n\n## SIWX Authentication (Sign-In With X)\n\nThe `GET /api/deep-research/{conversationId}` endpoint requires wallet-based authentication via EIP-4361 (SIWE). When called without a valid `X-SIWX` header, the endpoint returns `401` with a SIWE challenge. The client must sign this challenge with the same wallet that made the original payment and resend the request.\n\nThe `X-SIWX` header is a base64-encoded JSON object: `{ \"message\": \"<EIP-4361 message>\", \"signature\": \"0x...\" }`.\n\n## x402 Payment Protocol\n\nAll paid endpoints return `402 Payment Required` with a `PAYMENT-REQUIRED` header when no payment is provided. The header contains the payment requirements (price, token, network) that clients use to construct a payment.\n\nSee [x402 docs](https://docs.cdp.coinbase.com/x402/core-concepts/how-it-works) for details."},"servers":[{"url":"/","description":"Current deployment"}],"tags":[{"name":"Research","description":"Deep research endpoints"},{"name":"Data Analysis","description":"x402-protected data analysis endpoints. Upload files, run paid analysis, poll with SIWX auth, download artifacts."},{"name":"Literature","description":"x402-protected literature search endpoints. Fast mode ($0.015) returns results immediately. Deep mode ($0.15) requires polling with SIWX auth."},{"name":"Files","description":"Free file upload proxy for analysis input."},{"name":"System","description":"Health and operational endpoints"}],"paths":{"/api/deep-research/start":{"post":{"tags":["Research"],"summary":"Start a deep research job","description":"Submit a research query to BIOS. Requires an x402 payment signature.\n\nThe payment is **verified but not settled** — settlement happens asynchronously when the job completes.\n\nIf no `PAYMENT-SIGNATURE` header is provided, returns `402` with payment requirements.","operationId":"startResearch","parameters":[{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"x402 payment signature. Omit to receive `402` with payment requirements.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message","researchMode"],"properties":{"message":{"type":"string","description":"The research query or question.","example":"What are the latest developments in quantum computing?"},"researchMode":{"type":"string","enum":["steering","semi-autonomous","fully-autonomous"],"description":"Research depth. Determines pricing: steering ($0.20), semi-autonomous ($1.00), fully-autonomous ($8.00)."},"conversationId":{"type":"string","description":"Optional. Continue an existing conversation by providing its ID."},"clarificationSessionId":{"type":"string","description":"Optional. Session ID for clarification follow-ups."}}}}}},"responses":{"200":{"description":"Research job queued successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"conversationId":{"type":"string","description":"Unique ID to poll for results."},"status":{"type":"string","enum":["queued"]}}},"example":{"conversationId":"conv_abc123","status":"queued"}}}},"400":{"description":"Invalid request body or missing `message` field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Missing required field: message"}}}},"402":{"description":"Payment required. Returns payment requirements in the `PAYMENT-REQUIRED` header and response body.","headers":{"PAYMENT-REQUIRED":{"description":"Encoded payment requirements for x402 clients.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"},"example":{"x402Version":2,"resource":{"url":"https://example.com/api/deep-research/start","description":"BIOS deep research job","mimeType":"application/json"},"accepts":[{"scheme":"exact","network":"eip155:8453","amount":"200000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0xa06D...cDa9F","maxTimeoutSeconds":1800,"extra":{"name":"USDC","version":"2"}}]}}}},"500":{"description":"Internal server error (DB or payment verification failure).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Internal server error"}}}},"4xx":{"description":"Upstream BIOS API error relayed with original status code and body (e.g. 429 rate limit, 503 service unavailable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"rate limit exceeded"}}}}}}},"/api/deep-research/{conversationId}":{"get":{"tags":["Research"],"summary":"Get research results","description":"Poll for the status and results of a research job. Requires SIWX (EIP-4361 SIWE) wallet authentication — only the wallet that made the original payment can access results.\n\n- **queued** — Job is still processing. No data returned.\n- **completed** — Payment was settled. Full BIOS response returned.\n- **timeout** — Payment expired before completion. A new x402 payment is required to retrieve the results.\n\nIf the job has completed upstream but the payment hasn't been settled yet, the endpoint settles the payment on-demand and returns results immediately.","operationId":"getResearch","parameters":[{"name":"conversationId","in":"path","required":true,"description":"The conversation ID returned from `POST /api/deep-research/start`.","schema":{"type":"string"}},{"name":"X-SIWX","in":"header","required":true,"description":"SIWX authentication header. Base64-encoded JSON with `message` (EIP-4361 SIWE message) and `signature` (wallet signature). Required for all requests.","schema":{"type":"string"}},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"Required only when conversation status is `timeout`. Provide a new x402 payment to retrieve results.","schema":{"type":"string"}}],"responses":{"200":{"description":"Research status or completed results.","content":{"application/json":{"schema":{"type":"object","properties":{"conversationId":{"type":"string"},"status":{"type":"string","enum":["queued","completed"]},"data":{"type":"object","description":"BIOS research data. Only present when status is `completed`.","nullable":true}}},"examples":{"queued":{"summary":"Job still processing","value":{"conversationId":"conv_abc123","status":"queued"}},"completed":{"summary":"Job completed with results","value":{"conversationId":"conv_abc123","status":"completed","data":{"summary":"Quantum computing has seen...","sources":["https://..."]}}}}}}},"401":{"description":"Authentication required. Returns a SIWE challenge that the client must sign with the paying wallet.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"siwx":{"type":"object","description":"SIWE challenge fields. Client must construct an EIP-4361 message, sign it, and resend via X-SIWX header.","properties":{"domain":{"type":"string"},"uri":{"type":"string"},"nonce":{"type":"string"},"chainId":{"type":"integer"},"statement":{"type":"string"},"version":{"type":"string"},"issuedAt":{"type":"string","format":"date-time"},"expirationTime":{"type":"string","format":"date-time"}}}}},"example":{"error":"Authentication required","siwx":{"domain":"example.com","uri":"https://example.com/api/deep-research/conv_abc123","nonce":"a1b2c3d4e5f6","chainId":8453,"statement":"Sign in to access your BioAgent research results","version":"1","issuedAt":"2025-01-01T00:00:00.000Z","expirationTime":"2025-01-01T00:05:00.000Z"}}}}},"402":{"description":"Payment required (conversation timed out, new payment needed).","headers":{"PAYMENT-REQUIRED":{"description":"Encoded payment requirements.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"},"example":{"x402Version":2,"resource":{"url":"https://example.com/api/deep-research/conv_abc123","description":"BIOS research result retrieval (retry)","mimeType":"application/json"},"accepts":[{"scheme":"exact","network":"eip155:8453","amount":"200000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0xa06D...cDa9F","maxTimeoutSeconds":1800,"extra":{"name":"USDC","version":"2"}}]}}}},"404":{"description":"Conversation not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Conversation not found"}}}},"500":{"description":"Internal server error (DB or unknown status).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Internal server error"}}}},"4xx":{"description":"Upstream BIOS API error relayed with original status code and body (e.g. 429 rate limit, 503 service unavailable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service unavailable"}}}}}}},"/api/files/upload":{"post":{"tags":["Files"],"summary":"Upload a file for analysis","description":"Free endpoint. Upload a file to the upstream BIOS API. Returns a fileId to pass to data analysis.","operationId":"uploadFile","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The file to upload"}}}}}},"responses":{"200":{"description":"File uploaded successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileUploadResponse"}}}},"400":{"description":"Invalid request (missing file)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/analysis/run":{"post":{"tags":["Data Analysis"],"summary":"Start a paid data analysis task","description":"Submit a task description and optional file IDs. Requires x402 payment ($2.00). Returns a taskId for polling.","operationId":"startAnalysis","parameters":[{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"x402 payment signature. First request without this returns 402.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["taskDescription"],"properties":{"taskDescription":{"type":"string","description":"Description of the analysis task"},"fileIds":{"type":"array","items":{"type":"string"},"description":"Optional file IDs from POST /api/files/upload"}}}}}},"responses":{"200":{"description":"Analysis task created","content":{"application/json":{"schema":{"type":"object","properties":{"taskId":{"type":"string"},"status":{"type":"string","enum":["queued"]}}},"example":{"taskId":"task_abc123","status":"queued"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/api/agents/analysis/tasks/{taskId}":{"get":{"tags":["Data Analysis"],"summary":"Poll analysis task status / retrieve results","description":"Requires X-SIWX header (wallet auth). Returns status, or full results when completed. If timed out, returns 402 for re-payment.","operationId":"getAnalysisTask","parameters":[{"name":"taskId","in":"path","required":true,"description":"Task ID from POST /api/agents/analysis/run","schema":{"type":"string"}},{"name":"X-SIWX","in":"header","required":true,"description":"Base64-encoded JSON { message, signature } proving wallet ownership (EIP-4361 SIWE). On missing/invalid, returns 401 with siwx challenge.","schema":{"type":"string"}},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"x402 payment signature for timeout retry (only needed when status is timeout)","schema":{"type":"string"}}],"responses":{"200":{"description":"Task status or completed results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataAnalysisResponse"}}}},"401":{"description":"SIWX authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"siwx":{"type":"object","description":"SIWE challenge to sign and resend"}}}}}},"402":{"description":"Payment required (timeout retry)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/analysis/tasks/{taskId}/artifacts/{artifactId}/download":{"get":{"tags":["Data Analysis"],"summary":"Download an analysis artifact","description":"Requires X-SIWX header. Task must be completed. Returns a signed download URL.","operationId":"downloadAnalysisArtifact","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"}},{"name":"artifactId","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-SIWX","in":"header","required":true,"description":"SIWX wallet auth header","schema":{"type":"string"}}],"responses":{"200":{"description":"Artifact download URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtifactDownloadResponse"}}}},"400":{"description":"Task not completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"SIWX authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"siwx":{"type":"object"}}}}}},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/literature/query":{"post":{"tags":["Literature"],"summary":"Start a literature search","description":"Submit a question for literature search. Requires x402 payment (fast: $0.015, deep: $0.15). Fast mode returns results immediately. Deep mode returns a jobId for polling.","operationId":"startLiteratureQuery","parameters":[{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"x402 payment signature. First request without this returns 402.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["question","mode"],"properties":{"question":{"type":"string","description":"Literature search query"},"mode":{"type":"string","enum":["fast","deep"],"description":"Search depth. fast ($0.015) returns immediately, deep ($0.15) requires polling."},"maxResults":{"type":"integer","description":"Maximum number of results","nullable":true},"perSourceLimit":{"type":"integer","description":"Limit per source","nullable":true},"sources":{"type":"array","items":{"type":"string","enum":["arxiv","pubmed","clinical-trials"]},"description":"Data sources to search","nullable":true}}}}}},"responses":{"200":{"description":"Fast mode: full results. Deep mode: { jobId, status: \"queued\" }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiteratureQueryResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/api/agents/literature/jobs/{jobId}":{"get":{"tags":["Literature"],"summary":"Poll literature job (deep mode)","description":"Requires X-SIWX header (wallet auth). Returns status, or full results when completed. If timed out, returns 402 for re-payment.","operationId":"getLiteratureJob","parameters":[{"name":"jobId","in":"path","required":true,"description":"Job ID from POST /api/agents/literature/query (deep mode)","schema":{"type":"string"}},{"name":"X-SIWX","in":"header","required":true,"description":"Base64-encoded JSON { message, signature } proving wallet ownership (EIP-4361 SIWE).","schema":{"type":"string"}},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"x402 payment signature for timeout retry (only needed when status is timeout)","schema":{"type":"string"}}],"responses":{"200":{"description":"Job status or completed results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiteratureQueryResponse"}}}},"401":{"description":"SIWX authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"siwx":{"type":"object","description":"SIWE challenge to sign and resend"}}}}}},"402":{"description":"Payment required (timeout retry)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"404":{"description":"Job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/health":{"get":{"tags":["System"],"summary":"System health check","description":"Returns the health status of all system components (database, BIOS API, x402 facilitator), conversation statistics, and configuration info.\n\nReturns HTTP 503 if any component is `down`.","operationId":"healthCheck","responses":{"200":{"description":"System is healthy or degraded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"503":{"description":"System is down — at least one critical component is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}}},"/api/cron":{"get":{"tags":["System"],"summary":"Trigger settlement cron job","description":"Processes all `queued` conversations: checks BIOS for completion, settles valid payments, and marks expired ones as `timeout`.\n\nProtected by a Bearer token (`CRON_SECRET`). Typically invoked by Vercel Cron every minute.","operationId":"triggerCron","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Cron job executed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}},"example":{"ok":true}}}},"401":{"description":"Unauthorized — invalid or missing Bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Unauthorized"}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"CRON_SECRET Bearer token for the cron endpoint."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error message."},"reason":{"type":"string","description":"Machine-readable reason (payment errors).","nullable":true},"message":{"type":"string","description":"Human-readable details (payment errors).","nullable":true}},"required":["error"]},"HealthResponse":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded","down"]},"timestamp":{"type":"string","format":"date-time"},"uptime":{"type":"integer","description":"Seconds since process start."},"version":{"type":"string"},"components":{"type":"object","properties":{"upstreamApi":{"$ref":"#/components/schemas/ComponentHealth"},"database":{"$ref":"#/components/schemas/ComponentHealth"}}},"config":{"type":"object","properties":{"paymentAddress":{"type":"string"},"upstreamApiBaseUrl":{"type":"string"},"network":{"type":"string"},"pricing":{"type":"object","additionalProperties":{"type":"string"}}}}}},"PaymentRequired":{"type":"object","description":"x402 payment requirements returned when no valid payment is provided.","properties":{"x402Version":{"type":"integer","description":"x402 protocol version.","example":2},"resource":{"type":"object","description":"The resource that requires payment.","properties":{"url":{"type":"string","description":"The resource URL that requires payment.","example":"https://example.com/api/deep-research/start"},"description":{"type":"string","description":"Human-readable description of the paid resource.","example":"BIOS deep research job"},"mimeType":{"type":"string","example":"application/json"}}},"accepts":{"type":"array","description":"List of accepted payment methods.","items":{"type":"object","properties":{"scheme":{"type":"string","description":"Payment scheme identifier.","example":"exact"},"network":{"type":"string","description":"Chain ID in CAIP-2 format.","example":"eip155:8453"},"amount":{"type":"string","description":"Amount in token base units (USDC has 6 decimals, so 200000 = $0.20).","example":"200000"},"asset":{"type":"string","description":"Token contract address (USDC on Base).","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},"payTo":{"type":"string","description":"Wallet address to receive payment.","example":"0xa06D...cDa9F"},"maxTimeoutSeconds":{"type":"integer","description":"Maximum seconds before the payment authorization expires. Varies by researchMode: steering (1800), semi-autonomous (4200), fully-autonomous (29400).","example":1800},"extra":{"type":"object","description":"Additional scheme-specific fields.","properties":{"name":{"type":"string","description":"Token name.","example":"USDC"},"version":{"type":"string","description":"Token contract version.","example":"2"}}}}}},"extensions":{"type":"object","description":"x402 Bazaar discovery extensions. Contains metadata for AI agent discoverability via x402scan.","properties":{"bazaar":{"type":"object","properties":{"info":{"type":"object","description":"Example input/output for the endpoint, used by AI agents to understand how to call it."},"schema":{"type":"object","description":"JSON Schema describing the expected input and output format."}}}}}}},"ComponentHealth":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded","down"]},"latencyMs":{"type":"integer","nullable":true},"message":{"type":"string","nullable":true}}},"FileUploadResponse":{"type":"object","properties":{"fileId":{"type":"string"},"filename":{"type":"string"},"contentType":{"type":"string"},"size":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}},"DataAnalysisResponse":{"type":"object","properties":{"id":{"type":"string","nullable":true},"status":{"type":"string","nullable":true,"enum":["queued","completed","failed","timeout"]},"success":{"type":"boolean","nullable":true},"answer":{"type":"string","nullable":true},"directAnswer":{"type":"string","nullable":true},"reasoning":{"type":"array","items":{"type":"string"},"nullable":true},"artifacts":{"type":"array","items":{"type":"object"},"nullable":true}}},"LiteratureQueryResponse":{"type":"object","properties":{"answer":{"type":"string","nullable":true},"formattedAnswer":{"type":"string","nullable":true},"references":{"type":"array","items":{"type":"object"},"nullable":true},"contextPassages":{"type":"array","items":{"type":"object"},"nullable":true},"jobId":{"type":"string","nullable":true},"status":{"type":"string","nullable":true,"enum":["queued","completed","failed","timeout","pending"]},"reasoning":{"type":"array","items":{"type":"string"},"nullable":true}}},"ArtifactDownloadResponse":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"expiresIn":{"type":"integer","description":"URL expiry time in seconds"}}}}}}