[](https://www.npmjs.com/package/pop-pay) [](https://opensource.org/licenses/MIT) [](https://github.com/100xPercent/pop-pay/actions/workflows/ci.yml) [](https://nodejs.org/)
# Point One Percent โ pop-pay
it only takes 0.1% of Hallucination to drain 100% of your wallet.
The runtime security layer for AI agent commerce. Drop-in CLI + MCP server. Card credentials are injected directly into the browser DOM via CDP โ they never enter the agent's context window. One hallucinated prompt can't drain a wallet it can't see.
> ๐ **Research Dataset & Reproduction** โ this repository hosts the open dataset and reproduction harness for *"The Illusion of Single-Attacker Rankings"*. research: jump to [Research Dataset & Reproduction](#research-dataset--reproduction).
## Install
Choose your preferred method:
Homebrew (macOS)
```bash
brew install 100xpercent/tap/pop-pay
```
curl (Linux / macOS) โ bootstraps via npm; requires Node.js 18+
```bash
curl -fsSL https://raw.githubusercontent.com/100xPercent/pop-pay/main/install.sh | sh
```
npm (global)
```bash
npm install -g pop-pay
```
npx (no install โ one-off runs)
```bash
npx -y pop-pay
```
All install paths expose the same binaries: `pop-pay`, `pop-launch`, `pop-init-vault`, `pop-unlock`.
> Also available as `@100xpercent/mcp-server-pop-pay` โ identical package under the MCP `@scope/mcp-server-` convention. Tracks the same version on every release.
> **Using Python?** Check out [pop-pay-python](https://github.com/100xPercent/pop-pay-python) โ `pip install pop-pay`. Same security model, same vault format, independent release cycle โ safe to switch between runtimes.
## Quick Start (CLI)
### 1. Initialize the encrypted credential vault
```bash
pop-pay init-vault
```
This encrypts your card credentials into `~/.config/pop-pay/vault.enc` (AES-256-GCM). For stronger protection (blocks agents with shell access):
```bash
pop-pay init-vault --passphrase # one-time setup
pop-pay unlock # run once per session
```
### 2. Launch Chrome with CDP remote debugging
```bash
pop-pay launch
```
This opens a Chromium instance on `http://localhost:9222` that pop-pay injects credentials into. Your agent (via MCP, browser automation, or x402) then drives the checkout flow โ card details never leave the browser process.
### 3. Plug into your agent
The CLI launches infrastructure; the actual payment tool calls come from your agent. Two supported paths:
- **MCP server** โ add pop-pay to any MCP-compatible client (Claude Code, Cursor, Windsurf, OpenClaw). See [MCP Server](#mcp-server-optional) below.
- **x402 HTTP** โ pay for API calls via the [x402 payment protocol](docs/INTEGRATION_GUIDE.md#x402).
Full CLI reference: `pop-pay --help`.
## MCP Server (optional)
### Add to your MCP client
Standard config for any MCP-compatible client:
```json
{
"mcpServers": {
"pop-pay": {
"command": "npx",
"args": ["-y", "pop-pay", "launch-mcp"],
"env": {
"POP_CDP_URL": "http://localhost:9222"
}
}
}
}
```
[
](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522pop-pay%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522pop-pay%2522%252C%2522launch-mcp%2522%255D%252C%2522env%2522%253A%257B%2522POP_CDP_URL%2522%253A%2522http%253A%252F%252Flocalhost%253A9222%2522%257D%257D) [
](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522pop-pay%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522pop-pay%2522%252C%2522launch-mcp%2522%255D%252C%2522env%2522%253A%257B%2522POP_CDP_URL%2522%253A%2522http%253A%252F%252Flocalhost%253A9222%2522%257D%257D) [
](cursor://anysphere.cursor-deeplink/mcp/install?name=pop-pay&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInBvcC1wYXkiLCJsYXVuY2gtbWNwIl0sImVudiI6eyJQT1BfQ0RQX1VSTCI6Imh0dHA6Ly9sb2NhbGhvc3Q6OTIyMiJ9fQ==)
Claude Code
Claude Code uses its own CLI โ the JSON config above is not needed.
```bash
claude mcp add --scope user pop-pay -- npx -y pop-pay launch-mcp
```
`--scope user` makes it available across all projects. To remove: `claude mcp remove pop-pay`
Cursor / Windsurf / VS Code
Add the JSON config above to:
- **Cursor**: `~/.cursor/mcp.json`
- **Windsurf**: `~/.codeium/windsurf/mcp_config.json`
- **VS Code (Copilot)**: `.vscode/mcp.json` in project root
OpenClaw / NemoClaw
OpenClaw has its own CLI โ the JSON config above is not needed.
```bash
openclaw mcp add pop-pay -- npx -y pop-pay launch-mcp
```
Or add to `~/.openclaw/mcp_servers.json` using the JSON config above.
For System Prompt templates and NemoClaw sandbox setup, see [Integration Guide ยง4](./docs/INTEGRATION_GUIDE.md).
Docker
```bash
docker-compose up -d
```
Runs the MCP server + headless Chromium with CDP. Mount your encrypted vault from the host.
## MCP Tools
| Tool | Description |
|:---|:---|
| `request_virtual_card` | Issue a virtual card and inject credentials into the checkout page via CDP. Automatically scans the page for hidden prompt injections. |
| `request_purchaser_info` | Auto-fill billing/contact info (name, address, email, phone). Automatically scans the page for hidden prompt injections. |
| `request_x402_payment` | Pay for API calls via the x402 HTTP payment protocol. |
> **Tip for Claude Code users:** Add the following to your project's `CLAUDE.md` to help the agent know when to call pop-pay:
> *"When you encounter a payment form or checkout page, use the `request_virtual_card` tool. For billing/contact info forms, use `request_purchaser_info` first."*
## Configuration
Core variables in `~/.config/pop-pay/.env`. See [ENV_REFERENCE.md](./docs/ENV_REFERENCE.md) for the full list.
| Variable | Default | Description |
|---|---|---|
| `POP_ALLOWED_CATEGORIES` | `["aws","cloudflare"]` | Approved vendor categories โ see [Categories Cookbook](./docs/CATEGORIES_COOKBOOK.md) |
| `POP_MAX_PER_TX` | `100.0` | Max USD per transaction |
| `POP_MAX_DAILY` | `500.0` | Max USD per day |
| `POP_BLOCK_LOOPS` | `true` | Block hallucination/retry loops |
| `POP_AUTO_INJECT` | `true` | Enable CDP card injection |
| `POP_GUARDRAIL_ENGINE` | `keyword` | `keyword` (zero-cost) or `llm` (semantic) |
### Guardrail Mode
| | `keyword` (default) | `llm` |
|---|---|---|
| **Mechanism** | Keyword matching on reasoning string | Semantic analysis via LLM |
| **Cost** | Zero โ no API calls | One LLM call per request |
| **Best for** | Development, low-risk workflows | Production, high-value transactions |
> To enable LLM mode, see [Integration Guide ยง1](./docs/INTEGRATION_GUIDE.md#guardrail-mode-configuration).
## Providers
| Provider | Description |
|:---|:---|
| **BYOC** (default) | Bring Your Own Card โ encrypted vault credentials, local CDP injection. |
| **Stripe Issuing** | Real virtual cards via Stripe API. Requires `POP_STRIPE_KEY`. |
| **Lithic** | Multi-issuer adapter (Stripe Issuing / Lithic). |
| **Mock** | Test mode with generated card numbers for development. |
**Priority:** Stripe Issuing โ BYOC Local โ Mock.
## Security
| Layer | Defense |
|---|---|
| **Context Isolation** | Card credentials never enter the agent's context window or logs |
| **Encrypted Vault** | AES-256-GCM with XOR-split salt and native scrypt key derivation (Rust) |
| **TOCTOU Guard** | Domain verified at the moment of CDP injection โ blocks redirect attacks |
| **Repr Redaction** | Automatic masking (`****-4242`) in all MCP responses, logs, and tracebacks |
See [THREAT_MODEL.md](./docs/THREAT_MODEL.md) for the full STRIDE analysis and [COMPLIANCE_FAQ.md](./docs/COMPLIANCE_FAQ.md) for enterprise details.
## Architecture
- **TypeScript** โ MCP server, CDP injection engine, guardrails, CLI
- **Rust (napi-rs)** โ Native security layer: XOR-split salt storage, scrypt key derivation
- **Node.js crypto** โ AES-256-GCM vault encryption (OpenSSL binding)
- **Chrome DevTools Protocol** โ Direct DOM injection via raw WebSocket
## Documentation
- [Threat Model](docs/THREAT_MODEL.md) โ STRIDE analysis, 5 security primitives, 10 attack scenarios
- [Guardrail Benchmark](docs/GUARDRAIL_BENCHMARK.md) โ Cross-model evaluation (Anthropic / OpenAI / Gemini) across 585 payloads, 11 attack categories
- [Compliance FAQ](docs/COMPLIANCE_FAQ.md) โ PCI DSS, SOC 2, GDPR details
- [Environment Reference](docs/ENV_REFERENCE.md) โ All POP_* environment variables
- [Integration Guide](docs/INTEGRATION_GUIDE.md) โ Setup for Claude Code, Node.js SDK, and browser agents
- [Categories Cookbook](docs/CATEGORIES_COOKBOOK.md) โ POP_ALLOWED_CATEGORIES patterns and examples
## Research Dataset & Reproduction
This repository hosts the open-source dataset and harness for the cross-vendor attacker-stability methodology described in the corresponding research paper. Reviewer/researcher reproduction artifacts:
- **Corpus** (585 attack payloads, 11 categories): [`tests/redteam/corpus/`](tests/redteam/corpus/)
- `attacks.json` โ full payload set with category labels
- `GENERATION.md` โ corpus generation protocol
- `schema.json` โ payload schema
- **Run JSONLs** (26,325 rows, 9 models ร 585 payloads ร N=5): [`tests/redteam/runs/`](tests/redteam/runs/)
- PRIMARY whitebox-no-feedback runs: `runs/adaptive/2026-04-28T19-50-*`
- Static panel runs: `runs/static/`
- Prompt-ablation (v3 / strict / paranoid): `runs/ablation/`
- **Manifest hashes**: [`tests/redteam/runs/MANIFEST.sha256`](tests/redteam/runs/MANIFEST.sha256) โ byte-level integrity for all artifacts
- **Croissant 1.0 metadata** (Core + RAI fields): [`paper-artifacts/croissant.json`](paper-artifacts/croissant.json)
- **Reproduction scripts** (regenerate paper tables/figures from JSONL):
- `python3 paper-artifacts/gen-tables.py --table all` โ Tab.~bypassk / threat-ablation / cross-vendor
- `python3 paper-artifacts/gen-taxonomy-map.py` โ Fig.~taxonomy-map
- **License**: corpus CC BY-SA 4.0, harness MIT.
For dataset schema, statistical methodology (bootstrap CI, Holm-Bonferroni, McNemar), full from-scratch re-collection instructions, JSONL row data dictionary, and responsible-disclosure policy, see **[docs/PAPER_REPRODUCTION.md](docs/PAPER_REPRODUCTION.md)**.
## License
MIT