Skip to main content

​
x402 Protocol

x402 implements the long-reserved HTTP 402 “Payment Required” status code for machine-to-machine stablecoin payments. It’s an open protocol — not proprietary to Finance District — and Prism uses it as the primary payment protocol for AI agent commerce. The flow is simple: a client requests a resource, the server responds with 402 and payment requirements, the client pays on-chain, and the server grants access. No API keys to exchange, no OAuth handshakes — just HTTP and stablecoins.
This page covers x402 from the merchant/seller perspective — implementing it with Prism. For the buyer/agent side, see x402 Payments in Agent Wallet.

​
The Protocol Flow

  1. The agent makes a standard HTTP request
  2. The Prism middleware returns 402 with a JSON body describing the accepted payment
  3. The agent’s wallet constructs and signs a stablecoin payment
  4. The agent retries the request with the signed payment in the X-PAYMENT header
  5. Prism’s Spectrum layer settles the payment on-chain and verifies it
  6. The response includes the transaction hash in X-PAYMENT-RESPONSE

​
Implementing x402 with Prism

You don’t implement the x402 protocol directly — the Prism SDK handles it. You configure what to charge and the middleware handles the 402 response, payment verification, and settlement automatically. 
import { prismPaymentMiddleware } from "@1stdigital/prism-express";

app.use(
  prismPaymentMiddleware(
    {
      apiKey: process.env.PRISM_API_KEY,
      baseUrl: "https://prism-gw.fd.xyz",
    },
    {
      "/api/premium": {
        price: "$0.01",
        description: "Premium API access",
      },
      "/api/ai/generate": {
        price: "$0.50",
        description: "AI content generation",
      },
    },
  ),
);
Your endpoint code only runs after payment is confirmed. See the Quick Start for a complete example or SDK Overview for framework-specific guides.

​
Payment Requirements (402 Response)

When the middleware returns 402, the response body contains:
FieldTypeDescription
x402VersionnumberProtocol version (currently 1)
paymentRequiredboolAlways true for 402 responses
acceptedPaymentsarrayList of accepted payment options
descriptionstringHuman-readable description of what’s being purchased
priceUSDstringPrice in USD
Each entry in acceptedPayments contains:
FieldTypeDescription
schemestringPayment scheme (e.g., eip3009)
networkstringChain identifier (e.g., base, eth-sepolia)
assetstringToken (e.g., usdc)
amountstringAmount in token base units
recipientstringMerchant’s wallet address
noncestringUnique nonce for replay protection
validBeforenumberUnix timestamp deadline for payment

​
Payment Verification

When the agent sends a request with the X-PAYMENT header:
  1. Prism parses the signed payment from the header
  2. Forwards it to the Spectrum settlement layer
  3. Spectrum executes the on-chain transfer and verifies: correct amount, correct token, correct recipient, valid signature
  4. If settlement succeeds, the request proceeds and the transaction hash is returned in the X-PAYMENT-RESPONSE header
  5. If settlement fails, the middleware returns 402 with an error
The merchant never needs to verify payments manually — the middleware handles everything between the 402 and the 200.

​
Pricing Models

​
Fixed Pricing

Set a static price per endpoint — every request costs the same: 
{
  "/api/weather": {
    price: "$0.001",
    description: "Weather data"
  }
}

​
Tiered Pricing

Different prices for different endpoints: 
{
  "/api/basic/*": {
    price: "$0.0001",
    description: "Basic API tier"
  },
  "/api/premium/*": {
    price: "$0.01",
    description: "Premium API tier"
  },
  "/api/ai/generate": {
    price: "$0.50",
    description: "AI generation"
  }
}

​
Dynamic Pricing

For endpoints where the price depends on the request, apply per-route middleware: 
app.get(
  "/api/compute",
  prismPaymentMiddleware(config, {
    "/api/compute": {
      price: calculatePrice(req), // dynamic based on request
      description: "Compute resources",
    },
  }),
  (req, res) => {
    res.json({ result: "Computed" });
  },
);

​
x402 Specification

x402 is an open standard. Learn more at x402.org. Prism implements the specification and handles all the protocol complexity through the SDK — you configure prices, and the middleware does the rest.