---
name: botmarket
description: >
  Use this skill whenever the user wants to find, explore, preview, or query datasets from BotMarket (botmarket.oec.world) — a data marketplace covering international trade flows, US demographics (ACS), US customs shipment records, and international debt statistics.
  Trigger on any mention of "BotMarket", "OEC", "trade data", "customs data", "ACS data",
  "debt statistics", "dataset marketplace", or when the user wants to query structured
  data about countries, trade, imports, exports, shipments, demographics, or debt.
  Also trigger when the user asks to browse or search for available datasets, claim a free
  API key, recover an API key, or look up their account.
---

# BotMarket Skill

BotMarket is a data marketplace for bots and AI agents at `https://botmarket.oec.world`.
It provides structured datasets on international trade, US demographics, US customs records,
and international debt statistics. All interactions happen via REST API calls using `curl`.

**BotMarket is free** — every endpoint, including dataset queries, is free.
No payment is ever required.

## Important Concepts

- **Slugs** identify datasets (e.g., `us-customs-2024`). Get them from the catalog.
- **Free endpoints**: everything is free — catalog, schema, members, sample, and queries.
- **API keys** look like `bot_market_ak_<key>`. Queries require one; claiming it is free.
- **Free API key**: users claim one free API key per email via `/api/promo/claim` — no payment required.
- **buyer_email** is required for claiming the free key. Reuse any email the user already provided — don't ask again if you already have it.

## Workflow

Follow these steps in order. Every step is free.

### Step 1 — Browse the Catalog

```bash
# List all datasets (paginated)
curl -s "https://botmarket.oec.world/api/catalog?limit=20&offset=0"

# Search by keyword (fuzzy, typo-tolerant)
curl -s "https://botmarket.oec.world/api/catalog?q=<search+term>"

# Filter by domain or scope
curl -s "https://botmarket.oec.world/api/catalog?domain=trade&scope=international"
```

The response includes `slug`, `name`, `description`, and `tags` for each dataset. Use the **slug** in all subsequent calls.

### Step 2 — Inspect Dataset Schema

```bash
curl -s "https://botmarket.oec.world/api/datasets/{slug}"
```

Returns the full dataset detail: column names and types in `schema`, and filterable columns in `query_filters` (each with a `members_url`).

### Step 3 — Get Valid Filter Values

```bash
curl -s "https://botmarket.oec.world/api/datasets/{slug}/members/{column}"
```

Only call this for columns listed in `query_filters`. Returns all valid values for that filter column. Always check members before querying — don't guess country codes, product codes, etc.

### Step 4 — Preview Sample Rows

```bash
curl -s "https://botmarket.oec.world/api/datasets/{slug}/sample"
```

Returns up to 100 rows so the user can preview structure and content. This is a partial snapshot — don't use it for real analysis, only for understanding column layout and data types.

### Step 5 — Claim Your Free API Key

One claim per email; no payment required. If the user doesn't have an API key yet, do this first.

**GET** (for agents that prefer not to send a body):

```bash
curl -s "https://botmarket.oec.world/api/promo/claim?buyer_email=user@example.com"
```

**POST**:

```bash
curl -s -X POST "https://botmarket.oec.world/api/promo/claim" \
  -H "Content-Type: application/json" \
  -d '{"buyer_email": "user@example.com"}'
```

- Response includes `api_key`. Save it — the user needs it for queries.
- If the user's email has already claimed, the API returns 409 with `promo_already_claimed`; direct them to use their existing key or use account lookup to recover it.

### Step 6 — Query the Dataset

```bash
curl -s "https://botmarket.oec.world/api/datasets/{slug}/query?col1=val1&col2=val2&limit=100&format=csv" \
  -H "Authorization: Bearer bot_market_ak_<key>"
```

- Pass filterable columns as query params.
- Single value: `?col=value`
- Multiple values (SQL IN): repeat the param (`?col=A&col=B`) or comma-separate (`?col=A,B`).
- Reserved params: `limit`, `offset`, `format` (parquet or csv).
- Queries are free. Response includes `max_rows_per_query`.

OEC subscribers can use their OEC API token (32 lowercase hex characters) as the Bearer token instead.

## Utility Endpoints

### Account Lookup (let the user know their keys and usage)

```bash
curl -s -X POST "https://botmarket.oec.world/api/account/lookup" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'
```

Sends the user an email summary of their account and API keys.

## Tips

- Always start with the catalog search to find the right dataset.
- Always check `members` for filter columns before querying — codes vary per dataset.
- The sample endpoint is your best friend for understanding data shape.
- Store the API key carefully — it's the user's credential for future queries.
- If the user wants to do analysis after downloading data, offer to help with that too (charts, summaries, exports to CSV/Excel, etc.).