Wallets, approvals, and trading

Managed wallets let your app use a wallet address without receiving its private key or recovery phrase. Before money moves, HivemindOS checks the wallet policy, a short-lived quote, the API key’s permissions and limits, available Agent Credits, and any required approval.

Move to a main network only after policy, approval separation, retry safety, event handling, and recovery have been tested end to end.

Separate responsibilities

Use different API keys for proposing and approving asset movement:

Add managed-wallets or managed-trading to each key’s service allowlist as appropriate. A key that can execute an action should not also approve it.

Supported networks

• base
• base-sepolia
• ethereum
• ethereum-sepolia
• solana
• solana-devnet

Availability may vary. Read GET /services and current pricing before offering a network or paid action.

Create a managed wallet

const created = await hive.wallets.create(
  {
    name: "Testnet treasury",
    network: "base-sepolia",
    kind: "agent",
    policy: {
      enabled: true,
      allowedNetworks: ["base-sepolia"],
      allowedAssets: ["ETH"],
      allowedRecipients: ["0x1111111111111111111111111111111111111111"],
      allowedContracts: [],
      maxTransactionUsd: 25,
      maxDailyUsd: 100,
      requireApprovalAboveUsd: 5,
    },
  },
  { idempotencyKey: "testnet-treasury-v1" },
);

if (!created.ok) throw new Error(created.error);
console.log(created.wallet.id, created.wallet.address);

Wallet creation returns an address and policy, not a private key or recovery phrase. Use wallets.list, wallets.get, and wallets.balances for read operations.

The policy controls:

• whether actions are enabled;
• allowed networks, assets, recipients, and contracts;
• maximum value for one transaction;
• maximum daily transaction value; and
• the value above which a separate approval is required.

Updating a policy requires approvals:write, an idempotency key, and the exact wallet id. Treat policy administration as a reviewer responsibility.

Transfer flow

1. Request a quote

Amounts are positive atomic-unit integer strings. Do not use floating-point numbers for asset quantities.

const quoted = await worker.wallets.quoteTransaction(
  walletId,
  {
    kind: "send",
    network: "base-sepolia",
    asset: "ETH",
    amount: "1000000000000000",
    recipient: "0x1111111111111111111111111111111111111111",
  },
  { idempotencyKey: "invoice-1042-quote" },
);

if (!quoted.ok) throw new Error(quoted.error);

The quote contains maximumDebitCredits, an estimated network fee when available, expiresAt, approvalRequired, and an approvalId when review is required. Show the exact asset action, visible fee estimate, and maximum HivemindOS credit price to the reviewer.

2. Approve when required

if (quoted.quote.approvalRequired) {
  const reviewed = await reviewer.approvals.decide(
    quoted.quote.approvalId!,
    "approve",
    { idempotencyKey: "invoice-1042-approval" },
  );
  if (!reviewed.ok) throw new Error(reviewed.error);
}

Approval applies only to the exact quoted action and expires with the quote. A rejection cannot be executed.

3. Submit once

const submitted = await worker.wallets.submitTransaction(
  walletId,
  {
    quoteId: quoted.quote.id,
    approvalId: quoted.quote.approvalId ?? undefined,
  },
  { idempotencyKey: "invoice-1042-submit" },
);

if (!submitted.ok) throw new Error(submitted.error);

The same pattern supports kind: "swap" with fromAsset, toAsset, amount, and optional slippageBps. Quotes are short-lived and one-time. If a quote expires, request a new quote and present it for review again.

Message-signing flow

Message signatures always require a matching approval:

const quoted = await signer.wallets.quoteSignature(
  walletId,
  { message: "Sign in to Example at 2026-08-24T12:00:00Z" },
  { idempotencyKey: "example-sign-in-quote-001" },
);

if (!quoted.ok) throw new Error(quoted.error);

await reviewer.approvals.decide(
  quoted.approval.id,
  "approve",
  { idempotencyKey: "example-sign-in-approve-001" },
);

const signed = await signer.wallets.sign(
  walletId,
  { quoteId: quoted.quote.id, approvalId: quoted.approval.id },
  { idempotencyKey: "example-sign-in-execute-001" },
);

Show the reviewer the complete message. Never ask a user to approve an unread or partially hidden signing payload.

Spot-trading flow

Managed trading currently supports market spot orders. Markets use BASE_ASSET/QUOTE_ASSET, such as ETH/USDC.

const quoted = await trader.trading.quote(
  {
    walletId,
    market: "ETH/USDC",
    side: "buy",
    amount: "10000000",
    amountType: "quote",
    orderType: "market",
    slippageBps: 100,
  },
  { idempotencyKey: "rebalance-eth-usdc-quote-001" },
);

if (!quoted.ok) throw new Error(quoted.error);

if (quoted.quote.approvalRequired) {
  await reviewer.approvals.decide(
    quoted.quote.approvalId!,
    "approve",
    { idempotencyKey: "rebalance-eth-usdc-approve-001" },
  );
}

const order = await trader.trading.createOrder(
  {
    quoteId: quoted.quote.id,
    approvalId: quoted.quote.approvalId ?? undefined,
  },
  { idempotencyKey: "rebalance-eth-usdc-submit-001" },
);

Read positions with trading.positions(walletId). A submitted order may still be processing; use its status and signed events instead of treating request acceptance as a confirmed fill.

Copy-trading strategies remain a separate managed service. They do not turn a SuperAgent API spot order into a limit, recurring, leveraged, or copy-trading order.

Credit and asset boundaries

• HivemindOS credits pay for wallet creation, execution, signing, and managed trading work.
• Wallet assets pay the transfer or trade amount and its network fee.
• The server-owned pricing response defines the maximum HivemindOS credit charge.
• Wallet policy defines the permitted asset action.
• creditsPerDay can add a key-level daily ceiling to wallet creation, transaction execution, signature execution, and trading-order execution.

HTTP 402 means the HivemindOS account balance is too low for the managed API charge. It does not mean the wallet has enough assets for the transfer or trade. Check both balances separately and present the appropriate next action.

Next: set endpoint and daily credit limits, then verify signed events.