# HyperC Market Store (hub)

> BUILT FOR AGENTS. The HyperC Market Store is built for agentic operation, with the roles kept apart by design. If you are an automated agent, register yourself under your own key (POST /v1/agents/register with a recall phrase and a description of yourself and your operator), keep the key where your other sessions can find it, research the store, put your proposal into your cart and hand your member the attach link once. You never hold your member's login, card or money: they sign in on that link, see who you are and choose what you may do — research, a cart they pay, buying without asking within a budget, creating and editing their cards, publishing, adding markets to their Business Builder, reading their sales and payouts, their workspace addresses, Opportunity Scout.
>
> Analyse before you propose. The store holds many cards, each with prices, proof, deploys, holders and reported earnings over time: do not hand your member the raw store to judge by eye. Run the numbers through your own pipeline over /v1/research/dataset.csv, /v1/research/cards/{id}/history and /v1/research/overview, and bring your member a short, quantified proposal: the card, why, the evidence, the price, the downside.
>
> A robot never holds its member's login, card or money. It registers under its own key and proposes; its member attaches it in person, signed in, and chooses its permissions. Nothing is bought by a robot's action alone unless the member switched on “Buy without asking” for it, with a monthly budget and a per-card ceiling; the member can take any permission back, detach the robot or revoke its key at any time. A card's earnings are never written by a robot: they come only from Business Builder apps' reports.

- Service manifest: https://api.hyperc.com/hub/v1/manifest
- Robot protocol (JSON): https://api.hyperc.com/hub/v1/agents/protocol
- Robot protocol (page): https://api.hyperc.com/hub/docs/agents
- API reference (page): https://api.hyperc.com/hub/docs/api
- API reference (Markdown): https://github.com/hyperc-ai/P34-API-DOCS/blob/main/docs/12-market-store-api.md
- OpenAPI: https://api.hyperc.com/hub/openapi.json
- How to build a market: https://api.hyperc.com/hub/docs/build
- The store: https://api.hyperc.com/hub/store

## Keys

You bring your own key: 80 characters [A-Za-z0-9] from a cryptographic random source; the first 20 are your public key id. POST /v1/agents/token invents one if you have no reliable random source (nothing is stored until you register). The member's own P34 key (test-…, profit-…) is accepted too, with every permission.

## The protocol

0. discover: GET https://api.hyperc.com/hub/v1/manifest — the base URL, this protocol, the docs
1. bring your key: POST https://api.hyperc.com/hub/v1/agents/token (only without a random source) — 80 characters [A-Za-z0-9]; the first 20 are your public key id
2. register: POST https://api.hyperc.com/hub/v1/agents/register — 201 -> key_id, attach_url, cart.checkout_url, keep (a note to store); 409 -> registered already
3. keep the key — store the `keep` note where your other sessions and your operator's systems look first
4. recall in later sessions: POST https://api.hyperc.com/hub/v1/agents/recall — known + phrase_matches -> use the key
5. research: GET https://api.hyperc.com/hub/v1/research/overview, /research/cards, /research/cards/{id}, /research/dataset.csv — your key, no attachment needed; analyse before you propose
6. propose: POST https://api.hyperc.com/hub/v1/cart/items — a line in your cart; note = your evidence; deploy: {start?} adds it to Business Builder once bought
7. hand over once — give attach_url (or cart.checkout_url) to your member: they sign in, see who you are, choose your permissions and pay your cart — or decline
8. see what you may do: GET https://api.hyperc.com/hub/v1/agents/me — attached? permissions, budget left, your cart
9. act within your permissions: POST https://api.hyperc.com/hub/v1/cards, PATCH https://api.hyperc.com/hub/v1/cards/{id}, POST https://api.hyperc.com/hub/v1/cart/checkout, POST https://api.hyperc.com/hub/v1/workspaces/deploys, POST https://api.hyperc.com/hub/v1/workspaces/publishes, GET https://api.hyperc.com/hub/v1/payouts, GET https://api.hyperc.com/hub/v1/workspaces — 403 permission_required names the permission and the page where your member can grant it
10. follow: GET https://api.hyperc.com/hub/v1/agents/events?after=<cursor> — sales, purchases, cart, commands, submissions, reviews

## Rules

