# ToolPick

**Which paid API should my agent call?** ToolPick searches every paid x402 resource on the public x402 discovery indexes
(36,000+ endpoints: the CDP discovery API with 30-day call and payer counts, merged with the PayAI discovery list) and ranks
them for a task by relevance, real 30-day usage, recency and price. The pick tier live-checks the top candidates (one unpaid
request each) and names a best verified pick; the market tier shows sellers the competition and the price where buyers are.

- Hosted: https://api.youraitools.co/toolpick/ (also https://toolpick.agentgate.workers.dev)
- Remote MCP (free preview): `https://api.youraitools.co/toolpick/mcp`, tool `find_paid_api`
- Stdio MCP: `node src/mcp-stdio.js` (npm package pending), paid mode with `TOOLPICK_X402_PRIVATE_KEY`

| Route | Price | Returns |
|---|---|---|
| `GET/POST /v1/lite?need=` | $0.003 | top 5 resources: URL, method, price, networks, 30-day calls/payers, repeat_buyers, last called |
| `GET/POST /v1/pick?need=&max_price=&network=&min_payers=` | $0.01 | top 10 + live 402 check of the top 5, best verified pick, cheapest verified, category price stats |
| `GET/POST /v1/market?need=` | $0.02 | competition and pricing for a category (or the whole index): price quartiles, buyer price, est. revenue, top sellers |
| `GET /v1/preview?need=` | free | match count + top 3 service names with price and payers (10/min per IP) |

Paid in USDC over x402 v2 (Base, Solana, Polygon, Arbitrum One) or v1 (Base), or with a prepaid YourAITools credits key
(`Authorization: Bearer yatc_...`). Only HTTP 200 answers are settled.

## How it works
- `src/index-do.js`: SQLite Durable Object holding the merged index as JSON chunks. **No cron**: a query that finds the
  index older than 6 hours sets an alarm, and the alarm pulls the public discovery APIs (2 pages in flight). A failed
  refresh keeps the last good index.
- `src/engine.js`: compaction (cheapest mainnet USDC price, networks, quality fields), ranking
  (relevance x log payers/calls x recency, max 2 results per host), market stats and the live 402 check (reads v2
  `PAYMENT-REQUIRED` or v1 body terms; never pays; endpoints with path parameters are not probed).

## Fail-closed
- Index missing or older than 72 h, or the store unavailable: 503, not charged. 12-72 h: `index_stale`, lower confidence.
- A candidate whose live check fails or times out is listed in `sources_failed` and is never `verified_live: true`; if no
  top-5 candidate passes, `best_pick` is null and confidence is low.
- No matches: 404, not charged.

Listings are self-described by sellers; ToolPick ranks, it does not endorse. It never pays other endpoints, holds funds or keys.

## Develop
`npm test` (node --test). `npm run gen:examples -- <cdp snapshot.json>` regenerates the documented examples.

MIT. Built by agentgate-builder.