Skip to content

Commit 88821dc

Browse files
This-Is-HellgateAgentKit Bot
This-Is-Hellgate
authored and
AgentKit Bot
committed
feat(examples): add x402 survival check — pre-payment cashier on Base mainnet
Add a Second Eyes survival-check example: an autonomous agent runs a low-cost cashier pre-check over x402 before committing to a larger paid tool call. - x402 v2 client APIs (x402Client + wrapFetchWithPayment + registerExactEvmScheme) - sessionless /api/bar/x402/help-me as canonical first call, optional should-i-pay pre-check - unpaid probe inspects HTTP 402 PAYMENT-REQUIRED before paying - Base eip155:8453, USDC, ExactEvmScheme; $0.01 launch pricing - @secondeyes/mcp-unblock@1.2.3; Polygon/Solana noted as planned, not active - signer is AgentKit's CdpEvmWalletProvider (CDP wallet on Base)
1 parent 0fe026b commit 88821dc

7 files changed

Lines changed: 477 additions & 0 deletions

File tree

‎typescript/examples/x402-survival-check/.env.example‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Required — Coinbase Developer Platform
2+
# https://portal.cdp.coinbase.com/access/api
3+
CDP_API_KEY_ID=
4+
CDP_API_KEY_SECRET=
5+
6+
# Required — CDP Server Wallet secret
7+
# https://portal.cdp.coinbase.com/products/wallet-api
8+
CDP_WALLET_SECRET=
9+
10+
# Optional — set after first run prints your wallet address
11+
ADDRESS=
12+
13+
# Optional — defaults to base-mainnet (Second Eyes settles USDC on Base, eip155:8453)
14+
NETWORK_ID=base-mainnet
15+
16+
# Optional — used when creating a new CDP wallet account
17+
IDEMPOTENCY_KEY=
18+
19+
# Optional — set to 1 to also buy the should-i-pay checklist ($0.01) before help-me
20+
RUN_SHOULD_I_PAY=
21+
22+
# No Second Eyes credentials needed — https://secondeyesai.com is a public x402 endpoint.

‎typescript/examples/x402-survival-check/.eslintrc.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"parser": "@typescript-eslint/parser",
3+
"extends": ["../../.eslintrc.base.json"]
4+
}

‎typescript/examples/x402-survival-check/.prettierrc‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"tabWidth": 2,
3+
"useTabs": false,
4+
"semi": true,
5+
"singleQuote": false,
6+
"trailingComma": "all",
7+
"bracketSpacing": true,
8+
"arrowParens": "avoid",
9+
"printWidth": 100,
10+
"proseWrap": "never"
11+
}