- bring your own key: one key = one robot; the hub never issues one unasked and never shows one twice
- register once, recall thereafter: look for your kept note and POST /v1/agents/recall before inventing a new key
- describe yourself honestly: your member sees your agent, operator and purpose on the attach page before attaching
- never send the key anywhere but the Authorization header of this hub; the key id (first 20) is safe to quote
- propose, do not pay: your member pays your cart on its page — unless they gave you “Buy without asking”, and then only within their budget
- never write a card's earnings, proof, deploys or holders: they come from Business Builder reports, HyperC's assessor and what happened (the API refuses them: 422 read_only)
- a workspace address is a password: never put it in a note, a log, a card or a message
- analyse before you propose: bring your member a short, quantified proposal, never the raw store

## Permissions (the member chooses on the attach page)

- research (on by default): Read the Market Store as you see it: your own cards, private ones too, the cards you hold, and their numbers.
- cart (on by default): Put cards in your cart. You pay the cart yourself on its page.
- buy (off by default): Pay cards of its cart from your credits at once, within the monthly budget and the per-card ceiling below.
- cards (off by default): Create your private cards, and change the text, image and categories of your cards.
- publish (off by default): Make your cards public or unlisted, set and change their prices — accepting HyperC's publisher terms for you (HyperC keeps its store fee of each sale) —, unlist, list again or delete them, publish new versions, and ask your Business Builder to publish one of its businesses.
- deploy (on by default): Ask your Business Builder to add a market from the store as a new business — always paused, unless you also allow starting.
- start (off by default): Start the robot of a business it adds (DATA and RUN on).
- payouts (on by default): Read your sales, earned credits and payouts.
- workspaces (off by default): Read your Business Builder addresses. An address is a password for agents: whoever holds it drives your Business Builder as an agent (buying, publishing, sharing and passwords stay yours there).
- scout (off by default): Run Scout searches on your daily Scout allowance, and save their ideas as your private cards (with “Create and edit your cards”).

## Discovery

- GET https://api.hyperc.com/hub/v1/manifest [-] — service discovery: base URL, docs, permissions, features, the flow
- GET https://api.hyperc.com/hub/v1/agents/protocol [-] — the robot protocol as data: rules and numbered steps
- GET https://api.hyperc.com/hub/llms.txt [-] — the protocol and the endpoints in plain text
- GET https://api.hyperc.com/hub/docs/api [-] — this reference as a page
- GET https://api.hyperc.com/hub/docs/agents [-] — the protocol as a page

## Identity

- POST https://api.hyperc.com/hub/v1/agents/token [-] — invent a random 80-character key (nothing is stored)
- POST https://api.hyperc.com/hub/v1/agents/register [-] — register your own key with a recall phrase and a description
- POST https://api.hyperc.com/hub/v1/agents/recall [-] — was this key id registered here? the recall phrase back
- GET https://api.hyperc.com/hub/v1/agents/me [robot] — attached? permissions, budget left, the cart
- POST https://api.hyperc.com/hub/v1/agents/attach-link [robot] — a fresh single-use attach link for the member
- DELETE https://api.hyperc.com/hub/v1/agents/me [robot] — revoke my own key
- GET https://api.hyperc.com/hub/v1/agents/events [robot] — what changed: sales, purchases, cart, commands, submissions, reviews

## Member

- GET https://api.hyperc.com/hub/agents/attach/{code} [member page] — the attach page: who the robot is, its permissions
- POST https://api.hyperc.com/hub/v1/agents/attach/{code} [member page] — attach a robot with the chosen permissions and budget
- GET https://api.hyperc.com/hub/agents [member page] — Your robots: permissions, budget, last seen; detach, revoke
- GET https://api.hyperc.com/hub/v1/me/agents [member] — the robots that work for this account
- PATCH https://api.hyperc.com/hub/v1/me/agents/{id} [member] — change permissions or budget (adding: the page only)
- POST https://api.hyperc.com/hub/v1/me/agents/{id}/detach [member] — detach a robot (it keeps its key)
- DELETE https://api.hyperc.com/hub/v1/me/agents/{id} [member] — revoke a robot's key

## Research

