|
1
|
--- |
|
2
|
title: "Agentic Commerce with x402 (Local Simulation)" |
|
3
|
sidebarTitle: "Agentic Commerce x402" |
|
4
|
description: "Map the OpenAI cookbook controlled agentic commerce flow onto ProcureNet sessions, USDC settlement, and AI agents — using a local-only x402 simulation with no live funds." |
|
5
|
--- |
|
6
|
|
|
7
|
ProcureNet already orchestrates buyer sessions, USDC settlement, and background AI agents. This guide shows how an **agentic commerce** pattern fits those concepts when an agent needs to call a **paid API** that speaks the [x402](https://github.com/coinbase/x402) `HTTP 402 Payment Required` challenge. |
|
8
|
|
|
9
|
The runnable example lives at [`examples/agentic-commerce-x402/`](https://github.com/mindtdilly/Omnipay/tree/main/examples/agentic-commerce-x402). It is adapted from the OpenAI Cookbook partner example *Controlled agentic commerce with AgentCore Payments*. |
|
10
|
|
|
11
|
<Warning> |
|
12
|
**Local simulation only.** This example never moves real funds. There are no live payment gates, no AWS credentials, no Amazon Bedrock AgentCore calls, and no wallet private keys. Synthetic payment proofs only. Live AgentCore Payments is intentionally out of scope for this guide (`value_transferred=false`). |
|
13
|
</Warning> |
|
14
|
|
|
15
|
## What you will learn |
|
16
|
|
|
17
|
- How four authority boundaries cooperate: agent, application policy, payment session, paid API |
|
18
|
- How that maps to ProcureNet [session lifecycle](/concepts/session-lifecycle), [USDC settlement](/concepts/payment-settlement), [orchestration](/concepts/orchestration-modes), and [AI agents](/configuration/ai-agents) |
|
19
|
- How to run the local pytest suite without network payment side effects |
|
20
|
|
|
21
|
## Architecture in four responsibilities |
|
22
|
|
|
23
|
| Layer | Owns | Does not own | |
|
24
|
|---|---|---| |
|
25
|
| **Agent** | Tool selection and a typed proposal | Approval, budget, wallet access, settlement truth | |
|
26
|
| **Application policy** | Merchant allowlist, purpose, spending limits, human approval, idempotency, receipts, audit | Signing credentials | |
|
27
|
| **Payment session (simulated)** | Synthetic proof generation inside a bounded local adapter | Business authorization | |
|
28
|
| **Paid API (merchant)** | `402` challenge and fulfillment when a valid proof is presented | Deciding whether your app may spend | |
|
29
|
|
|
30
|
In the Omnipay package these map to: |
|
31
|
|
|
32
|
1. `omnipay_x402.agent` — scripted one-tool loop (no live model SDK required) |
|
33
|
2. `omnipay_x402.policy` + `CommerceApplication` — application-owned controls |
|
34
|
3. `LocalPaymentProcessor` — synthetic proofs; `aws_stub.live_agentcore_status()` returns `SKIPPED` / `NOT_READY` |
|
35
|
4. `SyntheticMerchant` — in-memory HTTP transport that returns `402` then `200` |
|
36
|
|
|
37
|
```mermaid |
|
38
|
sequenceDiagram |
|
39
|
participant Agent |
|
40
|
participant App as Application policy |
|
41
|
participant Pay as Local payment session |
|
42
|
participant API as Paid API |
|
43
|
|
|
44
|
Agent->>App: Propose x402_fetch(url, purpose) |
|
45
|
App->>API: GET resource |
|
46
|
API-->>App: 402 PAYMENT-REQUIRED |
|
47
|
App->>App: Authorize (merchant, budget, approval) |
|
48
|
App->>Pay: Authorize synthetic proof |
|
49
|
Pay-->>App: Proof + receipt |
|
50
|
App->>API: GET resource + PAYMENT-SIGNATURE |
|
51
|
API-->>App: 200 + report + PAYMENT-RESPONSE |
|
52
|
App-->>Agent: Typed evidence (no wallet material) |
|
53
|
``` |
|
54
|
|
|
55
|
## How x402 works in the sim |
|
56
|
|
|
57
|
1. The merchant returns **HTTP 402** with a machine-readable `PAYMENT-REQUIRED` header. |
|
58
|
2. The application treats that challenge as a **proposal**, validates it against policy, and optionally requires a human `ApprovalGrant`. |
|
59
|
3. `LocalPaymentProcessor` creates a **synthetic** proof bound to an idempotency key. |
|
60
|
4. The application retries with `PAYMENT-SIGNATURE`. The merchant verifies the proof and returns the paid content plus `PAYMENT-RESPONSE`. |
|
61
|
5. An append-only **audit trail** records the sequence for later review. |
|
62
|
|
|
63
|
Nothing in this path touches a chain, a wallet, or an external payment provider. |
|
64
|
|
|
65
|
## Map onto ProcureNet concepts |
|
66
|
|
|
67
|
<CardGroup cols={2}> |
|
68
|
<Card title="Session lifecycle" icon="arrows-spin" href="/concepts/session-lifecycle"> |
|
69
|
Treat the commerce `session_expires_at` and approval windows like ProcureNet |
|
70
|
session TTLs: expire closed, never silently extend spending authority. |
|
71
|
</Card> |
|
72
|
<Card title="Payment settlement" icon="coins" href="/concepts/payment-settlement"> |
|
73
|
Production ProcureNet settles USDC via |
|
74
|
[`usdc-request`](/api/usdc-request), |
|
75
|
[`usdc-watch`](/api/usdc-watch), and |
|
76
|
[`usdc-manual-confirm`](/api/usdc-manual-confirm). |
|
77
|
The example only **shapes** the same currency/network vocabulary locally. |
|
78
|
</Card> |
|
79
|
<Card title="Orchestration modes" icon="diagram-project" href="/concepts/orchestration-modes"> |
|
80
|
Application policy—not the model—owns merchant allowlists and budgets, |
|
81
|
analogous to how orchestration modes choose transport and prefill depth. |
|
82
|
</Card> |
|
83
|
<Card title="AI agents" icon="robot" href="/configuration/ai-agents"> |
|
84
|
Like OpenClaw workers, the economic tool is application-bound. Agents propose; |
|
85
|
they do not mint approvals or hold settlement truth. |
|
86
|
</Card> |
|
87
|
</CardGroup> |
|
88
|
|
|
89
|
<Tip> |
|
90
|
When you later wire a real paid supplier API into ProcureNet, keep the same |
|
91
|
split: session + policy in your backend, settlement via the USDC APIs, and |
|
92
|
agents limited to proposing tool calls against pre-bound capabilities. |
|
93
|
</Tip> |
|
94
|
|
|
95
|
## Run the local example |
|
96
|
|
|
97
|
```bash |
|
98
|
cd examples/agentic-commerce-x402 |
|
99
|
uv sync |
|
100
|
uv run pytest |
|
101
|
``` |
|
102
|
|
|
103
|
Expected coverage includes: |
|
104
|
|
|
105
|
- **Happy path** — approved purchase completes the full `402 → proof → 200` sequence with audit events |
|
106
|
- **Denial without approval** — amounts above the threshold fail with `human_approval_required` before any synthetic charge |
|
107
|
- **Fabricated receipt rejection** — agent output that invents a `receipt_id` fails closed against application evidence |
|
108
|
|
|
109
|
Confirm the safety invariants: |
|
110
|
|
|
111
|
```python |
|
112
|
from omnipay_x402 import VALUE_TRANSFERRED, live_agentcore_status |
|
113
|
|
|
114
|
assert VALUE_TRANSFERRED is False |
|
115
|
assert live_agentcore_status()["status"] == "SKIPPED" |
|
116
|
``` |
|
117
|
|
|
118
|
## Attribution |
|
119
|
|
|
120
|
Adapted from the OpenAI Cookbook example *Controlled agentic commerce with AgentCore Payments* (authors: Deepak Jain and Sid Rampally). See [`examples/agentic-commerce-x402/SOURCE.md`](https://github.com/mindtdilly/Omnipay/blob/main/examples/agentic-commerce-x402/SOURCE.md) for the upstream URL and intentional omissions (all live AgentCore / AWS modules). |