电商 | Xona Docs

智能体购物工具，包括跨主流电商平台的商品搜索、以图搜商品，以及 TikTok Shop 搜索和商品详情。

智能体购物工具，包括跨主流电商平台的商品搜索、以图搜商品，以及 TikTok Shop 搜索和商品详情。共 4 个 endpoint，每个都由 x402 支付协议控制访问，并以 USDC 结算。也可以通过 MCP 服务器连接相同的 endpoint，用于智能体之间的调用。

商品搜索

通过一条自由文本查询，在 Google Shopping、Amazon 和 eBay 上发现商品。系统会从查询中解析价格区间、商品状况、排序方式和目标平台，然后将结果统一为同一种结构，跨平台去重并排序。价格随搜索的平台数量而变化，搜索一个平台为 $0.0067，搜索全部三个平台为 $0.02。

POST /shop/search

价格

$0.0067 - $0.02

网络

Solana

x402

也可在 Base/SKALE (USDC)、Base (USDC)、Robinhood (USDG)、Stable (USDT0) 上付款。

请求参数

参数	类型	必填	说明
`query`	`textarea`	是	自由文本商品查询。其他所有条件都从中推断，包括价格区间、商品状况、排序方式以及要搜索的平台。
`marketplaces`	`string[]`	否	将搜索限定在特定平台：google_shopping、amazon、ebay。平台越少，价格越低。留空则从查询中推断。
`price_min`	`number`	否	最低价格筛选。会覆盖查询中隐含的条件。
`price_max`	`number`	否	最高价格筛选。会覆盖查询中隐含的条件。
`condition`	`select`	否	商品状况。注意 Amazon 只销售全新商品，因此在请求二手或翻新商品时会跳过 Amazon。可选值：`new`、`open_box`、`refurbished`、`used`、`for_parts`。
`sort`	`select`	否	结果排序。relevance 会让结果在各平台间分布；任何显式排序都会严格按顺序返回。可选值：`relevance`、`price_asc`、`price_desc`、`rating`、`reviews`、`discount`、`newest`。
`country`	`string`	否	用于选择平台站点的 2 位国家代码
`limit`	`number`	否	返回商品的最大数量，1-50

响应

返回 results（已排序的商品，包含 marketplace、title、url、image、price、discount、rating、reviews_count、seller、condition、shipping，以及表示同一商品在其他平台有售的 also_available_at）、price_summary（min/max/median）、intent（查询的解析方式）以及 sources（每个平台的结果数量和耗时）

示例

curl -X POST "https://api.xona-agent.com/shop/search" \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <x402-payment-payload>" \
  -d '{
  "query": "cheapest refurbished airpods pro under $150 on ebay",
  "marketplaces": [],
  "price_min": 0,
  "price_max": 0,
  "condition": "new",
  "sort": "relevance",
  "country": "us",
  "limit": 20
}'

以图搜商品

通过照片而非文本查询来发现商品。Google Lens 会识别图片中的物品以及销售它的零售商，并统一为与商品搜索相同的结构。Identify 模式以 $0.02 返回视觉匹配结果和推导出的商品名称；Shop 模式还会将该商品在 Google Shopping、Amazon 和 eBay 上进行完整比价。

POST /shop/lens

价格

$0.02 - $0.04

网络

Solana

x402

也可在 Base/SKALE (USDC)、Base (USDC)、Robinhood (USDG)、Stable (USDT0) 上付款。

请求参数

参数	类型	必填	说明
`image_url`	`image-picker`	是	选择一张商品照片。照片上传后，生成的公开 URL 会被发送到 API，因此单个商品的清晰照片效果最好。
`mode`	`select`	否	identify 返回图片内容以及销售者。shop 还会在各平台间比较识别出的商品，由于需要执行额外搜索，费用更高。可选值：`identify`、`shop`。
`q`	`string`	否	与图片一起使用以缩小匹配范围的可选文本，例如颜色或尺码。
`marketplaces`	`string[]`	否	仅限 Shop 模式。将比价限定在 google_shopping、amazon 或 ebay。平台越少，价格越低。
`price_min`	`number`	否	丢弃低于此价格的匹配结果。
`price_max`	`number`	否	丢弃高于此价格的匹配结果。
`condition`	`select`	否	商品状况。注意 Amazon 只销售全新商品，因此在请求二手或翻新商品时会跳过 Amazon。可选值：`new`、`open_box`、`refurbished`、`used`、`for_parts`。
`sort`	`select`	否	结果排序。relevance 会优先显示 Google 标记为完全相同商品的匹配结果。可选值：`relevance`、`price_asc`、`price_desc`、`rating`、`reviews`、`discount`。
`country`	`string`	否	用于选择站点的 2 位国家代码
`limit`	`number`	否	返回匹配结果的最大数量，1-50

