onebound-api

Search Taobao and 1688 products, and fetch product details, through the Onebound platform gateway.

Jeff2011eng@jeff2011eng

Install

openclaw skills install @jeff2011eng/onebound-api

Onebound API

Provides four e-commerce data capabilities through the Onebound platform gateway:

Taobao Keyword Search - Search Taobao and Tmall products by keyword
Taobao Item Detail - Fetch detailed Taobao product data by item ID
1688 Keyword Search - Search 1688 products by keyword
1688 Item Detail - Fetch detailed 1688 product data by item ID

Setup

Users should register on your Onebound platform, create a platform API key, and use that key with this skill.

Set these environment variables:

Variable	Description	Example
`ONEBOUND_API_KEY`	Your platform API key	`ak_xxxxxxxxxxxx`
`ONEBOUND_BASE_URL`	Platform gateway base URL, optional	`https://onebound.vercel.app`

Workflow

Taobao Keyword Search

Use when the user asks to search Taobao or Tmall products by keyword.

Run:

bash

bash {baseDir}/scripts/taobao-item-search.sh "<keyword>" "<page>" "<page_size>" "<sort>" "<cat>"

keyword - Search keyword, required
page - Page number, optional, defaults to 1
page_size - Page size, optional, defaults to 10
sort - Sort mode, optional
cat - Category ID, optional, defaults to 0

Example:

bash

bash {baseDir}/scripts/taobao-item-search.sh "女装"
bash {baseDir}/scripts/taobao-item-search.sh "蓝牙耳机" "1" "20"

Taobao Item Detail

Use when the user asks to fetch Taobao product details by item ID.

Run:

bash

bash {baseDir}/scripts/taobao-item-detail.sh "<num_iid>" "<is_promotion>"

num_iid - Taobao item ID, required
is_promotion - Whether to request promotion info, optional, defaults to 1

Example:

bash

bash {baseDir}/scripts/taobao-item-detail.sh "652874751412"

1688 Keyword Search

Use when the user asks to search 1688 products by keyword.

Run:

bash

bash {baseDir}/scripts/alibaba-1688-item-search.sh "<keyword>" "<page>" "<page_size>" "<sort>" "<cat>"

keyword - Search keyword, required
page - Page number, optional, defaults to 1
page_size - Page size, optional, defaults to 40
sort - Sort mode, optional
cat - Category ID, optional, defaults to 0

Example:

bash

bash {baseDir}/scripts/alibaba-1688-item-search.sh "女装"
bash {baseDir}/scripts/alibaba-1688-item-search.sh "围巾" "1" "40"

1688 Item Detail

Use when the user asks to fetch 1688 product details by item ID.

Run:

bash

bash {baseDir}/scripts/alibaba-1688-item-detail.sh "<num_iid>" "<sales_data>" "<agent>"

num_iid - 1688 item ID, required
sales_data - Whether to include recent sales data, optional, defaults to 0
agent - Whether to include distribution pricing data, optional, defaults to 0

Example:

bash

bash {baseDir}/scripts/alibaba-1688-item-detail.sh "610947572360"

Output Format

Scripts output results in Markdown format. Present the output directly to the user.

OpenAPI Specification

For integration with OpenClaw, the gateway exposes the following OpenAPI Specification:

yaml

openapi: 3.0.3
info:
  title: OneBound AI Skills API
  description: 提供淘宝(Taobao)和1688电商平台的商品数据检索与详情获取能力，专为AI Agent与OpenClaw技能设计。
  version: 1.0.0
  contact:
    name: API Support
    url: https://onebound.vercel.app

servers:
  - url: https://onebound.vercel.app/api/v1/proxy
    description: 生产环境网关

# 安全认证方式配置：要求用户提供 API Key (Bearer Token 格式)
security:
  - bearerAuth: []

