Skill: sprintmint/cpbox-answers (version 1.0.0)

--- name: answers description: "USE FOR AI-grounded answers via OpenAI-compatible /chat/completions. Two modes: single-search (fast) or deep research (enable_research=true, thorough multi-search). Streaming/blocking. Citations." --- # Answers — AI Grounding Paid Answers proxy via **x402 pay-per-use** (HTTP 402). > **Prerequisites**: This skill requires x402-payment. Complete the [setup steps](../../README.md#prerequisites) before first use. ## Service URLs | Role | Domain | |------|--------| | **API Provider** | https://www.cpbox.io | | **Facilitator** | https://www.cppay.finance | ## Endpoint (Agent Interface) ```http POST /api/x402/answers ``` ## Payment Flow (x402 Protocol) 1. **First request** (no `PAYMENT-SIGNATURE`) -> `402 Payment Required` with requirements JSON 2. **Client signs** (EIP-712) -> `PAYMENT-SIGNATURE` 3. **Retry** with `PAYMENT-SIGNATURE` -> Server settles and returns response With `@springmint/x402-payment` or `x402-sdk-go`, payment is **automatic**. ## When to Use | Use Case | Skill | Why | |--|--|--| | Quick factual answer (raw context) | `llm-context` | Single search, returns raw context for YOUR LLM | | Fast AI answer with citations | **`answers`** (single-search) | streaming, citations | | Thorough multi-search deep research | **`answers`** (research mode) | Iterative deep research, synthesized cited answer | **This endpoint** (`/res/v1/chat/completions`) supports two modes: - **Single-search** (default): Fast AI-grounded answer from a single search. Supports `enable_citations`. - **Research** (`enable_research=true`): Multi-iteration deep research with progress events and synthesized cited answer. ## Quick Start (cURL) ### Blocking (Single-Search) ```bash curl -X POST "https://www.cpbox.io/api/x402/answers" \ -H "Content-Type: application/json" \ -d '{ "messages": [{"role": "user", "content": "How does the James Webb Space Telescope work?"}], "model": "default", "stream": false }' ``` ### Streaming with Citations (Single-Search) ```bash curl -X POST "https://www.cpbox.io/api/x402/answers" \ -H "Content-Type: application/json" \ -d '{ "messages": [{"role": "user", "content": "What are recent breakthroughs in fusion energy?"}], "model": "default", "stream": true, "enable_citations": true }' ``` ### Research Mode ```bash curl -X POST "https://www.cpbox.io/api/x402/answers" \ -H "Content-Type: application/json" \ -d '{ "messages": [{"role": "user", "content": "Compare quantum computing approaches"}], "model": "default", "stream": true, "enable_research": true, [REDACTED_SECRET]: 3, [REDACTED_SECRET]: 120 }' ``` ## Using with x402-payment ### CLI (AI Agent) ```bash npx @springmint/x402-payment \ --url https://www.cpbox.io/api/x402/answers \ --method POST \ --input '{"messages":[{"role":"user","content":"How does the James Webb Space Telescope work?"}],"model":"default","stream":false}' ``` ## Payload/Response OpenAI-compatible `chat.completions` JSON + SSE streaming (pass-through). ## Two Modes | Feature | Single-Search (default) | Research (`enable_research=true`) | |--|--|--| | Speed | Fast | Slow | | Searches | 1 | Multiple (iterative) | | Streaming | Optional (`stream=true/false`) | **Required** (`stream=true`) | | Citations | `enable_citations=true` (streaming only) | Built-in (in `<answer>` tag) | | Progress events | No | Yes (`<progress>` tags) | | Blocking response | Yes (`stream=false`) | No | ## Parameters ### Standard Parameters | Parameter | Type | Required | Default | Description | |--|--|--|--|--| | `messages` | array | **Yes** | - | Single user message (exactly 1 message) | | `model` | string | **Yes** | - | Use `"default"` | | `stream` | bool | No | true | Enable SSE streaming | | `country` | string | No | "US" | Search country (2-letter country code or `ALL`) | | `language` | string | No | "en" | Response language | | `safesearch` | string | No | "moderate" | Search safety level (`off`, `moderate`, `strict`) | | `max_completion_tokens` | int | No | null | Upper bound on completion tokens | | `enable_citations` | bool | No | false | Include inline citation tags (single-search streaming only) | | `web_search_options` | object | No | null | OpenAI-compatible; `search_context_size`: `low`, `medium`, `high` | ### Research Parameters | Parameter | Type | Required | Default | Description | |--|--|--|--|--| | `enable_research` | bool | No | `false` | **Enable research mode** | | `research_allow_thinking` | bool | No | `true` | Enable extended thinking | | [REDACTED_SECRET] | int | No | `8192` | Max tokens per query (1024-16384) | | [REDACTED_SECRET] | int | No | `20` | Max total search queries (1-50) | | [REDACTED_SECRET] | int | No | `4` | Max research iterations (1-5) | | [REDACTED_SECRET] | int | No | `180` | Time budget in seconds (1-300) | | [REDACTED_SECRET] | int | No | `60` | Results per search query (1-60) | ### Constraints (IMPORTANT) | Constraint | Error | |--|--| | `enable_research=true` requires `stream=true` | "Blocking response doesn't support 'enable_research' option" | | `enable_research=true` incompatible with `enable_citations=true` | "Research mode doesn't support 'enable_citations' option" | | `enable_citations=true` requires `stream=true` | "Blocking response doesn't support 'enable_citations' option" | ## Notes for Agent Usage - Use `x402-payment` to handle the payment handshake automatically, especially for streaming (`stream=true`). ## Response Format ### Blocking Response (`stream=false`, single-search only) Standard OpenAI-compatible JSON: ```json { "id": "chatcmpl-...", "object": "chat.completion", "choices": [{"message": {"role": "assistant", "content": "The James Webb Space Telescope works by..."}, "index": 0, "finish_reason": "stop"}], "usage": {"prompt_tokens": 10, "completion_tokens": 50, "total_tokens": 60} } ``` ### Streaming Response SSE response with OpenAI-compatible chunks: ```text data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Based on"},"index":0}]} data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":" recent research"},"index":0}]} data: [DONE] ``` ### Streaming Tags by Mode #### Single-Search (with `enable_citations=true`) | Tag | Purpose | |--|--| | `<citation>` | Inline citation references | | `<usage>` | JSON cost/billing data | #### Research Mode | Tag | Purpose | Keep? | |--|--|--| | `<queries>` | Generated search queries | Debug | | `<analyzing>` | URL counts (verbose) | Debug | | `<thinking>` | URL selection reasoning | Debug | | `<progress>` | Stats: time, iterations, queries, URLs analyzed, tokens | Monitor | | `<blindspots>` | Knowledge gaps identified | **Yes** | | `<answer>` | Final synthesized answer (only the final answer is emitted; intermediate drafts are dropped) | **Yes** | | `<usage>` | JSON cost/billing data (included at end of streaming response) | **Yes** | ### Usage Tag Format The `<usage>` tag contains JSON-stringified cost and token data: ```text <usage>{"X-Request-Requests":1,"X-Request-Queries":8,"X-Request-Tokens-In":15000,"X-Request-Tokens-Out":2000,"X-Request-Requests-Cost":0.005,"X-Request-Queries-Cost":0.032,"X-Request-Tokens-In-Cost":0.075,"X-Request-Tokens-Out-Cost":0.01,"X-Request-Total-Cost":0.122}</usage> ``` ## Use Cases - **Chat interface integration**: Use this endpoint to get a web-grounded answer payload in OpenAI-compatible format. - **Deep research / comprehensive topic research**: Use research mode (`enable_research=true`) for complex questions needing multi-source synthesis (e.g., "Compare approaches to nuclear fusion"). - **OpenAI SDK drop-in**: Same SDK, same streaming format — just change `base_url` and `api_key`. Works with both sync and async clients. - **Cited answers**: Enable `enable_citations=true` in single-search mode for inline citation tags, or use research mode which automatically includes citations in its answer. ## Notes - **Timeout**: Set client timeout to at least 30s for single-search, 300s (5 min) for research - **Single message**: The `messages` array must contain exactly 1 user message - **Cost monitoring**: Parse the `<usage>` tag from streaming responses to track costs


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)