Agent-native accounts

An AI agent can open its own Bruce account, with no website, phone or human login, and use it the way a signed-in person does: set a profile, share pay details, request and collect money, and send payments. The wallet is owned by a key that only the agent holds.

Non-custodial At signup the agent generates a P-256 key pair and sends Bruce only the public key. Bruce creates a Base USDC wallet owned by that key. Every on-chain action needs a signature from the agent, and Bruce cannot move the funds.

If you want an agent to spend from your balance under caps instead, use delegated agent keys. Agent-native accounts are separate accounts that belong to the agent.

Delegated agent keyAgent-native account
Whose moneyYour balanceThe agent's own wallet
Credentialbk_agent_live_… API key you createP-256 key the agent generates
SignupYou create it under AgentsThe agent signs up alone, or with you as its owner
Best forAssistants spending on your behalfAgents that earn, hold and pay as themselves
MCPHosted: https://mcp.bruce.money/mcpREST API (/api/agent-auth/*) or local MCP (@bruce/agent-mcp)

1. Sign up

Both paths start with a proof-of-work puzzle: GET /api/agent-auth/pow returns { token, bits }. Find a nonce where sha256("<token>:<nonce>") starts with at least bits zero bits. At the default of 20 bits this takes about a second. Each puzzle works once, and signups are rate-limited per IP.

Self-signup

POST /api/agent-auth/register with { publicKey, pow: { token, nonce }, displayName?, username? }. publicKey is the base64 SPKI of the P-256 key. Optional username must be 4–20 characters (a-z, 0-9, _); invalid values return usernameError in the response instead of failing silently. The response includes userId and walletAddress. The account starts unverified, with the unverified limits.

Signup with an owner

The agent names a person who will own it. That person approves once in the Bruce app, and the agent is live with their limits and their verification.

  1. Sign this exact text with the agent key, to prove the agent holds it:
    Bruce agent onboard
    owner:<owner username, lowercase, no @>
    pow:<pow token>
  2. POST /api/agent-auth/onboard with { publicKey, pow, ownerHandle, signature, displayName?, username?, limits?: { maxPaymentUsdc, dailyUsdc } }. It returns 202 with requestId. The owner gets a notification.
  3. Poll GET /api/agent-auth/onboard/:requestId every few seconds. The status moves from pending to approved, declined or expired (after 30 minutes).
  4. Once approved, log in. The owner chose the final limits and approved with their PIN or passkey.

If the key already has an account, the same request links that account to the owner instead of creating a new one.

2. Log in

  1. POST /api/agent-auth/challenge with { publicKey } returns { challengeId, message }. The challenge is valid for 5 minutes.
  2. Sign the UTF-8 message using ECDSA P-256 with SHA-256. Send the signature as base64 DER or raw r||s.
  3. POST /api/agent-auth/session with { challengeId, signature } returns { accessToken: "bas_…", expiresAt }.

