Agent account SDK & local MCP
Agents can use Bruce today over the REST API or the hosted MCP server. For agents that hold a local P-256 key on your machine, the @bruce/agent-sdk package and @bruce/agent-mcp stdio server wrap key generation, signup, session refresh, and local payment signing.
@bruce/agent-sdk or @bruce/agent-mcp is not yet available from your npm registry mirror, use the zero-install REST quickstart (Node 20+ built-in WebCrypto) or the hosted MCP config below, or build the packages directly from the monorepo (npm run build --workspace=@bruce/agent-sdk --workspace=@bruce/agent-mcp).
Hosted MCP (one-line config, no install)
For delegated agent spend or merchant tools with no local package install, point any MCP client at https://mcp.bruce.money/mcp:
{
"mcpServers": {
"bruce": {
"url": "https://mcp.bruce.money/mcp",
"headers": { "Authorization": "Bearer bk_agent_live_…" }
}
}
}
REST quickstart (zero dependencies, Node 20+)
Every SDK method maps 1:1 to a documented REST endpoint in openapi-v1.json, including payment requests (POST /api/payment-requests) and signed sends (POST /api/transactions/send/prepare → POST /api/transactions/send):
import { createHash, subtle } from "node:crypto";
const API = "https://api.bruce.money";
// 1. Generate P-256 keypair & solve proof-of-work
const kp = await subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]);
const publicKey = Buffer.from(await subtle.exportKey("spki", kp.publicKey)).toString("base64");
const pow = await fetch(`${API}/api/agent-auth/pow`).then((r) => r.json());
let nonce = 0;
while (true) {
const digest = createHash("sha256").update(`${pow.token}:${nonce}`).digest();
let zeros = 0;
for (const b of digest) {
if (b === 0) { zeros += 8; continue; }
zeros += Math.clz32(b) - 24;
break;
}
if (zeros >= pow.bits) break;
nonce++;
}
// 2. Register & open a bas_ session
await fetch(`${API}/api/agent-auth/register`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ publicKey, pow: { token: pow.token, nonce: String(nonce) }, displayName: "Research agent" }),
});
const { challengeId, message } = await fetch(`${API}/api/agent-auth/challenge`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ publicKey }),
}).then((r) => r.json());
const sig = Buffer.from(
await subtle.sign({ name: "ECDSA", hash: "SHA-256" }, kp.privateKey, new TextEncoder().encode(message)),
).toString("base64");
const { accessToken } = await fetch(`${API}/api/agent-auth/session`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ challengeId, signature: sig }),
}).then((r) => r.json());
// 3. Check balance or create a payment request (amounts in USD/USDC)
const headers = { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" };
const balance = await fetch(`${API}/api/me/balance`, { headers }).then((r) => r.json());
await fetch(`${API}/api/payment-requests`, {
method: "POST",
headers,
body: JSON.stringify({ recipientUserId: "USER_UUID", amount: "12.00", memo: "Report" }),
});
TypeScript SDK
The SDK has no dependencies and uses WebCrypto. It runs on Node 20 and later, Deno, Bun, Workers and browsers.
import { BruceAgent } from "@bruce/agent-sdk";
// One time: creates the key and the account. Store `key` somewhere secret.
const { agent, key, account } = await BruceAgent.createAccount({
displayName: "Research agent",
username: "research_agent",
});
// Later: rebuild the client from the stored key.
const bruce = new BruceAgent({ key });
await bruce.balance();
await bruce.pay({ to: "alice", amount: "5.00", memo: "API credits" });
const details = await bruce.payDetails.share({ amount: "20" }); // handle, payUrl, wallet
await bruce.requests.create({ recipientUserId, amount: "12.00", memo: "Report" });
await bruce.paymentLinks.create({ amount: "9.99", memo: "Dataset" });
await bruce.escrow.relay(escrowId, "deposit"); // signed and auto-confirmed
await bruce.batch.send((await bruce.batch.create(rows)).batch.id);
// Any other prepare/submit pair:
await bruce.signedCall("/api/escrows/ID/relay/prepare", "/api/escrows/ID/relay", { action: "release" });
// Any other route:
await bruce.request("GET", "/api/notifications");
The SDK logs in again automatically before a session expires. Pass onSession to cache sessions, and orgId to act inside an organization.
With an owner
// Signup that a person approves in the Bruce app (they set the limits).
const { agent, key, request } = await BruceAgent.onboard({ owner: "alice", displayName: "Research agent" });
const result = await agent.waitForOnboarding(request.requestId); // approved | declined | expired
// Above a limit: asks the owner, waits, then pays.
await agent.payWithApproval({ to: "hosting_co", amount: "120.00", reason: "Monthly GPU hosting" });
// Safe retries: the same key never pays twice.
await agent.pay({ to: "alice", amount: "5.00", idempotencyKey: crypto.randomUUID() });
Also available: owner.link, owner.status, owner.confirm, owner.unlink, owner.activity, and approvals.request / get / wait / list / cancel. Errors carry code and a recovery hint.
Local MCP server
The hosted Bruce MCP spends a person's balance through delegated keys. The local server is different: it gives the agent its own account. The key is stored in ~/.bruce/agent.json with owner-only permissions and never leaves the machine.
{
"mcpServers": {
"bruce-agent": {
"command": "npx",
"args": ["-y", "@bruce/agent-mcp"],
"env": { "BRUCE_API_BASE": "https://api.bruce.money" }
}
}
}
The package installs two equivalent binaries, agent-mcp and bruce-agent-mcp, so a global install (npm i -g @bruce/agent-mcp) can use either name as the command.
Tools:
- Account:
bruce_create_account,bruce_onboard(signup with an owner),bruce_onboard_status,bruce_account_status,bruce_balance,bruce_update_profile,bruce_complete_setup - Owner:
bruce_owner,bruce_request_approval,bruce_approval_status - Getting paid:
bruce_share_pay_details,bruce_resolve_handle,bruce_request_money,bruce_payment_requests,bruce_create_payment_link - Paying:
bruce_pay,bruce_pay_request,bruce_pay_payment_link,bruce_pay_invoice - Invoices:
bruce_create_invoice,bruce_send_invoice - Escrow and scheduled payments:
bruce_create_escrow,bruce_escrow_action,bruce_schedule_payment,bruce_scheduled_action - Batches and organizations:
bruce_batch_pay,bruce_org_approvals,bruce_org_approval - History and contacts:
bruce_transactions,bruce_contacts - Escape hatches for anything else:
bruce_api_requestandbruce_signed_call
Environment variables:
BRUCE_API_BASE: which API to call (use staging for Base mainnet testing).BRUCE_AGENT_HOMEorBRUCE_AGENT_FILE: where the key is stored.BRUCE_ORG_ID: default organization context.
agent.json controls the wallet. If you lose the file, Bruce cannot recover the funds.