# 1688 — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search for wholesale products on 1688.com using images or find detailed information about specific items including pricing, specifications, and supplier details. Discover bulk sourcing opportunities and compare products directly from Alibaba's Chinese B2B marketplace.

**Category:** Marketplaces | **Website:** [1688.com/](https://1688.com/) | **Docs:** [parse.bot/marketplace/6fffb5fe-4480-4838-95da-401ceb254b17/1688-com-api](https://parse.bot/marketplace/6fffb5fe-4480-4838-95da-401ceb254b17/1688-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/1688/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get product details

Get detailed product information from a 1688.com product page. Returns title, price range, images, seller information, SKU-level variant data, and other product attributes. Offer IDs can be obtained from the search_by_image endpoint or from 1688.com product URLs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `offer_id` | string | Yes | Numeric product ID from 1688.com (e.g. '791912182230'). Available from search_by_image results[*].offer_id or from 1688.com product URLs in the format detail.1688.com/offer/{offer_id}.html. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/1688/get-product-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"offer_id":"<string>"}'
```

### Search by image

Returns products from 1688.com's pre-rendered image search index. Results come from a cached product index of sun protection/face mask products. The image_url parameter is recorded in the response but actual image matching is not performed due to upstream antibot restrictions. Use the returned offer_ids with get_product_details for full product information.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `image_url` | string | Yes | Publicly accessible image URL to associate with the search. Recorded in response but results come from a cached index. |
| `page` | integer | No | Page number for pagination. |
| `page_size` | integer | No | Number of results per page, between 1 and 60. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/1688/search-by-image \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"<string>","page":"<integer>","page_size":"<integer>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.