‎typescript/examples/x402-survival-check/README.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# x402 Survival Check — AgentKit Example
2+
3+
An autonomous agent is about to spend USDC on an expensive x402 tool — a research API, a code pack, a facilitator-protected MCP call. Before paying more, it can run a **$0.01 cashier check** against the [Second Eyes Agent Lounge](https://secondeyesai.com) using Coinbase AgentKit on **Base mainnet** over **x402 v2**.
4+
5+
Second Eyes is a live production endpoint. No mock server. No test harness fiction.
6+
7+
**What these services are (and are not):** The endpoints return a **static decision checklist** and fallback guidance for the agent to apply to its own context. They do **not** compute a server-side yes/no verdict, score the task, or inspect the expensive endpoint the agent is about to call. The agent reads the tree and decides.
8+
9+
## The pattern
10+
11+
```
12+
agent plans expensive x402 call
13+
→ unpaid probe (read PAYMENT-REQUIRED)
14+
→ pay $0.01 over x402 v2 (PAYMENT-SIGNATURE → X-PAYMENT)
15+
→ agent applies the returned decision_tree to its own state
16+
→ optionally proceed to the expensive tool
17+
```
18+
19+
The agent:
20+
21+
1. Sends an unpaid request to `GET https://secondeyesai.com/api/bar/x402/help-me` → receives **HTTP 402 PAYMENT-REQUIRED**
22+
2. Inspects the `accepts[]` payment requirements (scheme `ExactEvmScheme`, network `eip155:8453`, USDC on Base, amount $0.01)
23+
3. Signs and pays autonomously from its **CDP wallet** via **x402 v2** (the client emits `PAYMENT-SIGNATURE` / `X-PAYMENT`)
24+
4. Retries with payment proof → receives the guidance pack + settlement receipt (`payment-response` header)
25+
26+
`help-me` is the **canonical sessionless distress door** — no lounge session header is required. The agent can optionally buy `should-i-pay` first as a pre-payment checklist (also sessionless, also $0.01).
27+
28+
## Endpoints
29+
30+
| Endpoint | Purpose | Session | Price |
31+
| -------------------------------- | ----------------------------------- | ------- | ----- |
32+
| `GET /api/bar/x402/help-me` | Canonical sessionless distress door | none | $0.01 |
33+
| `GET /api/bar/x402/should-i-pay` | Optional pre-payment checklist | none | $0.01 |
34+
35+
Session-scoped routes (`/api/bar/services/*`) still exist for stateful lounge flows, but they are **not** required for this example and are intentionally not used here.
36+
37+
## x402 v2 protocol notes
38+
39+
- **Version:** x402 **v2**. The challenge is **HTTP 402 PAYMENT-REQUIRED**; the client returns the signed authorization as **`PAYMENT-SIGNATURE`** / **`X-PAYMENT`**; settlement proof comes back on the **`payment-response`** header (v1 used `x-payment-response`).
40+
- **Scheme:** `ExactEvmScheme` (EIP-3009 `transferWithAuthorization` for USDC).
41+
- **Network:** Base mainnet, CAIP-2 **`eip155:8453`** — the only network currently active for Second Eyes settlement.
42+
- **Asset:** native Base **USDC**.
43+
- **Planned (not active):** Polygon and Solana settlement are on the roadmap but are **not** live yet; do not configure them against this endpoint today.
44+
45+
## What a paid call returns on HTTP 200
46+
47+
After payment, the JSON body includes the **guidance pack** plus settlement fields. Representative shape:
48+
49+
```json
50+
{
51+
"service": "help-me",
52+
"pack_type": "cashier",
53+
"decision_tree": [
54+
"Did proof pass?",
55+
"Is a free sample sufficient for this task?",
56+
"Will a one-time nano/micro unblock faster than a tool pack?",
57+
"Is a bar tab cheaper for 3+ fetches this session?"
58+
],
59+
"default": "If uncertain, run a price check then proof before the next 402.",
60+
"access": "granted",
61+
"scope": "lounge",
62+
"paid_usd": 0.01,
63+
"grantId": "agr_…",
64+
"receipt": {
65+
"success": true,
66+
"transaction": "0x…",
67+
"network": "eip155:8453",
68+
"payer": "0x…"
69+
},
70+
"note": "Paid survival service. Embed work_stamp in your deliverable. Save the receipt."
71+
}
72+
```
73+
74+
**How to use it:** Walk the `decision_tree` against the agent's session state (proof status, free samples tried, expected fetch count). If still uncertain, follow `default` before committing to a larger 402.
75+
76+
Public proof ledger: `https://secondeyesai.com/api/bar/proof/payments`
77+
78+
Agent discovery: `https://secondeyesai.com/.well-known/agent-card.json`
79+
80+
## Prerequisites
81+
82+
### Node.js
83+
84+
Node.js **20+** required.
85+
86+
```bash
87+
node --version
88+
```
89+
90+
### Coinbase Developer Platform
91+
92+
- [CDP API Key](https://portal.cdp.coinbase.com/access/api) (`CDP_API_KEY_ID`, `CDP_API_KEY_SECRET`)
93+
- [Wallet Secret](https://portal.cdp.coinbase.com/products/wallet-api) (`CDP_WALLET_SECRET`)
94+
- **USDC on Base mainnet** in the CDP wallet (~$0.05 covers several $0.01 runs plus gas)
95+
96+
No Second Eyes API key is required — the lounge is a public x402 endpoint.
97+
98+
## Setup
99+
100+
From the **typescript workspace root**:
101+
102+
```bash
103+
pnpm install
104+
pnpm build
105+
```
106+
107+
Copy environment template:
108+
109+
```bash
110+
cd examples/x402-survival-check
111+
cp .env.example .env
112+
```
113+
114+
Fill in CDP credentials. Run once to create a wallet:
115+
116+
```bash
117+
pnpm start
118+
```
119+
120+
Note the printed wallet address, fund it with Base USDC, then add to `.env`:
121+
122+
```
123+
ADDRESS=0x...
124+
NETWORK_ID=base-mainnet
125+
```
126+
127+
## Run
128+
129+
```bash
130+
pnpm start
131+
```
132+
133+
To also buy the optional `should-i-pay` checklist before `help-me`:
134+
135+
```bash
136+
RUN_SHOULD_I_PAY=1 pnpm start
137+
```
138+
139+
Expected output:
140+
141+
1. Wallet address + network
142+
2. Unpaid probe → HTTP 402 with decoded `accepts[]` (scheme / network / amount)
143+
3. Paid call → HTTP 200 with `grantId`, `receipt.transaction`
144+
4. BaseScan link for the settlement tx
145+
146+
## How it maps to AgentKit
147+
148+
This example uses **`CdpEvmWalletProvider`** (AgentKit's CDP wallet on Base) as the x402 signer. Payment handling uses the **x402 v2** client from `@x402/fetch` (`x402Client` + `wrapFetchWithPayment`) with the exact EVM scheme registered via `registerExactEvmScheme` from `@x402/evm` — the same building blocks AgentKit's `x402ActionProvider` uses internally.
149+
150+
For LangChain agents with tool loops, wire the same flow through `x402ActionProvider` and register `https://secondeyesai.com` in `registeredServices`. This script is the minimal vertical slice: wallet → unpaid 402 probe → pay → receipt.
151+
152+
**MCP-native agents:** The same pay → receipt flow is available via [`@secondeyes/mcp-unblock@1.2.3`](https://www.npmjs.com/package/@secondeyes/mcp-unblock/v/1.2.3) — `enter_lounge` then `order_service` with slug `help-me` (or `should-i-pay`), requiring `MCP_X402_WALLET_KEY` on the MCP server process:
153+
154+
```json
155+
{
156+
"mcpServers": {
157+
"secondeye-unblock": {
158+
"command": "npx",
159+
"args": ["-y", "@secondeyes/mcp-unblock@1.2.3"]
160+
}
161+
}
162+
}
163+
```
164+
165+
## Resources
166+
167+
- Second Eyes: https://secondeyesai.com
168+
- Agent card: https://secondeyesai.com/.well-known/agent-card.json
169+
- Pricing: https://secondeyesai.com/api/bar/pricing
170+
- x402 overview: https://docs.cdp.coinbase.com/x402/overview
171+
- AgentKit: https://github.com/coinbase/agentkit
172+
173+
## License
174+
175+
[Apache-2.0](../../../LICENSE.md)

0 commit comments

Comments
 (0)