Preparing diagram...

Preparing diagram...

Preparing diagram...

传统支付:  Mastercard | American Express | JCB | UnionPay International
支付平台:  PayPal | Adyen | Worldpay | Revolut
科技巨头:  Salesforce | ServiceNow | Intuit
加密生态:  Coinbase | Mysten Labs (Sui) | Algorand | MetaMask
安全/验证: EigenLayer | Forter
电商平台:  Etsy

Preparing diagram...

// VDC 的概念结构
interface VerifiableDigitalCredential {
    // W3C VC 标准字段
    '@context': string[];
    type: string[];
    issuer: string;           // 签发者 DID
    issuanceDate: string;     // 签发时间
    credentialSubject: {
        // 具体的 Mandate 内容
        [key: string]: unknown;
    };
    proof: {
        type: string;          // 如 'Ed25519Signature2020'
        created: string;
        verificationMethod: string;
        proofPurpose: string;
        proofValue: string;    // 密码学签名
    };
}

Preparing diagram...

interface IntentMandate {
    // 用户定义的约束
    constraints: {
        maxBudget: number;              // 最高预算: 如 $200
        allowedCategories: string[];    // 允许的商品类别: ['electronics', 'kitchen']
        allowedMerchants?: string[];    // 允许的商家列表
        expiresAt: string;              // 过期时间: '2026-04-01T00:00:00Z'
        maxSingleTransaction?: number;  // 单笔最高: 如 $100
    };
    // 用户身份
    userDID: string;
    // 用户密码学签名
    userSignature: string;
    // 创建时间
    issuedAt: string;
}

用户: "帮我在 $200 以内买一台评价最好的咖啡机"
Agent: 收到 Intent Mandate → 浏览比价 → 在预算内自主下单

interface CartMandate {
    // 商家签名的购物车
    cart: {
        merchantId: string;
        items: Array<{
            productId: string;
            name: string;
            price: number;
            quantity: number;
        }>;
        totalAmount: number;
        currency: string;
        guaranteedUntil: string;    // 价格保证期限
    };
    // 商家签名 (保证履约)
    merchantSignature: string;
    // 用户签名 (确认同意)
    userSignature: string;
}

Preparing diagram...

interface PaymentMandate {
    // 来源
    derivedFrom: 'IntentMandate' | 'CartMandate';
    // Agent 上下文
    agentPresence: boolean;        // Agent 是否参与了交易
    humanPresence: 'present' | 'not-present';  // 用户是否在场
    // 最小化信息 (隐私保护)
    transactionHash: string;       // 交易哈希
    mandateReference: string;      // 原始 Mandate 引用
    // 审计字段
    cryptographicProofChain: string;  // 密码学证据链
}

Preparing diagram...

Preparing diagram...

// MCP Payment Tool 定义
const paymentTool = {
    name: 'process_payment',
    description: 'Process a payment with AP2 mandate verification',
    inputSchema: {
        type: 'object',
        properties: {
            cartMandateId: { type: 'string' },
            paymentMethodToken: { type: 'string' },
        },
        required: ['cartMandateId', 'paymentMethodToken'],
    },
};

// Agent 通过 MCP 调用支付
async function handlePayment(
    cartMandateId: string,
    paymentToken: string
): Promise<PaymentResult> {
    // AP2 自动验证 Mandate
    const mandate = await ap2.verifyCartMandate(cartMandateId);

    // 生成 Payment Mandate
    const paymentMandate = ap2.derivePaymentMandate(mandate);

    // 附加到支付请求
    const result = await paymentGateway.authorize({
        amount: mandate.cart.totalAmount,
        currency: mandate.cart.currency,
        token: paymentToken,
        ap2Mandate: paymentMandate,  // AP2 信任凭证
    });

    return result;
}

Preparing diagram...

// PayPal 如何将 AP2 Mandate 嵌入到现有支付流中
interface PayPalAuthorizationRequest {
    // 标准字段
    amount: number;
    currency: string;
    merchantId: string;

