--- 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, 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://liamvisionary.github.io/hivemindos/for-users/platform-api/mcp.html) for direct agent connection and tool behavior. - [Agent setup](https://hivemindos.app/superagent-api/llms.txt) for the complete bootstrap and x402 quick start. - [Developer guide](https://liamvisionary.github.io/hivemindos/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 the first key must be created, use `HIVEMINDOS_CREDIT_TOKEN` 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. Create a key only when needed and authorized. 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 `@hivemindos/sdk` for TypeScript or JavaScript when it fits the project. Otherwise use HTTPS or generate a client from OpenAPI. 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. ## 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 four stable 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. ## 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.