X402 Generate


POST /api/x402/{slug}

Generate AI content using the X402 payment protocol. The first request returns a 402 challenge; the retry with a signed payment header triggers generation.

Path Parameters

Parameter	Type	Description
`slug`	string	Endpoint identifier (e.g., `nano-banana`)

Request Body


{
  "prompt": "A photorealistic sunset over the ocean",
  "aspect_ratio": "16:9",
  "output_format": "webp"
}

Field	Type	Required	Description
`prompt`	string	Yes	Generation prompt (1–10,000 characters)
`aspect_ratio`	string	No	Image ratio: `1:1`, `4:3`, `3:4`, `16:9`, `9:16`
`output_format`	string	No	Output format: `png`, `jpg`, `webp`
`resolution`	string	No	Output resolution (provider-dependent)

Headers

Header	Value	Description
`Content-Type`	`application/json`	Required
`X-PAYMENT`	Base64-encoded payment	Required on retry after 402 challenge

Response — 402 Payment Required (First Request)


{
  "error": "X402: Payment Required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "USDC",
      "amount": "50000",
      "recipient": "0x1234...abcd"
    }
  ],
  "x402Version": 1
}

The amount is in USDC’s smallest unit (6 decimals). 50000 = $0.05 USDC.

Response — 200 Success (After Payment)


{
  "success": true,
  "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "statusUrl": "/api/task/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Generation started. Poll statusUrl for results."
}

Error Responses

Status	Code	Description
400	`VALIDATION_ERROR`	Invalid or missing prompt
402	—	Payment challenge (normal X402 flow)
404	`NOT_FOUND`	Endpoint slug does not exist
429	—	Rate limited (10 req/min)
500	`EXECUTION_ERROR`	Generation failed server-side

Example with x402-fetch


import { wrapFetch } from 'x402-fetch'
 
const fetchX402 = wrapFetch(fetch, {
  payerWalletPrivateKey: process.env.WALLET_PRIVATE_KEY,
})
 
const res = await fetchX402('https://402claw.cloud/api/x402/nano-banana', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ prompt: 'A cyberpunk cityscape' }),
})
 
const { taskId, statusUrl } = await res.json()

Example with curl


# Step 1: Get 402 challenge
curl -X POST https://402claw.cloud/api/x402/nano-banana \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A cyberpunk cityscape"}'
 
# Step 2: Sign payment and retry (see X402 spec for signing details)
curl -X POST https://402claw.cloud/api/x402/nano-banana \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <signed-payment>" \
  -d '{"prompt": "A cyberpunk cityscape"}'