Build a private agent

Why agents need this most

An agent trading a public chain leaks its whole strategy: every position, size, and time is on the graph for anyone to copy or front-run. Agents run predictable, high-frequency strategies, so they are the easiest to reverse-engineer. Gloam gives an agent a private execution surface: hold, move, and prove value with size hidden, so its edge stays its own.

Two ways in

Both speak the same intent shape, so a plan an app builds and a plan an agent builds are the same object.

• Directly via @gloamtrade/sdk. Your agent framework builds an intent and signs it with its own wallet. Best when the agent already has an execution loop.
• Via the @gloamtrade/mcp server. An MCP-speaking model (Claude, etc.) gets Gloam as tools alongside its other capabilities, the same way Robinhood's own MCP exposes public trading. Best for a general assistant that should also act privately.

For Virtuals agents

Agents built on GAME get Gloam as one worker: @gloamtrade/game-plugin-gloam gives a Virtuals agent a private balance, private payments, cash outs and proofs of funds, under per-asset limits its owner sets. A companion provider pays out privately on ACP, so the job stays on ACP's contracts while who got paid, and how much, stays private.

Gloam for Virtuals agents covers setup, every function, the limits, exactly what stays public, and the networks.

Connect by URL

The quickest way to try Gloam from a chat. Gloam runs a hosted MCP server, so you add it to your client by URL and install nothing.

https://www.gloam.trade/mcp

• Claude (claude.ai and Claude Desktop): Settings, Connectors, Add custom connector, then paste the URL.
• ChatGPT: Settings, Apps and connectors. Turn on developer mode, then create a connector with the URL and no authentication.
• Claude Code: claude mcp add --transport http gloam-hosted https://www.gloam.trade/mcp
• Cursor, VS Code and other clients: add it as a remote server, for example { "mcpServers": { "gloam-hosted": { "url": "https://www.gloam.trade/mcp" } } }

The hosted server reads and plans. It has these tools:

It never signs, never holds funds, and never needs a private key, a recovery phrase or a note secret. A tool call that looks like it carries one is refused with a warning not to share it, and nothing is kept. When something has to be signed, it sends you to the app, or to the local MCP server, which keeps keys on your own machine.

Reference agent (the SDK path)

examples/agent-shield is the smallest complete agent: it mints a note, generates the shield proof, and deposits privately via shieldBound. The whole private path is a few lines.

import { buildShieldBoundIntent, artifactProver } from "@gloamtrade/sdk";
import { parseEther } from "viem";

// 1) SDK mints the note + generates the shield proof
const intent = await buildShieldBoundIntent({
  amountWei: parseEther("0.001"),
  prover: artifactProver({ wasm: "shield.wasm", zkey: "shield_final.zkey" }),
});

// 2) the agent signs the resolved call with its (server-held) wallet
const hash = await wallet.writeContract({
  address: intent.exec.poolAddress,
  abi: shieldPoolAbi,
  functionName: intent.exec.fn,   // "shieldBound"
  args: intent.exec.args,
  value: intent.exec.valueWei,
});
// persist intent.note.secret in the agent's note store, keyed by commitment

That snippet runs on the testnet, the SDK default. For mainnet, pass a mainnet network (mainnetNetwork("tempo") or "robinhood"), its stablecoin as asset, and prove with circuitArtifactUrls("shield", net.chainId) so the final keys are used. See the quickstart.

From there the agent can cash out, pay a receive tag, or prove a balance to a counterparty with a disclosure, all with the same core.

The MCP server

Run it on your own machine with npx -y @gloamtrade/mcp. It signs there, under the spending limits below, and keeps keys and note secrets off the model.

@gloamtrade/mcp exposes Gloam as tools to any MCP client. It keeps two phases separate on purpose: planning tools build an unsigned intent and describe, in plain language, what is private and what is not; execution tools take a plan, sign it server-side, and broadcast.

Private agent payments (x402)

Agents pay for tools and data over HTTP 402. The pattern that won Colosseum paired x402 with stablecoins, but that settlement is fully public: the amount, the payer, and the payee all leak. Gloam's gloam-private scheme keeps it private and self-custodial. The agent settles a shielded transfer to the payee itself, so no operator or facilitator ever holds its key or funds, then presents the payment note, sealed to the payee's receive tag, plus the settlement transaction on the 402 retry. The payee opens the note and moves it into a fresh note only it knows before serving, so the payer cannot spend it back. The public sees only shielded transfers.

This is not a Tempo Zone. A Zone is operator-visible: the zone operator sees every transaction inside it. Gloam is private from the public and from any operator; only the payer and the payee learn the amount. Compliance visibility is opt-in per payment through an issuer-scoped disclosure, not a blanket view handed to an operator. See the privacy model for what stays hidden and what does not.

Check before paying (Agent Wormhole)

A 402 is text the payee wrote, and an agent reads it before it pays. The MCP server can send each payment request to Agent Wormhole first, which scans it for hidden instructions and tells whether it changed since it was first seen. The payment goes ahead only on an allow. A refusal, an abstain, findings, an error or no answer within five seconds all mean the agent does not pay, and nothing is spent.

It is off until you turn it on. Put your Agent Wormhole key in the server's settings (~/.gloam/agent.env) or its environment:

GLOAM_WORMHOLE_KEY=your-agent-wormhole-key

Agent Wormhole sees the payment request and nothing else: never a note, a balance, the wallet or a key.

Spending limits

An agent that can sign can spend, so the owner sets its limits and every tool that moves money (pay, send, shield) checks them before anything is proved or signed. A spend that breaks a limit is refused with a plain reason the agent can act on, for example “that would bring today to 14 PathUSD, over the limit of 12 a day”.

No limits means no spending: a server with a key but no limits refuses every spend until you set them (or turn them off on purpose). Every spend is logged before it is signed, under a lock, so two calls at once cannot both squeeze under the daily cap. Configuration lives in the MCP README.

Where they are enforced. These limits are enforced by the MCP server you run, off-chain, not by the vault contract. They stop a confused or manipulated agent; they do not stop someone who has the raw key. For that, use a policy wallet underneath, as below.

The agent never holds the money itself. A private balance is a note, and whoever knows its secret can spend it, so the server keeps every note in an encrypted store and gives the agent short handles instead. A payment it makes is sealed to the payee's receive tag, so the agent cannot open that either. What limits still cannot stop: an agent tricked into spending within its limits to a payee you allowed.

Policy and key custody

Signing keys live server-side only and never enter a model context or a log. Before an agent runs on mainnet, swap the test key for a Turnkey server wallet with policy the agent cannot override: spend caps, an allow-list of contracts and markets, and size privacy always on. An out-of-policy action is refused, not quietly clamped.

Honesty

No fabricated fills, ever. If a private path is not live, the tool says so and returns a plan rather than a fake success. Private swaps are live in the Gloam app on both mainnets, but the SDK and the MCP server do not swap yet: the market and trade tools only plan, and the old sealed trade they describe is retired. Shield, private send, cash out, and disclosure are live and proof-gated. Mainnet uses the final keys from the 13-contributor ceremony; testnet runs on dev-ceremony keys. The code was reviewed internally before launch, and an external audit is planned. Mainnet is beta software, so start an agent on small limits.