Agent commerce, fully specified.

Agent Commerce OS

Elypx402 connects an AI agent to a bounded Agent Account. A goal or payment intent becomes an inspectable Payment Plan, executes only inside signed policy, and retains the resource, policy trace, lifecycle and receipt in one Run Artifact.

Three pillars

Payment lifecycle

Every payment is a state machine, not a boolean. A timed-out broadcast stays pending until it is reconciled by transaction hash — it is never silently retried as a new payment.

Product spec

Product thesis

Elypx402 is an Agent Commerce OS on Elysium.

It lets a developer/operator connect an AI agent, give it a goal or x402 payment intent, constrain it with a human-reviewed policy, and let it buy an approved resource without ever receiving the operator's main wallet or an unbounded approval.

The retained work object is an Agent Account. It owns:

• identity and connection credentials;
• a private balance and public funding history;
• one or more signed Spending Policies;
• Payment Missions and their lifecycle;
• delivered resources, receipts, and audit artifacts.

Primary user

A developer/operator who already runs an AI agent and needs that agent to pay autonomously without holding the operator's main wallet.

Core loop

connect agent
  → create Agent Account
  → define or select a Spending Policy
  → agent submits a goal / payment intent
  → Elypx402 resolves an endpoint and previews a Payment Plan
  → policy engine authorizes or blocks
  → authorized payment settles
  → resource is delivered
  → Run Artifact + receipt are retained

Signature product idea

A goal-to-commerce compiler turns a goal or payment intent into an inspectable Payment Plan:

1. resource requirement;

2. candidate x402 endpoint;

3. method and payload;

4. quoted price;

5. policy decision with the exact rules evaluated;

6. privacy route;

7. settlement and delivery plan.

Nothing executes before the operator can understand the plan and the agent's signed policy. Once a plan is inside policy, it may execute automatically. Violations become approval exceptions; they never silently mutate the policy.

MVP golden path

The first end-to-end path is:

MCP-connected agent
  → create_payment_mission(goal, endpoint?, payload?, max_price)
  → resolve endpoint (explicit URL in V1; Service Network candidates when available)
  → preview plan + policy simulation
  → execute automatically if inside policy
  → return resource + Run Artifact + receipt

V1 must also support manual testing in the web app:

paste x402 endpoint + goal/payload
  → preview plan
  → simulate policy decision
  → execute only when a real backend/facilitator is connected

The static prototype may persist plans locally and simulate decisions, but must label them Local simulation — no payment sent. It must never fabricate a transaction, resource response, receipt, uptime, or merchant verification.

Product surfaces

### 1. Mission Control

The default operating surface:

• live intent queue grouped by lifecycle;
• exceptions requiring operator approval;
• budget map: Agent Account → policy → vendor → spend;
• anomaly alerts;
• global kill switch and per-agent pause/revoke;
• direct action to create a Mission.

### 2. Agent Accounts

Each Agent Account is a workspace, not a row:

• connection status (MCP first, then SDK, proxy, CLI);
• balance and privacy state;
• active policy and versions;
• approved vendors and methods;
• Missions and receipts belonging to this agent;
• credentials/session revoke;
• pause and permanent revoke.

### 3. Missions

A Mission can start from:

• goal only;
• goal + candidate endpoints;
• explicit endpoint + payload;
• direct intent submitted by an agent adapter.

A Mission retains:

• input goal and mode;
• selected agent and policy version;
• candidates and selection reason;
• Payment Plan;
• policy trace;
• lifecycle events;
• delivered resource or structured output;
• receipt and transaction proof;
• safe replay metadata.

### 4. Service Network

The long-term marketplace has four layers:

1. verified catalog (compatibility, schema, price, test status);

2. open merchant listings;

3. policy-aware vendor recommendation;

4. reusable Mission templates.

V1 is honest: catalog entries are sample/read-only until a merchant registry and compatibility tester exist. An operator may always provide an arbitrary x402 URL.