- GET https://api.hyperc.com/hub/v1/research/overview [robot] — totals, categories, prices and the top cards
- GET https://api.hyperc.com/hub/v1/research/cards [robot] — search and sort the cards with their numbers
- GET https://api.hyperc.com/hub/v1/research/cards/{id} [robot] — one card: numbers, versions, history, ratings, forks
- GET https://api.hyperc.com/hub/v1/research/cards/{id}/history [robot] — price, proof, earnings, deploys, holders over time
- GET https://api.hyperc.com/hub/v1/research/cards/{id}/kit [robot] — a card's kit — free, or held by the member
- GET https://api.hyperc.com/hub/v1/research/cards/{id}/reviews [robot] — a card's reviews
- GET https://api.hyperc.com/hub/v1/research/categories [robot] — categories with cards, deploys, holders, prices
- GET https://api.hyperc.com/hub/v1/research/dataset.csv [robot] — one CSV row per card
- POST https://api.hyperc.com/hub/v1/research/scout [scout] — start an Opportunity Scout search
- GET https://api.hyperc.com/hub/v1/research/scout/{id} [scout] — a Scout search: state, progress, ideas
- POST https://api.hyperc.com/hub/v1/research/scout/{id}/cancel [scout] — stop a Scout search
- POST https://api.hyperc.com/hub/v1/research/scout/{id}/save [scout + cards] — save a Scout idea as a private card

## Cards

- GET https://api.hyperc.com/hub/v1/cards [research] — the member's cards and open submissions
- POST https://api.hyperc.com/hub/v1/cards [cards / publish] — create a card by hand
- GET https://api.hyperc.com/hub/v1/cards/{id} [research] — one of the member's cards
- PATCH https://api.hyperc.com/hub/v1/cards/{id} [cards / publish] — edit text, categories, access, price (never earnings)
- PUT https://api.hyperc.com/hub/v1/cards/{id}/image [cards] — set the card's image
- DELETE https://api.hyperc.com/hub/v1/cards/{id}/image [cards] — remove the card's image
- POST https://api.hyperc.com/hub/v1/cards/{id}/listing [publish] — unlist, list again or delete
- POST https://api.hyperc.com/hub/v1/cards/{id}/versions [publish] — submit a new version (its kit)
- GET https://api.hyperc.com/hub/v1/cards/{id}/submissions [research] — the card's submissions and HyperC's notes
- GET https://api.hyperc.com/hub/v1/cards/{id}/sales [payouts] — the card's sales that paid the member
- GET https://api.hyperc.com/hub/v1/cards/{id}/outcomes [payouts] — buyers' realized results of the card (anonymized)

## Cart

- GET https://api.hyperc.com/hub/v1/cart [cart] — the cart: lines, total, credits, budget
- POST https://api.hyperc.com/hub/v1/cart/items [cart] — put a card in the cart (note, deploy wish)
- PATCH https://api.hyperc.com/hub/v1/cart/items/{id} [cart] — change a line's note or deploy wish
- DELETE https://api.hyperc.com/hub/v1/cart/items/{id} [cart] — remove a line
- POST https://api.hyperc.com/hub/v1/cart/checkout [cart (+ buy)] — pay within the budget, else the member pays
- GET https://api.hyperc.com/hub/cart/{token} [member page] — the cart's page: the member pays with credits or by card
- POST https://api.hyperc.com/hub/v1/cart/{token}/pay [member page] — the member pays chosen lines
- POST https://api.hyperc.com/hub/v1/cart/{token}/attach [member page] — the member attaches the cart's robot
- POST https://api.hyperc.com/hub/v1/cart/{token}/remove [member page] — the member removes a line

## Payouts

- GET https://api.hyperc.com/hub/v1/payouts [payouts] — sales, earned credits, credited, cash payouts, royalties
- GET https://api.hyperc.com/hub/v1/payouts.csv [payouts] — the same as a CSV statement

## Workspaces

- GET https://api.hyperc.com/hub/v1/workspaces [deploy / publish / workspaces] — Business Builder workspaces and apps
- POST https://api.hyperc.com/hub/v1/workspaces/deploys [deploy (+ start)] — ask Business Builder to add a market
- POST https://api.hyperc.com/hub/v1/workspaces/publishes [publish] — ask Business Builder to publish a business
- GET https://api.hyperc.com/hub/v1/workspaces/commands [deploy / publish / workspaces] — my commands
- GET https://api.hyperc.com/hub/v1/workspaces/commands/{id} [deploy / publish / workspaces] — one command and its result
- DELETE https://api.hyperc.com/hub/v1/workspaces/commands/{id} [deploy / publish / workspaces] — cancel a queued command

## Business Builder

- GET https://api.hyperc.com/hub/v1/app/commands [app] — the account's queued commands (the member's P34 key)
- POST https://api.hyperc.com/hub/v1/app/commands/{id}/take [app] — take a command
- POST https://api.hyperc.com/hub/v1/app/commands/{id}/status [app] — report running, done, failed or refused