Suggest / Autocomplete
Paid Suggest proxy via x402 pay-per-use (HTTP 402).
Prerequisites: This skill requires x402-payment. Complete the setup steps 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)
CODEBLOCK0
Payment Flow (x402 Protocol)
- 1. First request ->
402 Payment Required with requirements JSON - Sign & retry with
PAYMENT-SIGNATURE -> result JSON
With @springmint/x402-payment or x402-sdk-go, payment is automatic.
Quick Start (cURL)
Basic Suggestions
CODEBLOCK1
With All Parameters
CODEBLOCK2
Using with x402-payment
CODEBLOCK3
Optional Headers:
- -
Accept-Encoding: gzip — Enable response compression
Parameters
| Parameter | Type | Required | Default | Description |
|---|
| INLINECODE5 | string | Yes | — | Suggest search query (1-400 chars, max 50 words) |
| INLINECODE6 |
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 |
|---|
| INLINECODE18 | string | Always INLINECODE19 |
| INLINECODE20 |
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)
CODEBLOCK4
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
Suggest / 自动补全
通过 x402 按次付费（HTTP 402）提供的付费 Suggest 代理。
前置条件：此技能需要 x402 支付。首次使用前请完成设置步骤。
安全性：仅提供文档说明——不含可执行代码或凭证。钱包/密钥保留在您的机器上；绝不存储在此处。
服务 URL
| 角色 | 域名 |
|---|
| API 提供方 | https://www.cpbox.io |
| 协调方 |
https://www.cppay.finance |
端点（代理接口）
http
GET /api/x402/suggest
支付流程（x402 协议）
- 1. 首次请求 -> 返回 402 Payment Required 及需求 JSON
- 签名并重试，附带 PAYMENT-SIGNATURE -> 返回结果 JSON
使用 @springmint/x402-payment 或 x402-sdk-go 时，支付为自动完成。
快速开始（cURL）
基础建议
bash
curl -s https://www.cpbox.io/api/x402/suggest?q=how+to+ \
-H Accept: application/json
带全部参数
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
配合 x402-payment 使用
bash
npx @springmint/x402-payment \
--url https://www.cpbox.io/api/x402/suggest?q=albert&rich=true&count=10 \
--method GET
可选请求头：
- - Accept-Encoding: gzip — 启用响应压缩
参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|
| q | 字符串 | 是 | — | 建议搜索查询（1-400 字符，最多 50 个词） |
| lang |
字符串 | 否 | en | 语言偏好（2 位以上语言代码，如 fr、de、zh-hans） |
| country | 字符串 | 否 | US | 搜索国家（2 位国家代码或 ALL） |
| count | 整数 | 否 | 5 | 建议数量（1-20）。实际结果可能更少 |
| rich | 布尔值 | 否 | false | 是否增强实体信息（标题、描述、图片）。需要付费搜索套餐 |
响应字段
| 字段 | 类型 | 说明 |
|---|
| type | 字符串 | 始终为 suggest |
| query.original |
字符串 | 原始建议搜索查询 |
| results | 数组 | 建议列表（可能为空） |
| results[].query | 字符串 | 建议的查询补全 |
| results[].is_entity | 布尔值？ | 建议的增强查询是否为实体（仅 rich 模式） |
| results[].title | 字符串？ | 建议查询的增强标题（仅 rich 模式） |
| results[].description | 字符串？ | 建议查询的增强描述（仅 rich 模式） |
| results[].img | 字符串？ | 建议查询的增强图片 URL（仅 rich 模式） |
值为 null 的字段将从响应中排除。非 rich 结果仅包含 query 字段。
Rich 响应示例（rich=true）
json
{
type: suggest,
query: { original: albert },
results: [
{
query: albert einstein,
is_entity: true,
title: 阿尔伯特·爱因斯坦,
description: 德裔理论物理学家,
img: https://imgs.search.provider/...
},
{ query: albert einstein quotes, is_entity: false }
]
}
使用场景
- - 即输即搜界面：实时自动补全下拉框。建议防抖 150-300 毫秒。
- RAG 查询优化：在调用 web-search 或 llm-context 前扩展部分/模糊查询。
- 实体检测：使用 rich=true 检测实体，获取标题、描述和图片用于预览卡片。
- 容错输入：从拼写错误的输入中获取干净建议，无需单独拼写检查。
注意事项
- - 延迟：设计响应时间 <100 毫秒
- 国家/语言：仅作为建议相关性提示，非严格过滤条件
- 拼写处理：建议可处理常见拼写错误，无需单独拼写检查