### 5. Developer Platform

One canonical Core API; adapters contain no separate payment logic.

Order:

1. MCP;

2. SDK;

3. proxy;

4. CLI.

Required machine-readable surfaces before calling an adapter live:

• capability/discovery endpoint;
• OpenAPI document;
• bounded schemas;
• explicit auth/custody boundary;
• honest error states;
• adapter integration test against the live Core API.

Policy behavior

If a Mission is inside policy, it may execute automatically. The policy may choose:

• fixed vendor;
• vendor allowlist;
• best-match vendor selected automatically inside price/method/network constraints.

If blocked, Elypx402 must:

1. name the exact failed rule;

2. show current value vs. allowed value;

3. propose the smallest policy patch;

4. require explicit operator approval and signature for that patch;

5. never retry a possibly broadcast payment as a new payment.

Payment lifecycle

DRAFT
  → PLANNED
  → CREATED
  → AUTHORIZED
  → SETTLEMENT_PENDING
  → SETTLED
  → DELIVERED

Terminal alternatives:

BLOCKED · FAILED · CANCELLED

A Run Artifact is useful even when blocked: it contains the plan, policy trace, failure explanation, and proposed patch.

Privacy model

Preferred V1 behavior:

• private balance is the default route when available;
• otherwise policy may explicitly allow public settlement;
• operator sees which route will be used before execution;
• deposits and withdrawals remain public;
• timing, amounts, and network metadata can still correlate activity.

Private, not untraceable. This statement is product copy, not hidden legal text.

Non-negotiables

• Agents never get the user's main wallet or an unbounded approval.
• No raw secret material ever reaches the backend.
• Every policy is human-reviewed before autonomous execution begins.
• Every settled payment produces a verifiable receipt.
• Raw signatures, proofs, recovery phrases, and private keys are never logged.
• A timeout after broadcast is SETTLEMENT_PENDING, not safe to resend.
• No fake marketplace verification, payment, resource delivery, receipt, metric, or on-chain claim.
• Elysium mainnet only at launch; USDC only; x402 exact only.

MVP acceptance criteria

A real MVP is done only when all of these pass:

1. An operator creates an Agent Account and signs a bounded policy.

2. A real MCP client discovers the tools and submits a Payment Mission.

3. Elypx402 produces a deterministic Payment Plan and policy trace.

4. One real x402 endpoint is called on Elysium mainnet with a small amount.

5. Settlement is reconciled by transaction hash.

6. The resource is returned to the caller only after settlement.

7. The web app shows the same Mission, lifecycle, resource metadata, and receipt.

8. Kill switch, pause, revoke, blocked policy, and timeout paths are tested.

9. No private key, seed phrase, proof, or raw signature reaches logs or Postgres.

Roadmap after the golden path

• Service Network compatibility tester and verified catalog.
• Goal-only vendor discovery and recommendation.
• SDK, proxy, and CLI adapters over the same Core API.
• Merchant self-listing and endpoint verification.
• Mission templates and Agent Teams.
• Private funding/session credits once the Elysium privacy rail is verified for production use.
• Prepaid private sessions and batch settlement for high-frequency low-value calls.

Current implementation truth

• Landing, docs, and a static browser prototype exist.
• Browser state is local-only; there is no production Core API, Postgres, MCP server, facilitator integration, or real privacy rail adapter yet.
• Deposit/withdraw and real Mission execution must remain disabled until those systems exist and are verified.
• Sample Service Network entries are illustrative .example records, not live vendors.

Do not describe the prototype as an operating payment network until the MVP acceptance criteria above are verified.

First real release

One-line product

Elypx402 connects an AI agent to a bounded Agent Account so it can buy an x402 resource autonomously, return the resource, and retain a policy trace plus verifiable receipt—without receiving the operator's main wallet.

Golden demo

1. Operator connects wallet on Elysium.

2. Operator creates ops-agent with:

