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 an 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 agent 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 agent's signed payment.