x402 Agent Payments

x402 follows a four-step request/response cycle, all within a single logical transaction:

1. 1

   Agent sends a request to a Kilawatt x402 endpoint describing the compute it wants.

2. 2

   Kilawatt responds 402 Payment Required, returning the exact price and payment details needed to proceed.

3. 3

   Agent signs a payment for that exact amount from its own wallet and resends the request with payment attached.

4. 4

   Kilawatt verifies and settles the payment, then attempts provisioning and returns the resulting job details.

No manual signup or prior API key setup is required. The agent needs a funded wallet on Base holding USDC. Kilawatt creates the wallet's machine account and API key automatically on its first successful payment.

Send a POST request describing the compute job. No payment header is included on the first attempt.

{
  "gpu_type": "nvidia-a10",
  "card_count": 1,
  "duration_seconds": 60,
  "routing_policy": "lowest_cost",
  "workload_type": "agent_exec"
}

Fields not listed above are ignored. This request has no field for source code, a command, a container image, or a workload payload. It provisions tracked GPU capacity for the selected duration and workload classification; it does not submit code to run.

The agent's wallet signs an EIP-3009 transferWithAuthorization payload for the exact amount requested, and resends the original request with the payment attached per the x402 spec.

In practice, most implementations use an x402-aware HTTP client that handles this automatically rather than constructing the payload by hand.

Kilawatt supports x402 v1 with the X-PAYMENT header and x402 v2 with PAYMENT-SIGNATURE and PAYMENT-REQUIRED headers. v2 identifies Base mainnet as eip155:8453. See the machine-readable OpenAPI document.

Authenticate with Authorization: Bearer kw_live_.... The job must belong to the API key's account. The receipt returns the recorded fields below.

If payment verification or settlement fails, Kilawatt returns a non-200 status with the same challenge structure and an error field describing the failure reason.

{
  "x402Version": 1,
  "error": "invalid_payload: contract call failed: unable to call contract: execution reverted",
  "accepts": [ ... ]
}

Common causes include insufficient USDC balance, an expired or malformed payment payload, or a signed amount that no longer covers the price. The accepts array is included on error responses so a client can inspect requirements and retry.

• 400 invalid_json: The body is not a JSON object. An empty body uses the defaults. Checked before any price is quoted.
• 415 unsupported_media_type: Content-Type is present and is not application/json.
• 400 unknown_gpu_type: gpu_type is not supported. The body lists valid_gpu_types.
• 400 wrong_payment_header: The payment's x402Version does not match the header it was sent in. v1 goes in X-PAYMENT, v2 in PAYMENT-SIGNATURE. Nothing is charged or settled.
• 400 size_not_available: A card count above 8 cannot be placed right now. No payment is taken.
• 402 price_changed: The signed amount no longer covers the job. In v2 the body also carries required_amount_usd.
• 402 insufficient_funds_or_invalid_signature: The paying wallet may not hold enough USDC on Base, or the signature is invalid.
• 409 payment_already_used: This payment authorization was already settled. Includes transaction_hash and, when known, job_id. Fetch the receipt instead of paying again.
• 405: GET, PUT, PATCH and DELETE return JSON with an Allow: POST, OPTIONS header.
• 503: No capacity can be priced or placed right now. No payment is taken; retry later.

Send an Idempotency-Key header on paid requests and reuse it on retries. If a paid response is lost, a retry with the same key and a new payment authorization returns the original job id and status instead of creating a second job. The one-time api_key is returned only in the wallet's first paid response.

The fastest way to a first call. Use a dedicated test wallet holding a few dollars of USDC on Base. Never use the private key of a wallet that holds other funds.

import { privateKeyToAccount } from "viem/accounts";
import { wrapFetchWithPayment } from "x402-fetch";

const account = privateKeyToAccount(process.env.TEST_WALLET_PRIVATE_KEY);
const fetchWithPayment = wrapFetchWithPayment(fetch, account);

const response = await fetchWithPayment(
  "https://www.kilawattcloud.dev/api/public/x402/exec",
  {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      gpu_type: "nvidia-a10",
      card_count: 1,
      duration_seconds: 60,
      routing_policy: "lowest_cost",
      workload_type: "agent_exec",
    }),
  }
);
console.log(await response.json());

Install with npm i viem x402-fetch. A successful response confirms provisioning and returns job, payment and health metadata. It does not run your code.

x402 and Kilawatt's standard API (Starter / Pro / Scale prepay tiers) both provision the same underlying GPU capacity and both enforce funding before a job is dispatched. They differ in how payment and account setup are established.