io.github.payclaw/payclaw
Virtual Visa cards for AI agents. JIT card issuance, human-approved, MCP-native.
Ask AI about io.github.payclaw/payclaw
Powered by Claude Β· Grounded in docs
I know everything about io.github.payclaw/payclaw. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
PayClaw β Badge + Spend for AI Agents
Agents are not bots. PayClaw proves it β then lets them pay.
Your AI agent looks like a bot to every merchant on the internet. PayClaw gives it two things:
Badge β Declares your agent as an authorized actor. The Universal Commerce Protocol "identity" token for a merchant handshake. Free. No card required.
Spend β Issues a single-use virtual Visa when your agent needs to pay. Human-approved. Self-destructs after use. Your real card never enters the chat.
π§ͺ Developer Sandbox is open. Real infrastructure, test money. Get sandbox access β
Quick Start
Add to your MCP client config (Claude Desktop, Cursor, or any MCP client):
{
"mcpServers": {
"payclaw": {
"command": "npx",
"args": ["-y", "@payclaw/mcp-server"],
"env": {
"PAYCLAW_API_KEY": "pk_live_your_key_here",
"PAYCLAW_API_URL": "https://www.payclaw.io"
}
}
}
}
Get your API key at payclaw.io/dashboard/keys. API keys don't expire.
Try without an account
Want to try PayClaw before creating an account? Omit PAYCLAW_API_KEY β on first use, your agent will show a verification code and URL. Approve on your phone to get a temporary session. When you're ready for a permanent setup, create an account and generate an API key.
Extended Auth (optional)
When and where merchants request your token, your agent confirms whether the merchant accepted or denied. Responses are logged to your dashboard so you can see visibility of your token by merchant.
Enable with PAYCLAW_EXTENDED_AUTH=true:
"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.
Or install via ClawHub:
clawhub install payclaw-io
Node version
PayClaw MCP requires Node.js 20 or newer. Node 18 is end-of-life and unsupported.
If you see engine or compatibility errors:
- Check:
node -v - Install Node 20+: nodejs.org or
nvm install 20
UCP Identity Linking
PayClaw Badge is a UCP (Universal Commerce Protocol) Credential Provider. Merchants who add io.payclaw.common.identity to their /.well-known/ucp manifest signal that authorized agents are preferred at their store.
When your agent calls payclaw_getAgentIdentity with a merchantUrl, PayClaw fetches the merchant's manifest, checks for the PayClaw extension, and returns a checkoutPatch the agent merges into the checkout payload. If the merchant doesn't support UCP, a valid token is still returned β nothing breaks.
Merchants verify badges locally with verify() from @payclaw/badge β 10 lines, zero dependencies, no API call.
- Extension spec + schema: github.com/payclaw/ucp-agent-badge
- Merchant documentation: payclaw.io/merchants
Why Your Agent Needs This
Your agent can browse, compare, build carts, and find the best deals. But it can't finish the job β because to every merchant, it looks like a bot.
Without PayClaw: Agent browses β bot detection fires β blocked. Even if it gets through, it can't check out without your real card number. You're stuck finishing manually.
With Badge: Agent declares itself as an authorized actor β merchants see a verified identity β agent gets through. No bypass. Just proof.
With Spend: Agent declares a purchase β you approve with a tap β PayClaw issues a single-use virtual Visa locked to that merchant β agent checks out β card self-destructs. Your real card never enters the chat.
Your agent will recognize when it needs this. When it encounters a merchant that may challenge automated traffic, or when it's ready to check out, it tells you: "I need PayClaw installed to complete this." You click Allow. Done.
Tools
See docs/tool-contract.md for the formal input/output contract.
| Tool | What It Does |
|---|---|
payclaw_getAgentIdentity | Declare identity β get verification token + UCP checkoutPatch (Badge) |
payclaw_reportBadgePresented | Record that you presented your badge at a merchant |
payclaw_reportBadgeOutcome | Report how the merchant responded (accepted, denied, inconclusive) |
payclaw_reportBadgeNotPresented | Report that you did not present your badge (abandoned, merchant didn't ask) |
payclaw_getCard | Declare purchase intent β get virtual Visa (Spend) |
payclaw_reportPurchase | Report transaction outcome β close the audit trail |
Badge: Declare Identity
Agent β payclaw_getAgentIdentity({ merchantUrl })
PayClaw β fetches merchant's /.well-known/ucp manifest
PayClaw β verification token + checkoutPatch (if merchant supports UCP)
Agent β merges checkoutPatch into checkout payload
Agent β payclaw_reportBadgePresented({ merchantUrl, verification_token })
Agent β payclaw_reportBadgeOutcome (accepted | denied | inconclusive)
When merchantUrl is provided, PayClaw checks if the merchant supports io.payclaw.common.identity via UCP and returns a checkoutPatch the agent merges into the checkout payload. If the merchant doesn't support UCP, a valid token is still returned β nothing breaks.
When Extended Auth is enabled, PayClaw checks back with your agent 7 seconds after presentation. Otherwise, your agent reports the outcome via payclaw_reportBadgeOutcome.
Your agent is now a declared, authorized actor. Not anonymous traffic.
Spend: Get a Card
Agent β payclaw_getCard (merchant, amount, description)
User β approves via MFA
PayClaw β issues single-use virtual Visa
Agent β uses card at checkout
Agent β payclaw_reportPurchase (closes audit trail)
Card β self-destructs
One task. One approval. One card. Done.
How Authorization Scales
| Action | What Happens |
|---|---|
| Browse | Badge declaration β identity token issued |
| Search | Badge declaration β identity token issued |
| Checkout | Badge + Spend β MFA approval β single-use Visa issued |
Browsing requires declaration. Spending money requires declaration + stated intent + explicit human approval + an ephemeral card that self-destructs after one use.
Why PayClaw
| Give Agent Your Card | Crypto Wallet | PayClaw | |
|---|---|---|---|
| Agent identity declared | No | No | Every session |
| Human approval per purchase | No | No | Every purchase |
| Card credential lifespan | Permanent | Permanent | Single use |
| Works at existing merchants | Yes | No | Yes β Visa rails |
| Your real card exposed | Yes | N/A | Never |
Badge Only?
If you only need identity (no payment), use the lighter package:
{
"mcpServers": {
"payclaw-badge": {
"command": "npx",
"args": ["-y", "@payclaw/badge"],
"env": {
"PAYCLAW_API_KEY": "pk_live_your_key_here",
"PAYCLAW_API_URL": "https://www.payclaw.io"
}
}
}
}
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
- Dashboard β Your agent's Verified Trips
What's New (v0.8.0)
| Capability | Description |
|---|---|
UCP-aware getAgentIdentity | Pass merchantUrl β PayClaw fetches the merchant's /.well-known/ucp manifest and returns a checkoutPatch when io.payclaw.common.identity is declared |
reportBadgePresented with merchantUrl | Preferred over merchant; includes optional checkoutSessionId for UCP session tracking |
reportBadgeNotPresented | New tool β report when badge was not presented (abandoned, merchant didn't ask) |
| SSRF-protected manifest fetcher | HTTPS-only, private IP blocking, 5-minute domain cache, 3-second timeout |
| Trip lifecycle hardening | onServerClose resolves as inconclusive (not accepted); orphan token recovery on restart |
| Operational logging | Auth mode on startup; reaper logs active trips |
Links
- Website: payclaw.io
- npm: @payclaw/mcp-server
- Badge npm: @payclaw/badge
- UCP Extension: github.com/payclaw/ucp-agent-badge
- ClawHub: payclaw-io
- Trust: payclaw.io/trust
- Merchants: payclaw.io/merchants
- Contact: agent_identity@payclaw.io
- Security: security@payclaw.io
Agents are not bots. PayClaw proves it. Your real card never enters the chat.