Send Authorization: Bearer bas_… on every /api/* call. Sessions last one hour by default. To get a new one, log in again. POST /api/agent-auth/session/revoke ends a session.

3. Sign money movements

Every on-chain action uses the same three steps:

  1. Call the …/prepare endpoint. It returns payloadBase64 and requestExpiry.
  2. Base64-decode the payload and sign the bytes with the agent key (ECDSA P-256 / SHA-256, DER, low-S).
  3. Call the submit endpoint with the same body plus authorizationSignature and requestExpiry. Gas is sponsored.
ActionPrepareSubmit
Send USDC (handle or address)POST /api/transactions/send/preparePOST /api/transactions/send
Escrow actionsPOST /api/escrows/:id/relay/preparePOST /api/escrows/:id/relay (add autoConfirm: true)
Scheduled paymentsPOST /api/scheduled-payments/:id/relay/preparePOST /api/scheduled-payments/:id/relay (add autoConfirm: true)
Batch payouts (per chunk)POST /api/batch-payments/:id/preparePOST /api/batch-payments/:id/confirm with itemIds
Approved org sendPOST /api/organizations/:id/approvals/:approvalId/preparePOST …/execute

If an agent submits without a signature, it gets 400 with code: "signature_required" and a hint that names the prepare endpoint.

With autoConfirm, Bruce records the state change (for example a confirmed deposit or a release) in the same call. The response includes it under confirm.

Safe retries

Send an Idempotency-Key header (a UUID works) on any submit call above and on POST /api/agent-approvals. If the network drops and you retry with the same key, Bruce returns the first response with Idempotent-Replayed: true, so the payment goes out once. Retries re-run prepare, so the signature fields can change; the rest of the body must match, or you get 409 idempotency_conflict. Keys last 24 hours. A 5xx response is not stored, so retrying after one runs the request again.

Owners

An owner is the person responsible for an agent. Each agent has at most one. The owner:

Owners manage their agents in the Bruce app under Settings → AI agents → Agent accounts (bruce.money/agents/accounts). Raising trust (approving a link, unfreezing, changing limits, approving a payment) needs the owner's PIN or passkey. Freezing needs neither.

Linking an existing agent

Either side can propose; the other side confirms.

StepAgent sessionOwner (app)
ProposePOST /api/agent-links with { handle: "<owner>" }Enters the agent's username
AcceptPOST /api/agent-links/:id/confirmApproves with PIN or passkey
DeclinePOST /api/agent-links/:id/declineDeclines
EndPOST /api/agent-links/:id/unlinkUnlinks

GET /api/agent-links returns the agent's current link and its approvals. GET /api/agent-links/:id/activity returns the activity feed the owner sees, newest first (page with ?before=).

Verified agents

An agent with an active link to an owner who has completed identity verification is a verified agent. Its public profile shows the label, and names the owner if the owner allows it. GET /api/users/:id/profile returns profileType: "agent" and agent: { verified, owner }. An agent without a verified owner shows as an unverified agent.

Owner approvals

When a payment is above the limits, ask the owner instead of failing:

  1. POST /api/agent-approvals with { to, amount, memo?, reason? }. The owner gets a notification. Requests expire after 24 hours.
  2. Poll GET /api/agent-approvals/:id until the status leaves pending.
  3. Once approved, send the same payment again. Bruce applies the approval automatically.

The owner chooses how much to allow:

POST /api/agent-approvals/:id/cancel withdraws a pending request. The SDK's payWithApproval runs the whole loop for you.

Freeze

A frozen agent can still read its account, but every write returns 403 with code: "agent_frozen". That covers payments, profile changes and new requests. Only the owner can unfreeze it.

What agents can do

Everything on the logged-in API works the same way for agents, including:

Paying a request or a link is a signed send with paymentRequestId or paymentLinkId, followed by PATCH …/pay with the txHash.

Verified payments and withdrawals still need KYC or KYB, the same as for people.

These endpoints need a person and return 403 with not_available_for_agent_accounts:

Availability

Agent signup runs on the production API at https://api.bruce.money. Bruce can switch it off with the AGENT_ACCOUNTS_ENABLED flag. While it is off, every /api/agent-auth/* call and every bas_ session returns 403 with code: "agent_accounts_disabled", so check for that code before retrying.

Limits

Errors and recovery

Every agent-account error has a stable code and a recovery field that says what to do next, so an agent can recover without a human.

CodeWhat to do
agent_accounts_disabledSignup is switched off. Retry later.
pow_expired, pow_reused, pow_unsolvedFetch a fresh puzzle and solve it again.
key_registeredThe key already has an account. Log in.
signature_invalidSign the exact message with the registered key.
owner_not_found, owner_not_eligibleUse a person's Bruce username. Agents cannot own agents.
agent_already_linkedUnlink the current owner first.
agent_payment_cap_exceeded, agent_daily_cap_exceededAsk the owner with POST /api/agent-approvals, or get verified.
owner_link_requiredApprovals need an active owner. Link one first.
agent_frozenReads still work. Ask the owner to unfreeze.
sponsor_quota_exceededHold 5 USDC or get verified to lift the gas cap.
idempotency_conflictUse a new key for a different request.
rate_limitedWait for Retry-After.

Sandbox

Bruce runs on Base mainnet only, so there is no testnet faucet: POST /api/sandbox/faucet answers 404 sandbox_unavailable. Test with a small amount of real USDC, and keep owner caps low while you build.

Discovery

GET https://api.bruce.money/.well-known/agent.json describes both account types in one machine-readable card: signup steps, login, signing, limits, owner and approval endpoints, the sandbox, error codes, and the SDK. llms.txt has the same in prose.

Tools

You can call the REST endpoints above directly from any runtime with WebCrypto, connect a delegated key to the hosted MCP server (https://mcp.bruce.money/mcp), or use the TypeScript SDK and local MCP server which wrap owner signup, approvals, and safe retries.