Base x402

Sovereign Wallet OS is designed as a Base-first constitutional wallet framework. This page documents the relationship between Base, x402, USDC, and Sovereign's governance layer.

Why Base

Base is the natural home for governed agentic commerce. It provides:

• EVM-compatible wallets that autonomous agents can operate against
• USDC as the dominant stablecoin for machine-to-machine service payments
• x402 as an emerging payment protocol for API-level micropayments
• Builder Codes for attribution across app, wallet, and agent surfaces
• Spend Permissions as a path toward scoped, auditable agent spend authority
• A developer ecosystem and grant infrastructure aligned with agentic use cases

Sovereign does not compete with Base's primitives — it adds the governance layer that sits above them. Base gives agents the ability to pay. Sovereign controls whether a specific agent, under a specific wallet constitution, is allowed to pay.

What x402 provides

x402 is an HTTP-level payment protocol for machine-readable service payments. An agent that encounters an x402-gated API endpoint can respond to the payment challenge with a USDC payment, receive a receipt, and gain access to the data or service.

Without governance, this is equivalent to giving an agent a credit card with no spending limits, no merchant validation, and no audit trail.

What Sovereign adds

Sovereign intercepts the x402 payment request before any funds move. Instead of letting an agent respond to the payment challenge directly, the agent submits an EconomicIntent to Sovereign's constitutional runtime. The runtime:

• Verifies the merchant route fingerprint against the registered payee
• Checks the procurement wallet's budget allocation and daily limits
• Evaluates the wallet constitution (merchant allowlist, price ceiling, task binding)
• Issues a DecisionPacket scoped to this exact payment if approved
• Executes the x402 payment through an adapter using the packet as authorization
• Creates a DataArtifact linked to the merchant, route, decision, and wallet
• Writes an audit event and journal entry for the settled payment

The agent never touches the signing key. The x402 payment happens under constitutional authority, not unchecked agent authority.

Local x402 simulation

In the default local mode (SOVEREIGN_PAYMENT_MODE=mock_x402), Sovereign simulates the x402 payment flow without making any real network calls. The full constitutional evaluation runs — merchant checks, budget reservation, decision packet signing, artifact creation, provenance, accounting — but the payment itself is a deterministic local simulation.

This mode is designed for rapid local development, demo runs, and CI validation. The procurement constitution is identical to the one used in Base Sepolia mode.

SOVEREIGN_PAYMENT_MODE=mock_x402  # default

pnpm dev:api
pnpm demo:paid-data

Base Sepolia x402 mode

When configured with SOVEREIGN_PAYMENT_MODE=base_sepolia_x402, Sovereign executes real x402 payments using test USDC on Base Sepolia (eip155:84532). The procurement wallet uses a funded test buyer wallet to settle payments through the x402.org/facilitator endpoint.

The payment path is identical to local simulation — the only difference is that the execution adapter calls the real x402 protocol instead of the local mock. The constitutional evaluation, decision packet, and provenance chain are unchanged.

SOVEREIGN_PAYMENT_MODE=base_sepolia_x402
SOVEREIGN_X402_NETWORK=eip155:84532
SOVEREIGN_USDC_ADDRESS=0x036CbD53842c5426634e7929541eC2318f3dCF7e
SOVEREIGN_X402_FACILITATOR_URL=https://x402.org/facilitator
SOVEREIGN_BUYER_PRIVATE_KEY=0x...   # test wallet only
SOVEREIGN_MERCHANT_PAY_TO=0x...     # test merchant address
SOVEREIGN_X402_PRICE_ATOMIC=50000   # 0.05 USDC
SOVEREIGN_X402_PRICE_LABEL=0.05 USDC

Call the readiness endpoint to verify the configuration before running a demo:

curl http://localhost:3003/v1/demo/base-x402/readiness

The readiness response shows ready: true when all required env vars are present and the buyer private key resolves to a valid address. It shows the derived buyerAddress (never the private key) and the full payment configuration.

Future Base mainnet mode

A base_mainnet_x402 mode is defined in the payment mode registry but is intentionally disabled in the current MVP. Enabling real-money mainnet payments requires additional policy review, risk controls, and custody infrastructure.

Spend Permissions roadmap

Base's Spend Permission model allows wallets to grant scoped, time-bounded spend authority to agents without transferring custody. Sovereign's constitutional wallet framework is designed to compile wallet constitutions into Spend Permission targets — an agent's approved budget and merchant constraints become on-chain spend permissions rather than off-chain policy.

This is a roadmap item. The current MVP implements equivalent controls in the Sovereign runtime layer with the same semantic guarantees.

Builder Codes roadmap

Base's Builder Code system attributes on-chain transactions back to the app, wallet, and agent that originated them. Sovereign plans to embed Builder Codes in future Base transactions so that governed agent payments carry full attribution through the x402 payment path.

In the current MVP, provenance is tracked in Sovereign's own ledger. On-chain attribution through Builder Codes is a roadmap item.

Payment Rail reference

• payment.mode — mock_x402 | base_sepolia_x402
• payment.network — eip155:84532 (Base Sepolia)
• payment.tokenAddress — USDC on Base Sepolia: 0x036CbD53842c5426634e7929541eC2318f3dCF7e
• payment.facilitatorUrl — https://x402.org/facilitator
• payment.lastReceipt.txHash — present only when a real Base Sepolia payment was made
• payment.lastReceipt.settlementId — settlement reference from the facilitator

Open Akasha Control Room →