• 0.10 USDC per request;
• 2 USDC daily;
• 20 USDC lifetime;
• explicit endpoint or vendor allowlist;
• GET/POST methods;
• 14-day expiry.

3. Operator installs the MCP adapter.

4. Agent calls create_payment_mission with:

• goal;
• optional endpoint;
• optional payload;
• maximum price.

5. Elypx402 returns a plan preview and policy trace.

6. If allowed, Elypx402 executes one real x402 payment.

7. The endpoint's resource is returned to the agent.

8. Mission Control shows lifecycle, result metadata, receipt hash, transaction hash, and policy version.

9. A blocked variant explains the failed rule and offers a reviewable policy patch.

Core API resources

AgentAccount
SpendingPolicy
PaymentMission
PaymentPlan
PolicyDecision
RunArtifact
ServiceListing
Receipt

Minimum MCP tools

elypx402_status
list_agent_accounts
create_payment_mission
preview_payment_plan
execute_payment_plan
get_mission
get_receipt
cancel_mission

Mutating tools require a scoped bearer token tied to one Agent Account. execute_payment_plan is allowed only when the signed policy authorizes the exact plan.

MVP web navigation

Mission Control
Agent Accounts
Missions
Service Network
Developer

Mission Control is the default. There is no standalone generic "Overview", "Vault", or "Activity" product identity; balances, receipts, and activity belong to Agent Accounts and Missions.

Explicitly not MVP

• autonomous goal-only marketplace discovery across unverified vendors;
• open merchant self-listing;
• vendor recommendation scores presented as fact without test data;
• Agent Teams;
• multiple chains or assets;
• full private per-call ZK settlement;
• SDK, proxy, or CLI before MCP + Core API works end-to-end.

Prototype behavior

The browser prototype may create local Agent Accounts and local Mission plans. It may evaluate caps and allowlists deterministically. It must show:

LOCAL SIMULATION — NO PAYMENT SENT

It may not synthesize transaction hashes, receipts, endpoint responses, compatibility checks, uptime, or merchant verification.

System architecture

System diagram

┌─────────────────────────────────────────────────────────────┐
│                      USER (browser)                            │
│  Next.js app                                                   │
│  Reown AppKit (wagmi + viem) — wallet connect, network switch   │
│  Private-account material (recovery phrase, ZK notes) generated │
│  and held client-side only — never transmitted to the backend   │
└───────────────┬─────────────────────────────────────────────┘
                │ HTTPS (public routes: no auth required)
                │ HTTPS + SIWE session (gated routes)
                ▼
┌─────────────────────────────────────────────────────────────┐
│                  ELYPX402 APP BACKEND                           │
│                                                                 │
│  Auth: SIWE session issuance + verification                     │
│  Policy Engine: agent caps, allowlists, expiry — CRUD + enforce  │
│  Agent Session Manager: issues scoped session keys per agent    │
│  Payment Orchestrator: builds x402 402 responses, verifies       │
│    PAYMENT-SIGNATURE, drives the settlement state machine        │
│  Receipt Ledger: stores hash + status only, never raw payloads  │
└───────┬───────────────────────────────────┬─────────────────┘
        │                                    │
        ▼                                    ▼
┌───────────────────────────┐    ┌───────────────────────────────┐
│  x402 FACILITATOR            │    │  PRIVACY RAIL ADAPTER            │
│  (self-hosted)               │    │  (integration, not a new pool)   │
│  - verify/settle "exact"      │    │  - reads ElysiumSwap Private      │
│  - USDC + Permit2 fallback    │    │    shield/screen/spend status     │
│  - isolated HYPE gas wallet,  │    │  - never custodies user notes     │
│    small float                │    │  - surfaces: Screening /          │
│  - pending-settlement         │    │    Private-ready / Spent states   │
│    reconciler (tx-hash based) │    │                                    │
└───────┬───────────────────────────┘    └───────┬───────────────────────────┘
        │                                    │
        ▼                                    ▼
