PhotoMatchFun logo

HTTP-native payment

x402 payment guide

PhotoMatchFun uses x402 v2 for exact USDC payments on Base. Your wallet signs the server-issued requirement; PhotoMatchFun verifies and settles it before sending the physical order to fulfillment.

Protocol

x402 v2

Scheme

exact

Network

Base Mainnet

Asset

USDC

Treat the live PAYMENT-REQUIRED response and order-intent receipt as authoritative. Do not hardcode an amount or copy a recipient from documentation.

Payment handshake

Review first, authorize second

  1. 01

    Request

    POST the payment URL returned by create_order_intent. Without a signature, the server answers 402 with a PAYMENT-REQUIRED header.

  2. 02

    Validate and sign

    Your wallet verifies the amount, network, asset, recipient, order digest, and expiry against the intent the customer approved, then creates PAYMENT-SIGNATURE.

  3. 03

    Settle and fulfill

    Repeat the same POST with the signed header. A successful settlement returns PAYMENT-RESPONSE and queues the physical order.

Buyer-side example

Use an x402-capable client inside a wallet environment with an explicit spending policy. The wrapper handles the 402 challenge and signed retry.

Important: walletAccount is a signer object held by your wallet runtime. It is not a private key string and must never be sent to PhotoMatchFun.
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";

// walletAccount stays inside your trusted wallet runtime.
const paidFetch = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{
    network: "eip155:*",
    client: new ExactEvmScheme(walletAccount),
  }],
});

const response = await paidFetch(paymentUrl, { method: "POST" });
if (!response.ok && response.status !== 202) {
  throw new Error(await response.text());
}

const receipt = await response.json();

Before signing

  • The amount and currency match the order-intent receipt.
  • The order digest and intent ID match the order under review.
  • The requirement uses x402 v2, the exact scheme, USDC, and the expected Base network.
  • The intent has not expired and remains within the customer's approved spending limit.

Retry safely

  • For a busy response, respect Retry-After and retry the same payment URL.
  • If settlement is reported as unknown, retry the same signed payment exactly as instructed.
  • Never create a second authorization just because fulfillment is still processing.
  • If status requests operator review, retain the intent and status capability for support.

Start from the MCP order contract

The MCP guide covers product discovery, artwork uploads, consent, and order intents.

Read the MCP guide