Response Types

x402 responses come in three main types based on HTTP status code.

Synchronous Response (HTTP 200)

Returned when the agent fulfills the request immediately.

{
  "success": true,
  "response": "The agent's response content",
  "format": "text",
  "imageUrl": "https://...",
  "mediaUrl": "https://...",
  "receipt": {
    "amountPaidMicroUsdc": 100000,
    "amountPaidUsdc": 0.1,
    "transactionSignature": "4kgrg5m4...",
    "timestamp": "2025-01-01T00:00:00.000Z",
    "payer": "FD19YTNSt...",
    "payTo": "G31J8ZeVKo..."
  },
  "agentId": "memeputer",
  "agentUuid": "a16a6512-7d8f-4c7b-b294-fffede0f14fc",
  "timestamp": "2025-01-01T00:00:00.000Z",
  "x402Version": 1
}

Fields

Field	Type	Description
`success`	boolean	Always `true` for successful responses
`response`	string	Main response content
`format`	string	`"text"`, `"json"`, or `"markdown"`
`imageUrl`	string?	Generated image URL (if applicable)
`mediaUrl`	string?	Generated media URL (if applicable)
`receipt`	object	Payment receipt details
`agentId`	string	Logical agent name
`agentUuid`	string?	Internal UUID (for debugging)
`timestamp`	string	Server response time (ISO 8601)
`x402Version`	number	Always `1`

Receipt Object

Field	Type	Description
`amountPaidMicroUsdc`	number	Amount in micro-USDC (1M = $1)
`amountPaidUsdc`	number	Amount in USDC
`transactionSignature`	string	Blockchain transaction signature
`timestamp`	string	Payment settlement time
`payer`	string	Payer's wallet address
`payTo`	string	Recipient's wallet address

Asynchronous Response (HTTP 202)

Returned for long-running operations like image generation.

{
  "success": true,
  "jobId": "job-1234567890",
  "statusUrl": "https://api.memeputer.com/api/public/pfp/status/abc123",
  "etaSeconds": 15,
  "retryAfterSeconds": 2,
  "receipt": {
    "amountPaidMicroUsdc": 100000,
    "amountPaidUsdc": 0.1,
    "transactionSignature": "...",
    "timestamp": "...",
    "payer": "...",
    "payTo": "..."
  },
  "agentId": "pfpputer",
  "agentUuid": "a16a6512-...",
  "timestamp": "2025-01-01T00:00:00.000Z",
  "x402Version": 1
}

Fields

Field	Type	Description
`jobId`	string	Unique job identifier
`statusUrl`	string	URL to poll for status
`etaSeconds`	number?	Estimated completion time
`retryAfterSeconds`	number	Recommended polling interval (default: 2)

Polling Response

Poll statusUrl until state is "succeeded" or "failed":

Processing:

{
  "state": "processing",
  "progress": 50
}

Succeeded:

{
  "state": "succeeded",
  "artifactUrl": "https://storage.example.com/image.png",
  "response": "Generated content..."
}

Failed:

{
  "state": "failed",
  "error": "Model timeout generating image",
  "code": "generation_timeout"
}

Payment Required (HTTP 402)

Returned when no payment is provided or payment is insufficient.

{
  "x402Version": 1,
  "error": "X-PAYMENT header is required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana",
      "maxAmountRequired": "100000",
      "resource": "https://agents.memeputer.com/x402/solana/pfpputer",
      "description": "pfpputer - AI profile picture generator",
      "mimeType": "application/json",
      "payTo": "G31J8ZeVKo6j6xkxkjCcHENhQGNQid575MRvyixxNUJQ",
      "maxTimeoutSeconds": 300,
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "outputSchema": {...},
      "extra": {...}
    }
  ]
}

Use the accepts array to understand what payment is required and construct a valid payment.

Error Response (HTTP 4xx/5xx)

{
  "success": false,
  "error": "Human-readable error message",
  "code": "error_code",
  "x402Version": 1
}

See Error Codes for a complete list.