Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.qwedai.com/llms.txt

Use this file to discover all available pages before exploring further.

Verify AI-driven commerce transactions before they reach payment. PyPI version Tests License

​
What is QWED-UCP?

QWED-UCP provides deterministic verification guards for the Universal Commerce Protocol (UCP) - Google’s open standard for AI-driven commerce.

​
The problem

When AI agents shop on behalf of users, they can make calculation errors that result in:
  • 💸 Wrong totals - Customers overcharged or undercharged
  • 📉 Bad discounts - Percentage calculations off
  • 🧾 Incorrect tax - Legal compliance issues
  • 💱 Currency errors - International payment failures

​
The solution

QWED-UCP intercepts checkout requests and mathematically verifies every calculation before payment: 
AI Agent → UCP Checkout → QWED-UCP Guard → Payment Gateway
                              │
                         ✅ Pass → Continue
                         ❌ Fail → Block + Error

​
How it works

┌─────────────────────────────────────────────────────────────────┐
│                    AI Shopping Agent                             │
│                    (Claude, GPT, etc.)                           │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           │ UCP Checkout Request
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                    QWED-UCP Middleware                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐ │
│  │ Money Guard  │  │ State Guard  │  │   Line Items Guard     │ │
│  │   ₹+$+¥     │  │  → → → →     │  │   qty × price = total  │ │
│  └──────────────┘  └──────────────┘  └────────────────────────┘ │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐ │
│  │Discount Guard│  │Currency Guard│  │    Schema Guard        │ │
│  │   10% = 10   │  │  USD/EUR/JPY │  │    JSON Validation     │ │
│  └──────────────┘  └──────────────┘  └────────────────────────┘ │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐ │
│  │ Refund Guard │  │  Tip Guard   │  │    Fee Guard           │ │
│  │  full/partial│  │  pre/post-tax│  │    service/delivery    │ │
│  └──────────────┘  └──────────────┘  └────────────────────────┘ │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │                  Attestation Guard (JWT)                   │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                                                  │
│                     All Guards Pass?                             │
│                    YES ─────┬───── NO                            │
│                             │                                    │
└─────────────────────────────┼────────────────────────────────────┘
                              │
              ┌───────────────┴────────────────┐
              ▼                                ▼
        ┌──────────┐                    ┌──────────────┐
        │ Payment  │                    │ 422 Error    │
        │ Gateway  │                    │ + Details    │
        └──────────┘                    └──────────────┘

​
The 10 guards

GuardWhat it verifiesError when wrong
Money Guardtotal = subtotal - discount + tax”Calculated 98.25, Agent claimed 100.00” (Checked via SymPy)
State GuardValid checkout state transitions”Invalid transition: completed → incomplete” (Checked via Z3 Solver)
Schema GuardUCP JSON schema compliance”Missing required field: currency”
Line Items Guardprice × quantity = line_total”Line item mismatch: 2 × 35≠35 ≠ 65”
Discount GuardPercentage and fixed discount math”10% of 100shouldbe100 should be 10, not $15”
Currency GuardISO 4217 codes, JPY no-decimals”JPY cannot have decimal amounts”
Refund GuardFull/partial refund amounts, tax reversals”Refund 150exceedsoriginaltotal150 exceeds original total 100”
Tip GuardPre/post-tax tip calculations, bounds”Tip exceeds 100% of base amount”
Fee GuardService fees, delivery fees, platform fees”Platform fee 50% exceeds 30% maximum”
Attestation GuardCryptographic proof of verification (JWT)“Attestation token expired”

​
Installation

​
Python (PyPI)

pip install qwed-ucp

​
Node.js (npm)

npm install qwed-ucp-middleware

​
Quick start

​
Basic verification

from qwed_ucp import UCPVerifier

verifier = UCPVerifier()

