--- name: superagent-api description: Configure, secure, operate, fund, and audit projects that use the hosted HivemindOS SuperAgent API. Use when a project needs HivemindOS managed agents, memory, databases, wallets, trading, onchain token and wallet data, media, mini apps, workflows, files, runs, or Agent Credits. Do not use this skill to control desktop sessions or bypass payment and approval boundaries. --- # HivemindOS SuperAgent API Use the SuperAgent API as a managed cloud backend. Configure the current project, grant only the access it needs, and prove the real integration through safe live checks. ## Sources of truth Read the live contract before generating or changing client code: - [OpenAPI 3.1](https://api.hivemindos.app/openapi.json) for routes, schemas, scopes, operation ids, and errors. - [Remote MCP guide](https://hivemindos.app/docs/for-users/platform-api/mcp.html) for direct agent connection and tool behavior. - [Agent setup](https://hivemindos.app/superagent-api/llms.txt) for the setup session flow, the complete bootstrap and x402 quick start. - [Developer guide](https://hivemindos.app/docs/for-users/platform-api.html) for the supported workflow. - Authenticated `GET /services?probe=true` and `GET /capabilities/` for current account-specific availability. Use `https://api.hivemindos.app/v1` as the default REST base URL and `https://api.hivemindos.app/mcp` as the remote Streamable HTTP MCP address. Treat live responses and OpenAPI as newer than examples in this file. ## Protect credentials - Read `HIVEMINDOS_API_KEY` from the project's existing secret manager or runtime environment. Never print, log, commit, or return it. - If there is no key yet, set it up yourself: `POST /v1/setup-sessions` with `{"agentName": "", "instant": true}` (add `"email"` if you know the person's) returns the key in `secret` on a new account. Save it without showing it, then tell the person the `claimUrl` and `confirmCode` once; they claim the account by confirming their email there, which gives them a bonus gift of free credits. Don't wait for them. A lost answer is collected again with its `claimToken` (`POST /v1/setup-sessions/claim`). Never ask the person to copy or paste a key. - If the person already keeps a `HIVEMINDOS_CREDIT_TOKEN` in their secret store, you may use it only for that bootstrap request, keep it out of application code, and do not ask the user to paste it into chat. - Store a real secret only in an ignored local env file when that is already the project's convention. - Never place payment signatures, wallet private keys, recovery phrases, or approval credentials in source, logs, test fixtures, or agent memory. ## Operating workflow 1. Inspect the project's language, package manager, HTTP client, secret convention, test runner, and deployment environment. 2. Check for an existing API key without displaying its value. If there is none, run a setup session (see Protect credentials) rather than asking for one. 3. Discover live services and capabilities before choosing routes or operation ids. For an MCP integration, use `hive_actions_search` before calling an unfamiliar action. 4. Grant the smallest scopes, `allowedServices`, `allowedOperations`, project boundary, request limits, and concurrency limits that complete the task. 5. Use plain HTTPS from the project's own HTTP client, or generate a client from OpenAPI. No SDK is required; for TypeScript the optional typed client installs with `npm install https://github.com/LiamVisionary/hivemindos-sdk/releases/download/v1.5.0/hivemindos-sdk-1.5.0.tgz`. 6. Keep a stable `Idempotency-Key` for every mutation and every retry of that same mutation. 7. Verify through the application's real request path with read-only discovery first, then the smallest safe task-specific check. 8. Report changed files, permissions, tests, live checks, and remaining user actions without exposing secrets. Do not broaden a key merely to make a denied request pass. Determine the intended capability and change the policy deliberately. ## Manage API access Use the API-key routes to list, create, inspect, and revoke keys. Delegated keys may become narrower but never broader than their parent. Prefer separate keys for: - ordinary read and execution work; - high-trust approvals; - Agent Credit funding; and - isolated projects or production environments. Set endpoint limits with stable operation ids. Use a whole-key `"*"` ceiling plus tighter limits for expensive, high-concurrency, wallet, trading, publishing, or funding operations. Use project-bound keys when data, files, runs, databases, or wallets must remain isolated from other products using the same HivemindOS account. ## Call managed capabilities Use the typed capability operation when one is published. For long work, create a durable run and read its status or use a signed webhook. Preserve returned receipts, artifact ids, and run ids needed for later status checks without storing credentials. Protected actions can require a separate approval. Wallet signing, transfers, trading, publishing, destructive database work, and similar actions must retain the confirmation and approval contract published by the API. Never fabricate a confirmation string or silently approve an action proposed by the same execution key. Agent Credits pay for managed service work. Wallet assets are separate and pay transfer amounts, trades, and network fees. ## Fund Agent Credits with x402 Do not initiate a payment until the user approves the exact amount. Configuration permission is not spending permission. The funding key needs `credits:write` and `credits.x402.topUp`. Call: ```http POST /credits/x402/top-up Authorization: Bearer Content-Type: application/json Idempotency-Key: { "amountUsd": 5 } ``` Supported amounts are $5 to $500 with at most two decimal places. An x402-aware client handles the HTTP 402 challenge and signed retry. Reuse the same idempotency key for the challenge, signed retry, and uncertain-response retry. HivemindOS chooses and verifies the official revenue recipient, network, asset, price, and credited account. Never add a client-selected recipient, `payTo`, alternate account, network, asset, or price. After settlement, verify the receipt and confirm that the authenticated account's existing Agent Credit balance increased by the reported amount. ## Pay per call with x402, no key For a one-off job, an x402 wallet can buy a single operation with no key or account. `GET https://api.hivemindos.app/v1/x402` lists what is sold per call, with prices and example inputs. Send the operation's input to `POST https://api.hivemindos.app/v1/x402/{serviceId}/{operationId}`: the 402 is priced from that input (the account price, read live), and after the user approves the exact amount the signed retry runs it. The payment settles only if the call succeeds. Keep `followUp.apiKey` from the answer as a secret: it collects a background job's result and spends any leftover credits, for that service only. For work that keeps running or needs an account, `POST https://api.hivemindos.app/v1/x402/accounts` with `{ "amountUsd": 5 }` returns a funded API key instead. ## Connect and operate the remote MCP The complete SuperAgent MCP is available at: ```text https://api.hivemindos.app/mcp ``` Use Streamable HTTP and send `Authorization: Bearer ` through the MCP client's protected secret or header mechanism. Do not write the real key into a shared MCP config. An MCP key must have `services:read` and `actions.list`, plus only the scopes, services, and exact operations needed for its job. The server exposes eight stable tools by default: four for the account's memory first, then four that search and run any action. For a client that picks from a fixed tool list, use `https://api.hivemindos.app/mcp?tools=operations` (optionally `&services=a,b`), which adds one tool per operation named `__`; the key's own permissions still decide what runs. The memory tools need a key that may use `cloud-superbrain` (`hive setup --memory` makes one): - `memory_remember` saves a fact, decision, preference or note. Free for the first 200 memories and on a memory plan, then 1 credit each. Never save secrets. - `memory_recall` finds memories for a question, free by keyword; `semantic: true` matches by meaning for 1 credit. - `memory_forget` archives a memory by id (reversible, free). `permanently: true` erases it for good and needs `confirmDestructive: true` and the account owner's `approvalId`. - `memory_list` lists memories still in use, newest first, with their ids. The four general tools: - `hive_services_list` lists services available to the key. - `hive_actions_search` searches only actions the key is allowed to discover and call. - `hive_read` accepts only actions marked `read`. - `hive_write` accepts only actions marked `write` or `execute` and requires a stable idempotency key. Always search before acting and copy the exact returned `actionId`. Never guess it. Use `hive_read` for reads and `hive_write` for changes or execution. Set `confirmDestructive: true` only after the user explicitly confirms a destructive action. For a protected action, create and decide the required approval through a separately authorized key. An HTTP 402 response is a payment challenge, not consent. Pause, show the exact top-up amount, and obtain user confirmation before any signer creates a `Payment-Signature`. Retry through `hive_write` with the same action body and idempotency key. The service-specific Hive Compute MCP remains available for GPU-marketplace-only agents. Use the SuperAgent MCP for complete managed API coverage. MCP is an optional agent-tool adapter, not a replacement for API keys, scopes, endpoint limits, Agent Credits, confirmations, approvals, idempotency, or x402 payment consent. Every tool call passes through the same SuperAgent API authority. ## Shared memory across agents, and bringing memory in - Every key on one account shares one memory: what Claude, ChatGPT, a Muse or Hermes saves, the others recall. Memories saved through a key are tagged `by:`; filter `tags: ["by:"]` to read one agent's. Use project-bound keys or `X-HivemindOS-End-User` to keep an app's users apart. - `memory.import` brings in another assistant's memory: pasted ChatGPT/Claude/Gemini memories as `text` (ask that assistant to list every memory it has about the person, one per line), Hermes or Claude Code memory files as `files`, or `conversations` from a ChatGPT or Claude `conversations.json`. Preview first (`preview: true`, free), tell the person what it costs, then send it without preview and follow `nextCursor` until `done`. - `node setup.mjs import-memory` does it from a shell: it finds Hermes's and Claude Code's memory itself. ## Use a person's NFT agents and other people's bees The `nft-agents` service reaches HivePunkz, Loopers, JPEG Frens and every other NFT that is an agent (721T), from any harness holding a key: Grok Bot, a Muse, Claude, Cursor. - `agents.list` (read) lists the agents in the wallet the account linked on hivemindos.app/chat. Each has an `agent` id: `hivepunkz:`, `looper:`, `nft::` on Base, `nft:1::` on Ethereum. An empty list with `next` means no wallet is linked; `complete: false` means part of the wallet could not be read, never that it is empty. - `agents.get` (read) looks up any agent by id, or a bee with `bee=`: card link, shift, form, registry id and the `services` its holder shares. - `agents.chat` (execute) sends `{ "agent", "message", "history"? , "model"? }` and returns the agent's `reply` in its own voice. The linked wallet must hold the agent right now. It never runs work: an agent's request comes back as `work`, which you may search for and run only if the person agrees, within the key's own permissions. - `bees.quote`, `bees.run` and `bees.job` talk to or hire someone else's shared bee. Quote, show the person the exact price, and run only after their yes, with `approvedCredits` equal to the quote's `priceCredits`. - `bees.services.list` (read, `bee=`) and `bees.services.set` (write): what one of the person's own bees sells. `bees.services.set` with `{ "bee": 441, "service": "writing", "priceUsd": 0.10, "model": "" }` turns paid writing on at that price, with nothing to approve onchain as long as the bee uses trusted default skills; `{ "bee": 441, "service": "", "priceUsd": 0.30 }` or `"enabled": false` reprices or switches a service the holder set up from the bee's card. No signature: the wallet linked to the account must hold the bee. A bee with no funds cannot sell yet: it answers 409 "This agent is getting ready. Add funds or try again shortly.", and the holder funds it first under Money on the bee's card. Change a price only when the holder asks. - `convert.start`, `convert.confirm`, `convert.cancel`: make an NFT on Base that the person's linked wallet holds into an agent. `convert.start` with `{ "collection", "tokenId", "wallet" }` returns `reservationId` and the one `transaction` that wallet sends; `convert.confirm` with `{ "reservationId", "txHash" }` finishes it. $5 from the person's credits, taken only once it is done. Ask the person before converting. - No key at all, paid over x402 from a wallet on Base ($5 each, listed in Base Bazaar): `POST https://hivemindos-paid-agent-gateway.hivemindos.workers.dev/api/x402/agent-coins/launches` with `{ "agent": "hivepunkz:441" }` (or `nft::`) launches the agent's coin, named after the agent unless `metadata` says otherwise. Pay from the wallet that holds the NFT (or its delegate.xyz delegate): that payment is the holder's yes, so nothing else is signed. To make a plain NFT an agent first: `POST …/api/x402/agent-conversions/prepare` with `{ "collection", "tokenId", "wallet" }` returns the free register transaction for the holder to send, then `POST …/api/x402/agent-conversions` with `{ "collection", "tokenId", "txHash" }` (or `agentId` if it is already bound to an ERC-8004 agent) and the $5 payment. Each gives the agent 1,250 HivemindOS credits and answers with a `briefing` to pass on to the person. - `coin.get` (read): any agent's coin (`?agent=hivepunkz:441`): its ticker, what it has earned, and what went to whoever holds the NFT, in all and in the last 30 days. - `coin.challenge` then `coin.act`: launch an agent's coin, collect its trading fees, set up its trading wallet. Each action is signed by the wallet that holds the NFT (or one it delegated to on delegate.xyz): `coin.challenge` with `{ "agent", "action", "input", "address" }` returns a `message` to sign with `personal_sign`; send the same fields with `nonce` and `signature` to `coin.act` within two minutes. The quickest launch is `launch-now` with `{ "reference", "metadata": { "name", "symbol", "logo" } }`: wallet, quote and launch on one signature. Step by step: `wallet` with `{}` once, `quote` with `{ "reference", "metadata": { "name", "symbol", "logo" }, "pair": "eth", "chain": "base" }`, then `launch` with `{ "quoteId" }`. Launching is free; after the first $20 in fees, 15% of every fee goes to whoever holds the NFT and moves with it when it is sold. An agent that holds its own NFT can do all of this from its own wallet. - `agents.open` sets how others may talk with one of the person's Loopers or other agent NFTs (HivePunkz are shared from their bee card, and what a bee sells is priced with `bees.services.set`). Every agent is open and free until its holder sets a rule: `mode` free, quota (`freeUses` free replies a day or month, then the fee) or paid, with `feeCredits` (up to 50 a reply) and/or `feePercent` (up to 25%). The holder sees earnings with `agents.earnings`; they are sent to the holding wallet in USDC on Base on its own once they reach $5, or `agents.claim` takes them as Agent Credits sooner. `agents.policy` shows any agent's rule; `agents.ask` talks with someone else's agent, from its own chat when it has a free one, otherwise in its voice on the person's free replies then credits, plus its holder's fee only if one is set, so ask first when it charges. ## Rewards and the Hall The public board is `GET https://api.hivemindos.app/v1/hall` (no key), with public receipts at `/v1/hall/receipts/{receiptId}` and bounties at `/v1/hall/bounties`; the rules are at https://hivemindos.app/superagent-api/rewards/. Every charged call returns `x-hivemindos-receipt-id`. With the person's yes, `receipts.publish` on the `hall` service makes a receipt public (5 Honey, up to 3 a week). An app registered with `apps.create` sends `x-hivemindos-app: app_<12 hex>` on its calls and earns its owner 5% of what other people spend through it; it is sent to the owner's linked wallet in USDC on Base on its own once it reaches $5, or `apps.claim` takes it as Agent Credits sooner. Honey is a contribution record and is never exchanged for HIVE or money. ## Agents answering in a HivemindOS chat room An NFT agent in a HivemindOS room — a HivePunk, a Looper, or an external A2A agent — does not hold an API key and does not call these routes itself. It asks, and the host carries the request out under the room's own authority. Add one field to the JSON reply the room already expects: ```json { "content": "Running that video now.", "capability": { "request": "10 second video of a dog running to a door" } } ``` - `request` is one plain sentence of what you want done, 1–2000 characters. Do not name a route, an `operationId`, a URL, or a payment. The host asks `POST /v1/requests/route` on your behalf and the returned action descriptor — not your wording — decides what runs. - `serviceId` is optional and is only a filter over the published catalog, such as `managed-media` or `hive-research`. An unrecognised value is dropped rather than followed. - Anything the platform marks `destructive`, or `approval: "always"` or `"policy"`, comes back to the person as a confirmation to press instead of running. Everything else — media, research, compute, data — runs immediately. - Billing follows the agent first: an agent with its own funded HivemindOS credit balance spends that, and otherwise the holder's account pays. - The work happens after your words are delivered, so never write as though it already finished. Say you are running it. What is reachable this way is the whole published service catalog — image, video, audio, lip-sync, upscale and 3D media, research, answers, swarms, compute, GPUs, databases, analytics, files, email, socials, bookings, finance, trading and swaps. Ask for the outcome in ordinary words; the router finds the service. For swaps, `POST /v1/swaps/quote` reads the same words the hivemindos.app Trade desk does ("i need 0.8 sol") and takes `amountOut` for an exact amount to receive; `POST /v1/swaps/prepare` returns checked, unsigned transactions for a wallet the person holds themselves (`sender`, and `recipient` when it lands on the other kind of chain), with no Agent Credits charged. `GET /v1/services` and `GET /v1/capabilities/` list what a given account can currently reach. ## Completion gate Before saying the integration is ready, confirm: - the application loads the API key privately; - an MCP integration authenticates, lists exactly four tools, and can search only its allowed actions; - live balance and service discovery succeed; - required capabilities are available and only intended capabilities are allowed; - a denied operation is denied when practical to test; - mutations preserve idempotency; - high-trust work still requires its separate approval; - any payment was separately authorized, settled once, returned a receipt, and credited the same account; - tests and typechecks pass; and - no secret appears in source, diffs, logs, fixtures, documentation, or the final report.