响应

返回 results（采用相同商品结构的已排序视觉匹配结果，Google 确认为同一商品时附带 exact_match）、identified（从最佳匹配结果推导出的商品名称，可作为文本查询复用）、is_product_image（照片主要匹配到非零售页面时为 false）、marketplace_comparison（仅限 Shop 模式）、related_queries 以及 price_summary

示例

curl -X POST "https://api.xona-agent.com/shop/lens" \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <x402-payment-payload>" \
  -d '{
  "image_url": "https://example.com/product.jpg",
  "mode": "identify",
  "q": "in black",
  "marketplaces": [],
  "price_min": 0,
  "price_max": 0,
  "condition": "new",
  "sort": "relevance",
  "country": "us",
  "limit": 20
}'

TikTok Shop 商品详情

通过 URL 获取单个 TikTok Shop 商品的完整详情。返回搜索结果中的全部内容，另外还包括卖家描述、类目、所有商品图片、规格参数、可购买的变体及每个 SKU 的价格和库存、卖家评分和所在地、库存状态，以及带有文字内容的买家评价样本。仅支持美国站点，上游服务不提供其他地区的详情，而搜索覆盖全部 16 个站点。

POST /tiktok/product

价格

$0.015

网络

Solana

x402

也可在 Base/SKALE (USDC)、Base (USDC) 上付款。

请求参数

参数	类型	必填	说明
`url`	`string`	是	TikTok Shop 商品 URL。必须是 tiktok.com 链接，TikTok Shop 搜索结果中的 url 字段可以直接使用。
`region`	`select`	否	仅限 US。上游详情 endpoint 不提供其他站点，任何其他值都会在付款前被拒绝，而不是扣费后失败。可选值：`US`。
`raw`	`boolean`	否	同时在 raw 下返回未经处理的上游数据，用于获取统一结构未覆盖的字段。

响应

返回 product（搜索商品结构，外加 description、category、images、specifications、包含每个变体价格和库存的 skus、包含评分和所在地的 seller_detail、包含文字和作者的 reviews，以及 in_stock）、found（商品下架或无法访问时为 false）以及 cached

示例

curl -X POST "https://api.xona-agent.com/tiktok/product" \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <x402-payment-payload>" \
  -d '{
  "url": "https://www.tiktok.com/shop/pdp/1732469755419464435",
  "region": "US",
  "raw": false
}'

TikTok Shop 搜索

在 TikTok Shop 平台上进行关键词搜索，覆盖 16 个国家站点。结果采用与商品搜索相同的统一结构，因此 TikTok Shop 可以与 Google Shopping、Amazon 和 eBay 放在一起比较。每个商品都包含价格、原价、折扣、评分、销量、卖家以及 TikTok 自身的徽章。价格以站点本地货币返回，绝不默认为 USD。

POST /tiktok/search

价格

$0.015

网络

Solana

x402

也可在 Base/SKALE (USDC)、Base (USDC) 上付款。

请求参数

参数	类型	必填	说明
`query`	`string`	是	要在 TikTok Shop 中搜索的内容。
`region`	`select`	否	要搜索的国家站点。TikTok 按国家划分商品目录，因此这个参数决定了你能看到的全部内容。价格以该站点的货币返回。可选值：`US`、`GB`、`ID`、`MY`、`SG`、`TH`、`VN`、`PH`、`JP`、`DE`、`FR`、`IT`、`ES`、`IE`、`MX`、`BR`。
`page`	`number`	否	要获取的结果页码。
`raw`	`boolean`	否	同时在 raw 下返回未经处理的上游数据，用于获取统一结构未覆盖的字段。

响应

返回 results（已排序的商品，包含 marketplace、product_id、title、url、image、price {amount, currency}、original_price、discount_pct、rating、reviews_count、sold_count、seller、shop_id、ship_from、badges）、total_results、total_available（TikTok 自身对该查询的匹配数量）、price_summary（min/max/median）以及 cached

示例

curl -X POST "https://api.xona-agent.com/tiktok/search" \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <x402-payment-payload>" \
  -d '{
  "query": "wireless earbuds",
  "region": "US",
  "page": 1,
  "raw": false
}'

电商

商品搜索

价格

网络

x402

以图搜商品

价格

网络

x402

TikTok Shop 商品详情

价格

网络

x402

TikTok Shop 搜索

价格

网络

x402

本页目录