Developer docs

What the API is for, how it is priced, and how to call it: endpoints, x402 payment flow, code examples, MCP setup.

Try it before paying

Free sample dataset — 100 items, no signup, shows the exact answer shape.
MCP server — cached lookups are free for assistants.
Methodology — what every field means, and its limits.

Endpoints & prices

Endpoint	Returns	Price
`GET /api/worth?q=...`	Price estimate: low, typical, high	$0.01
`GET /api/deal?q=...&price=...`	Is this asking price a good deal?	$0.01
`GET /api/history?q=...`	Price history and trend	$0.02
`GET /api/sold?q=...`	Real sold prices from our own eBay shop	$0.01
`POST /api/batch`	Up to 10 items per call — JSON body {"items": ["..."]}, one result or error per item	$0.05
`GET /api/trends?category=...`	Category price trends: weekly average asking prices over 90 days	$0.01
`GET /api/top?category=...&limit=...`	Highest-priced tracked items in a category	$0.01
`GET /api/profit?q=...&buy=...`	Resale profit estimate: fees, postage, margin and break-even for a buy price	$0.01
`GET /health`	Service status and integrations	free

/api/worth answers also include a sold block automatically when matching shop sales exist.

Payment: x402 v2, USDC on Base (eip155:8453), facilitator https://api.cdp.coinbase.com/platform/v2/x402. No signup, no API key.

Errors, retries & billing safety

Status	Meaning	Billed?
`400`	Invalid request — missing/oversized `q` or bad `price`; see the JSON hint	No
`402`	Payment required — pay the challenge, retry with the payment header	Only if settled
`404`	Unknown endpoint	No
`5xx`	Temporary failure — safe to retry	No — payments settle only after a successful response

Payments are single-use EIP-3009 authorisations: the same signed payment can never settle twice, so re-sending a request after a network timeout cannot double-charge. If your wallet shows a settlement for a call that returned an error, message us via the shop and we will make it right.

Quickstart — curl

# 1. ask for the price (no payment yet)
curl -i "https://reusefulshop.com/api/worth?q=used+playstation+5+console"
# → HTTP 402 with a PAYMENT-REQUIRED header describing the exact price

# 2. pay with any x402 client, then retry with the payment header
# → HTTP 200 + JSON

Batch requests

POST /api/batch returns price estimates for up to 10 items in one paid call ($0.05), with one result or error per item. Invalid input — no items, more than 10, a non-string, or an item over 200 characters — is rejected with 400 before any payment.

curl -i -X POST "https://reusefulshop.com/api/batch" -H "content-type: application/json"   -d '{"items": ["used playstation 5 console", "canon ef 50mm f/1.8 lens used", "vintage royal worcester vase"]}'
# → HTTP 402 (x402 challenge): pay, then retry the same POST with the payment header
# → HTTP 200 {"batch": true, "count": 3, "results": [ ...one Estimate per item... ], "errors": []}

Each item is looked up exactly like /api/worth and carries the same fields (basis, sample, confidence, market, match_quality). Untracked items return found:false; per-item failures appear in errors without failing the whole call. Batch pricing is HTTP-API only — the MCP server exposes single-item tools.

Quickstart — TypeScript (buyer)

import { wrapFetchWithPaymentFromConfig } from '@x402/fetch';
import { ExactEvmScheme } from '@x402/evm/exact/client';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: 'eip155:*', client: new ExactEvmScheme(account) }],
});

const res = await fetchWithPayment(
  'https://reusefulshop.com/api/worth?q=used+playstation+5+console'
);
console.log(res.status, await res.json());

The buyer wallet only needs USDC on Base; the facilitator covers gas. A working example lives in the project's scripts/pay-test.mjs.

MCP server (Claude, Cursor, any MCP client)

Endpoint: https://reusefulshop.com/mcp (Streamable HTTP). Tools: get_worth, check_deal, get_history. Cached answers are free via MCP.

Cursor / generic MCP config:

{
  "mcpServers": {
    "reusefulshop": { "url": "https://reusefulshop.com/mcp" }
  }
}

Claude Desktop: Settings → Connectors → Add custom connector → URL above.

Behaviour & errors

402 — payment required (header carries price, asset, payTo, network).
400 — missing or invalid query parameters (e.g. price=0 for /api/deal).
404 — unknown route; JSON error lists the valid endpoints.
Fresh answers: cached for 24h; brand-new items are fetched on first request (typically 5–15 seconds; the API returns the cached answer once ready).
Free tier: 10 browser-style lookups per day per IP; machine requests always get the 402 challenge.

Machine-readable

/openapi.json — OpenAPI 3.1 spec
/.well-known/x402.json — resource manifest
/data/sample.json — free sample dataset (100 items)
/llms.txt — summary for AI assistants
GitHub repo — buyer examples, MCP config, MIT licensed