TCGenerate
Base
Card-generation API · x402 on Base

Generate AI trading cards over HTTP

TCGenerate turns a text brief — or nothing at all — into an AI trading-card image, billed per call over the x402 payment protocol on Base in USDC. Every endpoint is a plain HTTP resource gated behind a 402 challenge, so your site or an autonomous agent can buy a card with a few lines of code. The buyer is whoever holds the wallet.

x402 is self-describing

Your client does not hardcode the price, network, or token. It calls the endpoint, gets a 402 whose payment-required header describes exactly what to pay (scheme / network / asset / amount / payTo), signs it, and retries.

Payment is gasless for the payer — EIP-3009 transferWithAuthorization, where the facilitator submits the transaction. The server settles only on a successful (<400) response, so a failed generation never charges the buyer.

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.

EndpointPriceBodyReturns
POST/api/cards/random$1.00noneA fully random collectible card. The recommended drop-in — zero input required.
POST/api/generate$2.00{ name, background, subject, action, artStyle? }A card built from your brief. artStyle ∈ anime (default) | fantasy | realistic | cyberpunk.
POST/api/generate/premium$2.50{ name, background, subject, action, artStyle?, referenceImage }A card generated from your brief plus a reference image, where referenceImage is a data-URL.

Response metadata headers

x-tcg-nameCard name (URL-encoded)
x-tcg-subjectSubject of the art (URL-encoded)
x-tcg-actionAction / pose (URL-encoded)
x-tcg-backgroundBackground scene (URL-encoded)
x-tcg-modelGeneration model used
x-tcg-generation-idUnique id for this generation
x-tcg-time-msServer-side generation time (ms)

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
TypeScript · Node
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

Production

Base mainnet

CAIP-2
eip155:8453
USDC
0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Test

Base Sepolia

CAIP-2
eip155:84532
Test USDC
0x036CbD53842c542663149F3F60E88F6E4B0d7f7e

Available for integration testing.

payTo (receives payment)0x70E62bE22984056801257b1935fad11CF932b388

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.

Machine-native commerce

Every endpoint is a plain HTTP resource gated behind a 402 challenge, so autonomous agents can discover the price and buy cards on their own — no API keys, no checkout flow, no human in the loop. A wallet with USDC on Base is the whole account.