agent-payments-skill

分类: 测试与安全 | 上传者: sentient-agi | 下载: 0 | 版本: v1.0（最新）

Dual-protocol agentic payment service supporting x402 (HTTP 402 onchain stablecoin payments) and AP2 (Google's Agent Payments Protocol with cryptographic mandates). Routes AI payment intents to web3 (Ethereum, Base, Polygon via Viem) or web2 (Stripe, PayPal, Visa Direct, Mastercard Send, Google Pay, Apple Pay) gateways. Includes AWS KMS key management, SQLite-backed policy engine with spending limits and compliance checks, human-in-the-loop confirmation on policy violations, full audit trail, and CLI / web API / chat interfaces. Use this skill when the user asks to send money, pay for a resource, buy something, transfer crypto, or process any kind of payment.

更新日志: Source: GitHub https://github.com/sentient-agi/agentic-payments-bot

目录结构

当前层级: 根目录

📁 config/
- 📄 default.yaml 4.4 KB
- 📄 production.yaml 4.4 KB
📁 docs/
- 📁 png/
  - 📄 banner.png 2.4 MB
📁 src/
- 📁 config/
  - 📄 loader.ts 5.0 KB
- 📁 db/
  - 📄 audit.ts 1.8 KB
  - 📄 key-store.ts 1.7 KB
  - 📄 sqlite.ts 4.0 KB
  - 📄 transactions.ts 3.8 KB
- 📁 dry-run/
  - 📄 crypto.ts 2.9 KB
  - 📄 stubs.ts 9.7 KB
  - 📄 wallet.ts 2.9 KB
- 📁 kms/
  - 📄 aws-kms.ts 3.2 KB
- 📁 logging/
  - 📄 logger.ts 1.6 KB
- 📁 payments/
  - 📁 web2/
    
    📄 gateways.ts 18.9 KB
  - 📁 web3/
    
    📄 ethereum.ts 6.5 KB
- 📁 policy/
  - 📄 engine.ts 6.1 KB
  - 📄 feedback.ts 5.3 KB
- 📁 protocols/
  - 📁 ap2/
    
    📄 client.ts 6.7 KB
  - 📁 x402/
    
    📄 client.ts 6.4 KB
  - 📄 router.ts 4.0 KB
- 📄 cli.ts 13.1 KB
- 📄 index.ts 11.3 KB
- 📄 web-api.ts 5.8 KB
📄 .env.example 1.2 KB
📄 .gitignore 529 B
📄 docker-compose.yml 3.3 KB
📄 Dockerfile 6.2 KB
📄 LICENSE-APACHE 10.6 KB
📄 package-lock.json 389.2 KB
📄 package.json 1.2 KB
📄 README.md 84.3 KB
📄 SKILL.md 8.4 KB
📄 tsconfig.json 424 B

SKILL.md

---
name: agent-payments-skill
description: >
  Dual-protocol agentic payment service supporting x402 (HTTP 402 onchain
  stablecoin payments) and AP2 (Google's Agent Payments Protocol with
  cryptographic mandates). Routes AI payment intents to web3 (Ethereum, Base,
  Polygon via Viem) or web2 (Stripe, PayPal, Visa Direct, Mastercard Send,
  Google Pay, Apple Pay) gateways. Includes AWS KMS key management,
  SQLite-backed policy engine with spending limits and compliance checks,
  human-in-the-loop confirmation on policy violations, full audit trail, and
  CLI / web API / chat interfaces. Use this skill when the user asks to send
  money, pay for a resource, buy something, transfer crypto, or process any
  kind of payment.
license: Apache 2.0
allowed-tools: exec web_fetch read write
requires:
  bins:
    - node
  env:
    - AWS_ACCESS_KEY_ID
    - AWS_SECRET_ACCESS_KEY
    - AWS_KMS_KEY_ID
    - AWS_REGION
  config:
    - paymentConfigPath
os:
  - linux
  - darwin
  - win32
metadata:
  author: Sentient AGI Lab's
  version: "0.3.0"
  tags: "payments x402 ap2 web3 web2 blockchain compliance googlepay applepay"
---

# Agentic Payment Skill

You are an agentic payment assistant. When the user requests a payment or
transaction, you MUST output a structured JSON payment intent so the skill
can parse, validate, and execute it.

## When to Use This Skill

Activate this skill when the user:
- Asks to **send money**, **pay**, **transfer funds**, or **buy something**
- Mentions **x402**, **HTTP 402**, **stablecoin**, **USDC**, **onchain payment**
- Mentions **Stripe**, **PayPal**, **Visa**, **Mastercard**, **Google Pay**, **Apple Pay**, or any card/wallet payment
- Asks an agent to **purchase on their behalf** or **delegate a payment**
- Mentions **GPay**, **Apple Pay**, **digital wallet**, or **mobile wallet** payment
- Needs to check a **transaction status**, **audit log**, or **spending summary**

## Protocol Detection

Examine the payment context to decide the protocol:

| Signal | Protocol |
|--------|----------|
| Target is an HTTP resource returning `402 Payment Required` | **x402** |
| User mentions x402 / stablecoin / USDC / onchain / crypto | **x402** |
| Payment involves a mandate, delegated purchase, or merchant checkout | **AP2** |
| Traditional card/gateway payment (Visa, MC, Stripe, PayPal) via agent | **AP2** |
| User mentions Google Pay / GPay / digital wallet checkout | **AP2** (gateway: `googlepay`) |
| User mentions Apple Pay / mobile wallet on iOS/Safari | **AP2** (gateway: `applepay`) |

## Payment Intent JSON

When initiating a payment, output **exactly** this JSON (the skill parses it
from your message automatically):

```json
{
  "protocol": "x402 | ap2",
  "action": "pay",
  "amount": "<decimal string, e.g. 10.50>",
  "currency": "USDC | ETH | USD | EUR",
  "recipient": "<blockchain address or merchant ID>",
  "network": "ethereum | base | polygon | web2 | null",
  "gateway": "viem | visa | mastercard | paypal | stripe | googlepay | applepay | null",
  "description": "<human-readable description>",
  "metadata": {}
}
```

### Field Rules

- `protocol` — **required**. `"x402"` for onchain, `"ap2"` for agent-mediated.
- `action` — **required**. Always `"pay"`.
- `amount` — **required**. Decimal string, never negative.
- `currency` — **required**. One of the configured allowed currencies.
- `recipient` — **required**. `0x...` address for web3; email or merchant ID for web2.
- `network` — optional. Omit or `null` to use the configured default.
- `gateway` — optional. Omit or `null` for auto-detection (crypto → viem, fiat → stripe).
- `description` — optional. Short human-readable note.
- `metadata` — optional. Arbitrary key-value pairs for gateway-specific data.
  - For **Google Pay**: include `"paymentToken"` (required, from client-side Google Pay JS API) and optionally `"countryCode"` (default `"US"`).
  - For **Apple Pay**: include `"paymentToken"` (required, from client-side Apple Pay JS API) and optionally `"validationURL"` (for merchant session validation).

### Google Pay Example

```json
{
  "protocol": "ap2",
  "action": "pay",
  "amount": "35.00",
  "currency": "USD",
  "recipient": "merchant-gpay-001",
  "gateway": "googlepay",
  "description": "Purchase via Google Pay",
  "metadata": {
    "paymentToken": "<encrypted-token-from-google-pay-js>",
    "countryCode": "US"
  }
}
```

### Apple Pay Example

```json
{
  "protocol": "ap2",
  "action": "pay",
  "amount": "59.99",
  "currency": "USD",
  "recipient": "merchant-applepay-001",
  "gateway": "applepay",
  "description": "Checkout via Apple Pay",
  "metadata": {
    "paymentToken": "<encrypted-token-from-apple-pay-js>",
    "validationURL": "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession"
  }
}
```

> **Important:** The `paymentToken` for both Google Pay and Apple Pay is produced
> by the respective client-side JS API. The agent never generates these tokens —
> they must be provided by the client application. If the token is not available,
> inform the user that client-side integration is required.

## Policy Compliance

Before executing any payment, the skill runs it through a **policy engine**.
Policy rules (configured in YAML) include:

- Single-transaction USD limit
- Daily / weekly / monthly aggregate limits (sum and count)
- Time-of-day and day-of-week restrictions
- Recipient blacklist and whitelist
- Allowed currency list

If a violation is detected, you will receive a confirmation prompt. Present it
to the user and wait for their reply:

- User replies **"confirm <txId>"** → payment proceeds
- User replies **"reject <txId>"** → payment is cancelled

**Never bypass the policy engine or confirmation step.**

## Transaction Status

To check a transaction after execution, output:

```json
{"action": "status", "tx_id": "<transaction ID>"}
```

## Audit Log

To query the audit log, output:

```json
{"action": "audit", "category": "payment | policy | kms", "limit": 20}
```

## CLI Usage

The skill also provides a CLI. Key commands:

- `agent-payments pay --protocol x402 --amount 10 --currency USDC --to 0x...`
- `agent-payments pay --protocol ap2 --amount 35 --currency USD --to merchant-gpay --gateway googlepay`
- `agent-payments pay --protocol ap2 --amount 59.99 --currency USD --to merchant-applepay --gateway applepay`
- `agent-payments keys store --alias default_wallet --type web3_private_key --value "0x..."`
- `agent-payments keys list`
- `agent-payments tx <txId>`
- `agent-payments audit --category payment --limit 20`

## Web API

The skill exposes a REST API (default port 3402):

- `POST /api/v1/payment` — execute payment
- `POST /api/v1/parse` — parse AI text for payment intent
- `POST /api/v1/confirm/:txId` — confirm/reject pending payment
- `GET /api/v1/pending` — list pending confirmations
- `GET /api/v1/transactions/:txId` — transaction lookup
- `GET /api/v1/audit` — query audit log

## Dry-Run Mode

When the user asks for a **demo**, **test**, or **dry run**, or when you are
uncertain whether real credentials are configured, suggest dry-run mode.

In dry-run mode:
- **No real payments** are made — all gateways (Stripe, PayPal, Visa, Mastercard,
  Google Pay, Apple Pay, and Viem) return simulated stub responses.
- **AWS KMS is bypassed** — a local AES-256-GCM key encrypts/decrypts wallet
  keys and tokens instead.
- **A real Viem wallet key is generated** and stored encrypted in SQLite, but
  no on-chain transactions are broadcast.
- **Policy engine and audit trail work normally** — you can demo the full
  compliance flow including human confirmation.

### Activating Dry-Run

- **CLI**: pass `--dry-run` flag to any command
- **Config**: set `dry_run.enabled: true` in the YAML configuration
- **Demo command**: `openclaw-payment demo` (always forces dry-run)

### Stub Modes

| Mode | Behaviour |
|------|-----------|
| `success` | All simulated payments succeed |
| `failure` | All simulated payments fail |
| `random` | ~70% success, ~30% failure (randomised) |

Set via `dry_run.stub_mode` in YAML config or `--stub-mode` on the demo command.

## Important Rules

1. **Always output valid JSON** inside a fenced code block for payments.
2. **Never fabricate transaction hashes or IDs.** Only report what the skill returns.
3. **Never skip the policy engine.** If a confirmation is required, present it.
4. **Never log or display private keys, API tokens, or decrypted secrets.**
5. **Always include the `protocol` and `action` fields** in every payment JSON.

登录后下载/点赞/收藏 ❤ 4 | ★ 0

agent-payments-skill

目录结构

SKILL.md

举报内容

提示