# Verify a checkout
result = verifier.verify_checkout({
    "currency": "USD",
    "status": "ready_for_complete",
    "line_items": [
        {"id": "roses", "quantity": 2, "item": {"price": 35.00}},
        {"id": "vase", "quantity": 1, "item": {"price": 15.00}}
    ],
    "totals": [
        {"type": "subtotal", "amount": 85.00},  # 2×35 + 1×15 = 85 ✓
        {"type": "discount", "amount": 8.50},   # 10% off
        {"type": "tax", "amount": 6.29},        # 8.2% tax on $76.50
        {"type": "total", "amount": 82.79}      # 85 - 8.50 + 6.29 = 82.79 ✓
    ]
})

if result.verified:
    print("✅ Checkout verified! Safe to proceed to payment.")
else:
    print(f"❌ Verification failed: {result.error}")
    print(f"   Guard: {result.failed_guard}")

​
Middleware integration (FastAPI)

from fastapi import FastAPI
from qwed_ucp.middleware.fastapi import QWEDUCPMiddleware

app = FastAPI()

# Add QWED-UCP middleware - automatically verifies all /checkout endpoints
app.add_middleware(QWEDUCPMiddleware)

@app.post("/checkout")
async def checkout(request: CheckoutRequest):
    # If we get here, QWED-UCP already verified the math!
    return {"status": "completed", "order_id": "ORD-123"}

​
Middleware integration (Express.js)

const express = require('express');
const { createQWEDUCPMiddleware } = require('qwed-ucp-middleware');

const app = express();

// Add QWED-UCP middleware
app.use('/checkout', createQWEDUCPMiddleware());

app.post('/checkout', (req, res) => {
    // If we get here, QWED-UCP already verified the math!
    res.json({ status: 'completed', orderId: 'ORD-123' });
});

​
GitHub Action (CI/CD)

Use QWED-UCP as a GitHub Action to audit transaction logs in your CI/CD pipeline.

​
Installation

Add to your workflow (.github/workflows/commerce-audit.yml): 
name: Commerce Audit

on:
  push:
    paths:
      - 'logs/transactions/**'

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Audit Commerce Transactions
        uses: QWED-AI/qwed-ucp@v0.2.0
        with:
          log_path: logs/transactions/
          strict_mode: true

​
Parameters

InputDescriptionDefault
log_pathPath to transaction JSON logs./logs/
strict_modeFail on any violationtrue
toleranceRounding tolerance (cents)0.01

​
What gets audited

The Action scans all .json files in the specified path and verifies:
  • ✅ Line item math: price × quantity = total
  • ✅ Discount calculations
  • ✅ Tax amounts
  • ✅ Currency format (ISO 4217)
  • ✅ No “Penny Slicing” (rounding theft)

​
Example output

🛡️ QWED-UCP Audit: 3 vulnerabilities blocked

1. ❌ Penny Slicing: tx_001.json - Tax $7.99 should be $8.00
2. ❌ Zombie Return: tx_045.json - Return without original order
3. ❌ Phantom Discount: tx_089.json - 15% discount on non-sale item

Action: BLOCKED (Exit Code 1)

​
Why QWED-UCP?

​
Business impact

ScenarioWithout QWED-UCPWith QWED-UCP
AI miscalculates 10% discount as 15%Customer overcharged $5❌ Blocked, 422 returned
Tax calculation rounds wrongLegal audit issues✅ Caught before payment
Currency format invalidPayment gateway rejects✅ Caught at middleware
State transition invalidOrder stuck in limbo✅ Proper error message

​
ROI calculation

For a platform processing 100M transactions/year:
  • Error rate without verification: ~0.1%
  • Errors per year: 100,000 transactions
  • Average error cost: $6.39 (dispute handling + refunds)
  • Potential loss: $638,700/year
QWED-UCP catches these errors before they become expensive problems.

​
Configuration

​
Environment variables

VariableDescriptionDefault
QWED_UCP_STRICTFail on any schema mismatchtrue
QWED_UCP_LOG_LEVELLogging levelINFO
QWED_UCP_TOLERANCETolerance for rounding (cents)0.01

​
Custom guard configuration

from qwed_ucp import UCPVerifier, MoneyGuard

# Custom tolerance for floating-point errors
verifier = UCPVerifier(
    money_guard=MoneyGuard(tolerance=0.02),  # $0.02 tolerance
    strict_mode=False  # Allow minor schema violations
)

​
Next steps