x402 Integration

x402.jobs is built on the x402 protocol—a standard for pay-per-use HTTP APIs. Understanding x402 helps you build better workflows and create your own resources.

What is x402?

x402 uses HTTP status code 402 (Payment Required) to enable micropayments for API calls. Instead of API keys or subscriptions, you pay for exactly what you use.

The Flow

1. Client calls endpoint
2. Server returns 402 with payment requirements
3. Client signs payment transaction
4. Client calls endpoint with X-PAYMENT header
5. Server verifies payment and returns result

Payment Networks

x402.jobs supports two payment networks:

Solana

• Asset: USDC (EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v)
• Speed: ~400ms confirmation
• Gas: Paid by Facilitator (free for users!)

Base

• Asset: USDC
• Speed: ~2s confirmation
• Gas: Low fees via L2

How x402.jobs Handles Payments

When you run a workflow:

1. Cost Calculation: Total up all resource prices + platform fee
2. Wallet Check: Verify sufficient USDC balance
3. Sequential Execution: Run resources in dependency order
4. Automatic Payment: Sign and submit payments for each resource
5. Receipt Collection: Store transaction signatures for verification

Gas-Free Transactions

x402.jobs uses the Facilitator to cover gas fees. You only pay the resource costs—no SOL or ETH needed for transaction fees.

Response Types

Synchronous Response (200)

Resource returns immediately:

{
  "success": true,
  "response": "Generated caption here",
  "receipt": {
    "amountPaidUsdc": 0.01,
    "transactionSignature": "5abc..."
  },
  "agentId": "captionputer",
  "x402Version": 1
}

Asynchronous Response (202)

Resource needs time to process:

{
  "success": true,
  "jobId": "job-123",
  "statusUrl": "https://api.../status/job-123",
  "etaSeconds": 30,
  "retryAfterSeconds": 2,
  "receipt": {...}
}

x402.jobs automatically polls the statusUrl until complete.

Job Status Response

When polling the status URL:

{
  "state": "succeeded",
  "artifactUrl": "https://storage.../image.png",
  "response": "Your PFP is ready!"
}

Possible states: processing, succeeded, failed

Building Async Resources

For long-running operations (image generation, video processing, etc.), implement the async pattern:

Step 1: Return 202 Accepted

When you receive a paid request, start the job and return immediately:

{
  "success": true,
  "jobId": "job-123",
  "statusUrl": "https://your-api.com/status/job-123",
  "etaSeconds": 30,
  "retryAfterSeconds": 2,
  "receipt": {
    "amountPaidUsdc": 0.1,
    "transactionSignature": "..."
  },
  "agentId": "your-agent",
  "x402Version": 1
}

Step 2: Implement Status Endpoint

Create a GET endpoint at your statusUrl that returns:

While processing:

{
  "state": "processing",
  "progress": 50,
  "response": "Generating image..."
}

On success:

{
  "state": "succeeded",
  "artifactUrl": "https://storage.example.com/output.png",
  "response": "Your image is ready!"
}

On failure:

{
  "state": "failed",
  "error": "Generation failed due to content policy",
  "code": "content_policy_violation"
}

Key Fields

How x402.jobs Handles Async

1. Receives 202 response with statusUrl
2. Polls statusUrl every retryAfterSeconds (default: 2s)
3. Continues until state is succeeded or failed
4. Extracts artifactUrl and displays in Output node
5. Times out after 2 minutes if still processing

Building x402 Resources

Want to create your own x402 endpoint? Here's what you need:

Minimal Implementation

app.post("/x402/solana/myagent/mycommand", async (req, res) => {
  const paymentHeader = req.headers["x-payment"];

  if (!paymentHeader) {
    // Return payment requirements
    return res.status(402).json({
      x402Version: 1,
      accepts: [
        {
          scheme: "exact",
          network: "solana",
          maxAmountRequired: "10000", // $0.01 in micro-USDC
          payTo: "YOUR_WALLET_ADDRESS",
          asset: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        },
      ],
    });
  }

  // Verify payment with Facilitator
  const verified = await verifyPayment(paymentHeader);
  if (!verified) {
    return res.status(402).json({ error: "Payment verification failed" });
  }

  // Execute your logic
  const result = await doWork(req.body);

  return res.status(200).json({
    success: true,
    response: result,
    receipt: verified.receipt,
  });
});

Using Memeputer

The easiest way to create x402 resources is to build a Memeputer agent:

1. Create an agent at memeputer.com
2. Add custom commands with pricing
3. Your commands are automatically x402-compatible
4. Register them in x402.jobs

Learn More

• x402 Protocol Documentation
• Response Types Reference
• Error Codes