# Market Category Booster

> Maps a free-text product description onto the live category taxonomy of a
> marketplace, returning the full path: one match per taxonomy level, from the
> broadest category down to the most specific one.

Version 0.1.3. Built for agents: there is no web UI and no sign-up
form.

## How to use it

Three interchangeable surfaces, one behaviour behind them.

- MCP server (streamable HTTP): https://market-category-booster.com/mcp/
  Tools: `categorize_product`, `list_stores` (free), `payment_info` (free).
  Resources: `mcb://stores`, `mcb://stores/{store_id}/taxonomy-roots`,
  `mcb://pricing`.
- REST: `POST https://market-category-booster.com/categorizations` with `{"description": ..., "store_id": ...}`
  OpenAPI: https://market-category-booster.com/openapi.json — human-readable: https://market-category-booster.com/redoc
  Registry metadata: https://market-category-booster.com/.well-known/mcp.json
- A2A agent (JSON-RPC, protocol 1.0): https://market-category-booster.com/a2a
  Agent card: https://market-category-booster.com/.well-known/agent-card.json
  Methods: SendMessage, SendStreamingMessage, SubscribeToTask, GetTask,
  ListTasks, CancelTask, GetAgentCard, and the
  *TaskPushNotificationConfig family. Skills: `categorize-product`,
  `list-supported-stores` (free).
  SendStreamingMessage emits one SSE event per taxonomy level as the descent
  happens. To be notified without holding the connection, declare a webhook in
  `params.configuration.taskPushNotificationConfig` — https only, public hosts
  only.
  The card carries a detached JWS signature when a signing key is configured;
  verify it with the key at https://market-category-booster.com/.well-known/jwks.json, named by the `jku` of
  the protected header. Call GetExtendedAgentCard with a valid X-API-Key for
  the real operational limits.

The discovery documents (agent card, mcp.json, jwks.json, this file) carry an
ETag and Cache-Control: max-age=300. Re-read them with If-None-Match.

Example:

    curl -X POST https://market-category-booster.com/categorizations \
      -H 'content-type: application/json' -H 'X-API-Key: <key>' \
      -d '{"description": "over-ear bluetooth headphones", "store_id": "amazon.it"}'

## Reading the answer

`categories` is a list, not a single value: one match per taxonomy level,
ordered from broadest to most specific. Use the id of the last item as the
listing category. When that last item has `truncated: true` the descent
stopped on the per-request budget of 14000 tokens:
the path is valid but may not reach a leaf.

## Supported store_id values

- amazon.com
- amazon.it
- amazon.co.uk
- ebay.com
- ebay.it
- ebay.co.uk
- shopify.com
- en-US

## Authentication

Either an `X-API-Key` header, or an x402 payment proof. A key that is present
but invalid gets 401, not 402: a wrong credential is not a request for money.

### Pay per call with x402 (no registration)

Call without `X-API-Key` and you get HTTP 402 with the payment requirements in
the body and in the `PAYMENT-REQUIRED` header. Sign the authorization and
retry with it in the `PAYMENT-SIGNATURE` header. Your wallet address is your
identity: there is no sign-up.

- price: $0.048 per call, flat
- network: eip155:8453
- recipient: 0x9f7AdA8Af305a87aE27C8a4dB85bf446dba8859b
- facilitator: https://api.cdp.coinbase.com/platform/v2/x402

The price is flat and covers the worst case at the token budget, so a call
whose descent was truncated is billed the same as a complete one.

## Contact

s.reghenzi@codermine.com