[ephemeral_wallet] v1 design: x402 + CDP session (parent: #41)

[Hendobox]

Parent

Part of #41 — design-only precursor to a scoped skill PR. Research matrix and v1 recommendation: #41 (comment) (approved direction by @rosspeili).

Goal

Ship a thin Skillware skill for spend-capped / short-lived agent payment sessions that settle x402 HTTP 402 challenges using a dedicated CDP / AgentKit-style funded wallet — not classic virtual-card PANs in v1.

Working skill ID (open to rename): finance/agent_pay or finance/ephemeral_wallet with description clarified to agent payment session, not card Issuing.

Non-goals (v1)

• Stripe Issuing / Privacy.com-class PAN minting (optional later adapter)
• Stripe MPP as primary rail (fiat adapter later)
• AP2 mandates as primary backend (compose in v2)
• Depending on @asgcard/pay (TS reference only)
• Live chain / live facilitator in CI

Proposed actions

Action	Purpose
create_session	Create session metadata: spend_cap_usd, ttl_seconds, optional allowlist; bind to configured agent wallet
status	Session remaining cap, expiry, last payment / receipt refs (no secrets)
pay	Given a URL (or 402 challenge payload): follow x402 flow (402 → sign/settle → retry); enforce session cap + TTL
revoke	Expire session immediately (fail closed on further pay)

Optional later: quote (inspect 402 without settling).

Env / config (draft)

• Dedicated agent wallet secrets only in .env (e.g. CDP / private key env names TBD after CDP+x402 SDK pass) — never in tool args or YAML
• Optional: facilitator URL (default public x402 facilitator), network (base-sepolia for demo)
• config.yaml.example: default cap, TTL, network — gitignored real config

Constitution (draft)

1. Dedicated agent wallet only — never personal/treasury keys
2. Never return private keys, seed phrases, or full PANs/CVVs in tool output
3. Fail closed on missing env, over-cap, expired session, or unverifiable settlement
4. Not financial advice; on-chain results may differ from quotes
5. Redact secrets in logs / agent_hint; instructions teach agents not to echo secrets

Provider interface

Keep a small internal provider boundary so v1 is x402+CDP but later adapters (MPP, Issuing) can plug in without rewriting the action router.

Tests

• Mocked HTTP 402 → payment header → 200 path
• Cap exceeded / TTL expired → structured error
• Missing wallet env → missing_config (agent-friendly), not bare traceback
• No live Base / facilitator in CI

Acceptance for design sign-off

• Skill ID / category agreed (finance/…)
• Action list + env var names locked enough for PR1
• Constitution + secret redaction rules agreed
• Explicit reject list vs Issuing/MPP/AP2/ASG unchanged unless Ross finds blockers

Implementation plan (after sign-off)

1. PR1: bundle skeleton — manifest, instructions, constitution, mocked create_session / status / revoke, stub or mocked pay
2. PR2: real x402 client path behind mocks + optional demo script (EVM_TX_HANDLER-style demo flag)

Assignee

@Hendobox — continuing from #41 research spike.

[rosspeili]

Thanks @Hendobox, this is a very good design draft, and it matches the direction from #41 (x402 + CDP session, Issuing/MPP/AP2 deferred).

Process

• Parent is [New Skill]: One-Time Agent Wallets #41 only. This is not under RFC 115 / wallet_screening.
• No extra sub-issues needed for v1 unless we hit a hard split later.
• Keep [New Skill]: One-Time Agent Wallets #41 open for history, we can close [New Skill]: One-Time Agent Wallets #41 + [ephemeral_wallet] v1 design: x402 + CDP session (parent: #41) #272 together when the first skill PR merges.

What’s good

• Thin action set (create_session / status / pay / revoke)
• Strong non-goals
• Constitution + secret redaction posture
• Mocked tests / no live chain in CI
• Provider boundary for later adapters
• PR1 skeleton → PR2 real path

Please lock before PR1 (essential)

1. Skill ID, pick one: keep finance/ephemeral_wallet (preferred unless you have a strong rename reason) or finance/agent_pay, and update [New Skill]: One-Time Agent Wallets #41 wording to match.
2. Env var names, concrete list (CDP + network + optional facilitator), secrets only in .env, never tool args.
3. Output schema per action (session id, remaining cap, expiry, payment/receipt refs) with an explicit “never returns keys/PANs” note.
4. Session state model, how session survives across agent turns (in-memory only vs host-held session id vs temp store). This is the tricky bit, fail closed if unclear. We could use vector db, or cache + download log eg. in csv or markdown automatically after each payment? This opens room for discussion related to the CLI (where we are expanding path customization, eg. new path for payment logs could be set by user or default to prefixed location?)
5. Boundary, do not duplicate defi/evm_tx_handler (no general swap/send). This skill is spend-capped x402 settlement for agent HTTP payments.
6. Manifest requirements / extras once the Python SDK choice is fixed.

Nice-to-have

• Optional quote after pay works
• Demo script with offline mock default (same spirit as evm_tx_handler)
• One short “why not Issuing in v1” note in instructions.md so agents don’t ask for PANs

Once those essentials are locked in a follow-up comment here, PR1 skeleton + mocks is good to start. <3

[Hendobox]

Thanks @rosspeili — locking essentials for PR1 below. Parent remains #41 only (not #115).

Design lock (pre-PR1)

1. Skill ID

finance/ephemeral_wallet (keep original path; description clarifies spend-capped x402 agent payment session, not card PANs).

Will align #41 wording / catalog copy to that meaning in the skill PR.

2. Env vars (secrets in .env only — never tool args / YAML)

Var	Required	Purpose
CDP_API_KEY_ID	yes (for live pay)	CDP auth
CDP_API_KEY_SECRET	yes (for live pay)	CDP auth
CDP_WALLET_SECRET	yes (for live pay)	Dedicated agent wallet secret
EPHEMERAL_WALLET_NETWORK	no	Default base-sepolia (demo); prod e.g. base
EPHEMERAL_WALLET_FACILITATOR_URL	no	Default public x402 facilitator
EPHEMERAL_WALLET_SESSION_DIR	no	Optional on-disk session + payment log dir (see §4)

config.yaml.example: non-secret defaults only (default_spend_cap_usd, default_ttl_seconds, network). Real config.yaml gitignored.

Exact CDP SDK field names confirmed when pay is wired in PR2; PR1 uses the same env names with mocked wallet.

3. Output schema (never keys / PANs)

create_session

{
  "status": "ready",
  "session_id": "ews_…",
  "spend_cap_usd": 5.0,
  "remaining_usd": 5.0,
  "expires_at": "ISO-8601",
  "network": "base-sepolia",
  "wallet_address": "0x…",
  "agent_hint": "Pass session_id on later status/pay/revoke. No secrets in this payload."
}

status

{
  "status": "ready",
  "session_id": "ews_…",
  "remaining_usd": 3.2,
  "expires_at": "ISO-8601",
  "revoked": false,
  "payments_count": 2,
  "last_payment": { "url": "https://…", "amount_usd": 0.5, "tx_ref": "…", "at": "ISO-8601" }
}

pay

{
  "status": "confirmed",
  "session_id": "ews_…",
  "remaining_usd": 2.7,
  "payment": {
    "url": "https://…",
    "amount_usd": 0.5,
    "network": "base-sepolia",
    "tx_ref": "…",
    "receipt_ref": "…"
  },
  "agent_hint": "Do not ask for or display private keys or card PANs."
}

revoke

{
  "status": "revoked",
  "session_id": "ews_…",
  "remaining_usd": 2.7,
  "revoked_at": "ISO-8601"
}

Errors: structured status (missing_config | expired | revoked | over_cap | error) + agent_hint. Never return private keys, seeds, CDP secrets, or full PANs/CVVs.

4. Session state model (fail closed)

v1:

1. Host-held session_id — skill returns session_id on create_session; agent must pass it on every later call (same pattern as carrying intent across tool turns).
2. Process memory — default store is in-memory for the skill process (fine for single-host agent loops / demos).
3. Optional durable log — if EPHEMERAL_WALLET_SESSION_DIR (or config path) is set, append-only JSONL under that dir:
   • sessions.jsonl — create/revoke lifecycle
   • payments.jsonl — one line per successful pay (url, amount, tx_ref, timestamp, session_id)
     No vector DB in v1. Markdown export can be a later CLI nicety, not required for PR1.
4. Fail closed — unknown / expired / revoked session_id → structured error, no pay. Missing dir when durability requested → error (don’t silently drop to memory-only if user asked for disk).

Out of scope for v1 skill: inventing a new global CLI “payment logs” path flag. If/when CLI path customization grows, we can document a recommended default under the user’s skill data dir; track that as a separate CLI note, not a blocker for PR1.

5. Boundary vs defi/evm_tx_handler

This skill only does spend-capped x402 settlement for agent HTTP payments (create_session / status / pay / revoke).
No general swap, transfer, Uni router, or wallet send — use defi/evm_tx_handler for that.

6. Manifest requirements / extras (PR1 stub → PR2 lock)

• PR1: minimal / none beyond stdlib + existing Skillware deps; pay fully mocked.
• PR2: pin concrete packages once chosen (likely x402 + CDP/AgentKit pieces); add manifest.requirements and per-skill extra via repo convention.

Nice-to-haves (after essentials)

• Optional quote once pay works
• Demo script with offline mock default (EPHEMERAL_WALLET_EXAMPLE_DEMO=1, same spirit as evm_tx_handler)
• Short “why not Issuing / PANs in v1” in instructions.md

Plan

Unless you object to §4 (session durability), I’ll start PR1: bundle skeleton + mocked create/status/pay/revoke + constitution + tests, linked to Fixes progress on #272 / Part of #41.

[renezander030]

The design lock covers secrets and IDs well, but spend_cap_usd and ttl_seconds are still enforced by the same process the agent controls, so in v1 they are a UX affordance rather than a bound: a forked or prompt-injected agent that skips the cap check spends whatever the CDP wallet holds, and revoke fails closed only inside your own action router.

Funding the session wallet with exactly the cap makes balance the enforcement and turns revoke into a sweep back to treasury, at the price of one funding transaction per session and leftover dust. Keeping the counter but reconciling it against on-chain balance on every pay and status, failing closed on divergence, adds an RPC read to the hot path and still trusts the process. Pushing enforcement to an allowlisted spender or facilitator-side policy is the only version that survives a hostile agent, and it is more than a thin v1.

One thing worth pinning either way is whether cap and TTL are evaluated at the 402 challenge or at settlement, since a payment started a second before expiry otherwise settles after revoke. For v1 I would fund to the cap and label the counter in status as display rather than enforcement, because that is the only bound that holds when the process itself is what failed.

[rosspeili]

Thanks @Hendobox, design lock looks good. Skill ID, env names, schemas, session model (§4), and the evm_tx_handler boundary are enough to start PR1 (skeleton + mocks). No objection on optional JSONL durability. I think we can push this to a new branch and test extensively, then ammend prs there, until the skill is flawless even for a v1.

One note from the @renezander030 that makes sense: in-process cap/TTL/revoke are soft policy unless the wallet itself is funded to the cap (or later facilitator/spender policy). You can state that clearly in constitution / instructions.md so we don’t over-claim “hard limit” in v1. We can pick funded-to-cap vs soft-counter for PR2.

Go ahead on PR1, and we can review together. <3

[rosspeili]

Thanks @renezander030, this is an important distinction, and agreed if the agent process holds the CDP wallet secret, in-skill spend_cap_usd / TTL / revoke are UX/policy, not a cryptographic bound against a hostile or prompt-injected agent.

For Skillware v1 we’ll keep the thin skill, document that clearly, and prefer funded-to-cap (or equivalent) as the real bound when we wire live pay in PR2, plus pin whether expiry is evaluated at 402 challenge vs settlement. Facilitator/spender-side policy is a later hardening step, not PR1.

Appreciate the sharp threat-model read. <3 Any other feedback, comments, or commits are welcome if you wanna work on this alongside @Hendobox <3