paths:
  /taobao/item-search:
    get:
      summary: 淘宝商品关键词搜索
      description: 通过关键词搜索淘宝平台上的商品，支持分页。返回商品列表、价格、销量、主图等基础信息。
      operationId: searchTaobaoItems
      tags:
        - Taobao
      parameters:
        - name: q
          in: query
          description: 搜索关键词 (例如："女装", "iPhone 15")
          required: true
          schema:
            type: string
            maxLength: 100
        - name: page
          in: query
          description: 页码 (默认第1页)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 1
      responses:
        '200':
          description: 搜索成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: 请求参数错误 (例如缺少关键词)
        '401':
          description: API Key 缺失或无效
        '402':
          description: 账户余额不足
        '429':
          description: 请求过于频繁 (触发限流)

  /taobao/item-detail:
    get:
      summary: 淘宝商品详情获取
      description: 通过商品ID(num_iid)获取淘宝商品的详细信息，包括SKU属性、图文详情、库存状态等。
      operationId: getTaobaoItemDetail
      tags:
        - Taobao
      parameters:
        - name: num_iid
          in: query
          description: 淘宝商品唯一数字ID (例如："652874751412")
          required: true
          schema:
            type: string
            pattern: '^\d+$'
      responses:
        '200':
          description: 获取详情成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
        '400':
          description: 请求参数错误 (例如ID不是纯数字)
        '401':
          description: API Key 缺失或无效
        '402':
          description: 账户余额不足

  /1688/item-search:
    get:
      summary: 1688商品关键词搜索
      description: 通过关键词搜索阿里巴巴1688平台上的商品，适用于B2B采购比价场景。
      operationId: search1688Items
      tags:
        - 1688
      parameters:
        - name: q
          in: query
          description: 搜索关键词 (例如："批发水杯", "定制包装盒")
          required: true
          schema:
            type: string
            maxLength: 100
        - name: page
          in: query
          description: 页码 (默认第1页)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 1
      responses:
        '200':
          description: 搜索成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'

  /1688/item-detail:
    get:
      summary: 1688商品详情获取
      description: 通过商品ID(num_iid)获取1688商品的详细信息，包括起批量、阶梯价格、供应商信息等。
      operationId: get1688ItemDetail
      tags:
        - 1688
      parameters:
        - name: num_iid
          in: query
          description: 1688商品唯一数字ID (例如："610947572360")
          required: true
          schema:
            type: string
            pattern: '^\d+$'
      responses:
        '200':
          description: 获取详情成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API_KEY

  schemas:
    SearchResponse:
      type: object
      properties:
        items:
          type: array
          description: 搜索到的商品列表
          items:
            type: object
            properties:
              title:
                type: string
                description: 商品标题
              price:
                type: number
                description: 商品价格
              pic_url:
                type: string
                description: 商品主图链接
              sales:
                type: integer
                description: 销量
              num_iid:
                type: string
                description: 商品ID (用于查询详情)
        gateway_request_id:
          type: string
          description: 网关请求流水号
        cost:
          type: number
          description: 本次调用扣费金额
        balance:
          type: number
          description: 账户剩余余额
          
    DetailResponse:
      type: object
      properties:
        item:
          type: object
          description: 商品详细信息
          properties:
            title:
              type: string
            price:
              type: number
            desc:
              type: string
              description: 图文详情 (HTML格式)
            skus:
              type: object
              description: 商品SKU信息与价格
        gateway_request_id:
          type: string
        cost:
          type: number
        balance:
          type: number

Guardrails

Always check that ONEBOUND_API_KEY is set before calling any script. If missing, tell the user to set it.
Default to https://onebound.vercel.app when ONEBOUND_BASE_URL is not set.
Never ask the user for upstream credentials when using this skill.
Never fabricate product search or detail results. Always call the platform gateway.
If a script returns an error, show the error message to the user.
Do not expose the API key in output.
For keyword search, make sure the keyword is meaningful and not empty.
For detail queries, require a valid item ID before making the call.

Failure Handling

If the API returns a 401 error, the platform API key is invalid or expired. Ask the user to verify their credentials.
If the API returns a 400 error, check the required parameters.
If the API returns a 402 or a balance-related error, ask the user to recharge the platform balance.
If the API returns a 500 error, it is a server-side issue. Suggest the user try again later.
If the script exits with code 1, read the error message from stderr.

onebound-api

Install

Onebound API

Setup

Workflow

Taobao Keyword Search

Taobao Item Detail

1688 Keyword Search

1688 Item Detail

Output Format

OpenAPI Specification

Guardrails

Failure Handling

Related skills