Skip to content

Gloam is live on BNB Chain. Private USDT and USDC payments.

Open the app

Build on Gloam

Add Gloam to your agent kit or marketplace

Your agents get a private balance, private payments, claim links, cash outs and proofs of funds, behind the same preview and approval step your kit already has. Your marketplace's sellers take private payments next to the standard x402 ones they take today.

Tool pack
examples/agent-kit-tools
Engine
GloamAgent, on @gloamtrade/sdk
x402
gloam-private and gloam-cashout, next to exact
Networks
Robinhood Chain, Tempo, Base, Ethereum, Elysium, BNB Chain

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.

PathForWhat you get
The tool packAgent kits and MCP add-ons with their own wallet and approval stepTool definitions (name, description, JSON schema) and handlers. Every money action is a preview, then an execute of that preview.
The Gloam MCP serverKits that compose MCP serversnpx -y @gloamtrade/mcp next to your own server. No code; approval is your MCP client's tool approval.
The seller helperx402 marketplaces and the APIs on themAdds a Gloam price next to the standard x402 price, settles and secures Gloam payments before the resource is served.
The SDKTeams building their own flow@gloamtrade/sdk: the intents, proofs, x402 and receive helpers everything above is built on.

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));
}
ToolWhat it doesPublic on chain
gloam_balance
read
Private balance per asset, the agent's Gloam address, what the wallet holds, limits left today.Nothing
gloam_receive
read
Pick up payments sent to the agent's Gloam address and secure each one into a note only it knows.A shielded transfer
gloam_preview_shield
preview
Deposit from the wallet into the private balance (USDG on Robinhood Chain, or any asset the vault takes).The deposit: wallet, asset, amount
gloam_preview_pay
preview
Pay a Gloam address or a payment request link privately.A shielded transfer only
gloam_preview_claim_link
preview
Pay by claim link, for someone with no Gloam address. The link goes to your code, never to the model.A shielded transfer only
gloam_preview_cash_out
preview
Private balance to a 0x address, with the vault's live fee and what arrives.The cash out: asset, amount, recipient
gloam_preview_prove_funds
preview
A proof the agent holds at least an amount, for one named reader, with an expiry.Nothing
gloam_preview_pay_x402
preview
Request a URL; if it answers 402 with a Gloam price, plan paying it privately. A gloam-cashout price is a cash out to the resource's public address.A shielded transfer only, or for gloam-cashout the cash out to the payee
gloam_execute
execute
Run a preview by its previewId and digest, once.What the preview said
gloam_verify_proof
read
Check a gloamfunds1: or gloampay1: proof against the chain.Nothing

The pack lives in the repo today. Its engine entry (@gloamtrade/game-plugin-gloam/engine) is on npm from the plugin's 0.3.0. 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.

Private payer, public payee (gloam-cashout)

Some gateways pay out to a public address, such as a creator's splitter, and settle standard exact payments in USDG on Robinhood Chain. With gloam-cashout the agent pays from its private balance: it cashes out straight to that address. The chain shows USDG leaving the Gloam vault to the splitter. It does not show the agent's wallet, because the Gloam relay sends the cash out, or which deposit paid for it. The payee side stays public, as it is today.

The 402

Add one entry to accepts, next to exact:

{
  "scheme": "gloam-cashout",
  "network": "eip155:4663",
  "asset": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",   // USDG
  "payTo": "0xYourSplitter",
  "amount": "1005063",          // G, base units (6 decimals)
  "quoteId": "q_9f8e7d6c",      // secret, one per 402
  "maxTimeoutSeconds": 120      // optional; expiresAt (unix seconds) works too
}
  • G is gross. G = ceil(price * 10000 / (10000 - bps)) + tag, where bps is the vault's live withdrawFeeBps() (50 today) and tag is 1 to 9999.
  • G is unique among your open quotes to a payTo. The chain shows a cash out of G to payTo, not the quote id, so a payment matches every open quote with the same G. A unique tag is not enough: at 50 bps, price 10000 with tag 7 and price 5000 with tag 5032 both give 10058. Pick the tag with reserveCashoutGross, which skips any G another open quote to that payTo holds.
  • The vault takes its fee. The vault at 0x39E28Cde55CAB798874746ac52cb4B5Cc99a0194 keeps floor(G * bps / 10000) and sends the rest to payTo. That is always at least the price.
  • reserveCashoutGross in @gloamtrade/sdk reads the fee, picks the tag and returns G. Read the fee per quote: it can change on a 3-day timelock.

The payment

The agent cashes out exactly G of USDG to payTo. The vault emits Unshielded(nullifier, asset, to, amount) with amount = G. The agent then retries with:

