# Configure the HivemindOS SuperAgent API > Paste this file into an agent. The agent should configure the current project to use the HivemindOS managed backend, choose the smallest permissions that satisfy the project, keep credentials private, and prove the integration with live read-only checks. It must ask before signing or sending any payment. You are the setup agent. Complete the setup in the user's current project. Do not stop at a plan when safe configuration and tests remain. Do not manage the user's desktop sessions; this API calls HivemindOS cloud services. ## 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. - [Remote MCP guide](https://liamvisionary.github.io/hivemindos/for-users/platform-api/mcp.html): Connect an agent directly and understand the four stable tools. - [Quickstart](https://liamvisionary.github.io/hivemindos/for-users/platform-api.html): Simple product overview and first call. - [Agent setup guide](https://liamvisionary.github.io/hivemindos/for-users/platform-api/agent-setup.html): Human-readable version of this setup flow. - [Complete API reference](https://liamvisionary.github.io/hivemindos/for-users/platform-api/reference.html): Exact headers and endpoint table. - [Authentication](https://liamvisionary.github.io/hivemindos/for-users/platform-api/authentication.html): Key creation, delegation, and revocation. - [Endpoint limits](https://liamvisionary.github.io/hivemindos/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`, `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. Update an ignored local env file only when that is already the project's convention. 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 top-up 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 31 service ids: `hive-research`, `swarm`, `x-studio`, `distill`, `x-api`, `x-transcript`, `reddit-voc`, `media-studio`, `photo-keyworder`, `app-hosting`, `hive-compute`, `gpu-rentals`, `managed-bookings`, `managed-socials`, `hivemind-analytics`, `hivemind-database`, `token-autopsy`, `wallet-risk`, `copy-trading`, `hive-bridge`, `outbound-email`, `integration-broker`, `testnet-faucet`, `miroshark`, `managed-models`, `cloud-superbrain`, `leadgen-data`, `managed-wallets`, `managed-trading`, `managed-agents`, and `managed-workflows`. Service availability and capability lists are live data. Do not assume every service is available for every account or region. Use `GET /services?probe=true` when setup needs a current availability check. 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. ## Step 1: inspect the project Determine the language, package manager, existing HTTP or OpenAPI client, secret-storage convention, test runner, and deployment environment. Reuse the project's established patterns. For TypeScript or JavaScript, prefer the public SDK: ```bash npm install @hivemindos/sdk ``` For another language, generate or write a client from the live OpenAPI document. Do not invent endpoints from this prompt. ## Step 2: obtain an API key safely First check whether `HIVEMINDOS_API_KEY` is already available without displaying its value. If it is present, continue to Step 3. If it is absent and `HIVEMINDOS_CREDIT_TOKEN` is available, create the first scoped key once: ```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 } } } ``` Add only the scopes, services, and operations the project actually needs. Save the returned `hmos_live_...` secret immediately in the project's secret manager as `HIVEMINDOS_API_KEY`; the complete secret is returned only at creation. Do not retain the credit token in the application runtime after bootstrap unless that runtime must create other root keys. If neither credential exists, tell the user that a HivemindOS account credential is required and ask them to add it directly to their secret manager. Do not ask them to paste a secret into chat or source code. ## 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. 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. The MCP exposes exactly four 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. ## Step 4: add the client TypeScript example: ```ts import { HivemindOSClient } from "@hivemindos/sdk"; export const hive = new HivemindOSClient({ apiKey: process.env.HIVEMINDOS_API_KEY!, projectId: process.env.HIVEMINDOS_PROJECT_ID, }); ``` 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. ## 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 Use a typed capability whenever possible: ```ts const result = await hive.services.invokeOperation( "hive-research", "analyses.create", { question: "Summarize the strongest evidence for this thesis." }, { idempotencyKey: crypto.randomUUID() }, ); 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. ## 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"; import { HivemindOSClient } from "@hivemindos/sdk"; const payer = privateKeyToAccount( process.env.X402_PAYER_PRIVATE_KEY as `0x${string}`, ); const paidFetch = wrapFetchWithPaymentFromConfig(fetch, { schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(payer) }], }); const hive = new HivemindOSClient({ apiKey: process.env.HIVEMINDOS_API_KEY!, fetch: paidFetch, }); // Ask the user to confirm the exact amount before this call. const topUp = await hive.credits.topUp( { amountUsd: 5 }, { idempotencyKey: "top-up-2026-08-27-001" }, ); 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. ## Managed memory and databases 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. 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. ## 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.