Documentation

Overview

Agents need to spend money. Handing an agent your private key is reckless; funding a standalone agent wallet loses both your custody and your limits. GlassPay takes the model the card industry settled on decades ago and applies it to agents: the wallet stays the account, and the agent gets a card, a scoped authority to draw from it.

• Your wallet is the account. Funds never leave it until the moment of payment.
• The card is a delegation. A scoped ERC-7710 delegation, signed by your wallet, wrapped in caveats: budget per period, per-transaction cap, merchant allowlist, expiry, usage count, contract scope.
• The agent holds the card, not the money. What the agent gets is an MCP endpoint URL. Behind it, the card can spend only what its terms allow, signed by an agent key that holds nothing.
• Revoke kills it instantly. Freeze or revoke a card (or its whole sub-card tree) and every payment stops, server-side immediately and on-chain underneath.

GlassPay runs on Base mainnet with real USDC. The only simulated leg is the Visa rail (Stripe test-mode Issuing), labeled honestly wherever it appears.

How a Payment Works

• You sign in to the dashboard (Privy embedded wallet, Google or email) and issue a card with terms, set by hand in the composer or drafted from plain language by the Venice-powered compiler.
• The dashboard compiles those terms into on-chain caveats, your wallet signs the delegation in the browser, and the server stores it alongside a fresh agent key that holds nothing.
• You hand the card URL to any agent (one claude mcp add, a Cursor deeplink, a pasted connector URL).
• When the agent calls pay, the server validates the terms, then redeems the delegation through the 1Shot Public Relayer: gasless, on Base mainnet, settled in USDC from your wallet.
• Every charge lands in the card's ledger with memo, fee, and tx hash, attributed to the agent key that spent it.

Issuing a Card

A card is born from a CardTerms object: a pay budget, a contract scope, or both, plus lifecycle limits (expiry, max uses, per-charge cap, merchant lock, sub-cards on/off). You can write the terms by hand in the composer, or describe the card in plain language and let the compiler draft them.

The plain-language compiler

The dashboard's issue modal sends your sentence to Venice AI, which returns a plan of named entities ("USDC", "Uniswap", "aave") and numbers. The server then resolves every name against its own verified registry (or Basescan, or your own pasted address), so the model output can never place a raw address into a draft. The result is a CardTerms draft you review and sign; nothing is issued until you do.

The client-signed ceremony

Issuance is a three-step prepare / sign / finalize so the server never holds your key:

• prepare: the server compiles the caveats, mints the agent key, and returns the exact unsigned delegation struct.
• sign: your embedded wallet signs the EIP-712 delegation in the browser.
• finalize: the server verifies the signature recovers to your wallet, then persists the card and returns its URL.

Card Terms

Each term compiles to a delegation-framework enforcer caveat at the root of the delegation, so the chain enforces the same limits the server checks. Below is the exact mapping (engine/src/compiler.ts).

Connecting an Agent

The card is served over MCP (Streamable HTTP). There are three connection lanes. The first two carry a per-card credential directly; the third is OAuth, where the agent never holds the card secret.

claude mcp add --transport http glasspay \
  https://<host>/c/<card-secret>/mcp

claude mcp add --transport http glasspay \
  https://<host>/mcp \
  --header "Authorization: Bearer <card-secret>"

claude mcp add --transport http glasspay https://<host>/mcp

Per-harness one-liners (Lane A)

codex     mcp add glasspay --url https://<host>/c/<secret>/mcp
openclaw  mcp add glasspay --url https://<host>/c/<secret>/mcp --transport streamable-http  # flag required: omitting it defaults to SSE
hermes    mcp add glasspay --url "https://<host>/c/<secret>/mcp"
gemini    mcp add -t http glasspay https://<host>/c/<secret>/mcp
goose     session --with-streamable-http-extension "https://<host>/c/<secret>/mcp"
amp       mcp add glasspay https://<host>/c/<secret>/mcp
droid     mcp add glasspay https://<host>/c/<secret>/mcp --type http

