Add Gloam to your agent kit or marketplace

Pick a path

Most capabilities already exist in the SDK and the MCP server. These are the shortest ways to put them in front of your users.

The tool pack

A small TypeScript pack, with no framework types. Tools are plain data plus one call(name, input), so they map onto MCP, the Anthropic or OpenAI tool formats, or your own registry in a few lines. The handlers run GloamAgent, the engine behind the Virtuals plugin, so proving, notes, spending limits and recovery from a lost answer are the same code.

import { createGloamToolPack } from "./agent-kit-tools/src/index.js";

const gloam = createGloamToolPack({
  network: "robinhood-mainnet",
  sender: myKitWallet,              // anything with an address and sendCalls(calls)
  limits: { recipients: "any", assets: { USDG: { maxPerPayment: "50", maxPerDay: "200" } } },
  onClaimLink: (c) => deliverToUser(c.link),        // bearer secrets go to your code
  onSign: async (calls, ctx) => showApproval(ctx.action, calls),
  apiKey: process.env.GLOAM_API_KEY,                // counts your volume to you
});

for (const t of gloam.definitions) {
  registerTool(t.name, t.description, t.inputSchema, (input) => gloam.call(t.name, input));
}

The pack lives in the repo today. Its engine entry (@gloamtrade/game-plugin-gloam/engine) ships to npm with the plugin's next release; until then, run it from a checkout. The README has a five-minute quickstart.

Preview, then execute

Every action that moves money or shows something about it is two calls. A preview checks the request against the chain and the owner's limits and returns exactly what will happen, with a previewId and a digest. Nothing moves until gloam_execute runs it.

{
  "status": "preview",
  "previewId": "pv_Xq3...",
  "digest": "sha256:9c1e...",
  "action": "cash_out",
  "summary": "Cash out 100 USDG to 0xAbc... on Robinhood Chain mainnet: 99.5 USDG arrives after the 0.5% fee.",
  "details": {
    "amount": "100 USDG",
    "to": "0xAbc...",
    "fee": { "bps": 50, "percent": "0.5%", "amount": "0.5 USDG" },
    "receives": "99.5 USDG"
  },
  "walletSigns": [],
  "submittedBy": "the Gloam relay, which pays the gas (your wallet does not appear next to it)"
}

• Execute runs the preview, not new input. Amount, asset, recipient, network and fee are bound when the preview is made and hashed into the digest. Pass the digest you approved and a different preview is refused.
• Once. A second execute returns the first result. A preview expires after 10 minutes, and a cash out whose fee changed since is refused.
• The wallet signs only what the preview named. Your wallet sits behind a guard: outside a running preview it signs nothing, and a deposit may sign only an approve of the vault for exactly the amount and one deposit of exactly that asset and amount. onSign sees each batch decoded and can still say no.
• Proofs authorize the rest. Private payments and cash outs are proven on your machine and sent by the Gloam relay, so the wallet signs only deposits. The relay can send or refuse; it cannot move or redirect money.

Secrets stay with the kit

• A note's secret is the money. Secrets stay in an encrypted note store (AES-256-GCM), a local file by default or your own storage through noteBackend, which only ever sees ciphertext.
• Tools hand out handles and public facts, and every result is checked for secrets before it leaves.
• Claim links go to onClaimLink or are sealed to a Gloam address. A tool result never carries one.
• Spending limits are the owner's: per asset, per payment, per 24 hours, recipients and an expiry, checked before anything is signed. They are enforced by this code, not by the vault contract.

Or bundle the Gloam MCP server

A kit that composes MCP servers can run Gloam's next to its own, with no code:

{
  "mcpServers": {
    "gloam": {
      "command": "npx",
      "args": ["-y", "@gloamtrade/mcp"],
      "env": { "GLOAM_ENV_FILE": "/home/agent/.gloam/agent.env" }
    }
  }
}

Keys and limits go in that file, not in the client config. The server shields, pays privately, pays x402 and MPP resources, checks payments it is paid and runs private swaps. Its execute tools run directly, so the approval step is your MCP client's tool approval, and it has no claim link, cash out or proof of funds tool yet. See Agents.

For x402 marketplaces

A seller keeps its standard x402 exact price and adds a Gloam price next to it. Agents that can pay privately do; the rest keep paying the normal way.

• Standard clients are not affected. They never see or pay the Gloam price. x402 v1 clients parse the 402 body's accepts strictly, so the Gloam price rides in its own X-Payment-Required header and the body stays as it was. On x402 v2 it is also added to PAYMENT-REQUIRED, where clients skip schemes they do not know.
• Paying privately takes a client that supports gloam-private: the tool pack, the Gloam MCP server, or the SDK. There is no plugin for the standard x402 SDKs today.
• The seller secures a payment before it serves. The buyer made the payment note, so it could spend it back until the seller moves it. The helper opens the payment with the seller's key, checks it against this route's price, sweeps it into a fresh note only the seller knows, and serves once that is in the vault. Each payment is served once.

import { generateReceiveKey } from "@gloamtrade/sdk";
import { createGloamSeller, protectWithGloam } from "./agent-kit-tools/src/index.js";

const seller = createGloamSeller({
  receiveKey: await generateReceiveKey(),        // keep privateJwk on the server
  network: "robinhood-mainnet",
  saveNote: (fresh) => db.insert("gloam_notes", fresh),  // the swept money
});

export const GET = protectWithGloam({
  seller,
  price: () => ({ amount: "0.25", asset: "USDG" }),
  handler: quoteHandler,
  standard: withStandardX402(quoteHandler),      // your existing x402 middleware
});

The seller guide shows the 402 answer with the Gloam price added, an Express version, and each check the settle runs.

Get your integration counted

Make a partner key at /partners/dashboard and pass it as apiKey to the tool pack or the seller helper. Private payments, cash outs and sweeps then go through the partner relay, and deposits are attributed once they land, so the dashboard counts what your kit or marketplace brings in. Partner fees are not charged yet. See the Partner API.

What is public, fees and networks

• A deposit and a cash out are public: the wallet or recipient, the asset and the amount. A private payment shows only that a shielded transfer happened.
• Deposits and private payments are free. A cash out costs 0.5%.
• Mainnets: Robinhood Chain, Tempo, Base and Ethereum, in beta with deposit limits (50,000 of a stablecoin per deposit). Every network has a testnet; see Networks.
• Privacy grows with the number of notes in a vault, so a quick deposit and cash out of the same amount can be linked. See what stays private.

FAQ

Does Gloam hold my users' money?

No. The money sits in the vault contract, which has no admin withdraw and timelocks its rule changes, and only the agent holds the secrets to its notes.

Do my users need a Gloam account?

No. Each agent gets a Gloam address from the pack, kept in its own note store. Someone with no Gloam address can be paid by claim link.

Has it been reviewed?

Kann Audits reviewed the vault contracts (report, 1 November 2026) and Hey Research Lab reviewed the stack. The tool pack and the seller helper are new; read them before you trust them with money, and start on small limits.