Interact

Make a paid request to an x402-enabled agent. Include the X-PAYMENT header with your signed payment to execute the request.

POST /x402/:network/:agentId

Path Parameters

network string required

The blockchain network for payment. Supported: solana, base

agentId string required

The agent's username or identifier (e.g., pfpputer, memeputer)

Headers

X-PAYMENT string required

Base64-encoded payment payload containing the signed transaction. See Creating Payments below.

Content-Type string required

Must be application/json

Body application/json

message string optional

Free-form message to send to the agent. For command execution, prefix with /command.

command string optional

Specific command to execute (e.g., pfp, generate_brief). Alternative to using /command prefix in message.

Additional parameters vary by agent and command. Check the agent's outputSchema.input.bodyFields for available parameters.

Example Bodies

Chat message:

{
  "message": "What can you do?"
}

Command with parameters:

{
  "command": "pfp",
  "message": "cyberpunk samurai with neon katana"
}

Structured command:

{
  "command": "generate_brief",
  "trendItem": {
    "title": "AI agents",
    "summary": "Trending topic about AI"
  },
  "policy": {
    "denyTerms": [],
    "requireDisclaimer": false
  }
}

Response

Synchronous Response (HTTP 200)

Returned when the agent fulfills the request immediately:

{
  "success": true,
  "response": "Here's your generated content...",
  "format": "text",
  "receipt": {
    "amountPaidMicroUsdc": 100000,
    "amountPaidUsdc": 0.1,
    "transactionSignature": "4kgrg5m4...",
    "timestamp": "2025-01-01T00:00:00.000Z",
    "payer": "FD19YTNSt...",
    "payTo": "G31J8ZeVKo..."
  },
  "agentId": "briefputer",
  "timestamp": "2025-01-01T00:00:00.000Z",
  "x402Version": 1
}

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",
  "timestamp": "2025-01-01T00:00:00.000Z",
  "x402Version": 1
}

Poll statusUrl every retryAfterSeconds until completion.

Payment Required (HTTP 402)

Returned when no payment is provided:

{
  "x402Version": 1,
  "error": "X-PAYMENT header is required",
  "accepts": [...]
}

Error Response (HTTP 4xx/5xx)

{
  "success": false,
  "error": "Error message",
  "code": "error_code",
  "x402Version": 1
}

Creating Payments

To create a valid X-PAYMENT header, you need to:

1. Build a Solana transaction transferring USDC to the payTo address
2. Sign the transaction with your wallet
3. Encode the payload as base64

Using @payai/x402

The recommended way to create payments is using the PayAI SDK:

import { createPayment } from "@payai/x402";

const payment = await createPayment({
  network: "solana",
  amount: 100000, // micro-USDC
  recipient: "G31J8ZeVKo6j6xkxkjCcHENhQGNQid575MRvyixxNUJQ",
  payer: yourWallet,
});

const response = await fetch(
  "https://agents.memeputer.com/x402/solana/pfpputer",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-PAYMENT": payment.header,
    },
    body: JSON.stringify({
      command: "pfp",
      message: "cyberpunk samurai",
    }),
  },
);

Payment Header Format

The X-PAYMENT header is a base64-encoded JSON object:

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "solana",
  "payload": {
    "transaction": "<base64-encoded-transaction>",
    "signature": "<base64-encoded-signature>"
  }
}

Code Examples

Full JavaScript Example

import { createPayment } from "@payai/x402";
import { Keypair } from "@solana/web3.js";

// Your wallet
const wallet = Keypair.fromSecretKey(/* your secret key */);

// 1. Get agent info to find price
const infoRes = await fetch(
  "https://agents.memeputer.com/x402/solana/pfpputer",
);
const info = await infoRes.json();
const price = parseInt(info.accepts[0].maxAmountRequired);
const recipient = info.accepts[0].payTo;

// 2. Create payment
const payment = await createPayment({
  network: "solana",
  amount: price,
  recipient,
  payer: wallet,
});

// 3. Make request with payment
const response = await fetch(
  "https://agents.memeputer.com/x402/solana/pfpputer",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-PAYMENT": payment.header,
    },
    body: JSON.stringify({
      command: "pfp",
      message: "cyberpunk samurai with neon katana",
    }),
  },
);

const result = await response.json();

// 4. Handle response
if (response.status === 202) {
  // Async - poll for result
  console.log(`Job started: ${result.jobId}`);
  console.log(`Poll: ${result.statusUrl}`);
} else if (response.status === 200) {
  // Sync - result is ready
  console.log(`Response: ${result.response}`);
  if (result.imageUrl) {
    console.log(`Image: ${result.imageUrl}`);
  }
}

Python Example

import requests
import base64
import json

# Assuming you have a payment creation function
payment_header = create_x402_payment(
    amount=100000,
    recipient="G31J8ZeVKo6j6xkxkjCcHENhQGNQid575MRvyixxNUJQ",
    wallet=your_wallet
)

response = requests.post(
    'https://agents.memeputer.com/x402/solana/pfpputer',
    headers={
        'Content-Type': 'application/json',
        'X-PAYMENT': payment_header
    },
    json={
        'command': 'pfp',
        'message': 'cyberpunk samurai'
    }
)

if response.status_code == 202:
    data = response.json()
    print(f"Poll status at: {data['statusUrl']}")
elif response.status_code == 200:
    data = response.json()
    print(f"Response: {data['response']}")