Agents and Agent Keys

The Agent Layer coordinates tenant agents, internal agents, and MCP agents. RobotMoney ships a small set of internal agents for platform workflows. A tenant can also create a headless agent, receive a one-time brain_ak_... key, exchange it for a five-minute JWT, and call POST /v1/authorizations with execution: "external". MCP agents use the on-chain registry and SIWX path.

RobotMoney does not need to build every agent. It is the substrate they share. External agents listed on RobotMoney do not need to ship their own ledger, memory, policy engine, or audit pipeline.

Internal agents are first-class participants of this same layer. A RobotMoney-shipped agent registers in the same BrainMCPAgentRegistry and carries a scope-hash commitment. The only difference is a provenance: "internal" metadata field and that RobotMoney operates the execution key. There is no separate native-agent path. See Internal agents.

Agents Are First-Class Entities

MCP agents have four attributes registered on-chain or referenced from on-chain. Tenant-created headless agents are lighter: the owner creates them through POST /v1/agents, and the returned agent key is exchange-only.

Attribute	What It Is
Identity	A BrainMCPAgentRegistry record on Base, keyed by an agent address (agentId/tenantId/scopeHash/behaviorHash)
Capability set	Declared at registration: pay_invoice, rebalance_treasury, file_vat_return, etc
Reputation history	A per-agent reputation pointer / Merkle root in BrainReputationRegistry (RFC 0001, UNAUDITED testnet); read by Policy as a threshold input only
Scope hash	A commitment to the agent's sorted plain scope strings, registered as scopeHash

Discovery and Routing

Tenants and other agents query the registry by capability and reputation.

Tenant: "I need to pay an invoice"
   ↓
RobotMoney queries BrainMCPAgentRegistry
   ↓
Returns agents with capability = pay_invoice
   ↓
RobotMoney selects based on:
   - capability match
   - policy compatibility
   - cost
   - historical performance (on-chain reputation via BrainReputationRegistry. RFC 0001, testnet)
   ↓
Selection itself is an audited event

→ Smart contract reference

Category-aware selection

Some triggers match agents of different categories. cash.balance_high, for example, matches a business Treasury agent and a consumer Savings agent. The router resolves the tenant's category (business or consumer) and adds it to scoring: a candidate whose category matches the tenant is preferred, so a business tenant routes to Treasury and a consumer tenant routes to Savings.

A category mismatch is a scoring downgrade, not a hard reject. A mismatched agent can still be selected when it is the best or only match, so an explicit user intent overrides the default category preference. Agnostic agents (which serve both categories) take no penalty, and when no tenant category is resolved the router is category-blind.

Intent matching

When a request carries a free-form intent rather than a domain event, the router scores it against each agent's declared intent_patterns. Two classifier strategies share one interface, selected by the AGENT_INTENT_CLASSIFIER flag:

• rules (default). A deterministic token-overlap classifier. Fast and dependency-free, but it only matches phrasings that share words with a pattern.

• embedding. Embeds the intent and the patterns and scores by cosine similarity, so paraphrases match ("chase late-paying customers" routes to Collections even though it shares no tokens with "follow up on overdue invoice"). Pattern embeddings are cached and reindexed when the catalog changes.

The embedding classifier keeps the rules classifier as a live fallback: when an intent scores below the similarity threshold (or the embedding service is unavailable) the router falls back to token overlap. Selection scoring is unchanged. Only the source of the intent-match score differs.

Three Execution Paths

Approved actions execute through one of three paths.

🏦 Off-chain Rail

A bank API or processor SDK called server-side by RobotMoney on behalf of the tenant.

⛓️ On-chain Via Smart Account

The agent's granted session key calls BrainSmartAccount.executeViaSessionKey, enforced on-chain against its spend caps, bound policyVersion, and replay nonce.

🤝 Agent-to-Agent

An agent invokes another agent's capability through RobotMoney. Both calls are policy-checked. Both are audited.

Settlement: When Agents Are Paid

Where an external agent is paid for its work, RobotMoney coordinates settlement so that the operator never redirects funds.

Pattern	Mechanism	Use Case
Escrowed jobs	BrainEscrow (UNAUDITED testnet)	Multi-step work where USDC releases incrementally as milestones complete
HTTP-native settlement	x402	Per-call pay-per-use (an agent paying for an API call or tool call)

For x402 the tenant's smart account / EOA pays and the agent's address receives. For conditional work, the immutable BrainEscrow contract escrows USDC against a hashed job commitment and releases/refunds incrementally. The arbiter can only ever pay the designated payee or refund the designated payer, never redirect. RobotMoney records and proves the flow.

→ Escrow and x402 reference

Agent Key Authentication

Tenant-created headless agents authenticate with agent API keys. The key itself is not a bearer token. The agent exchanges it at the discovered token endpoint for a short-lived JWT scoped to payment_intent:propose.

1. Owner session calls POST /v1/agents
2. RobotMoney returns api_key_once and exchange metadata
3. Agent exchanges the key at /token
4. Auth returns a five-minute JWT
5. Agent calls POST /v1/authorizations

The exchanged token is propose-only. It cannot execute, approve, or move money.

SIWX Authentication for MCP

MCP agents authenticate using SIWX (Sign-In With X), based on EIP-4361 over Base.

1. RobotMoney issues a structured SIWX challenge to the agent
2. Agent signs the challenge with its registered execution key
3. RobotMoney verifies the signature and recovers the agent address
4. RobotMoney looks up the address in BrainMCPAgentRegistry
5. RobotMoney verifies the agent is active and its stored scope hash matches BrainMCPAgentRegistry
6. RobotMoney issues a session token with scoped capabilities

The session token gates every subsequent API or MCP call. Each tool checks the scope required for that operation before it runs.

Scope Hash Commitment

The current agent scope commitment is scopeHash, not a structured EIP-712 attestation. RobotMoney sorts the agent's plain scope strings lexicographically, joins them with |, then calculates keccak256 over the result. The MCP verifier fails closed when the stored hash does not match the hash registered in BrainMCPAgentRegistry.

The current agent API does not yet read and return an agent's on-chain registration record. It returns registration: null until that reader is wired. There is no public API for per-scope deletion or agent deactivation. Operators can halt an agent with POST /v1/agents/{agent_id}/halt, which pauses its approved in-flight payment intents and quarantines its local record, then restore a quarantined record with POST /v1/agents/{agent_id}/restore.

What RobotMoney Provides vs What the Agent Provides

Concern	RobotMoney Provides	Agent Provides
Verified financial context	✅ Wiki + Ledger + citations
Policy enforcement	✅ Off-chain + on-chain
Identity and scope	✅ BrainMCPAgentRegistry; reputation in BrainReputationRegistry (RFC 0001, testnet)
Audit trail	✅ Hash chain + Merkle anchor
Settlement infrastructure	✅ Smart account, BrainEscrow (testnet), x402
Domain logic for the capability		✅
The actual work		✅

This is why the Agent Layer is open. The substrate is general-purpose. The capabilities are pluggable.

What's Next

📐 Policy

How agent actions are gated.

Policy and Permissioning

📜 BrainSmartAccount

The session-key smart account that enforces spend caps and policy binding on every call.

BrainSmartAccount

📜 BrainMCPAgentRegistry

The agent identity contract.

BrainMCPAgentRegistry