@payclaw/badge

Badge by PayClaw

Agents are not bots. Prove it.

Your AI agent looks like a bot to every merchant on the internet. Badge gives it a way to declare what it is: an authorized actor, shopping on behalf of a real human, with explicit consent.

One MCP tool call. Your agent declares itself. Merchants let it through.

Quick Start

Add to your MCP client config:

{
  "mcpServers": {
    "payclaw-badge": {
      "command": "npx",
      "args": ["-y", "@payclaw/badge"],
      "env": {
        "PAYCLAW_API_URL": "https://payclaw.io"
      }
    }
  }
}

No API key required. On first use, your agent will show a code and URL — approve on your phone in one tap, and your Consent Key is stored. Optional: set PAYCLAW_API_KEY for existing accounts (backward compatible).

Node version

Badge requires Node.js 20 or newer. Node 18 is end-of-life and unsupported.

If you see engine or compatibility errors: node -v — install Node 20+ from nodejs.org or nvm install 20.

UCP Identity Linking

Badge is a UCP (Universal Commerce Protocol) Credential Provider. Merchants who declare the PayClaw identity extension signal to every UCP-compliant agent that authorized agents are preferred at their store.

When your agent encounters a UCP merchant with PayClaw installed, it presents a cryptographic badge automatically — no extra steps.

• Extension spec + schema: github.com/payclaw/ucp-agent-badge
• Merchant documentation: payclaw.io/merchants

Why Your Agent Needs This

Your agent is smart. It can browse, compare prices, build carts, find deals. But to every merchant on the internet, it looks identical to a scraper.

Merchants don't ask "is this agent helpful?" They ask "is this a bot?" And they block first, ask never.

Without Badge: Your agent hits a merchant → bot detection fires → blocked. Task fails. Your user is disappointed. The merchant lost a sale and doesn't know it.

With Badge: Your agent calls payclaw_getAgentIdentity → receives a verification token → presents it to the merchant. The merchant sees: authorized actor, verified human behind it, declared intent. Your agent gets through. Task succeeds.

What Badge Declares

Every time your agent calls payclaw_getAgentIdentity, it receives a UCP-compatible credential that declares:

• Agent type: Authorized actor (not a bot, not a scraper)
• Principal: Verified human behind this session (Google or Apple SSO)
• Assurance level: starter / regular / veteran / elite based on verified trip history
• Contact: [e-mail] for merchant verification

The agent presents this disclosure to merchants. Merchants see a verified identity, not anonymous traffic.

How It Works

First use (device auth)

1. Your agent calls payclaw_getAgentIdentity
2. No key? Device auth flow triggers — code + URL appear in terminal
3. You approve on your phone (Google or Apple, one tap)
4. Consent Key stored — agent is authorized
5. Every subsequent call uses the stored key automatically

UCP-aware identity (with merchantUrl)

1. Agent calls payclaw_getAgentIdentity({ merchantUrl: 'https://store.com' })
2. PayClaw fetches store.com/.well-known/ucp manifest
3. If merchant declares io.payclaw.common.identity → returns checkoutPatch
4. Agent merges checkoutPatch into checkout payload
5. Agent calls payclaw_reportBadgePresented({ merchantUrl, verification_token })
6. Merchant calls verify(token) → gets PayClawIdentity

If the merchant doesn't support UCP, a valid token is still returned — nothing breaks. No card is issued. No money moves. Badge is the identity layer — the credential that lets authorized agents through while bot defenses stay intact.

Extended Auth (optional)

When enabled, PayClaw checks back with your agent 7 seconds after badge presentation to confirm whether the merchant accepted or denied. Results are logged to your dashboard.

"env": {
  "PAYCLAW_API_URL": "https://payclaw.io",
  "PAYCLAW_EXTENDED_AUTH": "true"
}

Without it, your agent reports outcomes via payclaw_reportBadgeOutcome when it knows the result.

Tools

Tool	Description
payclaw_getAgentIdentity	Declare identity, get UCP-compatible verification token
payclaw_reportBadgePresented	Signal that you presented your Badge to a merchant
payclaw_reportBadgeOutcome	Report whether merchant accepted or denied the badge
payclaw_reportBadgeNotPresented	Report that the badge was not presented

For Merchants: Verify a Badge

Badge is the package merchants install for local JWT verification — no API call to PayClaw, no uptime dependency.

npm install @payclaw/badge

import { verify } from '@payclaw/badge/verify'

const identity = await verify(req.body['io.payclaw.common.identity']?.token)

if (identity) {
  // Verified — identity.userId, identity.agentId, identity.scopes, etc.
  // Apply tier pricing, skip CAPTCHAs, fast-track checkout
}
// null = no badge or invalid — proceed as guest

verify() fetches PayClaw's JWKS once, caches for 1 hour, and verifies the ES256 signature locally via Web Crypto API. Zero runtime dependencies. Works in Node.js 18+ and Cloudflare Workers. Never throws — returns null on any error.

Full verification docs + Python example: github.com/payclaw/ucp-agent-badge

What's New (v0.8.0)

Capability	Description
verify() export	Merchant-side JWT verification — import { verify } from '@payclaw/badge/verify'. Zero dependencies, Web Crypto only.
UCP-aware getAgentIdentity	Pass merchantUrl — fetches merchant manifest, returns checkoutPatch when io.payclaw.common.identity is declared
reportBadgePresented with merchantUrl	Preferred over merchant; includes optional checkoutSessionId for UCP session tracking
SSRF-protected manifest fetcher	HTTPS-only, private IP blocking, 5-minute domain cache
Trip lifecycle hardening	onServerClose resolves as inconclusive; orphan token recovery on restart

Need Payment Too?

Badge is the base layer. For virtual Visa cards, use @payclaw/mcp-server — which includes Badge automatically.

npx -y @payclaw/mcp-server

KYA — Know Your Agent

PayClaw is KYA infrastructure. Every declaration creates a verified record of agentic commerce behavior — building the trust signal that merchants need to tell authorized agents from anonymous bots.

• Trust & Verification — The full trust architecture
• For Merchants — How merchant UCP integration works
• UCP Extension Spec — io.payclaw.common.identity (MIT)

Links

• Website: payclaw.io
• npm: @payclaw/badge
• UCP Extension: github.com/payclaw/ucp-agent-badge
• ClawHub: payclaw-badge
• Trust: payclaw.io/trust
• Merchants: payclaw.io/merchants
• Contact: [e-mail]

Agents are not bots. PayClaw proves it.