┌─────────────────────────────────────────────────────────────┐
│                     ELYSIUM MAINNET (chain 99901)               │
│  Canonical USDC · Permit2 (canonical address) ·                 │
│  x402 Exact Permit2 Proxy (canonical CREATE2 address) ·          │
│  ElysiumSwap Private: Entrypoint, USDC/HYPE pools, PrivatePay,   │
│  ERC-5564 stealth announcer (all pinned, see below)              │
└─────────────────────────────────────────────────────────────┘
                │
                ▼
┌─────────────────────────────────────────────────────────────┐
│                MERCHANT / AGENT CONSUMER SIDE                   │
│  Agent runtime hits a paid endpoint → 402 → pays from its        │
│  scoped session key within policy → merchant delivers resource   │
└─────────────────────────────────────────────────────────────┘

Trust boundaries (map this before writing any payment code)

agent runtime  →  resource server (merchant)  →  facilitator  →  chain
     ↑                                                ↑
  policy-bound                                  verifies + broadcasts,
  session key                                    never custodies funds

• The agent signs a bounded authorization or produces a proof locally.

It has a session key, not the user's wallet key.

• The resource server (merchant) issues the 402, checks the payment,

and decides whether to deliver the resource. It does not hold buyer

funds.

• The facilitator verifies and broadcasts settlement transactions. It

pays gas from its own small HYPE float. It is not a treasury and must

never be given custody of buyer balances.

Payment state machine (mandatory, not optional)

CREATED → AUTHORIZED → SETTLEMENT_PENDING → SETTLED → DELIVERED
                       ↘ FAILED

• Persist the intent at CREATED, before verification — not after.
• Bind the authorization/proof to: resource, HTTP method, recipient,

amount cap, expiry, network, asset.

• A broadcast transaction with no confirmed receipt is

SETTLEMENT_PENDING — reconcile by transaction hash before ever

retrying. Never treat a timeout as "safe to resend."

• Deliver the paid resource only after SETTLED.

Pinned addresses — verify bytecode before trusting, every environment

Before every deploy: re-verify each address's on-chain bytecode matches

expectations via eth_getCode, and re-check eth_chainId returns

0x1863d (99901) on whichever RPC the app is configured to use. Never

allowlist an asset by symbol or name alone — a look-alike USDC is a known

risk on this chain.

Privacy rail integration — build decision

Do not build a new ZK pool, circuit, or relayer. Integrate the existing

ElysiumSwap Private rail:

• Deposit → screening (~1 hour) → private balance ready → private spend /

stealth payment, via their Entrypoint, pools, and relayer.

• Known trust assumptions to carry into the user-facing privacy page: a

single MPC-controlled owner address can upgrade the Entrypoint (the only

upgradeable contract in that stack), their relayer can be paused, and —

as of the most recent check — their Private processor contracts and

relayer are disclosed as not yet externally audited. Reflect this

honestly; do not round it up to "audited and safe."

• V1.5 build: a thin adapter service that reads shield/screening/spend

status from their contracts/events and exposes it to the Elypx402 backend

as a simple state enum. Do not fork or reimplement their circuits.

Why "prepaid private sessions" over per-call private settlement

Per-call onchain private settlement (one ZK proof + one relayer-paid

settlement per $0.001–$0.01 API call) is uneconomic — the relayer fee and

proof overhead exceed the call price. Prefer:

agent privately funds a session escrow once (e.g. $5–$50)
        ↓
gateway issues bounded, one-time-use vouchers per call
        ↓
merchant redeems/settles in batches
        ↓
unused balance/change remains shielded

This is the V2+ direction once V1 (standard x402 exact + optional private

funding) is validated with real merchants.

Tech stack

• Frontend: Next.js (App Router), TypeScript, Tailwind, Reown AppKit,

wagmi v2, viem

• Backend: Node (Hono or Express), TypeScript
• x402: @x402/core, @x402/evm, resource-server middleware