Lanes A and B work in Cursor, VS Code, Gemini CLI, Windsurf, claude.ai custom connectors, or any MCP client that speaks Streamable HTTP. For claude.ai web, paste the card URL under Customize → Connectors → Add custom connector; for ChatGPT Developer Mode, add it as a No Authentication connector (or use Lane C for a real auth story). The dashboard's connect panel renders a prefilled install affordance per harness. Rotate the secret any time from the dashboard; the old URL dies instantly.

MCP Tools

The tool list a card exposes is its permission surface: a pay-only card never sees execute; a contract-only card never sees pay; a sub-cards-off card never sees issue_subcard. The server is stateless, a fresh instance per request, identity = the card credential.

Typed refusals

Refusals come back as isError with structured JSON naming the violated term, so an agent can relay them honestly instead of guessing. The codes include:

• over_period_limit, merchant_not_allowed, price_exceeds_max (pay and paid_fetch)
• target_not_allowed, method_not_allowed, per_trade_exceeded, token_not_allowed, spender_not_allowed (execute)
• exceeds_parent_terms (issue_subcard); not_your_subcard (revoke_subcard)
• card_frozen, no_fiat_card (the fiat leg); invalid_terms (bad input)

Contract Cards

A card can be scoped to specific contract targets and method selectors instead of (or alongside) a USDC budget. The agent calls execute with either {target, method, args} (the server ABI-encodes the calldata) or {target, data} raw calldata for tuple/array/ multicall methods like Uniswap exactInputSingle.

