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

  1. 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.
  2. 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.
  3. Send a first payment request. Have the agent call create_order. The decision shows up on the feed within a second.
  4. Approve a held order. Orders at or above your approval line wait on the approvals page. Approve one and the proxy pays it.
MCP client config
{
  "mcpServers": {
    "paycurb": {
      "type": "http",
      "url": "https://paycurb-proxy-rickygole32-8911s-projects.vercel.app/mcp",
      "headers": {
        "x-agent-id": "office-agent"
      }
    }
  }
}
List the tools with curl
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.

FieldWhat it doesRuleWorkspace defaultStrict default
currencyThe only currency accepted. Anything else is blocked.R01USDUSD
per_transaction_limit_centsThe largest single payment. A larger one is blocked.R06$100.00$50.00
auto_approve_below_centsYour approval line. A purchase at or above it is held for you.R14$50.00$25.00
daily_limit_centsTotal spend in one day, counted in the proxy's POLICY_TIMEZONE. Going over is blocked.R07$200.00$100.00
merchant_window_limitSpend at one merchant inside a rolling window. Going over is blocked.R08$120.00 per 60 min$60.00 per 60 min
merchant_allowlistMerchants you trust. A purchase elsewhere is held or blocked, see unknown_merchant_action.R13acme-office, paper-conone
merchant_blocklistMerchants that are always blocked.R04nonenone
unknown_merchant_actionWhat happens at a merchant that is not on the allowlist: block or escalate.R04blockblock
allowed_categoriesMerchant categories that may be bought from. An empty list blocks every category.R05office_suppliesnone
block_recurringBlocks subscriptions and recurring payments.R03truetrue
max_quantity_per_lineThe most units of one item in one order.R10105
velocityHow many payments may go through inside a rolling window.R095 per 60 min5 per 60 min
refundsRefunds are held for you (escalate) or blocked.R12escalateescalate
payoutsPayouts are held for you (escalate) or blocked.R12blockblock
duplicate_window_minutesAn identical purchase inside this window is held for you.R1110 min10 min
approval_ttl_minutesHow long a held order waits for you before it expires.R151440 min15 min
Plain English the compiler accepts
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.
The workspace default policy
{
  "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.

A held answer
{
  "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.

Verify response
{
  "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 auth

    Body { 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 auth

    Clears the session cookie.

    { "ok": true }
  • GET/api/sessionNo auth

    Says whether the cookie on this request is a valid session.

    { "ok": true }

Policy

  • POST/api/policy/compileSession

    Body { 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/activateSession

    Body { 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/activeSession

    The 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/versionsSession

    Every version, newest first.

    [{ "version": 2, "active": true, "created_at": "...", "source_text": "..." }]

Decisions and approvals

  • GET/api/statsSession

    Today'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=50Session

    Recent 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=pendingSession

    Held 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/approveSession

    Approves 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/rejectSession

    Rejects a pending hold. Nothing is paid.

    The updated approval, with "status": "rejected"

    Errors: Same as approve

  • GET/api/streamSession

    Server 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=100Session

    Audit 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/verifySession

    Recomputes every hash from the first row.

    { "ok": true, "checked": 214, "first_broken_seq": null }

Workspace

  • GET/api/attacks/latestSession

    The latest attack suite report.

    { "generated_at": "...", "headline": { ... }, ... } or { "report": null }
  • POST/api/attacks/runSession

    Starts 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/resetSession

    Clears 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 auth

    Liveness check.

    { "ok": true }
  • ANY/mcpNo auth

    The 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_order

    Purchase, 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_order

    Read only, always allowed

    Look up a PayPal order by id. Required: id.

  • create_refund

    Refund, 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.

create_order call
{
  "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.

Read the full threat model on GitHub