# Lista Mercadolivre — 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 and browse products from Mercado Livre Brazil, view detailed pricing and offers, and explore categories to find daily deals and product information. Get comprehensive product details including specifications and current market offers all in one place.

**Category:** Marketplaces | **Website:** [lista.mercadolivre.com.br/](https://lista.mercadolivre.com.br/) | **Docs:** [parse.bot/marketplace/f6d31e6c-77e5-4f34-9aa0-df71418a9c4f/lista-mercadolivre-com-br-api](https://parse.bot/marketplace/f6d31e6c-77e5-4f34-9aa0-df71418a9c4f/lista-mercadolivre-com-br-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/lista-mercadolivre/`
**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 listing details

Fetch details of a single product listing including sold units (sales).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `item_id` | string | Yes | Mercado Livre Item ID or URL |

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

### Get lowest price item

Find the lowest-priced item matching a keyword within the Joias e Relógios (MLB3937) category on the Ofertas page. Useful for price comparison and deal-hunting within jewelry and watches. Returns the single cheapest matching item or null if no matches found.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | No | Keyword to filter items by name within the Joias e Relógios category (e.g. relogio, colar, brinco). Defaults to 'relogio' when omitted. |

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

### Get recent listings

Retrieve all current listings from the Ofertas (deals) page. All items on the page are active promotions. The days parameter is accepted for compatibility but does not filter results — the page only shows currently active deals.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `days` | integer | No | Accepted for compatibility but does not filter results; all returned listings are current active deals. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/lista-mercadolivre/get-recent-listings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"days":"<integer>"}'
```

### Search listings

Search for product listings on the Mercado Livre Brazil 'Ofertas' (deals) page. Without a category_id, returns all current deals. The query parameter filters results locally by name within the fetched listings. Returns matching listings with pricing, discount, and store information, plus aggregate statistics (total count, average price). Single-page response containing all matching deals in the selected category.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | No | Mercado Livre category ID to filter deals (e.g. MLB3937 for Joias e Relógios, MLB1648 for Informática). When omitted, returns all deals from the main Ofertas page. |
| `query` | string | No | Keyword to filter results by product name (case-insensitive local filter applied after fetching the category page). Works best when combined with category_id. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/lista-mercadolivre/search-listings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","query":"<string>"}'
```

## 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.