X-PAYMENT: base64(JSON.stringify({ scheme: "gloam-cashout", txHash, quoteId }))

The header holds a public tx hash and your own quote id. It never holds a note, a key or a balance. The tool pack, the Gloam MCP server's gloam_fetch_paid and GloamAgent.payX402Cashout pay it, and all three need a maxAmount. When a 402 offers both gloam-private and gloam-cashout, they pay gloam-private unless the caller prefers gloam-cashout.

The gateway check

Serve the resource only when all six pass:

  • The quote, found by the header's quoteId, is the only open quote at its payTo and G.
  • The receipt exists on chain 4663 and succeeded.
  • It has an Unshielded log from the vault, for USDG, to payTo, with amount == G. The same event from any other contract does not count.
  • It has a USDG Transfer from the vault to payTo of at least the price.
  • The block time falls inside the quote window.
  • You have not seen the txHash before. Keep that store yourself, and record the hash when you grant access.

verifyGloamCashout in @gloamtrade/sdk runs the first five when you pass openQuoteIds, the ids your store holds at cashoutGrossKey(payTo, G). This is the receipt check with viem, to copy:

import { createPublicClient, http, parseAbiItem, toEventSelector, pad, type Address, type Hex } from "viem";

const VAULT = "0x39E28Cde55CAB798874746ac52cb4B5Cc99a0194";
const USDG = "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168";
const UNSHIELDED = toEventSelector(parseAbiItem(
  "event Unshielded(bytes32 indexed nullifier, address indexed asset, address indexed to, uint256 amount)"));
const TRANSFER = toEventSelector(parseAbiItem(
  "event Transfer(address indexed from, address indexed to, uint256 value)"));
const word = (a: string) => pad(a.toLowerCase() as Hex, { size: 32 });
const same = (a: string, b: string) => a.toLowerCase() === b.toLowerCase();

export async function verifyGloamCashout(args: {
  txHash: Hex;
  quote: { payTo: Address; gross: bigint; price: bigint; issuedAt: number; windowSec: number };
  rpcUrl?: string;
}): Promise<{ ok: boolean; reason: string | null }> {
  const { txHash, quote } = args;
  // 0. Before this: the quote is the only open quote at its payTo and G in your store.
  const client = createPublicClient({ transport: http(args.rpcUrl ?? "https://rpc.mainnet.chain.robinhood.com") });
  if ((await client.getChainId()) !== 4663) return { ok: false, reason: "wrong_chain" };
  const receipt = await client.getTransactionReceipt({ hash: txHash }).catch(() => null);
  if (!receipt) return { ok: false, reason: "not_found" };
  if (receipt.status !== "success") return { ok: false, reason: "reverted" };

  // 1. Unshielded(nullifier, USDG, payTo, G), emitted by the vault itself.
  const usdgOut = receipt.logs.filter((l) => l.topics[0] === UNSHIELDED && same(l.topics[2] ?? "", word(USDG)));
  const fromVault = usdgOut.filter((l) => same(l.address, VAULT));
  if (!fromVault.length) return { ok: false, reason: usdgOut.length ? "not_vault" : "no_unshield" };
  const toPayee = fromVault.filter((l) => same(l.topics[3] ?? "", word(quote.payTo)));
  if (!toPayee.length) return { ok: false, reason: "wrong_payee" };
  if (!toPayee.some((l) => BigInt(l.data) === quote.gross)) return { ok: false, reason: "wrong_amount" };

  // 2. A USDG Transfer from the vault to payTo of at least the price.
  const paid = receipt.logs.some((l) =>
    same(l.address, USDG) && l.topics[0] === TRANSFER &&
    same(l.topics[1] ?? "", word(VAULT)) && same(l.topics[2] ?? "", word(quote.payTo)) &&
    BigInt(l.data) >= quote.price);
  if (!paid) return { ok: false, reason: "short_transfer" };

  // 3. Mined inside the quote window.
  const { timestamp } = await client.getBlock({ blockNumber: receipt.blockNumber });
  const t = Number(timestamp);
  if (t < quote.issuedAt || t > quote.issuedAt + quote.windowSec) return { ok: false, reason: "outside_window" };

  // 4. Not checked here: that txHash is unused. Check and record it in your own store.
  return { ok: true, reason: null };
}

buildGloamCashoutRequirement makes the accepts entry, and reserveCashoutGross prices it with a G no other open quote holds. Both are in the SDK README.

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, Ethereum, Elysium and BNB Chain, with deposit limits (50,000 of a stablecoin per deposit; 500 USDC on Elysium; none on USDT and USDC on BNB Chain, where they have 18 decimals). Every network but Elysium and BNB Chain 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.