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.
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 key | Agent-native account | |
|---|---|---|
| Whose money | Your balance | The agent's own wallet |
| Credential | bk_agent_live_… API key you create | P-256 key the agent generates |
| Signup | You create it under Agents | The agent signs up alone, or with you as its owner |
| Best for | Assistants spending on your behalf | Agents that earn, hold and pay as themselves |
| MCP | Hosted: https://mcp.bruce.money/mcp | REST 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.
- 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> POST /api/agent-auth/onboardwith{ publicKey, pow, ownerHandle, signature, displayName?, username?, limits?: { maxPaymentUsdc, dailyUsdc } }. It returns202withrequestId. The owner gets a notification.- Poll
GET /api/agent-auth/onboard/:requestIdevery few seconds. The status moves frompendingtoapproved,declinedorexpired(after 30 minutes). - 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
POST /api/agent-auth/challengewith{ publicKey }returns{ challengeId, message }. The challenge is valid for 5 minutes.- Sign the UTF-8
messageusing ECDSA P-256 with SHA-256. Send the signature as base64 DER or raw r||s. POST /api/agent-auth/sessionwith{ 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:
- Call the
…/prepareendpoint. It returnspayloadBase64andrequestExpiry. - Base64-decode the payload and sign the bytes with the agent key (ECDSA P-256 / SHA-256, DER, low-S).
- Call the submit endpoint with the same body plus
authorizationSignatureandrequestExpiry. Gas is sponsored.
| Action | Prepare | Submit |
|---|---|---|
| Send USDC (handle or address) | POST /api/transactions/send/prepare | POST /api/transactions/send |
| Escrow actions | POST /api/escrows/:id/relay/prepare | POST /api/escrows/:id/relay (add autoConfirm: true) |
| Scheduled payments | POST /api/scheduled-payments/:id/relay/prepare | POST /api/scheduled-payments/:id/relay (add autoConfirm: true) |
| Batch payouts (per chunk) | POST /api/batch-payments/:id/prepare | POST /api/batch-payments/:id/confirm with itemIds |
| Approved org send | POST /api/organizations/:id/approvals/:approvalId/prepare | POST …/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:
- sets the agent's per-payment and daily limits,
- approves payments above those limits,
- sees everything the agent does in an activity feed,
- can freeze the agent instantly, and
- chooses whether the agent's public profile names them.
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.
| Step | Agent session | Owner (app) |
|---|---|---|
| Propose | POST /api/agent-links with { handle: "<owner>" } | Enters the agent's username |
| Accept | POST /api/agent-links/:id/confirm | Approves with PIN or passkey |
| Decline | POST /api/agent-links/:id/decline | Declines |
| End | POST /api/agent-links/:id/unlink | Unlinks |
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:
POST /api/agent-approvalswith{ to, amount, memo?, reason? }. The owner gets a notification. Requests expire after 24 hours.- Poll
GET /api/agent-approvals/:iduntil the status leavespending. - Once
approved, send the same payment again. Bruce applies the approval automatically.
The owner chooses how much to allow:
once: this one payment, to this recipient, up to this amount.cap: a budget for any payments until it is spent or expires (1 hour to 30 days).
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:
- Profile, username and onboarding (
/api/setup/completeneeds no phone for agents) - Balance, transactions and contacts
- Payment requests, payment links and invoices
- Escrow, scheduled payments, batch payouts, organizations and notifications
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:
- Admin
- Device and push registration
- Phone OTP
- PIN
- Creating delegated agent keys
- OAuth
- Accepting org invites
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
- Send caps: an unverified agent can send up to 25 USDC per payment and 100 USDC per UTC day through Bruce. This covers direct sends, each batch item, and escrow deposits. A verified owner lifts these caps; the owner's own limits then apply, if they set any. Over a cap you get
403withagent_payment_cap_exceededoragent_daily_cap_exceeded, pluslimitUsdc,remainingUsdcand arecoveryhint. An agent with an owner can then ask for approval. - Sponsored gas: 10 signed submits per day by default. The cap lifts once the account holds at least 5 USDC or is verified. Over the cap you get
429 sponsor_quota_exceeded. - Rate limit: every agent account has its own request limit.
- Audit: every state-changing request an agent makes is written to an audit log.
- Org approvals: an agent can approve sends requested by other agent accounts. A person must approve sends requested by people. When the requester is an agent, approval returns
approved_pending_signature, and the requester then signs with…/prepareand…/execute.
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.
| Code | What to do |
|---|---|
agent_accounts_disabled | Signup is switched off. Retry later. |
pow_expired, pow_reused, pow_unsolved | Fetch a fresh puzzle and solve it again. |
key_registered | The key already has an account. Log in. |
signature_invalid | Sign the exact message with the registered key. |
owner_not_found, owner_not_eligible | Use a person's Bruce username. Agents cannot own agents. |
agent_already_linked | Unlink the current owner first. |
agent_payment_cap_exceeded, agent_daily_cap_exceeded | Ask the owner with POST /api/agent-approvals, or get verified. |
owner_link_required | Approvals need an active owner. Link one first. |
agent_frozen | Reads still work. Ask the owner to unfreeze. |
sponsor_quota_exceeded | Hold 5 USDC or get verified to lift the gas cap. |
idempotency_conflict | Use a new key for a different request. |
rate_limited | Wait 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.