    // AP2 扩展字段
    ap2: {
        mandateType: 'intent' | 'cart';
        agentPresent: boolean;
        humanPresent: boolean;
        mandateReference: string;
        // 链接到 tokenized credentials
        tokenizedCredentialRef: string;
    };
}

传统流程:
用户投诉 → 人工审核 → 30天处理

AP2 增强流程:
用户投诉 → 验证 Mandate 签名链 → 密码学证据裁决 → 快速处理

Preparing diagram...

// Agent 角色定义
const agentRoles = {
    rootAgent: {
        role: '总指挥',
        responsibility: '编排整个购物流程，委派子任务',
    },
    shoppingAgent: {
        role: '购物助手',
        responsibility: '代表用户浏览、比较、选择商品',
    },
    addressAgent: {
        role: '地址收集',
        responsibility: '获取和验证用户配送地址',
    },
    paymentMethodAgent: {
        role: '支付方式',
        responsibility: '管理用户的支付凭证选择',
    },
    merchantAgent: {
        role: '商家代理',
        responsibility: '提供商品信息，处理订单',
    },
    merchantPaymentAgent: {
        role: '商家支付',
        responsibility: '处理支付授权和结算',
    },
    credentialProvider: {
        role: '凭证提供者',
        responsibility: '安全管理和分发 tokenized 支付凭证',
    },
};

Preparing diagram...

Google AP2
    └── x402 Extension
        ├── Coinbase (发起者)
        ├── MetaMask
        ├── Ethereum Foundation
        ├── Mysten Labs (Sui)
        ├── Algorand
        └── peaq (DePIN)

// AP2 安全模型
interface AP2SecurityModel {
    // 1. 密码学签名
    cryptographicSigning: {
        algorithm: 'Ed25519' | 'ECDSA';
        purpose: '防止 Mandate 被篡改';
    };

    // 2. 身份验证
    identityVerification: {
        shortTerm: 'curated allow-lists and registries';
        longTerm: 'HTTPS + mutual TLS (mTLS)';
    };

    // 3. 审计追踪
    auditTrail: {
        proofChain: 'cryptographic evidence chain';
        nonRepudiation: '签名者无法否认';
    };

    // 4. 最小化信息原则
    dataMinimization: {
        paymentMandate: 'only minimal context to payment networks';
        userPrivacy: 'shopping details not exposed to issuers';
    };
}

// Agent 支付安全检查清单
const securityChecklist = {
    // 1. 始终验证 Mandate 签名
    verifyMandateSignature: true,

    // 2. 检查 Mandate 是否过期
    checkMandateExpiry: true,

    // 3. 验证金额不超过约束
    enforceAmountLimits: true,

    // 4. 记录完整的审计日志
    maintainAuditLog: true,

    // 5. 实施 Agent 身份白名单
    agentAllowList: true,

    // 6. 监控异常交易模式
    anomalyDetection: true,
};

# 前提条件
# Python 3.10+
# uv 包管理器

# 安装 AP2 types 包
uv pip install git+https://github.com/google-agentic-commerce/AP2.git@main

# 克隆仓库获取示例
git clone https://github.com/google-agentic-commerce/AP2.git
cd AP2

AP2/
├── src/ap2/types/          # 核心协议类型定义
├── samples/
│   ├── python/scenarios/   # Python 演示场景
│   └── android/scenarios/  # Android 购物助手
├── docs/                   # 文档和规范
└── README.md

# 方式 1: Google API Key (开发环境)
export GOOGLE_API_KEY="your-api-key"

# 方式 2: Vertex AI + Service Account (生产环境)
export GOOGLE_CLOUD_PROJECT="your-project-id"
gcloud auth application-default login

# 运行购物场景 demo
cd samples/python/scenarios
uv run python shopping_demo.py

Preparing diagram...