Generate AI trading cards over HTTP

The flow

1. 1

   Buyer calls the endpoint

   Your client sends a POST to a TCGenerate endpoint with a payment-wrapped fetch.

2. 2

   TCGenerate answers 402

   TCGenerate replies 402 Payment Required with a payment-required header describing exactly what to pay: scheme: exact, the network, the USDC asset, the amount, and the payTo address.

3. 3

   Client signs & retries

   The x402 client signs a USDC authorization for that exact amount and retries the request with an X-PAYMENT header.

4. 4

   TCGenerate settles & returns the card

   TCGenerate verifies and settles via the facilitator, generates the card, and returns 200 with the image bytes (JPEG) plus x-tcg-* metadata headers. Settlement happens only on a successful (<400) response, so a failed generation never charges the buyer.

Endpoints

All three respond with binary JPEG (content-type: image/jpeg), not JSON. Card metadata rides in the response headers.

Response metadata headers

Quickstart

Install the x402 client and viem, then let the payment-wrapped fetch handle the whole 402 → sign → retry handshake for you.

npm install @x402/fetch @x402/evm viem

import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

// A wallet funded with USDC on Base (no ETH needed — payments are gasless).
const account = privateKeyToAccount(process.env.BUYER_PRIVATE_KEY as `0x${string}`);
const wallet = createWalletClient({ account, chain: base, transport: http() });

// x402 reads the price/network/asset from the 402 challenge — nothing hardcoded.
const client = new x402Client().register("eip155:8453", new ExactEvmScheme(wallet));
const fetchWithPay = wrapFetchWithPayment(fetch, client);

// Buy a random card for $1. The 402 → sign → retry handshake is automatic.
const res = await fetchWithPay("https://tcgenerate.com/api/cards/random", { method: "POST" });

const cardJpeg = Buffer.from(await res.arrayBuffer());            // the image bytes
const name = decodeURIComponent(res.headers.get("x-tcg-name") ?? "");
// → save cardJpeg / display it / mint it. That's the whole integration.

Network reference

Because the client reads the network from the 402 challenge, the same integration code works against whichever network TCGenerate is currently serving — no code change to move from test to production.