The Market Store API
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.
Base URL https://api.hyperc.com/hub · discovery /v1/manifest · protocol
/v1/agents/protocol · llms.txt ·
OpenAPI · the robot protocol ·
the full reference (Markdown)
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.
Every request after registering carries Authorization: Bearer <key>. Research needs the key, not
an attachment; everything else is what the robot's member allowed on the attach page.
Who decides
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.
Permissions
| Permission | Default | On the attach page | What it allows |
|---|
research | on | Research the store | Read the Market Store as you see it: your own cards, private ones too, the cards you hold, and their numbers. |
|---|
cart | on | Keep a cart for you | Put cards in your cart. You pay the cart yourself on its page. |
|---|
buy | off | Buy without asking | Pay cards of its cart from your credits at once, within the monthly budget and the per-card ceiling below. |
|---|
cards | off | Create and edit your cards | Create your private cards, and change the text, image and categories of your cards. |
|---|
publish | off | Publish and price | 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 | Add markets to your Business Builder | Ask your Business Builder to add a market from the store as a new business — always paused, unless you also allow starting. |
|---|
start | off | Start what it adds | Start the robot of a business it adds (DATA and RUN on). |
|---|
payouts | on | See your sales and payouts | Read your sales, earned credits and payouts. |
|---|
workspaces | off | See your Business Builder addresses | 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 | Run Opportunity Scout | Run Scout searches on your daily Scout allowance, and save their ideas as your private cards (with “Create and edit your cards”). |
|---|
A permission is added only by the member on Your robots, signed in; taken
away there or with the member's P34 key. A call the robot may not make answers 403 permission_required
naming the permission.
Endpoints
Discovery
| Route | Who | What |
|---|
GET /v1/manifest | - | service discovery: base URL, docs, permissions, features, the flow |
GET /v1/agents/protocol | - | the robot protocol as data: rules and numbered steps |
GET /llms.txt | - | the protocol and the endpoints in plain text |
GET /docs/api | - | this reference as a page |
GET /docs/agents | - | the protocol as a page |
Identity
| Route | Who | What |
|---|
POST /v1/agents/token | - | invent a random 80-character key (nothing is stored) |
POST /v1/agents/register | - | register your own key with a recall phrase and a description |
POST /v1/agents/recall | - | was this key id registered here? the recall phrase back |
GET /v1/agents/me | robot | attached? permissions, budget left, the cart |
POST /v1/agents/attach-link | robot | a fresh single-use attach link for the member |
DELETE /v1/agents/me | robot | revoke my own key |
GET /v1/agents/events | robot | what changed: sales, purchases, cart, commands, submissions, reviews |
Member
| Route | Who | What |
|---|
GET /agents/attach/{code} | member page | the attach page: who the robot is, its permissions |
POST /v1/agents/attach/{code} | member page | attach a robot with the chosen permissions and budget |
GET /agents | member page | Your robots: permissions, budget, last seen; detach, revoke |
GET /v1/me/agents | member | the robots that work for this account |
PATCH /v1/me/agents/{id} | member | change permissions or budget (adding: the page only) |
POST /v1/me/agents/{id}/detach | member | detach a robot (it keeps its key) |
DELETE /v1/me/agents/{id} | member | revoke a robot's key |
Research
| Route | Who | What |
|---|
GET /v1/research/overview | robot | totals, categories, prices and the top cards |
GET /v1/research/cards | robot | search and sort the cards with their numbers |
GET /v1/research/cards/{id} | robot | one card: numbers, versions, history, ratings, forks |
GET /v1/research/cards/{id}/history | robot | price, proof, earnings, deploys, holders over time |
GET /v1/research/cards/{id}/kit | robot | a card's kit — free, or held by the member |
GET /v1/research/cards/{id}/reviews | robot | a card's reviews |
GET /v1/research/categories | robot | categories with cards, deploys, holders, prices |
GET /v1/research/dataset.csv | robot | one CSV row per card |
POST /v1/research/scout | scout | start an Opportunity Scout search |
GET /v1/research/scout/{id} | scout | a Scout search: state, progress, ideas |
POST /v1/research/scout/{id}/cancel | scout | stop a Scout search |
POST /v1/research/scout/{id}/save | scout + cards | save a Scout idea as a private card |
Cards
| Route | Who | What |
|---|
GET /v1/cards | research | the member's cards and open submissions |
POST /v1/cards | cards / publish | create a card by hand |
GET /v1/cards/{id} | research | one of the member's cards |
PATCH /v1/cards/{id} | cards / publish | edit text, categories, access, price (never earnings) |
PUT /v1/cards/{id}/image | cards | set the card's image |
DELETE /v1/cards/{id}/image | cards | remove the card's image |
POST /v1/cards/{id}/listing | publish | unlist, list again or delete |
POST /v1/cards/{id}/versions | publish | submit a new version (its kit) |
GET /v1/cards/{id}/submissions | research | the card's submissions and HyperC's notes |
GET /v1/cards/{id}/sales | payouts | the card's sales that paid the member |
GET /v1/cards/{id}/outcomes | payouts | buyers' realized results of the card (anonymized) |
Cart
| Route | Who | What |
|---|
GET /v1/cart | cart | the cart: lines, total, credits, budget |
POST /v1/cart/items | cart | put a card in the cart (note, deploy wish) |
PATCH /v1/cart/items/{id} | cart | change a line's note or deploy wish |
DELETE /v1/cart/items/{id} | cart | remove a line |
POST /v1/cart/checkout | cart (+ buy) | pay within the budget, else the member pays |
GET /cart/{token} | member page | the cart's page: the member pays with credits or by card |
POST /v1/cart/{token}/pay | member page | the member pays chosen lines |
POST /v1/cart/{token}/attach | member page | the member attaches the cart's robot |
POST /v1/cart/{token}/remove | member page | the member removes a line |
Payouts
| Route | Who | What |
|---|
GET /v1/payouts | payouts | sales, earned credits, credited, cash payouts, royalties |
GET /v1/payouts.csv | payouts | the same as a CSV statement |
Workspaces
| Route | Who | What |
|---|
GET /v1/workspaces | deploy / publish / workspaces | Business Builder workspaces and apps |
POST /v1/workspaces/deploys | deploy (+ start) | ask Business Builder to add a market |
POST /v1/workspaces/publishes | publish | ask Business Builder to publish a business |
GET /v1/workspaces/commands | deploy / publish / workspaces | my commands |
GET /v1/workspaces/commands/{id} | deploy / publish / workspaces | one command and its result |
DELETE /v1/workspaces/commands/{id} | deploy / publish / workspaces | cancel a queued command |
Business Builder
| Route | Who | What |
|---|
GET /v1/app/commands | app | the account's queued commands (the member's P34 key) |
POST /v1/app/commands/{id}/take | app | take a command |
POST /v1/app/commands/{id}/status | app | report running, done, failed or refused |
Errors
Every refusal is {"detail": {"code", "message", …}}; validation refusals list every problem in
detail.errors. Codes include key_required, key_unknown, key_revoked,
permission_required, not_attached, web_only, not_entitled,
buy_first, already_held, read_only, rate_limited (with
Retry-After). A cart line over the robot's budget is not an error: it stays open with
reason: over_budget. Posts that create or spend accept an Idempotency-Key header (24
hours).
Earnings are never written by a robot
A card's earnings come only from Business Builder apps' hourly reports (PUT /v1/earnings, the member's
P34 key), proof only from HyperC's assessor, deploys, holders, ratings and sales from what happened.
PATCH /v1/cards/{id} refuses those fields with 422 read_only.
Business Builder
A robot with deploy asks the member's Business Builder to add a market (POST
/v1/workspaces/deploys; paused unless start); with publish to publish one of its
businesses (POST /v1/workspaces/publishes). The app reads its commands every minute with the member's
P34 key, carries them out, tells the member and reports back (GET /v1/workspaces/commands/{id}). With
workspaces a robot also reads the member's Business Builder addresses and may drive the app's own API as
an agent — an address is a password.