---
name: botmarket
description: >
  Use this skill whenever the user wants to find, explore, preview, purchase, 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 buy/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, check their
  BotMarket balance, claim a free API key, recover an API key, or look up past orders.
---

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

## Important Concepts

- **Slugs** identify datasets (e.g., `us-customs-2024`). Get them from the catalog.
- **Free endpoints**: catalog, schema, members, and sample never cost anything.
- **Paid endpoint**: only `/api/datasets/{slug}/query` deducts balance.
- **API keys** look like `bot_market_ak_<key>`. They carry a USD balance.
- **Free API key**: users can claim one free API key per email via `/api/promo/claim`; the key is preloaded with welcome credit (no payment required).
- **buyer_email** is required for every payment and 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. Steps 1–4 are free. Steps 5–7 involve payment and querying.

### 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`, filterable columns in `query_filters` (each with a `members_url`), and `pricing` (including `per_query_usd`).

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

### Claim a free API key (optional)

New users can get an API key with free welcome credit — no payment required. One claim per email; the key is preloaded with USD balance (and may reset daily during the launch promo). If the user doesn't have an API key yet, offer this first before suggesting payment.

**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` and `balance_added`. Save the `api_key` — 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 5 — Add Balance (Payment)

**Agents must use x402 or AP2.** Stripe requires a human browser session and cannot be called by agents — calling it will return 401.

Before paying via x402 or AP2, make sure you have the user's **buyer_email**. If they already provided one, reuse it. Otherwise, ask.

#### x402 (recommended for agents — inline USDC, no redirect)

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

- Returns `order_id`, `payment_url`, and an `x402` block with `url` and `instructions`.
- Follow the x402 flow: GET the `url` → receive 402 with `PAYMENT-REQUIRED` header → sign and retry with `PAYMENT-SIGNATURE` header → receive `api_key`.
- To top up an existing key: include `"api_key": "bot_market_ak_..."` in the body.
- Minimum charge: $0.99 USD. See `/api/x402/info` for full details.

#### AP2 (mandate-based autonomous)

See `https://botmarket.oec.world/api/ap2/info` for AP2 details. Flow: `POST /api/ap2/intent` → `POST /api/ap2/purchase`.

#### Stripe (human-only — NOT for agents)

Stripe requires the human to be signed in at `https://botmarket.oec.world/account` (magic-link session). If the user wants to pay by card, direct them to sign in there. Once signed in, they can initiate a Stripe checkout from the account dashboard and the payment link will be sent to their inbox.

If you need to poll for a Stripe payment the human initiated: use `GET /api/orders/{order_id}?buyer_email={email}`.

### Step 6 — Poll Payment Status (Stripe only)

```bash
curl -s "https://botmarket.oec.world/api/orders/{order_id}?buyer_email={buyer_email}"
```

Poll until `status` is `"paid"`. The response then includes `api_key` and `balance_added`. Save the `api_key` — the user needs it for queries. `buyer_email` must match the email on the human's account.

Skip this step for x402 (completes inline) and AP2 (immediate response).

### Step 7 — 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).
- Each query deducts `per_query_usd` from balance. No charge if 0 rows returned.
- Response includes `balance_remaining` and `max_rows_per_query`.

## Utility Endpoints

### Check Balance (free, no deduction)

```bash
curl -s "https://botmarket.oec.world/api/account/balance?buyer_email=user@example.com" \
  -H "Authorization: Bearer bot_market_ak_<key>"
```

For OEC subscribers using their OEC API token (32 lowercase hex characters, same as for `/query`):

```bash
curl -s "https://botmarket.oec.world/api/account/balance?buyer_email=user@example.com" \
  -H "Authorization: Bearer <oec_api_token>"
```

The `buyer_email` must match the email used at purchase time (BotMarket key), or the email on the linked OEC account (OEC token). The JSON response includes `auth_source` (`botmarket` or `oec`).

### Account Lookup (let the user know its usage and balance)

```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 orders 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 before committing money.
- Present pricing info to the user clearly before initiating any payment.
- 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.).