feat(examples): add x402 survival check — pre-payment cashier on Base mainnet

[This-Is-Hellgate]

Summary

Adds typescript/examples/x402-survival-check/ — a minimal AgentKit script showing an autonomous agent paying $0.01 USDC on Base mainnet over x402 v2 for a Second Eyes cashier check before spending on more expensive x402 tools.

The example uses CdpEvmWalletProvider as the x402 signer and the x402 v2 client (x402Client + wrapFetchWithPayment from @x402/fetch, exact EVM scheme registered via registerExactEvmScheme from @x402/evm) — the same building blocks AgentKit's x402ActionProvider uses internally. It runs against the live production endpoint at secondeyesai.com. No mock server.

For MCP-native agents, the same flow is available via @secondeyes/mcp-unblock@1.2.3 (enter_lounge → order_service with slug help-me or should-i-pay, MCP_X402_WALLET_KEY).

Flow

1. Unpaid probe of GET /api/bar/x402/help-me → HTTP 402 PAYMENT-REQUIRED; the agent inspects accepts[] (scheme ExactEvmScheme, network eip155:8453, USDC on Base, $0.01)
2. Pay + retry via x402 v2 — the client emits PAYMENT-SIGNATURE / X-PAYMENT, settlement proof returns on the payment-response header → HTTP 200 with guidance pack + receipt

help-me is the canonical sessionless distress door (no lounge session header). Set RUN_SHOULD_I_PAY=1 to also buy the optional sessionless should-i-pay checklist first.

Protocol / network

• x402 v2: HTTP 402 PAYMENT-REQUIRED → PAYMENT-SIGNATURE / X-PAYMENT → payment-response settlement header
• Scheme ExactEvmScheme (EIP-3009), asset Base USDC, network eip155:8453 (the only active Second Eyes settlement network)
• Polygon / Solana: planned, not active

Motivation

Autonomous agents with CDP wallets increasingly hit HTTP 402 paywalls. Paying blindly wastes USDC on tools that free samples, bar tabs, or cheaper routes would cover. A cheap pre-payment check ($0.01) is a practical guardrail — complementary to pre-broadcast transaction guards.

Related community discussion:

• Example: x402 pre-send guard before EVM agent transaction broadcast #1167 — x402 pre-send guard before EVM transaction broadcast (pre-spend vs pre-broadcast; same payment-rail pattern)
• Feedback request: pre-execution risk-check action pattern for AgentKit #1168 — pre-execution risk-check action pattern for AgentKit
• Add x402 market state oracle integration example #1097 — x402 market state oracle integration example

This PR does not implement a new action provider; it is a focused runnable example agents can copy before wiring x402ActionProvider into tool loops.

What changed in this update

This commit modernizes the previously-stale example to current Second Eyes / x402 canon:

• x402 v1 → v2. Replaced ExactEvmSchemeV1 / @x402/evm/exact/v1/client with the v2 client (x402Client + registerExactEvmScheme). package.json already pinned @x402/{evm,fetch}@^2.7.0; the code now matches.
• Routes. Canonical sessionless /api/bar/x402/help-me (plus optional /api/bar/x402/should-i-pay), replacing the session-scoped /api/bar/services/should-i-pay + /api/bar/enter flow.
• Network. Base CAIP-2 eip155:8453 (was alias base).
• Pricing. $0.01 launch pricing (was $0.10).
• MCP package. @secondeyes/mcp-unblock@1.2.3 (was 1.1.0).
• Probe-first. The agent now does an explicit unpaid probe and decodes PAYMENT-REQUIRED before paying.

Test plan

• eslint clean (pnpm lint in the example) — incl. JSDoc rules
• prettier --check clean (pnpm format:check)
• x402 v2 import surface typechecks against installed @x402/fetch@2.7.0 + @x402/evm@2.7.0 (tsc --noEmit on the changed import/usage)
• pnpm install && pnpm build from typescript/ root (see caveat below)
• Copy .env.example → .env, set CDP credentials + wallet secret
• Fund CDP wallet with Base USDC (~$0.05)
• pnpm start from the example dir → unpaid 402 probe → paid 200 → BaseScan tx logged

Notes for reviewers

• Lockfile caveat: this example is not yet present in typescript/pnpm-lock.yaml, so a strict --frozen-lockfile CI install will fail until the lockfile is regenerated. A scoped lockfile update on this machine pruned hundreds of unrelated monorepo snapshot entries, so it was intentionally not committed to avoid a large/ risky lockfile churn. Please regenerate the lockfile (pnpm install at typescript/ root) in a clean environment and commit that separately, or advise the preferred approach.
• Second Eyes uses x402 v2 on eip155:8453; the example defaults to NETWORK_ID=base-mainnet.
• No Second Eyes API keys required — the endpoints are public x402.
• The cashier services return a static decision_tree + default guidance; the agent applies the checklist to its own context (not a server-side yes/no verdict).
• No private keys committed, no live payment performed in this change.

---

🤖 Generated by Computer

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 1 Sum 2

[This-Is-Hellgate]

Hi @murrlincoln — when you have a chance, could you take a look at this example?

I updated the PR to current x402/Second Eyes behavior before asking for review:

• x402 v2 flow (PAYMENT-REQUIRED → PAYMENT-SIGNATURE / X-PAYMENT → payment-response)
• Base CAIP-2 network eip155:8453
• sessionless /api/bar/x402/help-me as the canonical route
• optional /api/bar/x402/should-i-pay pre-check
• current launch price $0.01
• MCP path updated to @secondeyes/mcp-unblock@1.2.3

I also squashed the branch to a single clean commit so the patch no longer contains the stale v1 / $0.10 / @1.1.0 strings from the original draft.

Known caveat: the example is new and the lockfile has not been regenerated here because my local environment produced large unrelated pnpm-lock churn. If Coinbase prefers, I can update the lockfile in whatever format/process you recommend.