---
name: trawl-agent-setup
description: Integrate trawl's catalog of premium data APIs (eBay sold-listings data today, more coming) into a user's project — auth, the API catalog, quota semantics, and the rules to follow while doing it.
---

# trawl — Agent Setup

trawl is a catalog of **premium data APIs** for developers: plain HTTPS in,
typed JSON out. Each API is an engineered product — typed responses, stable
schemas, monitored uptime — not a thin wrapper. One key and one monthly
request pool work across the entire catalog, and new APIs are added over
time, so check the catalog below (or /llms.md) rather than assuming eBay is
all there is.

## Read this first

Fetch the full machine-readable reference before writing any integration code:

- **https://trawl.dev/llms.md** — the current catalog with every endpoint,
  parameter, response shape, and error code, in markdown. Treat it as the
  source of truth; do not guess parameters that are not listed there.

Human-readable docs (same content): https://trawl.dev/docs

## The API catalog

### eBay API — live

Base URL: `https://api.trawl.dev/ebay/v1`

Real sold-listings data across the US and UK marketplaces: 80+ million completed sales with final price, sale date, condition, shipping, and seller details. eBay itself only exposes ~90 days of sold history; this keeps the history and adds query controls.

Endpoints:

- `GET /sold` — sold listings matching every word in the query; filter by price, condition, category, sale-date window
- `GET /categories` — find category ids by name (matches the full category path; a numeric query looks up that exact id), for the category filter on /sold

Reach for it when the user needs market pricing and comps from real sales (not asking prices), portfolio valuation, deal alerting, resale and market research.

More APIs ship under the same base URL, key, and request pool — /llms.md
always lists the current catalog. If the user needs a data source that is not
covered yet, they can request and vote for it in the roadmap section at
https://trawl.dev.

## The 60-second integration

1. The **user** creates an account and API key: https://trawl.dev/signup
   (email code, no credit card; keys live at https://trawl.dev/console/keys).
2. Put the key in an environment variable (e.g. `TRAWL_KEY`) and call the API
   from backend code only.
3. First call:

```bash
curl "https://api.trawl.dev/ebay/v1/sold?query=iphone+15+pro" \
  -H "x-api-key: $TRAWL_KEY"
```

There is no SDK and none is needed — every language's stdlib HTTP client
works. Auth is a single `x-api-key` header, identical on every API in the
catalog.

## Rules

- **Ask before integrating.** Understand what the user is building first; do
  not create accounts, restructure code, or add dependencies unbidden.
- **Never invent, guess, or hard-code an API key.** The user mints their own
  key. If no key exists yet, point them at https://trawl.dev/signup and stop.
- **Keep the key out of client-side code and query strings.** Environment
  variable, backend calls only.
- **Quota semantics:** only successful (2xx) responses spend the monthly
  allowance — errors are free and don't count toward the per-second rate
  either. The pool is shared across all APIs in the catalog. A `429` WITH a
  `Retry-After` header is the per-second rate: wait that long and retry. A
  `429` WITHOUT it means the monthly allowance is spent: do NOT retry-loop;
  tell the user and point at https://trawl.dev/console/billing. On `503`
  retry with backoff (it costs nothing).
- **Read the rate headers** (`X-RateLimit-Limit`, `X-RateLimit-Remaining`,
  `X-RateLimit-Reset`) instead of tracking usage yourself.