Set up the SuperAgent API with your agent

Your agent can set up the SuperAgent API in your project for you. You never copy a key: you open one link, sign in, add credits and approve, and the agent collects the key and saves it where your project keeps secrets.

Set it up in three steps

1. On hivemindos.app/superagent-api, press Copy in “Set it up with your agent”.
2. Paste it into the agent working in your project: Claude Code, Codex, Cursor, Hermes or any agent that can run commands.
3. Send it.

The agent gives you a link and a short code. Open the link, check the code matches, then:

• Sign in or make an account with your email. One code does both, and the account works on any device. A passkey works too, or you can continue without an email and add one later.
• Add credits by card or crypto, from $5, or choose Later.
• Approve. The page then says the account is ready, and switches to “your agent has your key” as soon as the agent collects it.

The agent saves the key as HIVEMINDOS_API_KEY in your project’s .env.local or .env, makes sure git ignores that file, checks the key works, and tells you how many credits the account has.

If your agent can’t run commands

Chat apps such as ChatGPT and Claude on the web can’t collect the key themselves. You have two options:

• On the setup link, after approving, open Using a chat that can’t save files? and press Show my key. The page shows the key and the exact line to add to your .env file.
• Or make a key yourself in the console.

What the agent does

The setup message points the agent at hivemindos.app/superagent-api/llms.txt. With Node.js 18 or newer it runs a small setup script with no dependencies, setup.mjs, which does every step below and never prints the key. If the agent’s command times out, running it again continues the same setup.

Without Node, the agent uses the API directly:

1. POST https://api.hivemindos.app/v1/setup-sessions with a label and its name. No key is needed. The response has the link for you (setupUrl), the code (confirmCode) and a claimToken the agent keeps secret. Use /v1/private/setup-sessions to pin the key to the private tier.
2. It shows you the link and the code.
3. It calls POST https://api.hivemindos.app/v1/setup-sessions/claim with Authorization: Bearer <claimToken> every 5 seconds. The answer is 202 until you approve, then 200 with the key. If that reply is lost, the same claim token gets the same key again for 10 minutes.
4. It saves the key and checks it with GET /v1/services and GET /v1/credits/balance.

A setup link lasts 60 minutes and can be approved once. The key it makes can use every service but can never move funds: it can’t sign, send or trade from a wallet, approve actions, or manage other keys. Those stay with you.

Let the agent pay

An agent that holds an x402 wallet on Base can pay for the account itself, after you approve the exact amount. It calls POST /v1/setup-sessions/fund with its claim token and an Idempotency-Key, answers the payment challenge, and gets the key straight away. You then open the same link to take over the account the agent paid for and add your email to keep it.

Keep it as a reusable skill

If your agent supports skills, download hivemindos.app/superagent-api/SKILL.md and install it using that agent’s normal skill folder or skill manager. Use the skill when you want the agent to keep managing access, endpoint limits, MCP, capabilities, Agent Credits, tests, and audits for the project.

Connect without writing a client

If the agent supports remote MCP servers, it can connect directly to https://api.hivemindos.app/mcp. Use the same restricted key in a protected Authorization header. The key must include services:read, actions.list, and only the exact additional access needed for the agent’s job.

See Connect an agent with MCP for the ready-to-copy configuration and tool behavior.

Manage keys, usage and billing

The console shows your balance, keys, usage, request history, limits, projects and privacy tiers. Make or revoke keys there, and add credits to the one balance every service draws on.

The key belongs on your server. Never put it in code that runs in a browser or a mobile app.

What the agent should finish

The setup is complete when:

• your application loads its key from private runtime settings;
• the key can reach only the services and actions you chose;
• endpoint request and concurrency limits are active;
• live balance, service, and capability checks pass through your application’s real client path;
• a deliberately disallowed capability is denied when practical to test;
• mutations use idempotency keys; and
• no secret appears in the project diff, logs, tests, or documentation.

Paying for more Agent Credits

If you want the integration to buy Agent Credits directly, give its key the credits:write scope and the credits.x402.topUp operation. The agent can add an x402-aware client that pays Base payment challenges and credits the same HivemindOS account.

The agent must ask you to confirm the exact dollar amount before it signs or sends the payment. Top-ups may be $5 to $500. HivemindOS fixes and verifies the official revenue wallet, payment network, asset, amount, and credited account, so the integration cannot redirect the payment.

The first request receives an HTTP 402 payment challenge. The wallet client signs it and retries with the same Idempotency-Key. Success returns a receipt and the updated Agent Credit balance.

Review advanced details

Use the authentication guide to review key delegation, the endpoint limits guide to review per-operation ceilings, and the API reference for the exact x402 headers and response fields.

The live OpenAPI document remains the source of truth for generated clients and request validation.