x402 HTTP Payment Protocol

What x402 Actually Is

The HTTP 402 status code has existed since 1991, reserved for "Payment Required" but never formally implemented. x402 activates it as a machine-to-machine payment standard: a resource server emits a 402 response with structured payment details, the client constructs and signs a payment payload, retries the request, and the facilitator verifies and settles on-chain.

The key developer-facing insight: agent.fetch() handles all of this transparently. From a developer's perspective it looks identical to a normal fetch call — the entire payment layer is invisible. REAPP intercepts the flow at step 3 to inject mandate validation before any signing happens.

The Full Payment Flow on Stellar

Developer Transparency

The entire 7-step flow is abstracted behind a single function call. This is the core DX principle — agents should be able to pay for resources with the same ergonomics as fetching them.

// This is ALL the developer writes:
const data = await agent.fetch('https://api.dataservice.com/premium/report');

// agent.fetch() internally handles:
// 1. Initial request → receives 402
// 2. AP2 mandate validation against payment details
// 3. Soroban spending limit check
// 4. XDR transaction construction + agent signing
// 5. Facilitator verification
// 6. Retry with X-PAYMENT header
// 7. Stellar settlement (~3 seconds)
// 8. Audit trail recording on-chain
// 9. Returns response data

Why Stellar Beats EVM for Agentic Payments

Stellar's native advantages over EVM x402 directly enable the micropayment economics required for agentic commerce. The numbers matter at scale: an agent making 100 API calls per day at $0.001 each spends $0.10 — the same workflow on Ethereum at $0.01 minimum costs $1.00, ten times more.

Official @x402/* v2 Package Architecture

REAPP builds on the official @x402/* v2 package ecosystem from Coinbase, documented under the stellar/x402-stellar GitHub org and at developers.stellar.org/docs/build/apps/x402. The v2 architecture is transport-agnostic and chain-agnostic — REAPP registers a Stellar-specific scheme that plugs into this ecosystem.

Stellar-Specific Mechanics

The Stellar x402 implementation differs from EVM/SVM in key ways that directly benefit agentic micropayments:

• Soroban auth-entry signing — clients sign InvokeHostFunctionOp with expiration constraints (max_ledger bounds + random nonce for replay protection)
• Fee bump sponsorship — the facilitator sponsors network fees via fee bump transactions, so clients need zero XLM
• SEP-41 token standard — supports both built-in Stellar assets and Soroban contract assets
• Compatible wallets: Freighter, Albedo, Hana, HOT, Klever, OneKey (Freighter Mobile does NOT support x402 yet)

Core Protocol Types

// From @x402/core — defines the entire protocol surface
type Network = `${string}:${string}`;  // CAIP-2: "stellar:pubnet", "stellar:testnet"

type PaymentRequirements = {
  scheme: string;
  network: Network;
  asset: string;
  amount: string;
  payTo: string;
  maxTimeoutSeconds: number;
  extra: Record<string, unknown>;
};

type PaymentPayload = {
  x402Version: number;
  resource: ResourceInfo;
  accepted: PaymentRequirements;
  payload: Record<string, unknown>;
  extensions?: Record<string, unknown>;
};

Server Registration Pattern

import { paymentMiddleware, x402ResourceServer } from "@x402/express";
import { HTTPFacilitatorClient } from "@x402/core/server";
import { ExactStellarScheme } from "@reapp/x402-stellar/exact/server";

const facilitatorClient = new HTTPFacilitatorClient({
  url: "https://channels.openzeppelin.com/x402/testnet",
});
const server = new x402ResourceServer(facilitatorClient)
  .register("stellar:testnet", new ExactStellarScheme());

app.use(paymentMiddleware(
  { "GET /api/data": {
    accepts: [{ scheme: "exact", price: "$0.001",
      network: "stellar:testnet", payTo: "GBXE2KP4FXQF3JKDMR5H6CDHGLPRCAQNBOV3YF7OAHQB6GZXDP7WMKE" }],
    description: "Paid API endpoint"
  }},
  server,
));

Facilitator Trust Model

The facilitator is a non-custodial service that verifies payment signatures and submits transactions to the blockchain. REAPP treats it as part of the threat surface — the SDK is facilitator-agnostic. The OpenZeppelin Relayer x402 Plugin implements the full facilitator API and is the recommended production path:

• Testnet: https://channels.openzeppelin.com/x402/testnet
• Mainnet: https://channels.openzeppelin.com/x402
• Source: github.com/OpenZeppelin/relayer-plugin-x402-facilitator

Fee sponsorship uses the OpenZeppelin Relayer Channels — the replacement for LaunchTube, which was archived on March 9, 2026. The OZ Relayer sponsors network fees via fee bump transactions, so agent clients need zero XLM to operate. If the relayer is unavailable, agents pay standard Stellar fees ($0.00001 per operation).