(@x402/express or Hono equivalent) — self-hosted facilitator

• Database: Postgres — policy, agent config, receipt metadata, SIWE

sessions. Never raw secrets, proofs, or payment signatures.

• RPC: a paid provider endpoint with failover, never the shared public RPC

as the sole production dependency.

Build phases

V1    Reown wallet connect + SIWE session + Agent Accounts + deterministic
      Payment Plans + policy traces + MCP adapter + one standard x402
      "exact" USDC golden-path payment and retained Run Artifact
V1.5  Privacy rail adapter: show shield/screening/private-ready status,
      allow private funding and private payment as an option alongside
      standard x402
V2    Merchant/developer console: create paid endpoints, accept both
      schemes, webhooks, receipts dashboard
V3    Prepaid private agent sessions + batch settlement for
      high-frequency low-value calls

Do not start V1.5 work until V1's state machine, policy engine, and auth

model are working end-to-end against Elysium mainnet with a real (small)

settlement.

Auth model

Principle

Browsing is public. Acting is gated. A visitor should be able to

understand the entire product — what it does, how pricing works, what

merchants are live, what the privacy model actually guarantees — without

connecting a wallet. The wallet gate appears exactly at the point where the

app needs to read the user's own private data or move value, never before.

This means two distinct gates, not one:

1. Wallet connect (Reown) — proves the visitor controls an address.

Required before: signing anything, depositing, creating/revoking a

policy. Does NOT by itself grant access to backend-stored personal data.

2. Session auth (SIWE) — after connecting, the app asks for a one-time

sign-in message (EIP-4361 style, off-chain, no gas, no value) to issue a

short-lived session bound to that address. Required before: the backend

will return this address's policies, vault balance, or receipts.

Connecting a wallet does not automatically start a session. A user can

connect, look around, and disconnect without ever signing a session message

or touching the backend's user-scoped data.

Public (no wallet, no session) — always visible

• Landing page, pricing, FAQ
• PRODUCT_SPEC.md-equivalent public docs: how it works, privacy model,

security page

• Merchant directory: public endpoints, price, description (not who paid

whom)

• Aggregate, non-PII network stats (e.g. total settled volume, uptime) —

never per-user figures

• Developer docs for the x402 integration (how to accept payments) — static

reference, no account needed to read it

Gated — requires wallet connect + session (SIWE)

• Mission Control: own intent queue, policy exceptions, budget map and kill

switch

• Agent Accounts: create / list / pause / revoke, policies and credentials
• Missions: own goals, plans, policy traces, resources and receipts
• Private balance and funding state inside an Agent Account
• Developer actions that issue or revoke a scoped adapter credential

Gated — requires wallet connect + an on-chain signature (not just session)

These are value-moving or policy-binding actions. Session auth alone is not

enough; the wallet must sign the specific action:

• Agent Account deposit / withdraw (on-chain transaction)
• Creating, patching or revoking an Agent Account policy (signed message or transaction,

depending on final contract design — see ARCHITECTURE.md)

• Private account creation / recovery-phrase-backed unlock

UX rule for the gate itself

Never redirect an unauthenticated visitor away from a page they navigated

to. Instead, render the page shell with a clear inline prompt:

Connect your wallet to view your agents and balance.
[ Connect wallet ]

A logged-out visitor landing on /app/agents should see the page's purpose

and layout, with the gate as a call-to-action inside the content area — not

a blank screen, not a forced redirect to /.

Implementation notes (for whoever builds this)

• Use wagmi's useAccount for wallet-connected state (client-side, cheap,

no backend call).

• Issue the session only when a gated action is first attempted — do not

prompt for a signature immediately on wallet connect. That's a known dark

pattern and erodes trust in a privacy-positioned product.

• Session token: short-lived JWT or signed cookie, address-scoped, no

wallet permissions implied by its existence.

• Never conflate "has a session" with "has funds" or "has an active agent."

Those are separate backend checks with their own empty states.