SDK / API ReferencePayments
Challenge
Build a 402 body for an x402-paid request
Scope: payments:accept
Returns the standard x402 402 body to send back to a buyer (AI agent) that hasn't paid yet. Loomal resolves your payTo wallet from your Identity automatically.
Most sellers don't call this directly — the requirePayment middleware does it for you. See Accept payments.
Request
import { Loomal } from "@loomal/sdk";
const loomal = new Loomal({ apiKey: process.env.LOOMAL_API_KEY! });
const challenge = await loomal.payments.challenge({
amount: "0.05",
resource: "https://your-api.com/search",
description: "Search API",
network: "base",
});import os
from loomal import Loomal
loomal = Loomal(api_key=os.environ["LOOMAL_API_KEY"])
challenge = loomal.payments.challenge(
amount="0.05",
resource="https://your-api.com/search",
description="Search API",
network="base",
)curl -X POST https://api.loomal.ai/v0/payments/challenge \
-H "Authorization: Bearer loid-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"amount": "0.05",
"network": "base",
"resource": "https://your-api.com/search",
"description": "Search API"
}'Body
| Field | Type | Required | Description |
|---|---|---|---|
amount | string | Yes | Decimal USDC, up to 6 fractional digits. E.g. "0.05", "1.234567" |
network | string | Yes | "base" (Base mainnet — only supported network) |
resource | string | No | Full URL of the resource being paid for. Defaults to empty. |
description | string | No | Human-readable label shown in the 402 body, max 500 chars |
Response — 200 OK
{
"x402Version": 1,
"accepts": [{
"scheme": "exact",
"network": "base",
"maxAmountRequired": "50000",
"resource": "https://your-api.com/search",
"description": "Search API",
"mimeType": "",
"payTo": "0xYourIdentityWalletAddress",
"maxTimeoutSeconds": 60,
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"extra": { "name": "USD Coin", "version": "2" }
}]
}This is the canonical x402 spec response. Send the entire body back to the buyer with HTTP 402 Payment Required.
| Field | Description |
|---|---|
maxAmountRequired | Amount in raw USDC units (6 decimals). "50000" = 0.05 USDC. |
payTo | Your Identity's wallet address. |
asset | USDC contract on the chosen network. |
extra.name / extra.version | EIP-712 domain for the USDC contract. On Base mainnet: "USD Coin" / "2". |
Errors
| Status | error | Cause |
|---|---|---|
| 400 | bad_request | Invalid amount or network |
| 401 | unauthorized | Missing or invalid Authorization header |
| 403 | forbidden | API key lacks payments:accept scope |
| 409 | no_wallet | Identity has no wallet provisioned |
| 503 | feature_disabled | Payments not enabled on this Loomal instance |
Next
POST /v0/payments/redeem — verify and settle the buyer's signed payment.