@clawhub-sprintmint-825544a167
USE FOR web search. Returns ranked results with snippets, URLs, thumbnails. Supports freshness filters, SafeSearch, Goggles for custom ranking, pagination. P...
---
name: web-search
description: USE FOR web search. Returns ranked results with snippets, URLs, thumbnails. Supports freshness filters, SafeSearch, Goggles for custom ranking, pagination. Primary search endpoint.
version: 1.0.0
---
# Web Search
Paid Web Search proxy via **x402 pay-per-use** (HTTP 402).
> **Prerequisites**: This skill requires x402-payment. Complete the [setup steps](https://github.com/springmint/cpbox-skills#prerequisites) before first use.
>
> **Security**: Documentation only — no executable code or credentials. Wallet/keys stay on your machine; never stored here.
## Service URLs
| Role | Domain |
|------|--------|
| **API Provider** | https://www.cpbox.io |
| **Facilitator** | https://www.cppay.finance |
## Endpoint (Agent Interface)
```http
GET /api/x402/web-search
POST /api/x402/web-search/post
```
## Payment Flow (x402 Protocol)
This endpoint uses HTTP 402 Payment Required:
1. **First request** (no payment header) -> Server returns `402` with payment requirements JSON
2. **Client signs** the payment requirements (EIP-712) -> Produces a `PAYMENT-SIGNATURE`
3. **Retry** with `PAYMENT-SIGNATURE` header -> Server verifies, settles, returns result JSON
When using `@springmint/x402-payment` (Node.js) or `x402-sdk-go` (Go), the flow is handled **automatically**.
## Quick Start (cURL)
### Basic Search
```bash
curl -s "https://www.cpbox.io/api/x402/web-search?q=python+web+frameworks" \
-H "Accept: application/json"
```
### With Parameters
```bash
curl -s "https://www.cpbox.io/api/x402/web-search" \
-H "Accept: application/json" \
-G \
--data-urlencode "q=rust programming tutorials" \
--data-urlencode "country=US" \
--data-urlencode "search_lang=en" \
--data-urlencode "count=10" \
--data-urlencode "safesearch=moderate" \
--data-urlencode "freshness=pm"
```
## Using with x402-payment
### CLI (AI Agent)
```bash
npx @springmint/x402-payment \
--url https://www.cpbox.io/api/x402/web-search \
--method GET
```
> Tip: add query params directly to `--url`, e.g. `...?q=bitcoin+etf&freshness=pd`.
### Library (Node.js)
```ts
import { createX402FetchClient } from "@springmint/x402-payment";
const client = await createX402FetchClient();
const response = await client.request(
"https://www.cpbox.io/api/x402/web-search?q=python+web+frameworks&count=10",
{ method: "GET" },
);
const data = await response.json();
```
## When to Use Web Search
| Feature | Web Search (this) | LLM Context (`llm-context`) | Answers (`answers`) |
|--|--|--|--|
| Output | Structured results (links, snippets, metadata) | Pre-extracted page content for LLMs | End-to-end AI answers with citations |
| Result types | Web, news, videos, discussions, FAQ, infobox, locations, rich | Extracted text chunks, tables, code | Synthesized answer + source list |
| Unique features | Goggles, structured data (`schemas`), rich callbacks | Token budget control, threshold modes | Multi-iteration search, streaming, OpenAI SDK compatible |
| Speed | Fast (~0.5-1s) | Fast (<1s) | Slower (~30-180s) |
| Best for | Search UIs, data extraction, custom ranking | RAG pipelines, AI agents, grounding | Chat interfaces, thorough research |
## Parameters
| Parameter | Type | Required | Default | Description |
|--|--|--|--|--|
| `q` | string | **Yes** | - | Search query (1-400 chars, max 50 words) |
| `country` | string | No | `US` | Search country (2-letter country code or `ALL`) |
| `search_lang` | string | No | `en` | Language preference (2+ char language code) |
| `ui_lang` | string | No | `en-US` | UI language (e.g., "en-US") |
| `count` | int | No | `20` | Max results per page (1-20) |
| `offset` | int | No | `0` | Page offset for pagination (0-9) |
| `safesearch` | string | No | `moderate` | Adult content filter (`off`/`moderate`/`strict`) |
| `freshness` | string | No | - | Time filter (`pd`/`pw`/`pm`/`py` or date range) |
| `text_decorations` | bool | No | `true` | Include highlight markers |
| `spellcheck` | bool | No | `true` | Auto-correct query |
| `result_filter` | string | No | - | Filter result types (comma-separated) |
| `goggles` | string | No | - | Custom ranking filter (URL or inline) |
| `extra_snippets` | bool | No | - | Get up to 5 extra snippets per result |
| `operators` | bool | No | `true` | Apply search operators |
| `units` | string | No | - | Measurement units (`metric`/`imperial`) |
| `enable_rich_callback` | bool | No | `false` | Enable rich 3rd party data callback |
| `include_fetch_metadata` | bool | No | `false` | Include `fetched_content_timestamp` on results |
### Freshness Values
| Value | Description |
|--|--|
| `pd` | Past day (24 hours) |
| `pw` | Past week (7 days) |
| `pm` | Past month (31 days) |
| `py` | Past year (365 days) |
| `YYYY-MM-DDtoYYYY-MM-DD` | Custom date range |
### Result Filter Values
Filter types: `discussions`, `faq`, `infobox`, `news`, `query`, `videos`, `web`, `locations`
```bash
# Only web and video results
curl "...&result_filter=web,videos"
```
### Location Headers (Optional)
For location-aware results, add these headers. **Lat/Long is sufficient** when coordinates are known — the other headers are only needed as a fallback when coordinates are unavailable.
| Header | Type | Description |
|--|--|--|
| `X-Loc-Lat` | float | User latitude (-90.0 to 90.0) |
| `X-Loc-Long` | float | User longitude (-180.0 to 180.0) |
| `X-Loc-Timezone` | string | IANA timezone (e.g., "America/San_Francisco") |
| `X-Loc-City` | string | City name |
| `X-Loc-State` | string | State/region code (ISO 3166-2) |
| `X-Loc-State-Name` | string | State/region full name (e.g., "California") |
| `X-Loc-Country` | string | 2-letter country code |
| `X-Loc-Postal-Code` | string | Postal code (e.g., "94105") |
> **Priority**: `X-Loc-Lat` + `X-Loc-Long` take precedence. When provided, downstream services resolve the location directly from coordinates and the text-based headers (City, State, Country, Postal-Code) are not used for location resolution. Provide text-based headers **only** when you don't have coordinates. Sending both won't break anything — lat/long simply wins.
## Response Format
### Response Fields
| Field | Type | Description |
|--|--|--|
| `type` | string | Always `"search"` |
| `query.original` | string | The original search query |
| `query.altered` | string? | Spellcheck-corrected query (if changed) |
| `query.cleaned` | string? | Cleaned/normalized query |
| `query.spellcheck_off` | bool? | Whether spellcheck was disabled |
| `query.more_results_available` | bool | Whether more pages exist |
| `query.show_strict_warning` | bool? | True if strict safesearch blocked adult results |
| `query.search_operators` | object? | Applied search operators (`applied`, `cleaned_query`, `sites`) |
| `web.type` | string | Always `"search"` |
| `web.results[].title` | string | Page title |
| `web.results[].url` | string | Page URL |
| `web.results[].description` | string? | Snippet/description text |
| `web.results[].age` | string? | Human-readable age (e.g., "2 days ago") |
| `web.results[].language` | string? | Content language code |
| `web.results[].meta_url` | object | URL components (`scheme`, `netloc`, `hostname`, `path`) |
| `web.results[].thumbnail` | object? | Thumbnail (`src`, `original`) |
| `web.results[].thumbnail.original` | string? | Original full-size image URL |
| `web.results[].thumbnail.logo` | bool? | Whether the thumbnail is a logo |
| `web.results[].profile` | object? | Publisher identity (`name`, `url`, `long_name`, `img`) |
| `web.results[].page_age` | string? | ISO datetime of publication (e.g., `"2025-04-12T14:22:41"`) |
| `web.results[].extra_snippets` | list[str]? | Up to 5 additional excerpts |
| `web.results[].deep_results` | object? | Additional links (`buttons`, `links`) from the page |
| `web.results[].schemas` | list? | Raw schema.org structured data |
| `web.results[].product` | object? | Product info and reviews |
| `web.results[].recipe` | object? | Recipe details (ingredients, time, ratings) |
| `web.results[].article` | object? | Article metadata (author, publisher, date) |
| `web.results[].book` | object? | Book info (author, ISBN, rating) |
| `web.results[].software` | object? | Software product info |
| `web.results[].rating` | object? | Aggregate ratings |
| `web.results[].faq` | object? | FAQ found on the page |
| `web.results[].movie` | object? | Movie info (directors, actors, genre) |
| `web.results[].video` | object? | Video metadata (duration, views, creator) |
| `web.results[].location` | object? | Location/restaurant details |
| `web.results[].qa` | object? | Question/answer info |
| `web.results[].creative_work` | object? | Creative work data |
| `web.results[].music_recording` | object? | Music/song data |
| `web.results[].organization` | object? | Organization info |
| `web.results[].review` | object? | Review data |
| `web.results[].content_type` | string? | Content type classification |
| `web.results[].fetched_content_timestamp` | int? | Fetch timestamp (with `include_fetch_metadata=true`) |
| `web.mutated_by_goggles` | bool | Whether results were re-ranked by Goggles |
| `web.family_friendly` | bool | Whether results are family-friendly |
| `mixed` | object? | Preferred display order (see Mixed Response below) |
| `discussions.results[]` | array? | Forum discussion clusters |
| `discussions.results[].data.forum_name` | string? | Forum/community name |
| `discussions.results[].data.num_answers` | int? | Number of answers/replies |
| `discussions.results[].data.question` | string? | Discussion question |
| `discussions.results[].data.top_comment` | string? | Top-voted comment excerpt |
| `faq.results[]` | array? | FAQ entries |
| `news.results[]` | array? | News articles |
| `videos.results[]` | array? | Video results |
| `infobox.results[]` | array? | Knowledge graph entries |
| `locations.results[]` | array? | Local POI results |
| `rich.hint.vertical` | string? | Rich result type |
| `rich.hint.callback_key` | string? | Callback key for rich data |
### JSON Example
```json
{
"type": "search",
"query": {
"original": "python frameworks",
"altered": "python web frameworks",
"spellcheck_off": false,
"more_results_available": true
},
"web": {
"type": "search",
"results": [
{
"title": "Top Python Web Frameworks",
"url": "https://example.com/python-frameworks",
"description": "A comprehensive guide to Python web frameworks...",
"age": "2 days ago",
"language": "en",
"meta_url": {
"scheme": "https",
"netloc": "example.com",
"hostname": "example.com",
"path": "/python-frameworks"
},
"thumbnail": {
"src": "https://...",
"original": "https://original-image-url.com/img.jpg"
},
"extra_snippets": ["Additional excerpt 1...", "Additional excerpt 2..."]
}
],
"family_friendly": true
},
"mixed": {
"type": "mixed",
"main": [
{"type": "web", "index": 0, "all": false},
{"type": "web", "index": 1, "all": false},
{"type": "videos", "all": true}
],
"top": [],
"side": []
},
"videos": { "...": "..." },
"news": { "...": "..." },
"rich": {
"type": "rich",
"hint": {
"vertical": "weather",
"callback_key": "<callback_key_hex>"
}
}
}
```
### Mixed Response
The `mixed` object defines the preferred display order of results across types. It contains three arrays:
| Array | Purpose |
|--|--|
| `main` | Primary result list (ordered sequence of results to display) |
| `top` | Results to display above main results |
| `side` | Results to display alongside main results (e.g., infobox) |
Each entry is a `ResultReference` with `type` (e.g., `"web"`, `"videos"`), `index` (into the corresponding result array), and `all` (`true` to include all results of that type at this position).
## Search Operators
| Operator | Syntax | Description |
|--|--|--|
| Site | `site:example.com` | Limit results to a specific domain |
| File extension | `ext:pdf` | Results with a specific file extension |
| File type | `filetype:pdf` | Results created in a specific file type |
| In title | `intitle:python` | Pages with term in the title |
| In body | `inbody:tutorial` | Pages with term in the body |
| In page | `inpage:guide` | Pages with term in title or body |
| Language | `lang:es` | Pages in a specific language (ISO 639-1) |
| Location | `loc:us` | Pages from a specific country (ISO 3166-1 alpha-2) |
| Include | `+term` | Force inclusion of a term |
| Exclude | `-term` | Exclude pages containing the term |
| Exact match | `"exact phrase"` | Match the exact phrase in order |
| AND | `term1 AND term2` | Both terms required (uppercase) |
| OR / NOT | `term1 OR term2`, `NOT term` | Logical operators (uppercase) |
Set `operators=false` to disable operator parsing.
## Goggles (Custom Ranking)
Goggles let you **re-rank search results** — boost trusted sources, suppress SEO spam, or build focused search scopes.
| Method | Example |
|--|--|
| **Hosted** | `--data-urlencode "goggles=https://<hosted-goggle-url>"` |
| **Inline** | `--data-urlencode 'goggles=$discard\n$site=example.com'` |
> **Hosted** goggles should be hosted on a public URL and include `! name:`, `! description:`, `! author:` headers. **Inline** rules need no registration.
**Syntax**: `$boost=N` / `$downrank=N` (1–10), `$discard`, `$site=example.com`. Combine with commas: `$site=example.com,boost=3`. Separate rules with `\n` (`%0A`).
**Allow list**: `$discard\n$site=docs.python.org\n$site=developer.mozilla.org` — **Block list**: `$discard,site=pinterest.com\n$discard,site=quora.com`
**Resources**: See your upstream provider's Goggles documentation.
## Rich Data Enrichments
For queries about weather, stocks, sports, currency, etc., use the rich callback workflow:
```bash
# 1. Search with rich callback enabled
curl -s "https://www.cpbox.io/api/x402/web-search?q=weather+san+francisco&enable_rich_callback=true" \
-H "Accept: application/json"
# Response includes: "rich": {"hint": {"callback_key": "abc123...", "vertical": "weather"}}
# 2. Get rich data with the callback key
curl -s "https://www.cpbox.io/api/x402/web-rich?callback_key=abc123..." \
-H "Accept: application/json"
```
**Supported Rich Types**: Calculator, Definitions, Unit Conversion, Unix Timestamp, Package Tracker, Stock, Currency, Cryptocurrency, Weather, American Football, Baseball, Basketball, Cricket, Football/Soccer, Ice Hockey, Web3, Translator
### Rich Callback Endpoint
```http
GET /api/x402/web-rich?callback_key=...
```
| Parameter | Type | Required | Description |
|--|--|--|--|
| `callback_key` | string | Yes | Callback key from the web search `rich.hint.callback_key` field |
## Use Cases
- **General-purpose search integration**: Richest result set (web, news, videos, discussions, FAQ, infobox, locations) in one call. For RAG/LLM grounding, prefer `llm-context`.
- **Structured data extraction**: Products, recipes, ratings, articles via `schemas` and typed fields on results.
- **Custom search with Goggles**: Boost/discard sites with inline rules or hosted Goggles for fully customized ranking.
## Notes
- **Pagination**: Use `offset` (0-9) with `count` to page through results
- **Count**: Max 20 for web search; actual results may be less than requested
USE FOR video search. Returns videos with title, URL, thumbnail, duration, view count, creator. Supports freshness filters, SafeSearch, pagination.
---
name: videos-search
description: USE FOR video search. Returns videos with title, URL, thumbnail, duration, view count, creator. Supports freshness filters, SafeSearch, pagination.
version: 1.0.0
---
# Videos Search
Paid Videos Search proxy via **x402 pay-per-use** (HTTP 402).
> **Prerequisites**: This skill requires x402-payment. Complete the [setup steps](https://github.com/springmint/cpbox-skills#prerequisites) before first use.
>
> **Security**: Documentation only — no executable code or credentials. Wallet/keys stay on your machine; never stored here.
## Service URLs
| Role | Domain |
|------|--------|
| **API Provider** | https://www.cpbox.io |
| **Facilitator** | https://www.cppay.finance |
## Endpoint (Agent Interface)
```http
GET /api/x402/videos-search
POST /api/x402/videos-search/post
```
## Payment Flow (x402 Protocol)
1. **First request** -> `402 Payment Required` with requirements JSON
2. **Sign & retry** with `PAYMENT-SIGNATURE` -> result JSON
With `@springmint/x402-payment` or `x402-sdk-go`, payment is **automatic**.
## Quick Start (cURL)
### Basic Search
```bash
curl -s "https://www.cpbox.io/api/x402/videos-search?q=python+tutorial" \
-H "Accept: application/json"
```
### With Parameters
```bash
curl -s "https://www.cpbox.io/api/x402/videos-search" \
-H "Accept: application/json" \
-G \
--data-urlencode "q=machine learning explained" \
--data-urlencode "country=US" \
--data-urlencode "search_lang=en" \
--data-urlencode "count=20" \
--data-urlencode "freshness=pm"
```
## Using with x402-payment
```bash
npx @springmint/x402-payment \
--url "https://www.cpbox.io/api/x402/videos-search?q=python+tutorial&count=20" \
--method GET
```
## Parameters
| Parameter | Type | Required | Default | Description |
|--|--|--|--|--|
| `q` | string | **Yes** | - | Search query (1-400 chars, max 50 words) |
| `country` | string | No | `US` | Search country (2-letter country code or `ALL`) |
| `search_lang` | string | No | `en` | Language preference (2+ char language code) |
| `ui_lang` | string | No | `en-US` | UI language (e.g., "en-US") |
| `count` | int | No | `20` | Number of results (1-50) |
| `offset` | int | No | `0` | Page offset (0-9) |
| `safesearch` | string | No | `moderate` | Adult content filter (`off`/`moderate`/`strict`) |
| `freshness` | string | No | - | Time filter (`pd`/`pw`/`pm`/`py` or date range) |
| `spellcheck` | bool | No | `true` | Auto-correct query |
| `operators` | bool | No | `true` | Apply search operators |
| `include_fetch_metadata` | bool | No | `false` | Include `fetched_content_timestamp` in results |
### Freshness Values
| Value | Description |
|--|--|
| `pd` | Past day (24 hours) |
| `pw` | Past week (7 days) |
| `pm` | Past month (31 days) |
| `py` | Past year (365 days) |
| `YYYY-MM-DDtoYYYY-MM-DD` | Custom date range |
## Response Format
```json
{
"type": "videos",
"query": {
"original": "python tutorial",
"spellcheck_off": false
},
"extra": {
"might_be_offensive": false
},
"results": [
{
"type": "video_result",
"title": "Python Tutorial for Beginners",
"url": "https://www.youtube.com/watch?v=rfscVS0vtbw",
"description": "Learn Python programming from scratch...",
"age": "February 12, 2025",
"page_age": "2025-02-12T00:00:00",
"page_fetched": "2025-02-12T15:00:00Z",
"thumbnail": {
"src": "https://imgs.search.provider/...",
"original": "https://i.ytimg.com/vi/rfscVS0vtbw/hqdefault.jpg"
},
"video": {
"duration": "03:45:00",
"views": 1523000,
"creator": "freeCodeCamp",
"publisher": "YouTube",
"requires_subscription": false,
"tags": ["python", "programming"],
"author": {
"name": "freeCodeCamp.org",
"url": "https://www.youtube.com/@freecodecamp"
}
},
"meta_url": {
"scheme": "https",
"netloc": "youtube.com",
"hostname": "www.youtube.com",
"favicon": "https://imgs.search.provider/...",
"path": "\u203a watch"
}
}
]
}
```
## Response Fields
| Field | Type | Description |
|--|--|--|
| `type` | string | Always `"videos"` |
| `query.original` | string | The original search query |
| `query.altered` | string? | Spellcheck-corrected query (if changed) |
| `query.cleaned` | string? | Cleaned/normalized query |
| `query.spellcheck_off` | bool? | Whether spellcheck was disabled |
| `query.show_strict_warning` | bool? | True if strict safesearch blocked adult results |
| `query.search_operators` | object? | Applied search operators (`applied`, `cleaned_query`, `sites`) |
| `extra.might_be_offensive` | bool | Whether results may contain offensive content |
| `results[].type` | string | Always `"video_result"` |
| `results[].url` | string | Source URL of the video |
| `results[].title` | string | Video title |
| `results[].description` | string? | Video description |
| `results[].age` | string? | Human-readable age (e.g. "6 months ago") or absolute date (e.g. "February 12, 2025") |
| `results[].page_age` | string? | Page age from source (ISO datetime) |
| `results[].page_fetched` | string? | ISO datetime when page was last fetched (e.g. `2025-02-12T15:00:00Z`) |
| `results[].fetched_content_timestamp` | int? | Fetch timestamp (only with `include_fetch_metadata=true`) |
| `results[].video.duration` | string? | Time string (variable format) |
| `results[].video.views` | int? | View count as integer |
| `results[].video.creator` | string? | Channel/creator name |
| `results[].video.publisher` | string? | Platform (YouTube, Vimeo, etc.) |
| `results[].video.requires_subscription` | bool? | Whether video requires a subscription |
| `results[].video.tags` | list[str]? | Tags relevant to the video |
| `results[].video.author` | object? | Author profile |
| `results[].video.author.name` | string | Author name |
| `results[].video.author.url` | string | Author profile URL |
| `results[].video.author.long_name` | string? | Extended author name |
| `results[].video.author.img` | string? | Author profile image URL |
| `results[].thumbnail.src` | string | Served thumbnail URL |
| `results[].thumbnail.original` | string? | Original thumbnail URL |
| `results[].meta_url.scheme` | string? | URL protocol scheme |
| `results[].meta_url.netloc` | string? | Network location |
| `results[].meta_url.hostname` | string? | Lowercased domain name |
| `results[].meta_url.favicon` | string? | Favicon URL |
| `results[].meta_url.path` | string? | URL path |
## Search Operators
Use search operators to refine results:
- `site:youtube.com` - Limit to specific site
- `"exact phrase"` - Match exact phrase
- `-exclude` - Exclude term
Set `operators=false` to disable operator parsing.
## Use Cases
- **Video content research**: Find tutorials, explainers, and reviews by topic. Use the `video.duration`, `video.views`, and `video.creator` metadata to filter and rank results programmatically. Prefer videos-search over web-search when you need a dedicated video index with richer metadata (duration, views, creator, tags) and up to 50 results per request.
- **Fresh video monitoring**: Use `freshness=pd` or `freshness=pw` to track newly published video content on trending topics or specific subjects.
- **Platform-specific search**: Use `site:youtube.com` or `site:vimeo.com` operators to target specific video platforms.
- **Video metadata extraction**: Get view counts, durations, creator info, and tags for analytics, content curation, or recommendation systems.
## Notes
- **Pagination**: Use `offset` (0-9) with `count` for more results
- **Max results**: Up to 50 results per request
USE FOR query autocomplete/suggestions. Fast (<100ms). Returns suggested queries as user types. Supports rich suggestions with entity info. Typo-resilient.
---
name: suggest
description: USE FOR query autocomplete/suggestions. Fast (<100ms). Returns suggested queries as user types. Supports rich suggestions with entity info. Typo-resilient.
version: 1.0.0
---
# Suggest / Autocomplete
Paid Suggest proxy via **x402 pay-per-use** (HTTP 402).
> **Prerequisites**: This skill requires x402-payment. Complete the [setup steps](https://github.com/springmint/cpbox-skills#prerequisites) before first use.
>
> **Security**: Documentation only — no executable code or credentials. Wallet/keys stay on your machine; never stored here.
## Service URLs
| Role | Domain |
|------|--------|
| **API Provider** | https://www.cpbox.io |
| **Facilitator** | https://www.cppay.finance |
## Endpoint (Agent Interface)
```http
GET /api/x402/suggest
```
## Payment Flow (x402 Protocol)
1. **First request** -> `402 Payment Required` with requirements JSON
2. **Sign & retry** with `PAYMENT-SIGNATURE` -> result JSON
With `@springmint/x402-payment` or `x402-sdk-go`, payment is **automatic**.
## Quick Start (cURL)
### Basic Suggestions
```bash
curl -s "https://www.cpbox.io/api/x402/suggest?q=how+to+" \
-H "Accept: application/json"
```
### With All Parameters
```bash
curl -s "https://www.cpbox.io/api/x402/suggest" \
-H "Accept: application/json" \
-G \
--data-urlencode "q=albert" \
--data-urlencode "country=US" \
--data-urlencode "lang=en" \
--data-urlencode "count=10" \
--data-urlencode "rich=true"
```
## Using with x402-payment
```bash
npx @springmint/x402-payment \
--url "https://www.cpbox.io/api/x402/suggest?q=albert&rich=true&count=10" \
--method GET
```
**Optional Headers**:
- `Accept-Encoding: gzip` — Enable response compression
## Parameters
| Parameter | Type | Required | Default | Description |
|--|--|--|--|--|
| `q` | string | **Yes** | — | Suggest search query (1-400 chars, max 50 words) |
| `lang` | string | No | `en` | Language preference (2+ char language code, e.g. `fr`, `de`, `zh-hans`) |
| `country` | string | No | `US` | Search country (2-letter country code or `ALL`) |
| `count` | int | No | `5` | Number of suggestions (1-20). Actual results may be fewer |
| `rich` | bool | No | `false` | Enhance with entity info (title, description, image). Paid Search plan required |
## Response Fields
| Field | Type | Description |
|--|--|--|
| `type` | string | Always `"suggest"` |
| `query.original` | string | The original suggest search query |
| `results` | array | List of suggestions (may be empty) |
| `results[].query` | string | Suggested query completion |
| `results[].is_entity` | bool? | Whether the suggested enriched query is an entity (rich only) |
| `results[].title` | string? | The suggested query enriched title (rich only) |
| `results[].description` | string? | The suggested query enriched description (rich only) |
| `results[].img` | string? | The suggested query enriched image URL (rich only) |
Fields with `null` values are excluded from the response. Non-rich results contain only the `query` field.
### Rich Response Example (`rich=true`)
```json
{
"type": "suggest",
"query": { "original": "albert" },
"results": [
{
"query": "albert einstein",
"is_entity": true,
"title": "Albert Einstein",
"description": "German-born theoretical physicist",
"img": "https://imgs.search.provider/..."
},
{ "query": "albert einstein quotes", "is_entity": false }
]
}
```
## Use Cases
- **Search-as-you-type UI**: Real-time autocomplete dropdown. Debounce 150-300ms.
- **Query refinement for RAG**: Expand partial/ambiguous queries before calling `web-search` or `llm-context`.
- **Entity detection**: Use `rich=true` to detect entities with title, description, and image for preview cards.
- **Typo-tolerant input**: Get clean suggestions from misspelled input without separate spellcheck.
## Notes
- **Latency**: Designed for <100ms response times
- **Country/lang**: Hints for suggestion relevance, not strict filters
- **Typo handling**: Suggestions handle common typos without separate spellcheck
USE FOR spell correction. Returns corrected query if misspelled. Most search endpoints have spellcheck built-in; use this only for pre-search query cleanup o...
---
name: spellcheck
description: USE FOR spell correction. Returns corrected query if misspelled. Most search endpoints have spellcheck built-in; use this only for pre-search query cleanup or "Did you mean?" UI.
version: 1.0.0
---
# Spellcheck
Paid Spellcheck proxy via **x402 pay-per-use** (HTTP 402).
> **Prerequisites**: This skill requires x402-payment. Complete the [setup steps](https://github.com/springmint/cpbox-skills#prerequisites) before first use.
>
> **Security**: Documentation only — no executable code or credentials. Wallet/keys stay on your machine; never stored here.
## Service URLs
| Role | Domain |
|------|--------|
| **API Provider** | https://www.cpbox.io |
| **Facilitator** | https://www.cppay.finance |
## Endpoint (Agent Interface)
```http
GET /api/x402/spellcheck
```
## Payment Flow (x402 Protocol)
1. **First request** -> `402 Payment Required` with requirements JSON
2. **Sign & retry** with `PAYMENT-SIGNATURE` -> result JSON
With `@springmint/x402-payment` or `x402-sdk-go`, payment is **automatic**.
## Quick Start (cURL)
```bash
curl -s "https://www.cpbox.io/api/x402/spellcheck" \
-H "Accept: application/json" \
-G \
--data-urlencode "q=artifical inteligence" \
--data-urlencode "lang=en" \
--data-urlencode "country=US"
```
## Using with x402-payment
```bash
npx @springmint/x402-payment \
--url "https://www.cpbox.io/api/x402/spellcheck?q=artifical%20inteligence&lang=en&country=US" \
--method GET
```
## Parameters
| Parameter | Type | Required | Default | Description |
|--|--|--|--|--|
| `q` | string | **Yes** | — | Query to spell check (1-400 chars, max 50 words) |
| `lang` | string | No | `en` | Language preference (2+ char language code, e.g. `en`, `fr`, `de`, `pt-br`, `zh-hans`). 51 codes supported |
| `country` | string | No | `US` | Search country (2-letter country code or `ALL`) |
## Response Fields
| Field | Type | Description |
|--|--|--|
| `type` | string | Always `"spellcheck"` |
| `query.original` | string | The input query as submitted |
| `results` | array | Spell-corrected suggestions. May be empty when no correction is found |
| `results[].query` | string | A corrected version of the query |
## Example Response
```json
{
"type": "spellcheck",
"query": {
"original": "artifical inteligence"
},
"results": [
{
"query": "artificial intelligence"
}
]
}
```
## Use Cases
- **Pre-search query cleanup**: Check spelling before deciding which search endpoint to call
- **"Did you mean?" UI**: Show users a corrected suggestion before running the search
- **Batch query normalization**: Clean up user inputs in bulk
## Notes
- **Built-in alternative**: Web Search and LLM Context have `spellcheck=true` by default — use this standalone endpoint only when you need the correction before searching
- **Context-aware**: Corrections consider the full query context, not just individual words
USE FOR news search. Returns news articles with title, URL, description, age, thumbnail. Supports freshness and date range filtering, SafeSearch filter and G...
---
name: news-search
description: USE FOR news search. Returns news articles with title, URL, description, age, thumbnail. Supports freshness and date range filtering, SafeSearch filter and Goggles for custom ranking.
version: 1.0.0
---
# News Search
Paid News Search proxy via **x402 pay-per-use** (HTTP 402).
> **Prerequisites**: This skill requires x402-payment. Complete the [setup steps](https://github.com/springmint/cpbox-skills#prerequisites) before first use.
>
> **Security**: Documentation only — no executable code or credentials. Wallet/keys stay on your machine; never stored here.
## Service URLs
| Role | Domain |
|------|--------|
| **API Provider** | https://www.cpbox.io |
| **Facilitator** | https://www.cppay.finance |
## Endpoint (Agent Interface)
```http
GET /api/x402/news-search
POST /api/x402/news-search/post
```
## 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 JSON
With `@springmint/x402-payment` or `x402-sdk-go`, payment is **automatic**.
## Quick Start (cURL)
### Basic Search
```bash
curl -s "https://www.cpbox.io/api/x402/news-search?q=space+exploration" \
-H "Accept: application/json"
```
### Recent News (Past 24 Hours)
```bash
curl -s "https://www.cpbox.io/api/x402/news-search" \
-H "Accept: application/json" \
-G \
--data-urlencode "q=cybersecurity" \
--data-urlencode "country=US" \
--data-urlencode "freshness=pd" \
--data-urlencode "count=20"
```
### Date Range Filter
```bash
curl -s "https://www.cpbox.io/api/x402/news-search" \
-H "Accept: application/json" \
-G \
--data-urlencode "q=climate summit" \
--data-urlencode "freshness=2026-01-01to2026-01-31"
```
## Using with x402-payment
```bash
npx @springmint/x402-payment \
--url https://www.cpbox.io/api/x402/news-search \
--method GET
```
## Parameters
| Parameter | Type | Required | Default | Description |
|--|--|--|--|--|
| `q` | string | **Yes** | - | Search query (1-400 chars, max 50 words) |
| `country` | string | No | `US` | Search country (2-letter country code or `ALL`) |
| `search_lang` | string | No | `en` | Language preference (2+ char language code) |
| `ui_lang` | string | No | `en-US` | UI language (e.g., "en-US") |
| `count` | int | No | `20` | Number of results (1-50) |
| `offset` | int | No | `0` | Page offset (0-9) |
| `safesearch` | string | No | `strict` | Adult content filter (`off`/`moderate`/`strict`) |
| `freshness` | string | No | - | Time filter (`pd`/`pw`/`pm`/`py` or date range) |
| `spellcheck` | bool | No | `true` | Auto-correct query |
| `extra_snippets` | bool | No | - | Up to 5 additional excerpts per result |
| `goggles` | string or array | No | - | Custom ranking filter (URL or inline; repeat param for multiple) |
| `operators` | bool | No | `true` | Apply search operators |
| `include_fetch_metadata` | bool | No | `false` | Include fetch timestamps in results |
### Freshness Values
| Value | Description |
|--|--|
| `pd` | Past day (24 hours) - ideal for breaking news |
| `pw` | Past week (7 days) |
| `pm` | Past month (31 days) |
| `py` | Past year (365 days) |
| `YYYY-MM-DDtoYYYY-MM-DD` | Custom date range |
## Response Format
```json
{
"type": "news",
"query": {
"original": "space exploration"
},
"results": [
{
"type": "news_result",
"title": "New Developments in Space Exploration",
"url": "https://news.example.com/space-exploration",
"description": "Recent missions have advanced our understanding of...",
"age": "2 hours ago",
"page_age": "2026-01-15T14:30:00",
"page_fetched": "2026-01-15T15:00:00Z",
"meta_url": {
"scheme": "https",
"netloc": "news.example.com",
"hostname": "news.example.com",
"favicon": "https://imgs.search.provider/favicon/news.example.com",
"path": "/space-exploration"
},
"thumbnail": {
"src": "https://imgs.search.provider/..."
}
}
]
}
```
## Response Fields
| Field | Type | Description |
|--|--|--|
| `type` | string | Always `"news"` |
| `query.original` | string | The original search query |
| `query.altered` | string? | Spellcheck-corrected query (if changed) |
| `query.cleaned` | string? | Cleaned/normalized query from spellchecker |
| `query.spellcheck_off` | bool? | Whether spellcheck was disabled |
| `query.show_strict_warning` | bool? | True if strict safesearch blocked results |
| `query.search_operators` | object? | Applied search operators |
| `query.search_operators.applied` | bool | Whether operators were applied |
| `query.search_operators.cleaned_query` | string? | Query after operator processing |
| `query.search_operators.sites` | list[str]? | Domains from `site:` operators |
| `results[].type` | string | Always `"news_result"` |
| `results[].title` | string | Article title |
| `results[].url` | string | Source URL of the article |
| `results[].description` | string? | Article description/summary |
| `results[].age` | string? | Human-readable age (e.g. "2 hours ago") |
| `results[].page_age` | string? | Publication date from source (ISO datetime) |
| `results[].page_fetched` | string? | When page was last fetched (ISO datetime) |
| `results[].fetched_content_timestamp` | int? | Fetch timestamp (only with `include_fetch_metadata=true`) |
| `results[].meta_url.scheme` | string? | URL protocol scheme |
| `results[].meta_url.netloc` | string? | Network location |
| `results[].meta_url.hostname` | string? | Lowercased domain name |
| `results[].meta_url.favicon` | string? | Favicon URL |
| `results[].meta_url.path` | string? | URL path |
| `results[].thumbnail.src` | string | Served thumbnail URL |
| `results[].thumbnail.original` | string? | Original thumbnail URL |
| `results[].extra_snippets` | list[str]? | Up to 5 additional excerpts per result |
## Goggles (Custom Ranking)
Goggles let you **re-rank news results** — boost trusted outlets or suppress unwanted sources.
| Method | Example |
|--|--|
| **Hosted** | `--data-urlencode "goggles=https://<hosted-goggle-url>"` |
| **Inline** | `--data-urlencode 'goggles=$discard\n$site=example.com'` |
> **Hosted** goggles should be hosted on a public URL and include `! name:`, `! description:`, `! author:` headers. **Inline** rules need no registration.
**Syntax**: `$boost=N` / `$downrank=N` (1–10), `$discard`, `$site=example.com`. Combine with commas: `$site=example.com,boost=3`. Separate rules with `\n` (`%0A`).
**Allow list**: `$discard\n$site=docs.python.org\n$site=developer.mozilla.org` — **Block list**: `$discard,site=pinterest.com\n$discard,site=quora.com`
**Resources**: See your upstream provider's Goggles documentation.
## Search Operators
Use search operators to refine results:
- `site:local-paper.com` - Limit to specific news site
- `"exact phrase"` - Match exact phrase
- `-exclude` - Exclude term
Set `operators=false` to disable operator parsing.
## Use Cases
- **Breaking news monitoring**: Use `freshness=pd` for the most recent articles on a topic.
- **Custom news feeds with Goggles**: Boost trusted sources and discard other sources.
- **Historical news research**: Use `freshness=YYYY-MM-DDtoYYYY-MM-DD` to find articles from specific time periods.
- **Multilingual news**: Combine `country`, `search_lang`, and `ui_lang` for cross-locale results.
- **Data pipelines**: Set `include_fetch_metadata=true` for `fetched_content_timestamp` on each result.
## Notes
- **SafeSearch**: Defaults to `strict`
- **Pagination**: Use `offset` (0-9) with `count`
- **Extra snippets**: Up to 5 additional excerpts when `extra_snippets=true`
USE FOR getting local business/POI details. Requires POI IDs obtained from web-search (with result_filter=locations). Returns full business information inclu...
---
name: local-pois
description: USE FOR getting local business/POI details. Requires POI IDs obtained from web-search (with result_filter=locations). Returns full business information including ratings, hours, contact info. Max 20 IDs.
version: 1.0.0
---
# Local POIs (Search API)
Paid Local POIs proxy via **x402 pay-per-use** (HTTP 402).
> **Prerequisites**: This skill requires x402-payment. Complete the [setup steps](https://github.com/springmint/cpbox-skills#prerequisites) before first use.
>
> **Two-step flow**: This endpoint requires POI IDs from a prior web search.
>
> 1. Call `web-search` with `result_filter=locations` to get POI IDs from `locations.results[].id`
> 2. Pass those IDs to this endpoint to get full business details
>
> **Security**: Documentation only — no executable code or credentials. Wallet/keys stay on your machine; never stored here.
## Service URLs
| Role | Domain |
|------|--------|
| **API Provider** | https://www.cpbox.io |
| **Facilitator** | https://www.cppay.finance |
## Endpoint (Agent Interface)
```http
GET /api/x402/local-pois
```
## Payment Flow (x402 Protocol)
1. **First request** -> `402 Payment Required` with requirements JSON
2. **Sign & retry** with `PAYMENT-SIGNATURE` -> result JSON
With `@springmint/x402-payment` or `x402-sdk-go`, payment is **automatic**.
## Quick Start (cURL)
### Get POI Details
```bash
curl -s "https://www.cpbox.io/api/x402/local-pois" \
-H "Accept: application/json" \
-H "Accept-Encoding: gzip" \
-G \
--data-urlencode "ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA="
```
### Multiple POIs with Location Headers
```bash
curl -s "https://www.cpbox.io/api/x402/local-pois" \
-H "Accept: application/json" \
-H "Accept-Encoding: gzip" \
-H "X-Loc-Lat: 37.7749" \
-H "X-Loc-Long: -122.4194" \
-G \
--data-urlencode "ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=" \
--data-urlencode "ids=loc4HTAVTJKP4RBEBZCEMBI3NG26YD4II4PATIHPDYI=" \
--data-urlencode "units=imperial"
```
**Note**: POI IDs are opaque strings returned in web search `locations.results[].id`. IDs are ephemeral and expire after ~8 hours. The example IDs above are for illustration — fetch fresh IDs via `web-search` with `result_filter=locations`. Use `--data-urlencode` since IDs may contain `=`.
### POI ID Cache & Invalidation
| Aspect | Policy |
|--------|--------|
| **TTL** | POI IDs are valid for approximately 8 hours from issuance. |
| **Invalidation** | IDs cannot be refreshed or extended. After expiry, use `web-search` with `result_filter=locations` to obtain new IDs. |
| **Caching** | You may cache POI details (hours, ratings, etc.) locally for display; do not cache IDs beyond 8 hours for reuse in `local-pois` or `local-descriptions`. |
| **Expired ID** | Requests with expired IDs return empty or error results. Re-run the web search to get fresh IDs. |
## Using with x402-payment
```bash
npx @springmint/x402-payment \
--url "https://www.cpbox.io/api/x402/local-pois?ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA%3D" \
--method GET
```
## Parameters
| Parameter | Type | Required | Default | Description |
|--|--|--|--|--|
| `ids` | string[] | **Yes** | — | POI IDs from web search results (1-20) |
| `search_lang` | string | No | `en` | Language preference (2+ char language code) |
| `ui_lang` | string | No | `en-US` | UI language (locale code, e.g., "en-US") |
| `units` | string | No | null | `metric` (km) or `imperial` (miles) |
### Location Headers (Optional)
For distance calculation from user location:
| Header | Type | Range | Description |
|--|--|--|--|
| `X-Loc-Lat` | float | -90.0 to 90.0 | User latitude |
| `X-Loc-Long` | float | -180.0 to 180.0 | User longitude |
## Response Fields
The response has `type: "local_pois"` and a `results` array of `LocationResult` objects:
| Field | Type | Description |
|--|--|--|
| `title` | string | Business/POI name |
| `url` | string | Canonical URL for the location |
| `provider_url` | string | Provider page URL |
| `type` | string | Always `"location_result"` |
| `id` | string | POI identifier (opaque string, valid ~8 hours) |
| `description` | string? | Short description |
| `postal_address.type` | string | Always `"PostalAddress"` |
| `postal_address.displayAddress` | string | Formatted display address |
| `postal_address.streetAddress` | string? | Street address |
| `postal_address.addressLocality` | string? | City |
| `postal_address.addressRegion` | string? | State/region |
| `postal_address.postalCode` | string? | Postal/ZIP code |
| `postal_address.country` | string? | Country code |
| `contact.telephone` | string? | Phone number |
| `contact.email` | string? | Email address |
| `rating.ratingValue` | float? | Average rating (≥0) |
| `rating.bestRating` | float? | Max possible rating |
| `rating.reviewCount` | int? | Number of reviews |
| `rating.profile.name` | string? | Rating provider name |
| `rating.profile.url` | string? | Rating provider URL |
| `opening_hours.current_day` | object[]? | Today's hours (`abbr_name`, `full_name`, `opens`, `closes`) |
| `opening_hours.days` | object[][]? | Hours for each day of the week (same structure) |
| `coordinates` | [float, float]? | `[latitude, longitude]` tuple |
| `distance.value` | float? | Distance from user location |
| `distance.units` | string? | Distance unit (`km` or `miles`) |
| `categories` | string[] | Business categories (default `[]`) |
| `price_range` | string? | Price indicator (`$`, `$$`, `$$$`, `$$$$`) |
| `serves_cuisine` | string[]? | Cuisine types (restaurants) |
| `thumbnail.src` | string? | Thumbnail image URL |
| `thumbnail.original` | string? | Original image URL |
| `profiles` | object[]? | External profiles (`name`, `url`, `long_name`, `img`) |
| `reviews.reviews_in_foreign_language` | bool | Whether reviews in a foreign language are available |
| `pictures.results` | object[]? | Photo thumbnails |
| `action` | object? | Action to take — has `type` (string) and `url` (string) |
| `results` | object[]? | Related web results (`LocationWebResult` with `meta_url`) |
| `timezone` | string? | IANA timezone (e.g., `America/Los_Angeles`) |
| `timezone_offset` | int? | UTC timezone offset |
### Example Response
```json
{
"type": "local_pois",
"results": [
{
"type": "location_result",
"title": "Park Mediterranean Grill",
"url": "https://yelp.com/biz/park-mediterranean-grill-sf",
"provider_url": "https://yelp.com/biz/park-mediterranean-grill-sf",
"id": "loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=",
"postal_address": {
"type": "PostalAddress",
"displayAddress": "123 Main St, San Francisco, CA 94102",
"streetAddress": "123 Main St",
"addressLocality": "San Francisco",
"addressRegion": "CA",
"postalCode": "94102",
"country": "US"
},
"contact": { "telephone": "+1 415-555-0123" },
"thumbnail": {
"src": "https://example.com/thumb.jpg",
"original": "https://example.com/original.jpg"
},
"rating": {
"ratingValue": 4.5,
"bestRating": 5.0,
"reviewCount": 234,
},
"opening_hours": {
"current_day": [
{ "abbr_name": "Mon", "full_name": "Monday", "opens": "07:00", "closes": "21:00" }
]
},
"coordinates": [37.7749, -122.4194],
"distance": { "value": 0.3, "units": "miles" },
"categories": ["Mediterranean", "Greek"],
"price_range": "$$",
"serves_cuisine": ["Mediterranean", "Greek"],
"timezone": "America/Los_Angeles"
}
]
}
```
## Getting POI IDs
POI IDs come from the **Web Search API** (`web-search`) with `result_filter=locations`:
```bash
# 1. Search for local businesses
curl -s "https://www.cpbox.io/api/x402/web-search?q=coffee+shops+near+me&result_filter=locations" \
-H "Accept: application/json" \
-H "X-Loc-Lat: 37.7749" \
-H "X-Loc-Long: -122.4194"
# 2. Extract POI IDs from locations.results[].id
# 3. Use those IDs with this endpoint
```
## Use Cases
- **Local business lookup**: Retrieve full details (hours, contact, address) for POIs surfaced in web search
- **Restaurant discovery pipeline**: Search for restaurants, fetch POI details, filter by cuisine/rating/price_range
- **Business hours checker**: Get opening_hours for a business to determine if currently open
- **Location-aware application**: Combine with location headers to get distance calculations for nearby POIs
## Notes
- **ID format**: Opaque strings (use `--data-urlencode` for cURL)
- **Units**: `metric` or `imperial` for distance measurement preference
- **Max IDs**: Up to 20 IDs per request
USE FOR getting AI-generated POI text descriptions. Requires POI IDs obtained from web-search (with result_filter=locations). Returns markdown descriptions g...
---
name: local-descriptions
description: USE FOR getting AI-generated POI text descriptions. Requires POI IDs obtained from web-search (with result_filter=locations). Returns markdown descriptions grounded in web search context. Max 20 IDs per request.
---
# Local Descriptions (Search API)
Paid Local Descriptions proxy via **x402 pay-per-use** (HTTP 402).
>
> **Prerequisites**: This skill requires x402-payment. Complete the [setup steps](../../README.md#prerequisites) before first use.
>
> **Two-step flow**: This endpoint requires POI IDs from a prior web search.
>
> 1. Call `web-search` with `result_filter=locations` to get POI IDs from `locations.results[].id`
> 2. Pass those IDs to this endpoint to get AI-generated descriptions
## Service URLs
| Role | Domain |
|------|--------|
| **API Provider** | https://www.cpbox.io |
| **Facilitator** | https://www.cppay.finance |
## Endpoint (Agent Interface)
```http
GET /api/x402/local-descriptions
```
## Payment Flow (x402 Protocol)
1. **First request** -> `402 Payment Required` with requirements JSON
2. **Sign & retry** with `PAYMENT-SIGNATURE` -> result JSON
With `@springmint/x402-payment` or `x402-sdk-go`, payment is **automatic**.
## Quick Start (cURL)
### Get POI Description
```bash
curl -s "https://www.cpbox.io/api/x402/local-descriptions?ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA%3D" \
-H "Accept: application/json" \
-H "Accept-Encoding: gzip"
```
### Multiple POIs
```bash
curl -s "https://www.cpbox.io/api/x402/local-descriptions" \
-H "Accept: application/json" \
-H "Accept-Encoding: gzip" \
-G \
--data-urlencode "ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=" \
--data-urlencode "ids=loc4HTAVTJKP4RBEBZCEMBI3NG26YD4II4PATIHPDYI="
```
**Note**: POI IDs are opaque strings returned in web search `locations.results[].id`. They are valid for approximately 8 hours. The example IDs above are for illustration — fetch fresh IDs via `web-search` with `result_filter=locations`.
## Using with x402-payment
```bash
npx @springmint/x402-payment \
--url "https://www.cpbox.io/api/x402/local-descriptions?ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA%3D" \
--method GET
```
## Parameters
| Parameter | Type | Required | Default | Description |
|--|--|--|--|--|
| `ids` | string[] | **Yes** | — | POI IDs from web search `locations.results[].id` (1-20, repeated: `?ids=a&ids=b`) |
## Response Format
### Response Fields
| Field | Type | Description |
|--|--|--|
| `type` | string | Always `"local_descriptions"` |
| `results` | array | List of description objects (entries may be `null`) |
| `results[].type` | string | Always `"local_description"` |
| `results[].id` | string | POI identifier matching the request |
| `results[].description` | string? | AI-generated markdown description, or `null` if unavailable |
### Example Response
```json
{
"type": "local_descriptions",
"results": [
{
"type": "local_description",
"id": "loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=",
"description": "### Overview\nA cozy neighborhood cafe known for its **artisanal coffee**..."
}
]
}
```
## Getting POI IDs
POI IDs come from the **Web Search API** (`web-search`) with `result_filter=locations`:
```bash
# 1. Search for local businesses
curl -s "https://www.cpbox.io/api/x402/web-search?q=restaurants+san+francisco&result_filter=locations" \
-H "Accept: application/json"
# 2. Extract POI IDs from locations.results[].id
# 3. Use those IDs with local/pois and local/descriptions
```
## Use Cases
- **Local business overview**: Pair with `local-pois` to get both structured data (hours, ratings) and narrative descriptions
- **Travel/tourism enrichment**: Add descriptive context to POIs for travel planning or destination guides
- **Search results augmentation**: Supplement web search results with AI-generated summaries of local businesses
## Notes
- **Always markdown**: Descriptions use `###` headings, bullet lists, **bold**/*italics* — always formatted as markdown
- **Travel-guide tone**: Typically 200-400 words covering what makes the POI notable
- **AI-generated**: Descriptions are AI-generated based on web search context, not sourced from business profiles
- **Availability**: Not all POIs have descriptions — `description` may be `null`
- **Max IDs**: Up to 20 IDs per request
USE FOR RAG/LLM grounding. Returns pre-extracted web content (text, tables, code) optimized for LLMs. GET + POST. Adjust max_tokens/count based on complexity...
---
name: llm-context
description: USE FOR RAG/LLM grounding. Returns pre-extracted web content (text, tables, code) optimized for LLMs. GET + POST. Adjust max_tokens/count based on complexity. Supports Goggles, local/POI. For AI answers use answers. Recommended for anyone building AI/agentic applications.
---
# LLM Context
Paid LLM Context 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
GET /api/x402/llm-context
POST /api/x402/llm-context/post
```
## 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 JSON
With `@springmint/x402-payment` or `x402-sdk-go`, payment is **automatic**.
LLM Context delivers pre-extracted, relevance-ranked web content optimized for grounding LLM responses in real-time search results. Unlike traditional web search APIs that return links and snippets, LLM Context extracts the actual page content—text chunks, tables, code blocks, and structured data—so your LLM or AI agent can reason over it directly.
## LLM Context vs AI Grounding
| Feature | LLM Context (this) | AI Grounding (`answers`) |
|--|--|--|
| Output | Raw extracted content for YOUR LLM | End-to-end AI answers with citations |
| Interface | REST API (GET/POST) | OpenAI-compatible `/chat/completions` |
| Searches | Single search per request | Multi-search (iterative research) |
| Speed | Fast (<1s) | Slower |
| Plan | Search | Answers |
| Endpoint | `/res/v1/llm/context` | `/res/v1/chat/completions` |
| Best for | AI agents, RAG pipelines, tool calls | Chat interfaces, research mode |
## Endpoint
```http
GET https://www.cpbox.io/api/x402/llm-context
POST https://www.cpbox.io/api/x402/llm-context/post
```
**Authentication**: handled by x402 payment middleware
**Optional Headers**:
- `Accept-Encoding: gzip` — Enable gzip compression
## Quick Start
### GET Request
```bash
curl -s "https://www.cpbox.io/api/x402/llm-context?q=tallest+mountains+in+the+world" \
-H "Accept: application/json"
```
### POST Request (JSON body)
```bash
curl -s --compressed -X POST "https://www.cpbox.io/api/x402/llm-context/post" \
-H "Accept: application/json" \
-H "Accept-Encoding: gzip" \
-H "Content-Type: application/json" \
-d '{"q": "tallest mountains in the world"}'
```
### With Goggles (Inline)
```bash
curl -s "https://www.cpbox.io/api/x402/llm-context" \
-H "Accept: application/json" \
-G \
--data-urlencode "q=rust programming" \
--data-urlencode 'goggles=$discard
$site=docs.rs
$site=rust-lang.org'
```
## Using with x402-payment
```bash
npx @springmint/x402-payment \
--url "https://www.cpbox.io/api/x402/llm-context?q=rust+ownership&maximum_number_of_tokens=4096" \
--method GET
```
## Parameters
### Query Parameters
| Parameter | Type | Required | Default | Description |
|--|--|--|--|--|
| `q` | string | **Yes** | - | Search query (1-400 chars, max 50 words) |
| `country` | string | No | `US` | Search country (2-letter country code or `ALL`) |
| `search_lang` | string | No | `en` | Language preference (2+ char language code) |
| `count` | int | No | `20` | Max search results to consider (1-50) |
### Context Size Parameters
| Parameter | Type | Required | Default | Description |
|--|--|--|--|--|
| `maximum_number_of_urls` | int | No | `20` | Max URLs in response (1-50) |
| `maximum_number_of_tokens` | int | No | `8192` | Approximate max tokens in context (1024-32768) |
| `maximum_number_of_snippets` | int | No | `50` | Max snippets across all URLs (1-100) |
| `maximum_number_of_tokens_per_url` | int | No | `4096` | Max tokens per individual URL (512-8192) |
| `maximum_number_of_snippets_per_url` | int | No | `50` | Max snippets per individual URL (1-100) |
### Filtering & Local Parameters
| Parameter | Type | Required | Default | Description |
|--|--|--|--|--|
| `context_threshold_mode` | string | No | `balanced` | Relevance threshold for including content (`strict`/`balanced`/`lenient`) |
| `enable_local` | bool | No | `null` | Local recall control (`true`/`false`/`null`, see below) |
| `goggles` | string/list | No | `null` | Goggle URL or inline definition for custom re-ranking |
## Context Size Guidelines
| Task Type | count | max_tokens | Example |
|--|--|--|--|
| Simple factual | 5 | 2048 | "What year was Python created?" |
| Standard queries | 20 | 8192 | "Best practices for React hooks" |
| Complex research | 50 | 16384 | "Compare AI frameworks for production" |
Larger context windows provide more information but increase latency and cost (of your inference). Start with defaults and adjust.
## Threshold Modes
| Mode | Behavior |
|--|--|
| `strict` | Higher threshold — fewer but more relevant results |
| `balanced` | Default — good balance between coverage and relevance |
| `lenient` | Lower threshold — more results, may include less relevant content |
## Local Recall
The `enable_local` parameter controls location-aware recall:
| Value | Behavior |
|--|--|
| `null` (not set) | **Auto-detect** — local recall enabled when any location header is provided |
| `true` | **Force local** — always use local recall, even without location headers |
| `false` | **Force standard** — always use standard web ranking, even with location headers |
For most use cases, omit `enable_local` and let the API auto-detect from location headers.
## Location Headers
| Header | Type | Description |
|--|--|--|
| `X-Loc-Lat` | float | Latitude (-90.0 to 90.0) |
| `X-Loc-Long` | float | Longitude (-180.0 to 180.0) |
| `X-Loc-City` | string | City name |
| `X-Loc-State` | string | State/region code (ISO 3166-2) |
| `X-Loc-State-Name` | string | State/region name |
| `X-Loc-Country` | string | 2-letter country code |
| `X-Loc-Postal-Code` | string | Postal code |
> **Priority**: `X-Loc-Lat` + `X-Loc-Long` take precedence. When provided, text-based headers (City, State, Country, Postal-Code) are not used for location resolution. Provide text-based headers **only** when you don't have coordinates.
### Example: With Coordinates
```bash
curl -s "https://www.cpbox.io/api/x402/llm-context" \
-H "Accept: application/json" \
-H "X-Loc-Lat: 37.7749" \
-H "X-Loc-Long: -122.4194" \
-G \
--data-urlencode "q=best coffee shops near me"
```
### Example: With Place Name
```bash
curl -s "https://www.cpbox.io/api/x402/llm-context" \
-H "Accept: application/json" \
-H "X-Loc-City: San Francisco" \
-H "X-Loc-State: CA" \
-H "X-Loc-Country: US" \
-G \
--data-urlencode "q=best coffee shops near me"
```
## Goggles (Custom Ranking)
Goggles let you **control which sources ground your LLM** — essential for RAG quality.
| Use Case | Goggle Rules |
|--|--|
| Official docs only | `$discard\n$site=docs.python.org` |
| Exclude user content | `$discard,site=reddit.com\n$discard,site=stackoverflow.com` |
| Academic sources | `$discard\n$site=arxiv.org\n$site=.edu` |
| No paywalls | `$discard,site=medium.com` |
| Method | Example |
|--|--|
| **Hosted** | `--data-urlencode "goggles=https://<hosted-goggle-url>"` |
| **Inline** | `--data-urlencode 'goggles=$discard\n$site=example.com'` |
> **Hosted** goggles should be hosted on a public URL and include `! name:`, `! description:`, `! author:` headers. **Inline** rules need no registration.
**Syntax**: `$boost=N` / `$downrank=N` (1–10), `$discard`, `$site=example.com`. Combine with commas: `$site=example.com,boost=3`. Separate rules with `\n` (`%0A`).
**Allow list**: `$discard\n$site=docs.python.org\n$site=developer.mozilla.org` — **Block list**: `$discard,site=pinterest.com\n$discard,site=quora.com`
**Resources**: See your upstream provider's Goggles documentation.
## Response Format
### Standard Response
```json
{
"grounding": {
"generic": [
{
"url": "https://example.com/page",
"title": "Page Title",
"snippets": [
"Relevant text chunk extracted from the page...",
"Another relevant passage from the same page..."
]
}
],
"map": []
},
"sources": {
"https://example.com/page": {
"title": "Page Title",
"hostname": "example.com",
"age": ["Wednesday, January 15, 2025", "2025-01-15", "392 days ago"]
}
}
}
```
### Local Response (with `enable_local`)
```json
{
"grounding": {
"generic": [...],
"poi": {
"name": "Business Name",
"url": "https://business.com",
"title": "Title of business.com website",
"snippets": ["Business details and information..."]
},
"map": [
{
"name": "Place Name",
"url": "https://place.com",
"title": "Title of place.com website",
"snippets": ["Place information and details..."]
}
]
},
"sources": {
"https://business.com": {
"title": "Business Name",
"hostname": "business.com",
"age": null
}
}
}
```
### Response Fields
| Field | Type | Description |
|--|--|--|
| `grounding` | object | Container for all grounding content by type |
| `grounding.generic` | array | Array of URL objects with extracted content (main grounding data) |
| `grounding.generic[].url` | string | Source URL |
| `grounding.generic[].title` | string | Page title |
| `grounding.generic[].snippets` | array | Extracted smart chunks relevant to the query |
| `grounding.poi` | object/null | Point of interest data (only with local recall) |
| `grounding.poi.name` | string/null | Point of interest name |
| `grounding.poi.url` | string/null | POI source URL |
| `grounding.poi.title` | string/null | POI page title |
| `grounding.poi.snippets` | array/null | POI text snippets |
| `grounding.map` | array | Map/place results (only with local recall) |
| `grounding.map[].name` | string/null | Place name |
| `grounding.map[].url` | string/null | Place source URL |
| `grounding.map[].title` | string/null | Place page title |
| `grounding.map[].snippets` | array/null | Place text snippets |
| `sources` | object | Metadata for all referenced URLs, keyed by URL |
| `sources[url].title` | string | Page title |
| `sources[url].hostname` | string | Source hostname |
| `sources[url].age` | array/null | Page modification dates (when available) |
**Note**: Snippets may contain plain text OR JSON-serialized structured data (tables, schemas, code blocks). LLMs handle this mixed format well.
## Use Cases
- **AI Agents**: Give your agent a web search tool that returns ready-to-use content in a single call
- **RAG Pipelines**: Ground LLM responses in fresh, relevant web content
- **AI Assistants & Chatbots**: Provide factual answers backed by real sources
- **Question Answering**: Retrieve focused context for specific queries
- **Fact Checking**: Verify claims against current web content
- **Content Research**: Gather source material on any topic with one API call
## Best Practices
- **Token budget**: Start with defaults (`maximum_number_of_tokens=8192`, `count=20`). Reduce for simple lookups, increase for complex research.
- **Source quality**: Use Goggles to restrict to trusted sources. Set `context_threshold_mode=strict` when precision > recall.
- **Performance**: Use smallest `count` and `maximum_number_of_tokens` that meet your needs. For local queries, provide location headers.
USE FOR image search. Returns images with title, source URL, thumbnail. Supports SafeSearch filter. Up to 200 results.
---
name: images-search
description: USE FOR image search. Returns images with title, source URL, thumbnail. Supports SafeSearch filter. Up to 200 results.
---
# Images Search
Paid Images Search 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
GET /api/x402/images-search
```
## Payment Flow (x402 Protocol)
1. **First request** -> `402 Payment Required` with requirements JSON
2. **Sign & retry** with `PAYMENT-SIGNATURE` -> result JSON
With `@springmint/x402-payment` or `x402-sdk-go`, payment is **automatic**.
## Quick Start (cURL)
### Basic Search
```bash
curl -s "https://www.cpbox.io/api/x402/images-search?q=mountain+landscape" \
-H "Accept: application/json"
```
### With Parameters
```bash
curl -s "https://www.cpbox.io/api/x402/images-search" \
-H "Accept: application/json" \
-G \
--data-urlencode "q=northern lights photography" \
--data-urlencode "country=US" \
--data-urlencode "search_lang=en" \
--data-urlencode "count=20" \
--data-urlencode "safesearch=strict"
```
## Using with x402-payment
```bash
npx @springmint/x402-payment \
--url "https://www.cpbox.io/api/x402/images-search?q=mountain+landscape&count=20" \
--method GET
```
## Parameters
| Parameter | Type | Required | Default | Description |
|--|--|--|--|--|
| `q` | string | **Yes** | - | Search query (1-400 chars, max 50 words) |
| `country` | string | No | `US` | Search country (2-letter country code or `ALL`) |
| `search_lang` | string | No | `en` | 2+ char language code |
| `count` | int | No | 50 | Results to return (1-200) |
| `safesearch` | string | No | `strict` | `off` or `strict` (no `moderate` for images) |
| `spellcheck` | bool | No | true | Auto-correct query; corrected query in `query.altered` |
## Response Format
```json
{
"type": "images",
"query": {
"original": "mountain landscape",
"altered": null,
"spellcheck_off": false,
"show_strict_warning": false
},
"results": [
{
"type": "image_result",
"title": "Beautiful Mountain Landscape",
"url": "https://example.com/mountain-photo",
"source": "example.com",
"page_fetched": "2025-09-15T10:30:00Z",
"thumbnail": {
"src": "https://imgs.search.provider/...",
"width": 200,
"height": 150
},
"properties": {
"url": "https://example.com/images/mountain.jpg",
"placeholder": "https://imgs.search.provider/placeholder/...",
"width": 1920,
"height": 1080
},
"meta_url": {
"scheme": "https",
"netloc": "example.com",
"hostname": "example.com",
"favicon": "https://imgs.search.provider/favicon/...",
"path": "/mountain-photo"
},
"confidence": "high"
}
],
"extra": {
"might_be_offensive": false
}
}
```
## Response Fields
| Field | Type | Description |
|--|--|--|
| `type` | string | Always `"images"` |
| `query.original` | string | Original query |
| `query.altered` | string? | Spellchecked query (null if no correction) |
| `query.spellcheck_off` | bool? | Whether spellcheck was disabled |
| `query.show_strict_warning` | bool? | True if strict safesearch hid relevant results |
| `results[]` | array | List of image results |
| `results[].type` | string | Always `"image_result"` |
| `results[].title` | string? | Image title |
| `results[].url` | string? | Page URL where image was found |
| `results[].source` | string? | Source domain |
| `results[].page_fetched` | string? | ISO datetime of last page crawl |
| `results[].thumbnail.src` | string? | Proxy-served thumbnail URL (~500px width) |
| `results[].thumbnail.width` | int? | Thumbnail width |
| `results[].thumbnail.height` | int? | Thumbnail height |
| `results[].properties.url` | string? | Original full-size image URL |
| `results[].properties.placeholder` | string? | Low-res placeholder URL (proxy-served) |
| `results[].properties.width` | int? | Original image width (may be null) |
| `results[].properties.height` | int? | Original image height (may be null) |
| `results[].meta_url.scheme` | string? | URL protocol scheme |
| `results[].meta_url.netloc` | string? | Network location |
| `results[].meta_url.hostname` | string? | Lowercased domain |
| `results[].meta_url.favicon` | string? | Favicon URL |
| `results[].meta_url.path` | string? | URL path |
| `results[].confidence` | string? | Relevance: `low`, `medium`, or `high` |
| `extra.might_be_offensive` | bool | Whether results may contain offensive content |
## Use Cases
- **Visual content discovery**: Build image galleries, mood boards, or visual research tools. Use `count=200` for comprehensive coverage. Prefer over `web-search` when you need image-specific metadata (dimensions, thumbnails).
- **Content enrichment**: Add relevant images to articles or generated content. Use `country` and `search_lang` to target your audience's locale.
- **Safe image retrieval**: Default `safesearch=strict` ensures family-friendly results out of the box. Only two modes (off/strict) — no moderate option, unlike web/video/news search.
- **High-volume batch retrieval**: Up to 200 images per request (vs 20 for web, 50 for videos/news). Ideal for bulk image sourcing or visual analysis pipelines.
## Notes
- **SafeSearch**: Defaults to `strict` for images (stricter than web search)
- **High volume**: Can return up to 200 results per request
- **Thumbnails**: Proxy-served for user privacy (500px width). Use `properties.url` for original full-resolution image.
- **Dimensions**: `properties.width/height` may be missing for some images
- **Placeholder**: `properties.placeholder` is a low-res URL (not inline base64) useful for progressive loading UX
Guide users on how to use the Batch EVM Address Balance Query API (/api/x402/batch-balance). Use when users ask about batch balance queries, multicall balanc...
---
name: batch-balance
description: Guide users on how to use the Batch EVM Address Balance Query API (/api/x402/batch-balance). Use when users ask about batch balance queries, multicall balance lookups, or how to call the x402-protected balance endpoint.
version: 1.1.0
metadata: { "openclaw": { "emoji": "💰" } }
dependencies:
- "@springmint/x402-payment"
---
# Batch EVM Address Balance Query API
Batch query EVM address balances via Multicall3, with pay-per-use powered by x402 protocol.
> **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
```
POST /api/x402/batch-balance
Content-Type: application/json
```
## Payment Flow (x402 Protocol)
This endpoint uses HTTP 402 Payment Required. The three-step flow:
1. **First request** (no payment header) -> Server returns `402` with payment requirements JSON
2. **Client signs** the payment requirements using EIP-712 -> Produces a `PAYMENT-SIGNATURE`
3. **Retry** with `PAYMENT-SIGNATURE` header -> Server verifies, settles, returns result JSON
When using `@springmint/x402-payment` (Node.js) or `x402-sdk-go` (Go), all 3 steps happen **automatically**.
## Using with x402-payment
### CLI (AI Agent)
```bash
npx @springmint/x402-payment \
--url https://www.cpbox.io/api/x402/batch-balance \
--method POST \
--input '{"chain":"ethereum","token":"","addresses":["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","0xBE0eB53F46cd790Cd13851d5EFf43D12404d33E8"]}'
```
### Library (Node.js)
```ts
import { createX402FetchClient } from "@springmint/x402-payment";
const client = await createX402FetchClient();
const response = await client.request(
"https://www.cpbox.io/api/x402/batch-balance",
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
chain: "ethereum",
token: "",
addresses: [
"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
"0xBE0eB53F46cd790Cd13851d5EFf43D12404d33E8",
],
}),
},
);
const data = await response.json();
```
- This endpoint uses EVM/ERC20 payments. See [wallet configuration](https://github.com/springmint/x402-payment#wallet-configuration) for setup options.
## Request Parameters
| Parameter | Type | Required | Description |
|-------------|----------|----------|-------------|
| `chain` | string | Yes | Chain name: `ethereum`, `bsc`, `sepolia`, etc. |
| `token` | string | No | ERC-20 contract address. Empty = native token (ETH/BNB) |
| `addresses` | []string | Yes | Array of EVM addresses to query. Max 10,000. Must be `0x`-prefixed, 42 chars. |
## Request Body Example
```json
{
"chain": "ethereum",
"token": "",
"addresses": [
"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
"0xBE0eB53F46cd790Cd13851d5EFf43D12404d33E8"
]
}
```
## Response
JSON with `data` array:
```json
{
"data": [
{"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "balance": "1500000000000000000", "error": ""},
{"address": "0xBE0eB53F46cd790Cd13851d5EFf43D12404d33E8", "balance": "25000000000000000000", "error": ""}
]
}
```
`balance` is in smallest unit (wei). Divide by `10^decimals` for human-readable value.
## Go Example (Automatic Payment)
```go
package main
import (
"bytes"
"context"
"encoding/json"
"fmt"
"net/http"
x402 "github.com/springmint/x402-sdk-go"
"github.com/springmint/x402-sdk-go/mechanisms"
"github.com/springmint/x402-sdk-go/signers"
)
func main() {
signer := signers.NewEvmClientSigner("YOUR_PRIVATE_KEY_HEX")
xClient := x402.NewX402Client()
xClient.Register("eip155:*", &mechanisms.Permit402EvmClientMechanism{Signer: signer})
xHttp := x402.NewX402HTTPClient(http.DefaultClient, xClient)
reqBody := map[string]interface{}{
"chain": "ethereum",
"token": "",
"addresses": []string{
"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
"0xBE0eB53F46cd790Cd13851d5EFf43D12404d33E8",
},
}
bodyBytes, _ := json.Marshal(reqBody)
resp, err := xHttp.RequestWithPayment(context.Background(), "POST",
"https://www.cpbox.io/api/x402/batch-balance",
string(bodyBytes),
map[string]string{"Content-Type": "application/json"},
)
if err != nil {
panic(err)
}
defer resp.Body.Close()
var result struct {
Data []struct {
Address string `json:"address"`
Balance string `json:"balance"`
Error string `json:"error"`
} `json:"data"`
}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Printf("Done! Got %d results\n", len(result.Data))
}
```
## cURL Example (Manual Two-Step)
**Step 1 - Get payment requirements:**
```bash
curl -X POST https://www.cpbox.io/api/x402/batch-balance \
-H "Content-Type: application/json" \
-d '{"chain":"ethereum","token":"","addresses":["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"]}'
# Returns HTTP 402 with payment requirements JSON
```
**Step 2 - Pay and get result:**
```bash
curl -X POST https://www.cpbox.io/api/x402/batch-balance \
-H "Content-Type: application/json" \
-H "PAYMENT-SIGNATURE: BASE64_ENCODED_SIGNED_PAYLOAD" \
-d '{"chain":"ethereum","token":"","addresses":["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"]}'
```
## ERC-20 Token Example
Query USDT balances on BSC:
```bash
curl -X POST https://www.cpbox.io/api/x402/batch-balance \
-H "Content-Type: application/json" \
-H "PAYMENT-SIGNATURE: ..." \
-d '{
"chain": "bsc",
"token": "0x55d398326f99059fF775485246999027B3197955",
"addresses": ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"]
}'
```
## Error Codes
| HTTP Code | Meaning |
|-----------|---------|
| 400 | Bad request: missing addresses, no valid addresses, or >10,000 addresses |
| 402 | Payment required (first-time request, includes payment requirements) |
| 500 | Server error (RPC call failure) |
## Pricing
Each API call costs **0.0001 USDT** (paid automatically via x402 protocol, supports BSC and TRON).
## Supported Chains
Any EVM chain configured in the platform.
USE FOR AI-grounded answers via OpenAI-compatible /chat/completions. Two modes: single-search (fast) or deep research (enable_research=true, thorough multi-s...
---
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,
"research_maximum_number_of_iterations": 3,
"research_maximum_number_of_seconds": 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 |
| `research_maximum_number_of_tokens_per_query` | int | No | `8192` | Max tokens per query (1024-16384) |
| `research_maximum_number_of_queries` | int | No | `20` | Max total search queries (1-50) |
| `research_maximum_number_of_iterations` | int | No | `4` | Max research iterations (1-5) |
| `research_maximum_number_of_seconds` | int | No | `180` | Time budget in seconds (1-300) |
| `research_maximum_number_of_results_per_query` | 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