AchPay

Agentic Commerce Hub for Secure AI Payments

An open, deterministic protocol that gives AI agents a wallet they cannot misuse. Built with cryptographically signed quotes, pure policy validation, database idempotency, and tamper-evident audit chains.

Overview

Allowing an autonomous LLM to spend money is inherently risky. Traditional payment flows accept dynamic amounts from client code, leaving systems vulnerable to prompt injection, hallucinations, hallucinated prices, and runaway loops.

AchPay resolves this by enforcing strict separation between agent intent and financial execution:

• Agents never touch prices or amounts. The only handle an agent possesses is an expiring, catalog-backed quote_id.

• Untrusted merchant text cannot execute instructions. Product descriptions are isolated and withheld from decision paths.

• Spending limits are hard constraints. Policies evaluate deterministically without external network or database side effects.

• Every state transition is verifiable. All actions are recorded on an insert-only, cryptographic hash-chained audit ledger.

Related MCP server: Allowance MCP

Core Defense Layers

AchPay processes all agent transactions through six deterministic defense layers:

Quick Start

Prerequisites

• Node.js >= 20.0.0 and pnpm >= 9.0.0

• Docker Desktop (PostgreSQL & Redis)

• ngrok (optional, for live Razorpay webhook testing)

Installation

# Clone the repository
git clone https://github.com/Anas-github-acc/AchPay.git
cd AchPay

# Install dependencies
pnpm install

# Start local PostgreSQL (port 55432) and Redis (port 56379)
docker compose up -d

# Set up local environment
cp .env.example .env

Run Services

Start the Fastify API (:3000), Next.js Dashboard (:3001), and Webhook Tunnel with a single command:

pnpm dev:all

Run without ngrok tunnel: pnpm dev:all --no-tunnel

Open http://localhost:3001 to explore the audit ledger, mandate headroom, and the live security attack matrix.

MCP Protocol

AchPay provides an MCP server implementing standard tools for Claude Desktop, Cursor, and custom agent runtimes. Tools communicate over stdio or authenticated HTTP SSE.

Registered Agent Tools

• search_products — Search catalog items (SKU, title, price in integer paise, category). Excludes untrusted prose.

• get_product_details — Retrieve isolated product copy for a specific SKU.

• get_quote — Price a basket of { sku, qty } items; returns a cryptographically signed, expiring quote_id.

• create_checkout — Submit a transaction using quote_id and mandate_id. Returns charged, pending_approval, or denied.

• get_order_status — Inspect asynchronous payment settlement or human approval status.

• list_receipts — Read settled transaction history directly from the ledger.

Claude Desktop Integration

Add AchPay to your claude_desktop_config.json:

{
  "mcpServers": {
    "achpay": {
      "command": "pnpm",
      "args": ["--dir", "/path/to/AchPay", "mcp"]
    }
  }
}

Or configure directly via CLI:

pnpm mcp:add

Spending Policy

Spending boundaries are defined in policy.yaml. The policy engine executes purely over structured values with zero database or network dependencies:

# Transaction caps (in integer paise: 100 paise = 1 INR)
per_txn_max_paise: 50000          # ₹500 max per transaction
daily_max_paise: 500000           # ₹5,000 rolling 24-hour limit
velocity_max_per_hour: 5          # Max 5 checkouts per hour

# Human gate threshold
gate_above_paise: 30000           # > ₹300 requires human confirmation

# Denied categories
category_denylist:
  - alcohol
  - tobacco

# Choice bounding against prompt manipulation
max_qty_per_sku: 3
max_line_items: 10
gate_if_price_above_category_median_multiple: 2.0

Verification & Testing

AchPay ships with automated verification routines and an adversarial attack grid simulating hostile merchant feeds and prompt injection vectors:

# Run unit and integration tests
pnpm test

# Run adversarial attack grid (writes data/adversarial-results.json)
pnpm test:adversarial

# Walk the cryptographic hash chain and verify ledger integrity
pnpm verify:ledger

# Reclaim expired headroom allocations
pnpm reclaim

License

MIT © AchPay Contributors