PayWings

Policy-governed payments for AI agents. Agents pay through MCP or the terminal, and only within rules their human owner sets.

Leia em português · Design spec (pt-BR)

Sandbox only. No real money moves. Cards use the 411111 test BIN and Pix settlement is simulated.

Why

Prompt injection can talk an agent into anything, so spending rules can't live inside the agent. PayWings keeps them on the server:

• The agent asks, the server decides. Every purchase is a payment intent evaluated by a deterministic policy engine. The agent has no tool to approve, top up, or change limits.

• The data decides, not the agent's claim. For Pix, the payee is read from the BR Code itself. A code that says "Trusted Store" but points to someone else's key is denied.

• Minimal exposure. Cards are single-use, locked to one merchant and amount, and expire after 30 minutes.

• Humans approve out of band. Payments above a threshold wait for the owner. In the sandbox, every owner command that changes money or limits asks for an owner key the agent never holds, and approve also requires an interactive terminal.

• Everything is auditable. Every event goes into an append-only, hash-chained log: intent, decision, approval, execution. Card numbers never reach the log.

Related MCP server: MandateGuard

Install

Requires Node 22.18 or newer.

npm install --global paywings
paywings init       # creates ~/.paywings/sandbox.db with a "demo" agent and R$ 500.00

Or run without installing: npx paywings init. In that case, end the claude mcp add command that init prints with -- npx -y paywings mcp instead of -- paywings mcp. Versions follow semver; see the changelog.

Connect an agent

paywings init prints the agent key and a ready-made command to register the MCP server with Claude Code:

claude mcp add paywings --env PAYWINGS_AGENT_KEY=pw_test_... --env PAYWINGS_DB=~/.paywings/sandbox.db -- paywings mcp

Using Claude Desktop or Cursor? See docs/mcp-clients.md.

Then ask your agent to, for example, "upgrade my Vercel plan". It calls request_payment and gets back one of three results:

• executed, with a single-use card or a Pix receipt;

• pending_approval, while it waits for you;

• denied, with machine-readable reasons.

MCP tools

Policy

Each agent has its own policy, checked in this order:

1. Kill switch: is the agent frozen?

2. Allowed rails.

3. Pix code validity, and the amount encoded in it.

4. Merchant allow-list. A domain also matches its subdomains, but lookalikes such as vercel.com.evil.io don't match.

5. Blocked categories.

6. Per-transaction limit.

7. Monthly limit. Pending payments count toward it. Months start at midnight in PAYWINGS_TZ (default America/Sao_Paulo).

8. Payments per hour.

9. Balance.

10. Human-approval threshold. Dynamic Pix codes (which name only the PSP, not the final payee) always go to a human.

All failing rules are reported at once.

Owner commands

init also prints an owner key; store it in a password manager. Commands that create agents, change limits, top up, unfreeze, approve or reject ask for the owner key. Type it at the prompt (it isn't echoed) or pipe it as the first line of stdin. Never put it in an environment variable or file your agent can read: an agent with shell access can run the CLI too. Freezing needs no key, since stopping an agent is always safe.

Sandboxes created before the owner key existed: run paywings owner setup once.

paywings agents create research --balance 300 --per-tx 100 --monthly 500 --approve-above 30 --merchants vercel.com,openai.com
paywings pending
paywings approve pay_...          # owner key + interactive terminal; you type the amount to confirm
paywings reject pay_... --note "not now"
paywings agents freeze research   # kill switch
paywings audit verify             # checks the hash chain

Agent commands (terminal)

export PAYWINGS_AGENT_KEY=pw_test_...
paywings pay --amount 19.90 --rail card --merchant Vercel --domain vercel.com --category software --reason "upgrade requested by the user"
paywings pay --amount 35.90 --rail pix --merchant Store --pix "$(paywings pix-code --key store@example.com --name Store --city 'Sao Paulo' --amount 35.90)" --category office --reason "..."
paywings status pay_...

CLI output is in Portuguese for now. pay and status print JSON.

Development

npm install
npm test
npm run typecheck
npm run smoke:package

See CONTRIBUTING.md for commit and release conventions.

Roadmap

1. Sandbox (this repo): policies, approvals, Pix and card simulation, audit log.

2. Real money, small volume:

   • cards through a BaaS issuer or Stripe Issuing;

   • Pix through a licensed payment initiator (Open Finance);

   • REST API, WhatsApp approvals, web dashboard.

3. Network protocols: agentic tokens from the card networks, ACP/AP2, x402.

Security

The sandbox's database is a local file your agent's OS user can write. Read SECURITY.md for what is and isn't protected, and how to report a vulnerability.

License

Apache-2.0