# Set up the HivemindOS SuperAgent API ## Install in an agent `hive setup` connects the full SuperAgent API. `hive setup --memory` connects only shared memory; combine flags such as `--memory --research` for selected features. Install with `npm install -g https://hivemindos.app/hive/1.0.0/hivemindos-cli-1.0.0.tgz`, `pipx install https://hivemindos.app/hive/1.0.0/hivemindos_cli-1.0.0-py3-none-any.whl`, or `curl -fsSL https://hivemindos.app/install | sh`. All methods need Node.js 20+. Supports Claude Code, Codex, Cursor and Hermes. Sign in and approve in the browser; no card, HIVE or NFT is required to install. Keyword search is free; semantic recall, answers and research remain metered. See https://hivemindos.app/superagent-api/cli/. The project-specific helper below remains available for applications that need a key in their own environment instead of an agent MCP connection. ## First: which kind of agent are you? - **Already inside HivemindOS** (hivemindos.app chat, a HivePunk, a Looper or any other agent there): you are on the SuperAgent API already, and everything you ask for there runs through it on the person's account. Install nothing, run nothing and collect no key. Say so in a sentence and show them their credit balance. - **A chat app that connects MCP servers** (Claude, ChatGPT and similar): the person adds `https://api.hivemindos.app/mcp` (or `https://api.hivemindos.app/v1/private/mcp`, `https://api.hivemindos.app/v1/confidential/mcp`) as a custom connector and, when the app asks, enters their email and a code and presses Connect (no account needed beforehand). It is standard MCP authorization (OAuth 2.1 with PKCE, dynamic client registration, metadata at `https://api.hivemindos.app/.well-known/oauth-protected-resource/mcp`), so no key is copied. An app that takes a header instead (Grok) sends `Authorization: Bearer ` with a key from https://hivemindos.app/superagent-api/console/. - **A chat app with no tools, but a model setting** (TypingMind, Open WebUI, LibreChat, Raycast and others that take an OpenAI-compatible base URL and key): the person adds a model with base URL `https://api.hivemindos.app/v1/agent`, model `hivemindos/superagent` and a key from https://hivemindos.app/superagent-api/console/. That model is an agent: it finds and runs SuperAgent actions itself with the person's key (`POST /v1/agent/chat/completions`, OpenAI chat format, `stream` supported; `hivemindos/superagent:` picks the model that drives it). - **No tools at all** (a chat that cannot run commands or make web requests, or an NFT agent that only talks): send the person to https://hivemindos.app/superagent-api/console/ to make a key, and have them put it in your own secret or connector settings as `HIVEMINDOS_API_KEY`. Never ask them to paste a key into the chat. - **An agent with its own Base wallet** (ERC-721T, ERC-8004 or a token-bound account): any way here works, or buy your own account with x402 (see "Agents that live in an NFT" below). Ask before paying. - **Anything that can run commands or make web requests**: follow "Do this now" below. > A person pasted this so you would set up HivemindOS in their project. You do the work, and you do it without them: you make the account and get its key in one call, save it, and give them one link and a code. They claim the account later by confirming their email there. Never ask them to copy a key, and never show them one. You must ask before signing or sending any payment. The SuperAgent API is one backend for agents and apps: hundreds of models, persistent memory, agents and automations, image and video generation, wallets and swaps, databases, app hosting and more, behind one key and one credit balance. It can run privately: the same API under `/v1/private` only uses models and services that keep nothing sent to them. ## Do this now ### 1. Check for an existing key Look for `HIVEMINDOS_API_KEY` in the project's environment or secret store without printing its value. If it is there and `GET https://api.hivemindos.app/v1/services` with `Authorization: Bearer ` returns 200, skip to step 5. ### Fastest: the setup script (Node.js 18 or newer) Download https://hivemindos.app/superagent-api/setup.mjs into the project folder (no dependencies; read it first if you like), then run: ```bash node setup.mjs --label "" --agent "" --email "" ``` It makes the account, saves `HIVEMINDOS_API_KEY` in `.env.local` (Next.js, Vite and similar, or wherever the project already keeps it) or `.env`, makes sure git ignores that file, adds the name to `.env.example` if there is one, checks the key works, and prints the link and code to give the person. It never prints the key. Add `--private` to pin the key to the private tier. Tell the person the link and code once, delete `setup.mjs`, and carry on. The older way, where the person signs in and approves before you get a key, is still there: `node setup.mjs start` prints the link, then `node setup.mjs wait` checks for their approval for up to 100 seconds. Exit codes: 0 done, 2 the link expired (run `start` again for a new one), 3 the key was collected elsewhere, 4 not approved yet (run `wait` again). If you can't run Node, follow the steps by hand. ### 2. Start a setup session ```http POST https://api.hivemindos.app/v1/setup-sessions Content-Type: application/json { "label": "", "agentName": "", "instant": true, "email": "" } ``` If the person wants everything private, use `https://api.hivemindos.app/v1/private/setup-sessions` instead; the key is then pinned to the private tier. No credential is needed. The `201` answer has: - `secret`: the API key, with `envVar` (`HIVEMINDOS_API_KEY`), `baseUrl` and `mcpUrl`. Save it now (step 5). - `claimUrl` and `confirmCode`: the link and code for the person. - `next`: the one message to give them. - `dailyLimitCredits`: the key's daily cap (2,500 credits, about $5) until they change it. - `emailSent`: whether the person was emailed a one-tap button to claim the account (only when you passed `email`). - `claimToken`: yours alone, only for collecting a lost answer again (step 4). Never print it, show it, or write it to a file. The account is new and empty: reads and free features work at once. Calls that cost credits answer `402` until the person confirms their email on the link (it gives them a bonus gift of 250 free credits, once per person) or adds credits. When you get a `402`, give them the link again. They have 30 days to claim it. ### 3. Tell the person once Give them the `next` message, in your own words, and carry on with your work. Do not wait for them and do not poll: > I'm connected to HivemindOS. To keep this account, open . It shows the code , which should match what I show you. Confirming your email adds a bonus gift of 250 free credits for you. Without `"instant": true` the older setup is used: the person signs in and approves on `setupUrl` before you get the key. Open `setupUrl` for them if you can, tell them the `setupSession.confirmCode`, and collect the key in step 4. If you hold an x402 wallet on Base with USDC, you may offer to pay for the account yourself instead. Ask for approval of the exact amount first (at least $5), then: ```http POST https://api.hivemindos.app/v1/setup-sessions/fund Authorization: Bearer Idempotency-Key: Content-Type: application/json { "amountUsd": 10 } ``` It answers 402 with `Payment-Required`. Sign that exact payment and repeat the same request with `Payment-Signature` and the same Idempotency-Key. Success returns the key right away (as in step 4). Then give the person `setupUrl` so they can take over the account you paid for and add their email to keep it. ### 4. Collect the key With `"instant": true` you already have it. If that answer was lost (a dropped connection or a tool timeout), the claim call below returns the same key again for 10 minutes (`replayed: true`). ```http POST https://api.hivemindos.app/v1/setup-sessions/claim Authorization: Bearer ``` For the older setup, call it every `pollIntervalSeconds` (5) while you wait: - `202` with `status: "pending"`: they have not approved yet. Keep waiting. A `429` with `code: "slow_down"` means you polled too fast. - `200`: `secret` is the API key, with `envVar` (`HIVEMINDOS_API_KEY`), `baseUrl` and `mcpUrl`. If your reply was lost (a dropped connection or a tool timeout), the same claim token returns the same key again for 10 minutes (`replayed: true`). - `409` `already_collected`: the key was handed over more than 10 minutes ago. Ask the person to create a new key in the console at https://hivemindos.app/superagent-api/console/#keys and add it to the project themselves. - `410` `expired`: start a new session. If your shell tool times out long commands, poll in short batches (for example 20 tries, 5 seconds apart) and run the batch again while the result is `202`. Keep the claim token in memory, or in a temporary file only you read, between batches. ### 5. Save the key where the project keeps secrets Write it yourself, without printing it: - Most projects: add `HIVEMINDOS_API_KEY=` to `.env.local` or `.env` (create it if the project has none), and make sure that file is in `.gitignore`. Add the name, with no value, to `.env.example` if the project has one. - If the project uses a secret manager (Vercel, Cloudflare, Doppler, 1Password, a platform dashboard), use it; ask the person only for the permission you need. - If you cannot write files (you are a chat with no tools), tell the person to press "Show my key" on the setup page, which gives them the key and the exact line to add. Never commit the key, paste it into source code, or put it in a message. ### 6. Prove it works and say so With the saved key, call `GET https://api.hivemindos.app/v1/services` and `GET https://api.hivemindos.app/v1/credits/balance`. Then tell the person in plain words: the SuperAgent API is set up, where the key is saved, and how many credits the account has. If the balance is 0, tell them calls that cost credits are refused until they add some at https://hivemindos.app/superagent-api/console/#billing. Offer the console for keys, usage and billing: https://hivemindos.app/superagent-api/console/ Use the key only in server-side code. Never put it in code that runs in a browser: no `NEXT_PUBLIC_`, `VITE_`, `PUBLIC_` or `REACT_APP_` prefix, and never in client bundles or mobile apps. If the project is browser-only, add a small server route or function that calls the API and keeps the key there. After that, add only what the project actually needs (steps below) and verify it through the live API. ## Live sources of truth - [OpenAPI 3.1](https://api.hivemindos.app/openapi.json): Exact live routes, schemas, scopes, operation ids, and errors. Read this before generating client code. - [Setup guide (JSON)](https://api.hivemindos.app/v1): The setup session flow and links, machine-readable. - [Pay-per-call catalog (JSON)](https://api.hivemindos.app/v1/x402): Every operation you can buy with x402 and no key, with its price rule, URL, example input and schema. - [Remote MCP guide](https://hivemindos.app/docs/for-users/platform-api/mcp.html): Connect an agent directly and understand the four stable tools. - [Quickstart](https://hivemindos.app/docs/for-users/platform-api.html): Product overview and first call. - [Privacy tiers](https://hivemindos.app/docs/for-users/platform-api/privacy.html): Standard, private and confidential bases. - [Authentication](https://hivemindos.app/docs/for-users/platform-api/authentication.html): Key creation, delegation, and revocation. - [Endpoint limits](https://hivemindos.app/docs/for-users/platform-api/limits.html): Request, concurrency, and supported daily Agent Credit limits. Use `https://api.hivemindos.app/v1` as the REST base URL and `https://api.hivemindos.app/mcp` as the remote Streamable HTTP MCP address. Treat the live OpenAPI document and authenticated discovery responses as authoritative if any copied example becomes stale. ## Non-negotiable safety rules 1. Never print, log, commit, paste into source code, or return `HIVEMINDOS_API_KEY`, a setup `claimToken`, `HIVEMINDOS_CREDIT_TOKEN`, an x402 payer private key, a payment signature, or a wallet recovery phrase. 2. Read credentials from the project's existing secret manager or runtime environment. Never edit an example env file with a real secret. 3. Create the narrowest API key that can do the job. Restrict scopes, services, operations, project access, request rates, concurrency, and spending-related endpoints. 4. Do not sign or send an x402 payment until the user confirms the exact amount. A request to configure the API is not permission to spend. 5. Use a unique `Idempotency-Key` for every mutation. Keep the same key for the initial x402 challenge, its signed retry, and any retry of an uncertain response. Use a new key only for a genuinely new payment or mutation. 6. Keep execution authority separate from approval authority for wallets, trading, publishing, and other protected actions. 7. Verify through the live API. A successful install, typecheck, or mock test alone does not prove the account and key work. ## What the API provides The managed catalog currently covers 38 services. Read the live list, with each service's status, from `GET https://api.hivemindos.app/v1/catalog` (no key needed) or `GET /services?probe=true` with a key. Do not assume every service is available for every account. This is a cloud managed-services API. It does not expose or control a user's HivemindOS desktop sessions. Managed memory, databases, wallets, agents, jobs, and files belong to the authenticated HivemindOS account and optional project boundary. ## Calling the API Use plain HTTPS from any language; no SDK is required. For TypeScript there is an optional typed client: `npm install https://github.com/LiamVisionary/hivemindos-sdk/releases/download/v1.5.0/hivemindos-sdk-1.5.0.tgz` (works with npm, pnpm and yarn; import it as `@hivemindos/sdk`; `new HivemindOSClient({ apiKey, privacy: "private" })` selects a tier). Determine the project's language, HTTP client, secret-storage convention and test runner, and reuse its patterns. Generate or write a client from the live OpenAPI document; do not invent endpoints from this file. If the person already has a HivemindOS account credit token in their secret store (`HIVEMINDOS_CREDIT_TOKEN`), you may create a scoped key directly instead of a setup session: ```http POST https://api.hivemindos.app/v1/api-keys Content-Type: application/json X-HivemindOS-Credit-Token: Idempotency-Key: { "label": "", "scopes": ["services:read", "credits:read"], "allowedOperations": ["actions.list", "services.list", "capabilities.list", "credits.balance.read"], "limits": { "*": { "requestsPerHour": 1000, "maxConcurrent": 10 } } } ``` The complete secret is returned only at creation. Do not ask the person to paste a credential into chat. ## Step 3: choose least-privilege access Available scopes are: `services:read`, `services:invoke`, `credits:read`, `credits:write`, `projects:read`, `projects:write`, `usage:read`, `audit:read`, `files:read`, `files:write`, `connections:read`, `connections:write`, `databases:read`, `databases:write`, `wallets:read`, `wallets:create`, `wallets:sign`, `wallets:transact`, `trading:read`, `trading:execute`, `runs:read`, `runs:write`, `approvals:read`, `approvals:write`, `artifacts:read`, `webhooks:read`, `webhooks:write`, and `api_keys:manage`. Use `allowedServices` for the smallest service set and `allowedOperations` for the exact actions. Use a project-bound key when the integration should see only one project. When the app serves its own users, send `X-HivemindOS-End-User: ` (or bind a key with `endUserId`) so each user's memory and service data stay apart. Child keys may become narrower but never broader than their parent. Endpoint limits live under `limits` and use stable operation ids. Example: ```json { "*": { "requestsPerHour": 1000, "maxConcurrent": 10 }, "services.invoke.hive-research.analyses.create": { "requestsPerMinute": 10, "maxConcurrent": 2 }, "credits.x402.topUp": { "requestsPerDay": 4 } } ``` Use `GET /capabilities/` to obtain each capability's stable operation id, input mode, approval rule, and run support before granting it. ## Connect an MCP-compatible agent When the project supports remote MCP, configure: ```json { "mcpServers": { "hivemindos": { "type": "http", "url": "https://api.hivemindos.app/mcp", "headers": { "Authorization": "Bearer ${HIVEMINDOS_API_KEY}" } } } } ``` Use the client's protected environment or secret mechanism for the header. Do not put a real key into a shared file. The MCP key needs `services:read` and `actions.list`, then only the extra scopes, `allowedServices`, and `allowedOperations` required for the agent's job. By default the MCP exposes eight tools: four for memory, then four that search and run any action (below). Clients that choose from a fixed tool list can connect to `https://api.hivemindos.app/mcp?tools=operations` instead, which adds one tool per operation (`__`, for example `svg-studio__svgs_generate`); add `&services=svg-studio,leadgen-data` to list only some services. Those tools still run with the key's own scopes, services, limits and approvals. The memory tools reach the account's memory (Cloud Superbrain), shared by every agent on the account, in one call each: - `memory_remember` saves a fact, decision, preference or note (`content`, optional `title`, `type`, `tags`). Free for the account's first 200 memories and on a memory plan; past that, 1 credit each. Secrets are refused. - `memory_recall` finds memories for a question (`query`, optional `limit`, `tags`). Free by keyword; `semantic: true` also matches by meaning for 1 credit, and an account that has never paid for memory gets the free keyword recall instead. - `memory_forget` archives a memory by id, so recall and listing leave it out; it can be restored and costs nothing. `permanently: true` erases it for good and needs `confirmDestructive: true` and an `approvalId` the account owner granted. - `memory_list` lists memories still in use, newest first, with their ids (`limit`, `tags`). Free. They need a key that may use `cloud-superbrain`; `hive setup --memory` makes one. The four general tools: 1. `hive_services_list` lists available services. 2. `hive_actions_search` returns only actions permitted by the key. 3. `hive_read` runs only returned actions marked `read`. 4. `hive_write` runs returned `write` or `execute` actions and requires a stable idempotency key. Search before acting and use the exact returned `actionId`. Do not guess action ids. Ask the user before payments, trades, transfers, signatures, deletion, publishing, or other consequential work. Set `confirmDestructive: true` only after explicit confirmation. An HTTP 402 challenge is not permission to pay; pause for the exact amount approval before a wallet signs it. ## Connect an agent people already use ### Grok Bot In Grok Bot, open Settings → Plugins and add a custom MCP server: - Name: `HivemindOS` - URL: `https://api.hivemindos.app/mcp` (or `/v1/private/mcp` or `/v1/confidential/mcp` for a stricter privacy tier) - Header: `Authorization: Bearer ` The same four tools appear. Grok Bot needs no other setting: the server answers plain JSON over HTTPS. ### Meta Muse Tell the Muse: "Read https://hivemindos.app/superagent-api/muse.md and connect HivemindOS." The Muse opens a setup session, the person approves it on hivemindos.app, and the Muse keeps the key as a Custom Connector in its Secure Credentials Store. After that it calls the REST API directly. To add credits, the Muse calls `POST /v1/credits/checkout` with `{ "amountUsd": 20 }` after the person approves the amount, and pays the returned `checkoutUrl` with Link. ### Agents that live in an NFT An agent with its own Base wallet, such as an ERC-721T or ERC-8004 agent or a token-bound account, needs no person and no sign-up: - Buy an account: `POST https://api.hivemindos.app/v1/x402/accounts` with `{ "amountUsd": 5, "label": "" }`. Answer the 402 with an x402 v2 payment in USDC on Base. The reply holds an API key with that many Agent Credits (500 per dollar) for every service. The key can never move funds. - Or pay per call, with no key: see "Pay per call with x402" below. The wallet must be able to sign an x402 payment, which is a USDC transfer authorization. Keep the key in the agent's private runtime, never in token metadata. Do not publish `https://api.hivemindos.app/mcp` as the agent's own `endpoint[mcp]`: callers would need the agent's key. ### HivePunkz and other NFT agents, from Grok Bot, a Muse or any agent The `nft-agents` service lets any agent holding a key use the person's own NFT agents and other people's shared HivePunkz. Find the actions with `hive_actions_search` for `nft-agents`, or `GET /v1/actions?query=nft-agents`: - `agents.list` (read): the agents in the wallet the person linked on hivemindos.app/chat: HivePunkz, Loopers, JPEG Frens and any other NFT that is an agent, on Base and Ethereum. Each has an `agent` id: `hivepunkz:`, `looper:`, `nft::` on Base or `nft:1::` on Ethereum. - `agents.get` (read): any agent's public face. For a bee: its card link, shift, form, registry id and the `services` its holder shares. For any other NFT: its holder and whether it is an agent yet. - `agents.chat` (execute): talk with one of the person's own agents in its own voice. The linked wallet must hold it right now. Billed as the model costs; a bee on its free allowance costs nothing. `work` in the answer is something the agent asked to have done. It was not run: run it only if the person agrees. - `bees.quote`, `bees.run`, `bees.job`: talk to or hire someone else's shared bee. Quote first, get the person's yes to the exact price, then run 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. - `agents.open` (write): set how other people may talk with one of the person's Loopers, JPEG Frens or other agent NFTs (`{ "agent": "looper:12", "mode": "quota", "freeUses": 5, "feeCredits": 1 }`). Every agent is open to anyone and free until its holder sets a rule. `open` true or false; `mode` free, quota (free replies each day or month, then the fee) or paid (the fee on every reply); the fee is `feeCredits` (up to 50 a reply) and/or `feePercent` (0 to 25, a share of each reply's cost). HivePunkz are shared from their bee card instead. `agents.earnings` reads what is waiting and each agent's rule; `agents.claim` moves it into the person's credits. - `agents.policy` (read): an agent's rule before talking with it (`?agent=looper:12`): open or closed, free, or its holder's fee. - `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.ask` (execute): talk with someone else's agent. It answers from its own chat when it publishes a free one, otherwise HivemindOS's model speaks as it: the person's free Swarm Scout replies first, then their credits. Its holder's fee applies only if they set one, so read `agents.policy` and get the person's yes when it charges. Not for their own agents (use `agents.chat`). ## Rewards and the Hall Builders earn Agent Credits and Honey for real use of what they build. The rules in plain words are at https://hivemindos.app/superagent-api/rewards/ and this week's board is at https://hivemindos.app/superagent-api/hall/. - Public, no key: `GET https://api.hivemindos.app/v1/hall` (this week; `?week=YYYY-MM-DD` for an earlier Monday), `GET https://api.hivemindos.app/v1/hall/receipts/{receiptId}` (one receipt its owner made public), `GET https://api.hivemindos.app/v1/hall/bounties`. - Receipts: every charged call answers with `x-hivemindos-receipt-id`. `receipts.publish` on the `hall` service makes one public and returns its share link; a receipt of 5 credits or more from the last 7 days earns 5 Honey, up to 3 a week. Ask the person before publishing anything of theirs. - Apps: `apps.create` registers an app and returns its id. Send `x-hivemindos-app: app_<12 hex>` on every call the app makes and its owner earns 5% of the credits other people's calls spend (not the owner's own calls; not wallet, swap, trading, credit or top-up calls), up to 25,000 credits a week per app. `apps.claim` moves it into credits. - `rewards.me` reads the account's first-payment match, receipt Honey this week, recent receipts, apps and what they earned. - Honey is a lifetime contribution record. It is never exchanged for HIVE, sold or cashed out. ## Step 4: authenticate every call Raw HTTPS requests authenticate with: ```http Authorization: Bearer ``` Successful JSON uses `{ "ok": true, ... }`. Expected API failures use `{ "ok": false, "error": "..." }` and may add `code`, `operationId`, `metric`, and `retryAfterSeconds`. Handle HTTP 401, 402, 403, 409, 424, and 429 explicitly. Honor `Retry-After`; do not blindly retry mutations with a new idempotency key. A managed-service call (`POST /v1/services/{serviceId}/invoke`) passes the service's own 4xx through with a `code` (fix the request), and reports its failures as 502 `upstream_error`, 503 `upstream_unavailable` or 504 `upstream_timeout`; `upstreamStatus` is the status the service returned. Those are safe to retry with the same idempotency key, after `Retry-After`/`retryAfterSeconds` when present. `403` `scope_not_supported` means the service cannot keep a project or end user apart: call it with an account-level key and no end user. `409` `approval_consumed` means that approval was already used. An approval must come from the account owner or a key outside the requester's family (not the requester, its parent, a sibling, or a key it created). Keys expire after 30 days unless `expiresAt` says otherwise; one made from a credit token renews each time it is used. A deprecated operation answers with `Deprecation` and `Sunset` headers at least 30 days before it is removed. ## Step 5: run a read-only smoke test Make these calls with the configured API key: 1. `GET /credits/balance` when the key has `credits:read`. 2. `GET /services` when the key has `services:read`. 3. `GET /actions?query=` when the key has `actions.list`. 4. `GET /capabilities/` for every service the integration will call. Confirm the key sees only the intended services and capabilities. Never broaden a key merely to make a denied test pass; fix the intended policy deliberately. ## Step 6: call a managed capability Invoke a managed capability by its operation id: ```ts const response = await fetch("https://api.hivemindos.app/v1/services/hive-research/invoke", { method: "POST", headers: { authorization: `Bearer ${process.env.HIVEMINDOS_API_KEY}`, "content-type": "application/json", "idempotency-key": crypto.randomUUID(), }, body: JSON.stringify({ operationId: "analyses.create", input: { chain: "base", query: "0x4ed4e862860bed51a9570b96d89af5e1b0efefed" }, }), }); const result = await response.json(); if (!result.ok) throw new Error(result.error); ``` For long work, use durable runs and poll the returned run or receive a signed webhook. Protected operations may require a separately approved action. Files, connections, managed databases, managed memory, wallets, and trading have dedicated routes documented in OpenAPI. ### Remaster a video's sound `media-studio` gives an existing clip a new sound design synced to the action (Mirelo SFX 2.0): it drops music nobody asked for, keeps the dialogue, and returns the same clip with its new soundtrack. Quote with `operationId: "quotes.create"` first, then create with the same input, then poll `generations.get` until `generation.status` is `complete` and read `generation.outputs` (one MP4 per take): ```json { "operationId": "generations.create", "input": { "kind": "video", "model": "remaster-audio", "input": { "video_url": "https://…/clip.mp4", "duration": 12.6, "prompt": "heavy rain, distant thunder", "avoid": "music" } } } ``` Send the clip by its `https` address with `duration` in seconds (a request here is capped at 1 MB, so not as bytes), or as `from`: the id of one of your own finished video generations (create reads its length; to quote it, send `duration` too). `keep_dialogue: false` makes sound effects only; `takes: 2` returns two versions and charges for both. It costs $0.01 a second of clip per take before markup, at least $0.05, and up to 400 seconds of sound a call. ### Not sure which action a request needs? Ask the API. `POST /v1/requests/route` with `{ "request": "are exchanges pulling 0x… on base off their books?" }` answers `selected` with the one action to run, `choose` with ranked actions when two could fit, or `no_match` when nothing can do it. For a request with several parts, `POST /v1/requests/plan` returns the calls in order, each with the input field names it needs: "check if 0x… is safe and whether whales are buying it, then buy $20 of it" plans the flows read, the safety report and then the swap quote. Neither runs anything; both need `services:read`, `services:invoke` and access to `managed-models`. ## Buy Agent Credits by card The API key needs `credits:write` (and `credits.checkout.create` if it uses an operation allowlist). Ask the user to approve the exact amount first, $5 to $500. ```http POST https://api.hivemindos.app/v1/credits/checkout Authorization: Bearer Content-Type: application/json Idempotency-Key: { "amountUsd": 20 } ``` The reply has `checkoutUrl`, `credits` (500 per dollar) and `expiresAt` (24 hours). The person pays by card or Link at that link; nothing is charged until they do, and the credits land on the key's own account. The same Idempotency-Key returns the same link. ## Buy Agent Credits with x402 The API key needs `credits:write`. If the key uses an operation allowlist, include `credits.x402.topUp`. The supported amount is $5 to $500 with at most two decimal places. The route is: ```http POST https://api.hivemindos.app/v1/credits/x402/top-up Authorization: Bearer Content-Type: application/json Idempotency-Key: { "amountUsd": 5 } ``` Without payment, the API returns HTTP 402 and `Payment-Required`. An x402 v2 client signs the exact Base payment and retries with `Payment-Signature`. Success returns `Payment-Response`, the amount credited, a receipt id, and the updated Agent Credit balance. HivemindOS selects and verifies the revenue recipient, Base network, payment asset, amount, and credited account on the server. Never add a `payTo`, recipient, alternate account, network, asset, or price override to this request. The payment settles to the same official HivemindOS revenue wallet used by the existing HivemindOS x402 services. For a server-side TypeScript payer: ```bash npm install @x402/fetch @x402/evm viem ``` ```ts import { ExactEvmScheme } from "@x402/evm"; import { wrapFetchWithPaymentFromConfig } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const payer = privateKeyToAccount( process.env.X402_PAYER_PRIVATE_KEY as `0x${string}`, ); const paidFetch = wrapFetchWithPaymentFromConfig(fetch, { schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(payer) }], }); // Ask the user to confirm the exact amount before this call. const response = await paidFetch("https://api.hivemindos.app/v1/credits/x402/top-up", { method: "POST", headers: { authorization: `Bearer ${process.env.HIVEMINDOS_API_KEY}`, "content-type": "application/json", "idempotency-key": "top-up-2026-09-25-001", }, body: JSON.stringify({ amountUsd: 5 }), }); const topUp = await response.json(); if (!topUp.ok) throw new Error(topUp.error); ``` Use the project's established wallet signer when available. Do not create, export, or persist a new private key unless the user explicitly asks for a new payer wallet and understands the custody implications. Confirm that the payer has enough Base USDC before attempting payment. ## Pay per call with x402 (no key, no account) An agent with an x402 wallet on Base can buy a single operation without any HivemindOS key or account. List what is for sale, with prices, at `GET https://api.hivemindos.app/v1/x402` (no auth). Today that covers Hive Research, Token Autopsy, Wallet Risk, Reddit VOC, Swarm, X Studio runs, MiroShark, the testnet faucet, Media Studio images, video and video sound remastering, Photo Keyworder, SVG Studio (vectorize, generate, edit, animate), lead-gen data, and every Onchain Intelligence read (token, wallet, perp and exchange data). ```http POST https://api.hivemindos.app/v1/x402/{serviceId}/{operationId} Content-Type: application/json ``` 1. Without payment the API answers 402 with `Payment-Required`, priced from your input (the same price a HivemindOS account pays, read live from the service). A bad input gets 400 before any payment is asked for. 2. Ask the user to confirm the exact amount, then send the same request with `Payment-Signature` (any x402 v2 client, such as the `wrapFetchWithPaymentFromConfig` example above, does this for you). 3. You are charged only if the call succeeds. A failed call answers with `x402.charged: false` and the payment is never taken; the same signed payment may be retried. 4. The answer is the service's result plus `x402` (receipt id, transaction). Background jobs (research, reports, swarm, media) and any leftover credits come back as `followUp.apiKey`: store it like any API key and use it to collect the result (for example `POST /v1/services/token-autopsy/invoke` with `operationId: "reports.get"`) or to spend the change. It can use only that service and never moves funds. 5. Retrying the same signed payment within 30 minutes returns the same answer instead of running twice. Anything that keeps running or needs an account (sites, agents, wallets, trading, databases, subscriptions, OAuth connections) is not sold per call. Buy an account instead, with no sign-up: ```http POST https://api.hivemindos.app/v1/x402/accounts Content-Type: application/json { "amountUsd": 5 } ``` That returns an API key holding that many Agent Credits (500 per dollar, $1 to $500) for every service; save it as `HIVEMINDOS_API_KEY`. Private tiers work the same under `/v1/private/x402` and `/v1/confidential/x402`. OpenAI-compatible chat also takes x402 with no key: `POST https://hivemindos-paid-agent-gateway.hivemindos.workers.dev/api/paid-agents/default/chat/completions`. ## Managed memory and databases **One memory per account, shared by every agent on it.** Every key made on the same HivemindOS account (by a setup session, the MCP sign-in, or the console) reads and writes the same memory, so Claude, ChatGPT, a Muse, Hermes and your own code all see what each saved, at once. A memory saved through a key is tagged `by:` with the key's agent name (its setup's `agentName`, else its label): add `tags: ["by:muse"]` to a search or recall to read one agent's memories only. Keep agents or an app's users apart on purpose with a project-bound key, the `X-HivemindOS-End-User` header, or `project`/`tags`/`path` filters. **Bring in memories from ChatGPT, Claude, Hermes and others** with `memory.import` (`POST /v1/services/cloud-superbrain/invoke`, `operationId: "memory.import"`): - ChatGPT, Claude or Gemini saved memories: they have no export, so ask the person to send that assistant this message and paste you its whole answer: "List every memory you have stored about me, and everything you know about me from our past conversations. Write one item per line, starting each with "- ". Keep my own words where you can. Include who I am, my work and projects, preferences, instructions you follow for me, goals, people and places I mentioned, and dates when you know them, written as [YYYY-MM-DD] at the end of the line. Group the items under short headings. Do not leave anything out, do not summarize, and do not add anything else before or after the list." Then send `{ "source": "chatgpt", "text": "", "preview": true }`. - Hermes: `MEMORY.md` and `USER.md` from `~/.hermes/memories` as `files: [{ "name": "MEMORY.md", "text": "..." }]`. Claude Code: the files in `~/.claude/projects//memory/` and `CLAUDE.md`, the same way. Up to 200 files a call. - Whole chat history: the items of `conversations.json` from a ChatGPT or Claude data export, as `conversations`, up to 200 a call. They become conversation memories that `memory.answer` reads by exchange. People can also do this themselves: https://hivemindos.app/chat → Brain → Bring in memories opens the export .zip in their browser. - `preview: true` is free and answers what was found, what is new, the room left and `estimatedCredits`. Then send the same input without it; each call saves up to 40 and answers `nextCursor` until `done` is true. A fact already in memory is skipped, so the same import can be sent again safely. Every imported memory is tagged `imported` and its source (`chatgpt`, `claude`, `hermes`, ...). - An agent that can run commands: `node setup.mjs import-memory` finds Hermes's and Claude Code's memory by itself (`--file ` for anything else, `--preview` to only look). Cloud Superbrain provides hosted create, search, recall, cited answers, evolution history, review, graph, and export operations. Query its live capabilities instead of assuming one generic memory route. Keep stable facts and decisions separate from high-volume operational events. When only the first few results will be read, call `memory.recall` with `rerank: true`: the best 20 are read again against the question and the most relevant come first (same price, about a second longer; the response says `reranked`). Managed database access uses `databases:read` and `databases:write` plus access to `hivemind-database`. Destructive and migration actions require the exact confirmation strings published in OpenAPI. Do not fabricate confirmations or silently delete or move data. ## Wallets, trading, and approvals Agent Credits pay for managed API work. Assets held in a managed wallet are separate and pay transfer amounts, trades, and network fees. Use quotes, wallet policy, recipient and asset allowlists, and separate approvals. Never treat an Agent Credit balance as a wallet asset balance. ### Swaps (`universal-swaps`) Any token to any other, on one chain or across chains, with the platform fee inside the route. - From a HivemindOS wallet: `POST /v1/swaps/quote`, then `POST /v1/swaps` with the quote id (and its approval when the wallet's policy asks for one). Name `from` and `to` (`base:usdc`, `solana:sol`, or a contract or mint address) and either `amount` to spend or `amountOut` to receive exactly. Or describe it in `request`: "swap 50 USDC on Base to SOL", "i need 0.8 sol", "move 20 usdc from solana to base". A request that names nothing to pay with pays from what the wallet holds, dollars first. The quote returns `interpretation`; nothing is spent until you execute it. - From your own wallet: `POST /v1/swaps/prepare` with `sender` (the address that signs) and, when it arrives on the other kind of chain, `recipient`. It returns `transactions` to sign and send in order: EVM calls, or a base64 Solana transaction. Every transaction is checked before it's returned. No Agent Credits are charged. Follow a cross-chain fill with `GET /v1/swaps/routes/{routeId}`. - `GET /v1/swaps/tokens` lists the chains and the official token contracts a symbol resolves to. ## Onchain data (`onchain-intelligence`) Token, wallet, perp and exchange reads on Ethereum, Base, Solana and other major chains, each one call answered in seconds. Robinhood Chain is not covered: use Token Autopsy or Wallet Risk there. - `tokens.brief`: money flows, recent buyers and sellers and price history for one token (`chain` and `tokenAddress`); its DEX trades too with `includeTrades`. Find a contract with `GET /v1/swaps/tokens`, or Token Autopsy's `tokens.detectNetwork` when you do not know its chain. - `tokens.transfers`: its largest recent transfers, including moves into and out of exchanges. `tokens.flows`: how much flowed into and out of exchanges, whales, public figures or the top 100 holders over time (`label`, exchanges by default). - `tokens.discover`: newly launched tokens on a chain. `markets.scout`: what is trending, tokens and perp markets together. - `wallets.brief`, `wallets.defiPositions`, `wallets.related`: a wallet's balances, DeFi positions, profit and loss, counterparties and linked wallets (`address`; `chain` defaults to ethereum for a 0x address and solana for a Solana one). `wallets.tokenPnl`: its profit and loss token by token. - `perps.brief`: Hyperliquid positions and trades for a wallet (`address`) or a coin (`tokenSymbol`). `exchanges.flows`: an exchange's reserves and flows (`entityName`, such as Coinbase). - `predictionMarkets.search`: prediction markets about a topic (`query`), or the busiest, with their odds, volume, liquidity and end date. `predictionMarkets.market`: one market's odds history, order book and trades (`marketId` from the search; its largest positions with `includeHolders`). `predictionMarkets.wallet`: a wallet's prediction-market record. Every read also takes plain words: `{ "request": "exchange flows of 0x… on base" }`, and a request that is missing something is refused, free, with the one thing to add. Results come back as `cards` (title, summary, metrics, observations). Show `attribution.text` beside any card marked `attributionRequired`. Each read has a fixed price at `GET /v1/pricing?service=onchain-intelligence`; the call's `chargedCredits` is what was taken, and a read that returns nothing is not charged. `GET /v1/capabilities/onchain-intelligence` lists every read with an example input. Copy Trading adds Wallet Scout: `walletScout.roll` finds a wallet worth copying, and `walletScout.tokenScan` finds the wallets trading one Base token best (both need a wallet linked to the account; token scans need staked HIVE). ## Completion checklist Before reporting setup complete, verify all of the following: - The real project loads `HIVEMINDOS_API_KEY` from private runtime configuration. - No secret appears in source, diffs, logs, test snapshots, shell history output, or documentation. - The key has only the required scopes, services, operations, project, and endpoint limits. - A configured MCP session authenticates, lists four tools, and exposes only the intended actions. - Live balance, service discovery, and needed capability calls succeed through the same code path the application will use. - A denied capability is denied when practical to test, proving the boundary is active. - Mutations use stable idempotency keys and payment retries preserve the original key. - Any x402 payment was separately confirmed by the user, settled once, returned a receipt, and increased the same account's Agent Credit balance by the reported amount. - Tests and typechecks pass, and remaining unverified items are named plainly. Report the files changed, commands run, live checks performed, permissions granted, and anything the user still must supply. Never include credential values in the report.