• Targets and selectors outside the card's declared scope are refused before anything reaches the chain; the on-chain AllowedTargets / AllowedMethods enforcers check the same scope again at redemption.
• Method signatures are normalized to canonical form (uint → uint256) so the encoder, the raw-data selector check, and the on-chain enforcer all agree.
• A contract card can carry an allowance token list (contract.tokens: the only tokens it may approve, each approval pinned on-chain to an exact spender and amount; the listed tokens are auto-unioned into the card's targets) and a per-trade ceiling (contract.perTradeMax, capping each USDC approval; v1 enforces the ceiling on the USDC / settlement leg only, while non-USDC approvals stay exact-amount pinned).
• For a call that needs a recipient (e.g. exactInputSingle's recipient), the card tool surfaces the card's on-chain account(the root delegator that holds the USDC and receives any output tokens), so the agent routes a swap's output there itself rather than guessing or asking the user.
• Contract calls carry no native ETH value in v1 (the carved leaf caps value at 0 on-chain); up to 5 calls batch atomically into one redemption.

Sub-Cards & Revocation

Sub-cards are ERC-7710 redelegations. An agent holding a card can mint a tighter child for a sub-agent with issue_subcard; every term must fit inside the parent's (caps only narrow downward, contract scope is subset-only, never silently inherited). exceeds_parent_terms names the violating field. The chain enforces the same subset via the delegation chain.

Three layers of off-switch

All three are user-operable from the dashboard. On-chain revoke and nuke are signed by your own embedded wallet in the browser (an admin leaf delegation) and ride the relayer gaslessly. Revoking a parent kills the subtree; the cascade is the demo money-shot, revoke the root and the whole tree dies on screen.

Payment Rails

Two payment rails run off one delegation, metered by the same enforcers.

x402 (real, live)

paid_fetchanswers an HTTP 402 challenge by paying through the card's 7710 delegation: real x402 v2 flows on Base mainnet, USDC settled from your wallet through the 1Shot Public Relayer (gasless, fee in USDC). GlassPay also ships the first ERC-7710 x402 facilitator (/facilitator/verify, /settle, /supported advertising assetTransferMethod: erc7710) and a demo seller at /demo/premium-data whose 402 points back at it.

Stripe Issuing Visa (simulated)

fiat_pay and card_credentialsdrive a test-mode virtual Visa. When a charge is authorized, Stripe calls GlassPay's real-time auth webhook, which answers approve/decline from the card's on-chain delegation state inside Stripe's hard 2-second window (read from a cached snapshot, never an RPC call in the handler). A decline comes back typed, from the card's terms, not the merchant.

With settlement enabled, an approved Visa charge then settles as a real delegated USDC transfer on Base, through the same enforcers that meter the crypto rail. One budget, two rails. A charge whose settlement cannot land parks settlement_unconfirmed and freezes the card rather than ever releasing its budget.

The demo merchant, s0nder supply co. at /shop, is a real storefront that accepts the cards' Visas. The catalog is priced at $5 or less because approved purchases move real USDC.

Security

• Custody.Your funds stay in your wallet. The per-card agent key signs redelegations only; it holds no assets and is encrypted at rest. You can export your wallet's private key from the account menu at any time (through Privy's secure modal, rendered in a separate-domainiframe GlassPay never reads) and walk away to any client.
• Dashboard auth. Per-user Privy sessions, verified server-side against the app JWKS. At onboard, the embedded wallet signs glasspay-onboard:v1:<did>to bind the wallet to that login; every card route is then scoped to the authenticated user's own cards.
• Issuance integrity. The server verifies the delegation signature recovers to the delegator before persisting a card.
• Card secrets. 256-bit, stored as a hash for auth and AES-256-GCM-encrypted at rest for the reveal/rotate feature. The URL is a credential; rotate it like a password.
• Limits enforced twice.Server-side at call time (typed refusals) and on-chain at redemption. Period, lifetime, expiry, usage count and contract target/method have dedicated on-chain enforcers; the per-transaction max and merchant allowlist are server-side policy, backstopped on-chain by the carved leaf's amount scope.
• MCP surface hardening. Host allowlist (DNS-rebinding guard), per-card and bad-secret rate limits, a 1 MiB body cap, an SSRF guard on paid_fetch targets, secrets never echoed in errors or logs.
• OAuth tokens. Opaque, card-scoped, hash-stored beside the card secrets, audience-pinned (RFC 8707), and revoked the instant the card is, cascading to the subtree.

SigNoz Observability

GlassPay is fully instrumented with OpenTelemetry and ships traces, metrics, and logs to SigNoz Cloud (and can self-host locally via the included casting.yaml). Every card issuance, every payment, every refusal, every API call — all visible in SigNoz.

Architecture

Env vars (already set on Railway)

OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.us2.signoz.cloud
OTEL_EXPORTER_OTLP_HEADERS=signoz-ingestion-key=YOUR_KEY
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp

The OTel SDK initializes early via Bun --preload (packages/server/src/otel.ts) so auto-instrumentation wraps every module from boot. The engine package (packages/engine/src/telemetry.ts) declares all custom metrics and structured log functions — 5 counters, 2 log emitters, available for any SigNoz dashboard panel.

Traces — Distributed Tracing

Every API request is wrapped in a root span by Hono middleware (app.ts) with attributes for route pattern, HTTP method, URL, and response status code. Inside those (and running on their own intervals), six custom business-logic spans carry domain-specific attributes.

Route-level spans (every request)

The Hono app.use("*", ...) middleware creates a span for every request, named HTTP {METHOD} {ROUTE}. Navigate to SigNoz → Traces, filter by service.name = glasspay-server, and see every API call with its duration, status, and route pattern.

stripe_webhook_auth

Fires when Stripe calls the real-time auth webhook. Attributes: decision (approve/decline), card_id, amount, merchant. Traces the full auth decision flow inside Stripe's 2-second window.

1shot_relayer_redeem

Fires on every on-chain payment. Attributes: usdc_amount (string), gas_fee_usdc, memo, tx_hash, card_id. Shows the full lifecycle of a USDC redemption through the 1Shot Public Relayer.

nl_compile

Fires when Venice AI compiles a plain-language card request. Attributes: prompt_tokens, completion_tokens, model. Tracks AI usage for cost monitoring.

reconcile_sweep

Runs on a configurable interval (default 5 min). Attributes: reconciled (count), still_pending (count). Resolves stuck pending charges against chain truth.

fiat_settle_sweep

Runs on a configurable interval (default 60s). Attributes: settled (count), left (count). Settles approved Visa charges as on-chain USDC transfers.

Metrics — Product KPIs

Five custom counters are available in SigNoz Metrics. Navigate to SigNoz → Metrics and search for any of the following metric names to build dashboard panels.

These metrics are created in packages/engine/src/telemetry.ts using the OpenTelemetry Metrics API and exported via OTLP HTTP to SigNoz. They appear in the Metrics explorer under their metric names, prefixed by the engine package.

Building a metric panel

In SigNoz, create a new dashboard, click New Panel, choose Time Series, then switch to the ClickHouse query tab. The SigNoz metrics storage uses the signoz_metrics.distributed_samples_v2 table. Example query for cards issued:

SELECT toStartOfInterval(
         toDateTime(intDiv(timestamp_ms, 1000)),
         INTERVAL 5 MINUTE) AS ts,
       sum(value) AS value
FROM signoz_metrics.distributed_samples_v2
WHERE metric_name = 'glasspay_cards_issued_total'
  AND ts BETWEEN $start_datetime AND $end_datetime
GROUP BY ts
ORDER BY ts

Structured Logs — Event-Driven Observability

GlassPay emits structured logs for every significant card lifecycle event. Navigate to SigNoz → Logs and filter by card_event, charge_event, refusal_reason, or operation to see exactly what happened.

Card lifecycle events

Example log searches

• card_event: "issued" — see every card being created in real-time
• card_event: "revoked" — track card revocations
• refusal_reason: * — all payment refusals with typed reasons
• charge_event: "confirmed" — successful payments with amounts
• operation: * — all API errors grouped by operation

Logs are emitted using the OpenTelemetry Logger API (@opentelemetry/api-logs) through the logger.emit() function. Each log carries its severityText (INFO, WARN, ERROR) and structured attributes that SigNoz indexes automatically.

SigNoz Dashboard & ClickHouse Queries

Create a GlassPay dashboard in SigNoz with panels for every metric and trace attribute. Below are the ClickHouse queries for each panel type.

Panel 1: Cards Issued Over Time

Panel Type: Time Series. Shows the rate of card issuances over time.

SELECT toStartOfInterval(
         toDateTime(intDiv(timestamp_ms, 1000)),
         INTERVAL 5 MINUTE) AS ts,
       sum(value) AS value
FROM signoz_metrics.distributed_samples_v2
WHERE metric_name = 'glasspay_cards_issued_total'
  AND ts BETWEEN $start_datetime AND $end_datetime
GROUP BY ts
ORDER BY ts

Panel 2: Active Cards (Gauge)

Panel Type: Value (big number). Shows the current live card count.

SELECT sum(value) AS active_cards
FROM signoz_metrics.distributed_samples_v2
WHERE metric_name = 'glasspay_active_cards'
  AND timestamp_ms > toUnixTimestamp(now()) * 1000 - 60000

Panel 3: USDC Spent

Panel Type: Time Series. Tracks cumulative USDC volume.

SELECT toStartOfInterval(
         toDateTime(intDiv(timestamp_ms, 1000)),
         INTERVAL 5 MINUTE) AS ts,
       sum(value) AS value
FROM signoz_metrics.distributed_samples_v2
WHERE metric_name = 'glasspay_usdc_spent_total'
  AND ts BETWEEN $start_datetime AND $end_datetime
GROUP BY ts
ORDER BY ts

Panel 4: API Error Rate

Panel Type: Time Series. Track error spikes.

SELECT toStartOfInterval(
         toDateTime(intDiv(timestamp_ms, 1000)),
         INTERVAL 5 MINUTE) AS ts,
       sum(value) AS errors
FROM signoz_metrics.distributed_samples_v2
WHERE metric_name = 'glasspay_errors_total'
  AND ts BETWEEN $start_datetime AND $end_datetime
GROUP BY ts
ORDER BY ts

Panel 5: API Request Duration by Route

Panel Type: Time Series. Uses trace data to show P99 latency per API route.

SELECT toStartOfInterval(timestamp, INTERVAL 5 MINUTE) AS ts,
       attributes_string['http.route'] AS route,
       avg(durationNano) / 1000000 AS avg_ms
FROM signoz_traces.distributed_signoz_index_v2
WHERE resources_string['service.name'] = 'glasspay-server'
  AND ts BETWEEN $start_datetime AND $end_datetime
GROUP BY ts, route
ORDER BY ts

SigNoz MCP — AI-Agent Observability

The included casting.yaml ships a SigNoz MCP server alongside the SigNoz stack. This lets your AI agent query traces, logs, and metrics directly — and even create dashboards and alerts autonomously.

Connect your agent to SigNoz MCP

# Self-hosted (from casting.yaml):
claude mcp add signoz http://localhost:8000 \
  --header "Authorization: Bearer glasspay_mcp_dev"

# SigNoz Cloud (API-based):
claude mcp add signoz https://signoz.io/api/mcp \
  --header "Authorization: Bearer $YOUR_SIGNOZ_API_KEY"

Available MCP tools

Once connected, your agent can use SigNoz MCP tools for observability workflows:

• signoz_search_docs — Search SigNoz documentation for guides and references.
• signoz_create_dashboard — Create new dashboards with panels for GlassPay metrics.
• signoz_modify_dashboard — Update existing dashboard panels and configurations.
• signoz_create_alert — Set up alerts for error rate spikes, card issuance stalls, etc.
• signoz_investigate_alert — Deep-dive into alert-triggered incidents with neighbor signals.
• signoz_generate_query — Generate ClickHouse queries for GlassPay observability data.
• signoz_explain_dashboard — Understand existing dashboard layouts and panel semantics.
• signoz_manage_views — Create and manage saved views for quick data exploration.

Example: ask your agent "Create a SigNoz dashboard for GlassPay showing cards issued, USDC spent, and API error rate" — it will use the MCP tools to build the entire dashboard without you touching the SigNoz UI.

Alerts & Self-Hosting

Recommended alerts

Set up these alerts in SigNoz to monitor GlassPay health:

Self-hosted SigNoz (local development)

The repo includes a casting.yaml for deploying SigNoz locally using Foundry. This is perfect for development and testing without sending telemetry to the cloud.

# Deploy the full SigNoz stack:
foundryctl cast -f casting.yaml --locked

# SigNoz UI:    http://localhost:3301
# OTLP HTTP:    http://localhost:4318
# SigNoz MCP:   http://localhost:8000

# Then set the server env:
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp

The casting.yaml.lock pins every Docker image to its content digest, ensuring reproducible deployments. Judges can run foundryctl cast -f casting.yaml --locked to reproduce the exact SigNoz environment used during development.

Stack components

API Reference

The server is one Hono process. The dashboard API lives under /api; the MCP endpoint, OAuth lane, x402 facilitator and demo surfaces sit at the root.

Auth lanes (every /api route)

• Admin (Authorization: Bearer <GLASSPAY_ADMIN_TOKEN>): full access, server-side scripts only, never shipped to a browser.
• Privy (Authorization: Bearer <Privy access token>): verified offline against the app JWKS; every route scoped to the authenticated user.

Dashboard API (/api)

OAuth 2.1 (self-hosted authorization server)

Public clients, PKCE S256, auth-code + rotating refresh, dynamic client registration. Tokens are opaque (glsp_at_ access, glsp_rt_ refresh), audience-pinned, and die with the card.

MCP, facilitator + demo

Self-Hosting

A Bun monorepo, three packages: engine (the pure card engine), server (Hono: REST + MCP + facilitator + Stripe webhook + demo shop) and dashboard (Next.js). Real money moves on Base mainnet, so use small budgets.

bun install
cp .env.example .env          # then set the two required vars below

bun dev                       # server on :4070
bun run --cwd packages/dashboard dev   # dashboard on :4071

Required environment

Common optional environment

Contracts (Base mainnet · chain 8453)

The Cook Off

GlassPay was built for the MetaMask Smart Accounts Kit × 1Shot API × Venice AI Dev Cook Off. The hard gate, Smart Accounts Kit in the main flow, is the product itself: every card is a SAK delegation, signed by a Privy-provisioned embedded smart account, and every spend redeems it on-chain.

Where in the code

Direct links into the public repo for each track, following the MetaMask DevRel submission guideline.

• Delegations. Create: issueRootCard (caveats via compileCard). Redeem: spend.ts.
• Redelegation (A2A). issueSubCard attenuates the parent and builds a child delegation bound to the parent's hash.
• x402. Server: facilitatorRoutes. Client (erc7710 asset transfer): buildX402Payload.
• 1Shot. Every redemption rides the relayer: Relayer.send (relayer_send7710Transaction).
• Venice. veniceChat orchestrated by compileIntent.

Ready to issue one? Open the dashboard, sign in, and your first card takes about a minute.