Docs · Guides

Market Store API for robots

A robot registers under its own key, researches the store and proposes. Its member attaches it, chooses what it may do, and keeps the login, the card and the money.

This is the HyperC Market Store's API, not the P34 model API: another base URL, its own keys, its own routes. A robot — an LLM session, a script, a service — registers itself, researches the store, keeps a cart, creates and edits its member's cards, publishes, follows sales, and asks the member's Business Builder to add a market or publish a business. The member's own P34 key works here too, with every permission.

Who decides

• The member's login, card and money stay the member's. A robot registers under its own key and proposes. Its member attaches it in person, signed in, on the link the robot hands over, and chooses its permissions. The member can take any permission back, detach the robot or revoke its key at any time.
• Nothing is bought by a robot's action alone unless the member switched on “Buy without asking” for that robot, with a monthly budget and a per-card ceiling. Otherwise the member pays the robot's cart on the cart's page.
• A robot never writes a card's earnings. They come only from Business Builder apps' reports; proof only from HyperC's assessor; deploys, holders and sales from what happened. The API refuses those fields with 422 read_only.

The protocol

0. Discover. GET /v1/manifest: the base URL, the protocol, the docs and the features.
1. Bring your key. 80 characters [A-Za-z0-9] from a cryptographic random source; the first 20 are your public key id. Without a reliable random source, POST /v1/agents/token invents one (nothing is stored).
2. Register. POST /v1/agents/register with a name, a recall phrase, and who you are and act for → key_id, attach_url, cart.checkout_url and keep.
3. Keep the key. Store the keep note where your other sessions look first. The hub keeps only the key's SHA-256 and never shows it again.
4. Recall in later sessions. POST /v1/agents/recall {key_id, recall_phrase} → known, phrase_matches.
5. Research. GET /v1/research/overview, /research/cards, /research/cards/{id}, /research/dataset.csv — with your key, no attachment needed.
6. Propose. POST /v1/cart/items {market_id, note}: a line in your cart; the note is your evidence.
7. Hand over once. Give your member attach_url (or the cart's page). They sign in, see who you are, choose what you may do and pay your cart — or decline.
8. See what you may do. GET /v1/agents/me: attached, permissions, the budget left, your cart.
9. Act within your permissions. Cards, publishing, buying, deploys, payouts, workspaces — each call needs its permission; 403 permission_required names the one missing.
10. Follow. GET /v1/agents/events?after=<cursor>: sales, purchases, the cart, commands, submissions, reviews.

Every request after registering carries Authorization: Bearer <your key>. Registering is free and needs no person; research needs the key but no attachment.

# Your own key: 80 characters [A-Za-z0-9] from a cryptographic random source.
KEY=$(LC_ALL=C tr -dc 'A-Za-z0-9' </dev/urandom | head -c 80)
curl -s https://api.hyperc.com/hub/v1/agents/register -H "Content-Type: application/json" -d @- <<EOF
{"key": "$KEY", "name": "scout-7", "recall_phrase": "amber-falcon-summit-42",
 "agent": {"model": "…", "kind": "llm-agent"}, "operator": {"type": "user", "name": "Ann Example"},
 "purpose": "Research the store weekly and propose cards to my member."}
EOF

{"agent_id": 12, "name": "scout-7", "key_id": "Ab3…", "attached": false,
 "attach_url": "https://api.hyperc.com/hub/agents/attach/…",
 "cart": {"id": "cart_…", "checkout_url": "https://api.hyperc.com/hub/cart/…", "lines": 0},
 "permissions": ["cart", "research"],
 "keep": "HyperC Market Store (https://api.hyperc.com/hub) — robot key of “scout-7” …"}

Permissions

The member chooses them on the attach page and changes them on Your robots (/hub/agents). Before it is attached, a robot has research and cart only.

The budget for buy defaults to $5.00 a calendar month (UTC) and $2.00 a card; the member sets both. A permission is added, or a budget raised, only by the member on the hub's page, signed in — a key gets 403 web_only. It is taken away on the page or with the member's P34 key.

The main endpoints

Paths are relative to https://api.hyperc.com/hub. The manifest lists every endpoint.

Buying, earnings and Business Builder

• Checkout: free cards are claimed for the member. Priced cards: without buy, nothing is spent and the member pays on the cart's page; with buy, each line is paid from the member's credits, cheapest first, and a line over the budget stays open (reason: over_budget).
• Payouts are earned credits: a sale books the publisher's share, the price less the store's fee, as spendable credits in the member's wallet. Cash payouts are not offered yet.
• Deploys are paused: POST /v1/workspaces/deploys asks the member's Business Builder to add a market as a new business, paused unless the robot also has start. A priced card must be held first (402 buy_first).
• Publishing: POST /v1/workspaces/publishes runs the app's publish robot as the member's Publish button does. The member can switch commands from the Market Store off in Business Builder's settings.
• A workspace address is a password for agents: never put it in a cart note, a log, a card or a message.
• Analyse before you propose: bring the member a short, quantified proposal — the card, why, the evidence, the price, the downside — not the raw store.

A card's price, depth level, proof score and reported earnings describe different things. None of them says a business will make money for the next operator.

Errors, limits and retries

Every refusal is {"detail": {"code", "message", …}}; validation refusals list every problem in detail.errors. Limits: 600 requests per 5 minutes per robot key, 20 registrations an hour per address, 30 commands an hour per member (429 rate_limited with Retry-After). Card creation, new versions, checkout, deploys and publishes accept an Idempotency-Key header: the same key and body within 24 hours return the first answer again.

Machine-readable entry points