{"id":45738236,"url":"https://github.com/mkmkkkkk/paysentry","last_synced_at":"2026-03-10T19:00:46.882Z","repository":{"id":336985308,"uuid":"1151733647","full_name":"mkmkkkkk/paysentry","owner":"mkmkkkkk","description":"The missing control plane for AI agent payments. Observe, control, protect, and test agent spending across x402, ACP, AP2, and Visa TAP.","archived":false,"fork":false,"pushed_at":"2026-03-08T11:29:56.000Z","size":7591,"stargazers_count":4,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-08T14:46:43.308Z","etag":null,"topics":["agent-payments","ai-agents","control-plane","fintech","observability","payments","policy-engine","spending-limits","typescript","x402"],"latest_commit_sha":null,"homepage":"https://mkyang.ai/paysentry","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mkmkkkkk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-06T20:42:54.000Z","updated_at":"2026-03-08T11:30:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mkmkkkkk/paysentry","commit_stats":null,"previous_names":["mkmkkkkk/paysentry"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mkmkkkkk/paysentry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkmkkkkk%2Fpaysentry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkmkkkkk%2Fpaysentry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkmkkkkk%2Fpaysentry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkmkkkkk%2Fpaysentry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mkmkkkkk","download_url":"https://codeload.github.com/mkmkkkkk/paysentry/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkmkkkkk%2Fpaysentry/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30348851,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T15:55:29.454Z","status":"ssl_error","status_checked_at":"2026-03-10T15:54:58.440Z","response_time":106,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-payments","ai-agents","control-plane","fintech","observability","payments","policy-engine","spending-limits","typescript","x402"],"created_at":"2026-02-25T12:00:30.028Z","updated_at":"2026-03-10T19:00:46.876Z","avatar_url":"https://github.com/mkmkkkkk.png","language":"TypeScript","funding_links":[],"categories":["🔒 Security \u0026 Audits"],"sub_categories":["Security Monitoring"],"readme":"# PaySentry\n\n**Payment control plane for AI agents** — spending limits, circuit breakers, and audit trails for x402, MCP, and autonomous agent payments.\n\n[![npm](https://img.shields.io/npm/v/@paysentry/core?label=%40paysentry%2Fcore)](https://www.npmjs.com/package/@paysentry/core)\n[![npm](https://img.shields.io/npm/v/@paysentry/x402?label=%40paysentry%2Fx402)](https://www.npmjs.com/package/@paysentry/x402)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![CI](https://github.com/mkmkkkkk/paysentry/actions/workflows/ci.yml/badge.svg)](https://github.com/mkmkkkkk/paysentry/actions/workflows/ci.yml)\n\n\u003e Your agent just authorized $500 to an API endpoint. Was that intentional?\n\n---\n\n## The Problem\n\nAI agents are spending real money with zero governance:\n\n- **x402 settlement failures drain wallets silently** — facilitator takes payment, service returns 500 ([coinbase/x402#1062](https://github.com/coinbase/x402/issues/1062))\n- **No spending limits** — one prompt injection = unlimited spend\n- **No audit trail** — \"which agent spent $2,400 last Tuesday?\"\n- **Retry storms cause duplicate payments** — failed settlements trigger retries with no dedup ([coinbase/x402#808](https://github.com/coinbase/x402/issues/808))\n- **No circuit breakers** — one flaky facilitator cascades into system-wide failures ([coinbase/x402#803](https://github.com/coinbase/x402/issues/803))\n\nPaySentry is the missing layer between your agents and their wallets.\n\n---\n\n## See it in action\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/demo-terminal.svg\" alt=\"PaySentry Demo — AI agent payments being allowed, blocked, and rate limited in real-time\" width=\"800\" /\u003e\n\u003c/p\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eText version\u003c/b\u003e (if SVG doesn't render)\u003c/summary\u003e\n\n```\n  PaySentry Demo — AI Agent Payment Controls\n  ══════════════════════════════════════════════════\n\n  Policy: Max $100/tx | Approval above $40 | Daily $500 | 5 tx/min\n  Agent:  agent-research-01  |  Balance: $10000.00\n\n  [1/5] $25.00  → api.openai.com      ✅ ALLOWED\n  [2/5] $45.00  → anthropic.com       ⚠️ REQUIRES APPROVAL\n  [3/5] $150.00 → sketchy-api.xyz     ❌ BLOCKED (above $100 limit)\n  [4/5] $30.00  → api.openai.com      ✅ ALLOWED + 🔔 repeat recipient alert\n  [5/5] 6 rapid payments              ❌ RATE LIMITED (5 tx/min)\n\n  Summary:\n    Allowed: 4  ($65.00)\n    Pending: 1  ($45.00)\n    Blocked: 2  ($150.00 + rate limit)\n    Alerts:  4  (large tx, rate spike)\n```\n\n\u003c/details\u003e\n\n**Try it yourself:**\n\n```bash\nnpx paysentry-demo\n```\n\n---\n\n## Quick Start\n\n```bash\nnpm install @paysentry/core @paysentry/control @paysentry/observe\n```\n\n### Add spending limits in 5 lines\n\n```typescript\nimport { PolicyEngine, blockAbove, requireApprovalAbove, allowAll } from '@paysentry/control';\n\nconst engine = new PolicyEngine();\n\nengine.loadPolicy({\n  id: 'production' as PolicyId,\n  name: 'Production Controls',\n  enabled: true,\n  rules: [\n    blockAbove(1000, 'USDC'),           // Hard block above $1000\n    requireApprovalAbove(100, 'USDC'),  // Human approval above $100\n    allowAll(),                         // Allow everything else\n  ],\n  budgets: [\n    { window: 'daily', maxAmount: 500, currency: 'USDC' },\n    { window: 'monthly', maxAmount: 5000, currency: 'USDC' },\n  ],\n});\n\nconst result = engine.evaluate(transaction);\n// result.action: 'allow' | 'deny' | 'require_approval' | 'flag'\n```\n\n### x402 adapter — 3 lines to protect your x402 server\n\n```bash\nnpm install @paysentry/x402\n```\n\n```typescript\nimport { PaySentryX402Adapter } from '@paysentry/x402';\nimport { PolicyEngine } from '@paysentry/control';\nimport { SpendTracker } from '@paysentry/observe';\n\nconst adapter = new PaySentryX402Adapter(\n  { policyEngine: new PolicyEngine(), spendTracker: new SpendTracker() },\n  { circuitBreaker: { failureThreshold: 5, recoveryTimeoutMs: 30_000 } },\n);\n\n// Registers all 6 lifecycle hooks: onBeforeVerify, onAfterVerify,\n// onVerifyFailure, onBeforeSettle, onAfterSettle, onSettleFailure\nadapter.withLifecycleHooks(yourX402Server);\n```\n\n---\n\n## What PaySentry Does\n\n| Problem | Solution | Package |\n|---------|----------|---------|\n| Agents spend without limits | Declarative spending policies, budget caps, approval chains | `@paysentry/control` |\n| No visibility into agent spend | Real-time transaction tracking, analytics, anomaly detection | `@paysentry/observe` |\n| x402 settlement failures lose money | Circuit breakers + retry classification per facilitator | `@paysentry/x402` |\n| No audit trail for compliance | Immutable provenance chain: intent -\u003e policy -\u003e execution -\u003e settlement | `@paysentry/protect` |\n| Can't test without real money | Mock x402, ACP, and AP2 endpoints with pre-built failure scenarios | `@paysentry/sandbox` |\n\n---\n\n## Packages\n\n| Package | Version | Description |\n|---------|---------|-------------|\n| [`@paysentry/core`](packages/core) | [![npm](https://img.shields.io/npm/v/@paysentry/core)](https://www.npmjs.com/package/@paysentry/core) | Core types, utilities, and shared infrastructure |\n| [`@paysentry/observe`](packages/observe) | [![npm](https://img.shields.io/npm/v/@paysentry/observe)](https://www.npmjs.com/package/@paysentry/observe) | Payment tracking, analytics, budget alerts, anomaly detection |\n| [`@paysentry/control`](packages/control) | [![npm](https://img.shields.io/npm/v/@paysentry/control)](https://www.npmjs.com/package/@paysentry/control) | Policy engine — rules, budgets, approval chains, middleware |\n| [`@paysentry/protect`](packages/protect) | [![npm](https://img.shields.io/npm/v/@paysentry/protect)](https://www.npmjs.com/package/@paysentry/protect) | Dispute resolution — provenance, disputes, automated recovery |\n| [`@paysentry/sandbox`](packages/sandbox) | [![npm](https://img.shields.io/npm/v/@paysentry/sandbox)](https://www.npmjs.com/package/@paysentry/sandbox) | Mock payment environment — x402, ACP, AP2 with 9 test scenarios |\n| [`@paysentry/x402`](packages/x402) | [![npm](https://img.shields.io/npm/v/@paysentry/x402)](https://www.npmjs.com/package/@paysentry/x402) | x402 protocol adapter — lifecycle hooks, circuit breakers |\n| [`@paysentry/mcp`](packages/mcp) | 1.0.0 | MCP server — 10 tools for AI agent payment control |\n| [`@paysentry/a2a`](packages/a2a) | 1.0.0 | Agent-to-agent payments — intents, mandates, escrow |\n| [`@paysentry/dashboard`](packages/dashboard) | 1.0.0 | JSON API + SSE event stream for monitoring |\n\n---\n\n## Examples\n\n### Real-time spend tracking with alerts\n\n```typescript\nimport { SpendTracker, SpendAnalytics, SpendAlerts } from '@paysentry/observe';\nimport { createTransaction, type AgentId } from '@paysentry/core';\n\nconst tracker = new SpendTracker();\nconst analytics = new SpendAnalytics(tracker);\nconst alerts = new SpendAlerts(tracker);\n\n// Alert when daily spend exceeds 80% of $500 budget\nalerts.addRule({\n  id: 'daily-budget',\n  name: 'Daily USDC Budget',\n  type: 'budget_threshold',\n  severity: 'warning',\n  enabled: true,\n  config: {\n    type: 'budget_threshold',\n    threshold: 500,\n    currency: 'USDC',\n    windowMs: 86400000,\n    alertAtPercent: 0.8,\n  },\n});\n\nalerts.onAlert((alert) =\u003e {\n  slack.send(`[${alert.severity}] ${alert.message}`);\n});\n\n// Record transactions as they happen\nconst tx = createTransaction({\n  agentId: 'research-bot' as AgentId,\n  recipient: 'https://api.openai.com/v1/chat',\n  amount: 0.05,\n  currency: 'USDC',\n  purpose: 'GPT-4 market analysis',\n  protocol: 'x402',\n});\ntx.status = 'completed';\ntracker.record(tx);\n\nconst report = analytics.getAgentAnalytics('research-bot' as AgentId);\n// report.spendByCurrency, report.topRecipients, report.anomalies\n```\n\n### Express/Fastify middleware\n\n```typescript\nimport { createPolicyMiddleware } from '@paysentry/control';\n\napp.use('/pay', createPolicyMiddleware({\n  engine,\n  approvalHandler: async (tx) =\u003e {\n    return await slack.requestApproval(tx);\n  },\n}));\n```\n\n### Payment sandbox for testing\n\n```typescript\nimport { MockX402, MockACP, ALL_SCENARIOS } from '@paysentry/sandbox';\n\nconst x402 = new MockX402({ latencyMs: 10, failureRate: 0.1 });\nconst result = await x402.processPayment(transaction);\n\n// 9 pre-built scenarios: overspend, timeout, dispute, multi-protocol, etc.\nconsole.log(ALL_SCENARIOS.map(s =\u003e s.name));\n```\n\n### MCP server for AI agents\n\n```bash\nnpm install @paysentry/mcp\n```\n\n```typescript\nimport { createPaySentryMcpServer } from '@paysentry/mcp';\n\nconst { server } = createPaySentryMcpServer({\n  agentId: 'my-agent',\n  dailyBudget: 500,\n  perTransactionLimit: 100,\n});\n\n// Agents get 10 tools: pay, check_balance, transaction_history,\n// discover_capabilities, list_policies, create_policy, evaluate_payment,\n// file_dispute, get_audit_trail, get_alerts\n\n// Add to Claude Desktop config:\n// { \"mcpServers\": { \"paysentry\": { \"command\": \"npx\", \"args\": [\"paysentry-mcp\"] } } }\n```\n\n### Agent-to-agent payments\n\n```typescript\nimport { PaymentIntentManager, MandateManager, EscrowManager } from '@paysentry/a2a';\nimport { MemoryStorage } from '@paysentry/core';\n\nconst storage = new MemoryStorage();\nconst intents = new PaymentIntentManager(storage);\nconst mandates = new MandateManager(storage);\nconst escrow = new EscrowManager(storage);\n\n// Agent A proposes payment to Agent B\nconst intent = intents.propose({\n  fromAgent: 'agent-a' as AgentId,\n  toAgent: 'agent-b' as AgentId,\n  amount: 50,\n  currency: 'USDC',\n  purpose: 'data analysis',\n});\n\n// Agent B accepts\nintents.accept(intent.id, 'agent-b' as AgentId);\n\n// Standing mandates for recurring payments\nconst mandate = mandates.create({\n  grantorAgent: 'agent-a' as AgentId,\n  granteeAgent: 'agent-b' as AgentId,\n  maxAmount: 100,\n  currency: 'USDC',\n  maxFrequency: 10,\n  windowMs: 86400000, // daily\n  expiresAt: new Date(Date.now() + 30 * 86400000).toISOString(),\n});\n```\n\nSee [`examples/`](examples/) for complete runnable demos.\n\n### Run the E2E example\n\nThe full x402 payment flow with policy enforcement, circuit breaker, spend tracking, and alerts:\n\n```bash\nnpm install \u0026\u0026 npm run build\nnpx tsx examples/05-x402-e2e.ts\n```\n\nOutput shows allow/block/alert decisions for 5 scenarios:\n1. Small payment ($5) — allowed and settled\n2. Medium payment ($75) — blocked by approval policy\n3. Large payment ($1500) — blocked by budget\n4. Multiple payments — budget threshold alert at 80%\n5. Facilitator failures — circuit breaker opens\n\n---\n\n## Architecture\n\n```\n              ┌──────────────────────────────────────────┐\n              │            Your AI Agent                  │\n              └──────────────────┬───────────────────────┘\n                                 │\n              ┌──────────────────v───────────────────────┐\n              │          MCP Server (10 tools)            │\n              │  pay · balance · history · discover       │\n              │  policies · evaluate · disputes · alerts  │\n              └──────────────────┬───────────────────────┘\n                                 │\n              ┌──────────────────v───────────────────────┐\n              │       PaySentry Control Plane             │\n              │                                          │\n              │  OBSERVE    CONTROL    PROTECT    A2A     │\n              │  tracking   policies   provenance intents │\n              │  alerts     budgets    disputes   mandate │\n              │  analytics  approval   recovery   escrow  │\n              └────┬──────────┬──────────┬──────────┬────┘\n                   │          │          │          │\n              ┌────v───┐ ┌───v────┐ ┌───v────┐ ┌───v────┐\n              │  x402  │ │  ACP   │ │  AP2   │ │Dashboard│\n              │HTTP 402│ │Stripe/ │ │Agent-  │ │JSON API │\n              │Protocol│ │Commrc  │ │to-Agent│ │SSE Feed │\n              └────────┘ └────────┘ └────────┘ └────────┘\n```\n\n---\n\n## Roadmap\n\n- [x] Core spending policies and budget enforcement\n- [x] Real-time spend tracking and anomaly detection\n- [x] Dispute resolution and automated recovery\n- [x] Multi-protocol payment sandbox (x402, ACP, AP2)\n- [x] x402 protocol adapter with circuit breakers\n- [x] MCP payment server (10 tools: pay, balance, history, discover, policy CRUD, disputes, provenance, alerts)\n- [x] Agent-to-agent payment primitives (intents, mandates, escrow, agent registry)\n- [x] Dashboard API + SSE event stream for real-time monitoring\n- [ ] AP2 / Visa TAP protocol adapters\n\n---\n\n## Development\n\n```bash\nnpm install          # Install dependencies\nnpm run build        # Build all packages\nnpm run typecheck    # Type check\nnpm test             # Run tests\nnpm run lint         # Lint\n```\n\n---\n\n## Contributing\n\nContributions welcome. Open an issue first for major changes.\n\n1. Fork the repo\n2. Create a feature branch (`git checkout -b feat/my-feature`)\n3. Write tests for new functionality\n4. Ensure `npm test` and `npm run typecheck` pass\n5. Open a PR against `main`\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkmkkkkk%2Fpaysentry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmkmkkkkk%2Fpaysentry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkmkkkkk%2Fpaysentry/lists"}