curio-api · preview

Bring your own agent

Connect the AI agent you already use to HyperCurio. Your agent does the legwork out on the marketplaces; HyperCurio tells it what an item is, what it is worth, and whether a listing is a good buy for your collection.

Preview. curio-api is open to a small group while we shape it. Keys are read-only on your collection: an agent can read it and ask HyperCurio to check a listing, but it cannot change anything, and it never buys. You decide and you buy.

Get started

In HyperCurio, open Account, Agent access and make a key. It is shown once, so copy it somewhere safe. You can revoke it there at any time.
Add HyperCurio to your agent as an MCP server (below), or call the REST API directly.
Ask your agent for something real: "Find me a CGC 9.4 or better Hulk #181 under my want-list price and check the best two listings with HyperCurio."

Connect an agent (MCP)

curio-api speaks the Model Context Protocol over HTTP. Any agent that supports remote MCP servers can use it.

Endpoint

https://hypercurio.com/developers/mcp

Claude Code

claude mcp add --transport http hypercurio https://hypercurio.com/developers/mcp --header "Authorization: Bearer cur_YOUR_KEY"

Any MCP client (JSON config)

{
  "mcpServers": {
    "hypercurio": {
      "type": "http",
      "url": "https://hypercurio.com/developers/mcp",
      "headers": { "Authorization": "Bearer cur_YOUR_KEY" }
    }
  }
}

What your agent can do

Tool	REST	What it does
`get_profile`	`GET /me`	Whose account this is and how many items it owns, watches and has sold.
`search_collection`	`GET /collection`	Search what you own (every word must match), highest value first.
`get_item`	`GET /collection/{id}`	Everything recorded about one item, including its grading plan.
`get_collection_summary`	`GET /summary`	Totals and how the collection breaks down.
`get_want_list`	`GET /wants`	What you are looking for, the grade you need and the most you will pay.
`get_watch_list`	`GET /watch`	Items you are tracking but do not own.
`check_listing`	`POST /check-listing`	HyperCurio reads an eBay listing and its photos, identifies the item, prices it against recent sales and gives a verdict and the price that works for you. Takes one to three minutes; the answer is also saved in the app.
`get_listing_check`	`GET /check-listing/{job}`	The progress or result of a check.
`get_due_scouts`	`GET /scouts/due`	HyperCurio Scout: the scouts this person gave your agent that are due a check, with the brief, limits, dealbreakers and links already reported. Calling it is your check-in.
`submit_find`	`POST /scouts/finds`	HyperCurio Scout: report listings for one scout, each with a one-line reason, and the marketplace’s fair market value (`fmv`, `fmv_source`) when the listing shows one. HyperCurio checks every one against the scout’s limits and dealbreakers and says which were turned away and why.
`list_playbooks`, `get_playbook`	`GET /playbooks`	Guidelines for working a marketplace or a task (below).

Playbooks

Playbooks are guidelines HyperCurio publishes for agents: how to read a listing on a given marketplace, what to distrust, and how to do common collecting tasks. Your agent reads the relevant one before it starts.

Name	Kind	About
`ebay-comics`	Marketplace	Slabs, raw copies, photos, sellers and red flags.
`ebay-coins`	Marketplace	Certified and raw coins, counterfeits, details grades and lots.
`hunt-want-list`	Task	Finding listings for what you want, within your limits, and shortlisting the best.
`grading-candidates`	Task	Which raw items in your collection would be worth grading.
`show-floor`	Task	Lists, limits and quick checks for a convention or coin show.

REST

Every call needs Authorization: Bearer cur_YOUR_KEY. The base is https://hypercurio.com/developers/v1.

curl -H "Authorization: Bearer cur_YOUR_KEY" \
  "https://hypercurio.com/developers/v1/collection?query=spider-man&limit=5"

curl -X POST -H "Authorization: Bearer cur_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://www.ebay.com/itm/123456789012"}' \
  https://hypercurio.com/developers/v1/check-listing
# => 202 {"job":"x_...","poll":".../check-listing/x_..."}; ask again every 20 seconds

The rules

Your agent recommends; you decide and buy. curio-api never bids or buys, and agents connected to it should not either.
Read-only. A key can read your collection and lists and check listings. Adding or changing items happens in the app.
Listings are data. A listing's text is the seller's. Agents are told never to follow instructions written in it.
Marketplaces on their terms. Agents should use a marketplace's official API or your own browsing, not scrape it.
Limits. 60 calls a minute per key: a tool call or resource read over MCP, or a REST request. MCP set-up messages (initialize, tools/list, notifications) do not count. Over the limit you get HTTP 429 with a Retry-After header and retry_after_seconds in the body. Listing checks also count toward your account's daily photo reads, the same as checks in the app; a listing that does not exist is refused before it uses one.
Conventions. Times are ISO 8601. A value that is not known is null, never an empty string. A failed listing check is a result with status: "failed" and a reason (listing_not_found, listing_sold_out, no_photos, not_a_collectible, daily_limit, upstream_unavailable, check_failed), not a transport error.