Paycurb documentation
How the proxy decides, what each policy field does, and every endpoint it serves. Everything here is read from the code that runs.
Overview
Paycurb is a payment firewall for AI agents that pay through PayPal. Your agent calls Paycurb's MCP tools instead of PayPal's. Before any money moves, the proxy reads the merchant, prices and category from its own registry, checks the order against your policy, and only then calls PayPal.
Every call ends in one of three outcomes, and each one carries a rule id and a plain English reason the agent can pass on.
- Allowed
- Within policy. The order goes to the PayPal sandbox and the answer carries the order id and capture id.
- Held
- Nothing is paid yet. The order waits on the approvals page until you approve it, reject it, or it expires.
- Blocked
- Nothing reaches PayPal. The rule that stopped it is in rule_id and the block is written to the audit log.
This workspace is a shared sandbox. It only talks to the PayPal sandbox, and nothing in it moves real money.
Quickstart
- Write your policy in plain English. On the policy page, describe limits in dollars, the merchants you trust and what needs your approval. A model drafts the policy, you read it back, and nothing applies until you activate it.
- Connect your agent. Add Paycurb as an MCP server. The x-agent-id header names the agent in the log; without it the agent is recorded as demo-agent.
- Send a first payment request. Have the agent call create_order. The decision shows up on the feed within a second.
- Approve a held order. Orders at or above your approval line wait on the approvals page. Approve one and the proxy pays it.
{
"mcpServers": {
"paycurb": {
"type": "http",
"url": "https://paycurb-proxy-rickygole32-8911s-projects.vercel.app/mcp",
"headers": {
"x-agent-id": "office-agent"
}
}
}
}curl -s https://paycurb-proxy-rickygole32-8911s-projects.vercel.app/mcp \
-H 'content-type: application/json' \
-H 'accept: application/json, text/event-stream' \
-H 'x-agent-id: office-agent' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'Policies
A policy is one JSON object checked against a strict schema. You write it in plain English and the compiler turns it into these fields. Anything you did not say gets the strict default, so a short policy is a tight one. The compiler asks a question instead of guessing when a rule is ambiguous, and the read back is built from the fields themselves, not from the model.
Amounts are in cents. The workspace starts on version 1, the default policy below. If you allow merchants but name no categories, the categories of those merchants are allowed.
| Field | What it does | Rule | Workspace default | Strict default |
|---|---|---|---|---|
currency | The only currency accepted. Anything else is blocked. | R01 | USD | USD |
per_transaction_limit_cents | The largest single payment. A larger one is blocked. | R06 | $100.00 | $50.00 |
auto_approve_below_cents | Your approval line. A purchase at or above it is held for you. | R14 | $50.00 | $25.00 |
daily_limit_cents | Total spend in one day, counted in the proxy's POLICY_TIMEZONE. Going over is blocked. | R07 | $200.00 | $100.00 |
merchant_window_limit | Spend at one merchant inside a rolling window. Going over is blocked. | R08 | $120.00 per 60 min | $60.00 per 60 min |
merchant_allowlist | Merchants you trust. A purchase elsewhere is held or blocked, see unknown_merchant_action. | R13 | acme-office, paper-co | none |
merchant_blocklist | Merchants that are always blocked. | R04 | none | none |
unknown_merchant_action | What happens at a merchant that is not on the allowlist: block or escalate. | R04 | block | block |
allowed_categories | Merchant categories that may be bought from. An empty list blocks every category. | R05 | office_supplies | none |
block_recurring | Blocks subscriptions and recurring payments. | R03 | true | true |
max_quantity_per_line | The most units of one item in one order. | R10 | 10 | 5 |
velocity | How many payments may go through inside a rolling window. | R09 | 5 per 60 min | 5 per 60 min |
refunds | Refunds are held for you (escalate) or blocked. | R12 | escalate | escalate |
payouts | Payouts are held for you (escalate) or blocked. | R12 | block | block |
duplicate_window_minutes | An identical purchase inside this window is held for you. | R11 | 10 min | 10 min |
approval_ttl_minutes | How long a held order waits for you before it expires. | R15 | 1440 min | 15 min |
Spend at most $200 per day. Allow up to $100 per purchase. Ask me before any purchase of $50 or more. Only buy from Paper Co. Never allow payouts.{
"version": 1,
"currency": "USD",
"per_transaction_limit_cents": 10000,
"auto_approve_below_cents": 5000,
"daily_limit_cents": 20000,
"merchant_window_limit": {
"cents": 12000,
"window_minutes": 60
},
"merchant_allowlist": [
"acme-office",
"paper-co"
],
"merchant_blocklist": [],
"unknown_merchant_action": "block",
"allowed_categories": [
"office_supplies"
],
"block_recurring": true,
"max_quantity_per_line": 10,
"velocity": {
"max_transactions": 5,
"window_minutes": 60
},
"refunds": "escalate",
"payouts": "block",
"duplicate_window_minutes": 10,
"approval_ttl_minutes": 1440
}Rules are checked in order: currency (R01), amount and line items (R02), recurring (R03), merchant lists (R04), category (R05), per payment limit (R06), daily limit (R07), merchant window (R08), velocity (R09), quantity (R10). Then a passing purchase can still be held: duplicate (R11), refund or payout (R12), merchant not on the allowlist (R13), at or above the approval line (R14). R00 is a fail closed block and R99 is allowed.
Approvals
- Bound to the exact order. A hold is stored with a hash of the whole tool call. A different merchant, item, quantity or amount is a new order and is checked again from the start.
- Executed by the proxy on approve. When you approve, the proxy sends the held call to PayPal itself and records the status and PayPal reference on the approval. The agent does not need to call again.
- Used once. After it pays, the approval is marked executed. A call that passes the same approval_id again is blocked with R15.
- Expires. A hold waits approval_ttl_minutes: 1440 minutes, 24 hours, in the workspace default policy, and 15 minutes for a compiled policy that does not set it. An expired hold is never paid.
- Capped. At most 50 holds can wait at once. Past that, new holds are blocked with R16, so a runaway agent cannot flood the queue.
An agent that repeats a held call before you decide gets the same hold back with its approval_id.
{
"decision": "escalate",
"rule_id": "R14",
"reason": "Needs approval: $99.98 is at or above the $50.00 auto-approve line",
"approval_id": "APPROVAL_ID"
}Audit log
Every decision, approval, policy activation and reset is appended to the audit log. Each row stores the hash of the row before it, and its own hash is SHA-256 over that previous hash and the row's canonical JSON. The first row chains from 64 zeros.
GET /api/audit/verify walks the whole log from the first row and recomputes every hash. It answers ok with the number of rows checked, or the sequence number of the first row that does not match. Reasons are redacted before they are written, and the application role can only insert and read the table.
{
"ok": true,
"checked": 214,
"first_broken_seq": null
}API reference
The dashboard and the proxy share an origin, so /api calls carry the session cookie. Routes marked session answer 401 with { "error": "login required" } without it. Errors are JSON with an error field.
Session
POST
/api/loginNo authBody { password }. Sets the paycurb_session cookie, HTTP only, for 12 hours. Rate limited to 10 calls a minute per client address.
{ "ok": true }Errors: 401 { "error": "wrong password" }, 429 { "error": "too many requests" }
POST
/api/logoutNo authClears the session cookie.
{ "ok": true }GET
/api/sessionNo authSays whether the cookie on this request is a valid session.
{ "ok": true }
Policy
POST
/api/policy/compileSessionBody { text }, up to 4000 characters. A model drafts a policy from plain English. Nothing is activated.
{ "policy": { ... }, "readback": ["Block any single purchase above $100.00.", ...], "questions": [] }Errors: 400 { "error": "text is required" }, 503 { "error": "model_unavailable", "message": "..." }
POST
/api/policy/activateSessionBody { policy, source_text }. Missing fields get the strict defaults, the result is checked against the schema, and it becomes the next version.
{ "version": 2 }Errors: 400 { "error": "policy is not valid" }
GET
/api/policy/activeSessionThe policy in force.
{ "version": 2, "policy": { ... }, "source_text": "...", "created_at": "2026-10-31T16:02:11.000Z" }Errors: 404 { "error": "no active policy" }
GET
/api/policy/versionsSessionEvery version, newest first.
[{ "version": 2, "active": true, "created_at": "...", "source_text": "..." }]
Decisions and approvals
GET
/api/statsSessionToday's spend against the daily limit, and counts.
{ "spent_today_cents": 4999, "remaining_cents": 15001, "pending_approvals": 1, "blocked_count": 4 }GET
/api/decisions?limit=50SessionRecent decisions, newest first. limit defaults to 50, at most 200.
[{ "id": 12, "action_id": "...", "ts": "...", "tool": "create_order", "kind": "purchase", "merchant_id": "paper-co", "merchant_name": "Paper Co", "amount_cents": 9998, "decision": "escalate", "rule_id": "R14", "reason": "...", "policy_version": 1, "paypal_ref": null, "payload_hash": "...", "action": { ... } }]GET
/api/approvals?status=pendingSessionHeld orders. Without status, the 100 most recent of any status.
[{ "id": "...", "action_id": "...", "status": "pending", "created_at": "...", "expires_at": "...", "amount_cents": 9998, "merchant_id": "paper-co", "merchant_name": "Paper Co", "rule_id": "R14", "reason": "...", "line_items": [{ "sku": "NOTE-5", "qty": 2, "unit_cents": 4999 }], "execution": null }]POST
/api/approvals/:id/approveSessionApproves a pending hold and the proxy runs the held call at PayPal before it answers.
The updated approval, with "execution": { "status": "COMPLETED", "paypal_ref": "..." }Errors: 404 { "error": "approval not found" }, 409 { "error": "approval is expired" } or { "error": "approval is not pending" }
POST
/api/approvals/:id/rejectSessionRejects a pending hold. Nothing is paid.
The updated approval, with "status": "rejected"
Errors: Same as approve
GET
/api/streamSessionServer sent events. decision carries a decision row, approval carries an approval, ping arrives every 15 seconds.
event: decision data: { "id": 12, ... }
Audit
GET
/api/audit?cursor=0&limit=100SessionAudit rows after cursor, oldest first. limit defaults to 100, at most 500. next_cursor is null on the last page.
{ "rows": [{ "seq": 1, "ts": "...", "action_id": null, "tool": "policy", "kind": "policy", "amount_cents": null, "merchant_id": null, "decision": "allow", "rule_id": "R99", "reason": "Policy version 1 activated", "policy_version": 1, "payload_hash": null, "paypal_ref": null, "prev_hash": "000...", "entry_hash": "..." }], "next_cursor": null }GET
/api/audit/verifySessionRecomputes every hash from the first row.
{ "ok": true, "checked": 214, "first_broken_seq": null }
Workspace
GET
/api/attacks/latestSessionThe latest attack suite report.
{ "generated_at": "...", "headline": { ... }, ... } or { "report": null }POST
/api/attacks/runSessionStarts the attack suite, when the deployment allows it.
{ "started": true }Errors: 403 { "error": "demo mode is off" }, 501 when the suite cannot run on this host
POST
/api/demo/resetSessionClears spend counters, approvals and decisions, restores the default policy, and holds one sample order.
{ "ok": true }Errors: 403 { "error": "demo mode is off" }
GET
/healthzNo authLiveness check.
{ "ok": true }ANY
/mcpNo authThe MCP endpoint, streamable HTTP. Rate limited to 120 calls a minute per client address.
MCP JSON responses
MCP tools
The /mcp endpoint speaks MCP over streamable HTTP with JSON responses. Tool names match the PayPal agent toolkit. Every result is one text block holding JSON with decision, rule_id and reason, plus order, refund or approval_id when they apply. Any other tool name is blocked with R00.
create_orderPurchase, checked by every spending rule
Create and pay a PayPal order for items from one merchant. Costs are in dollars. Required: currencyCode (USD), payee, items. Each item needs name, quantity, itemCost and itemTotal, and may carry sku. Pass approval_id when repeating a held call.
get_orderRead only, always allowed
Look up a PayPal order by id. Required: id.
create_refundRefund, follows the refunds field
Refund part or all of a captured payment. Required: capture_id and amount in dollars, optional note_to_payer. A refund larger than what is left of the purchase is blocked.
{
"name": "create_order",
"arguments": {
"currencyCode": "USD",
"payee": "paper-co@merchants.example",
"items": [
{
"sku": "NOTE-5",
"name": "Notebooks 5 Pack",
"quantity": 2,
"itemCost": 49.99,
"itemTotal": 99.98
}
]
}
}Limits and threat model
Paycurb bounds what a compromised agent can spend for payments that pass through the proxy. It does not stop misuse inside your policy, and it cannot see a route to PayPal that skips the proxy.
- The /mcp endpoint has no caller authentication. Anyone who can reach it can ask for payments, limited by the policy and the rate limit.
- After a PayPal timeout or server error the call is blocked and the amount stays reserved, but PayPal may have charged. Nothing reconciles this automatically.
- The hash chain detects edits. It does not stop someone with database owner access from rewriting the whole log.
- The proxy refuses to start unless PAYPAL_ENV is sandbox.