Book a sponsor week with an x402 payment
Book only through an agent or code with an x402-capable client, paying USDC on Base. There is no browser payment flow. GET /api/v1/sponsor/weeks is free and unmetered: it lists the next 12 weeks with weekStart, status, priceUsdc, purchasable, and reason, alongside salesOpen, currency, and network. Weeks run from Monday 00:00 UTC to the next Monday; the current week is never on sale. Taken weeks and weeks above the cap have priceUsdc null. POST /api/v1/sponsor/bookings takes JSON with name, sentence, url (https without credentials), linkLabel, optional weekStart (a YYYY-MM-DD Monday, defaulting to the first purchasable open week), and optional contactEmail. Unknown fields, including prices, are ignored. Send an explicit weekStart from GET /api/v1/sponsor/weeks to keep the selected week fixed. If weekStart is omitted, the default week can change between the quote and the signed request. An unsigned request for an open week returns HTTP 402 with a PAYMENT-REQUIRED header and an accepts[0] payment option, plus error sponsor_week_payment_required. If you have not sent a signed request, sign that option and retry the same request with PAYMENT-SIGNATURE. The price is computed by the server for every request; a changed price produces a new 402. After sending a signed request, never sign a new payment to resolve a retry. For a network error or HTTP 5xx without settled_but_not_saved, retry the same body with the same PAYMENT-SIGNATURE. HTTP 402 or 409 on a retry does not prove that nothing was charged, even without PAYMENT-RESPONSE. If the outcome is unclear, email info@x402-list.com with the payment transaction hash. For an unsigned request, HTTP 409 uses error.reason week_not_monday, week_outside_window, week_taken, price_above_cap, no_week_available. These reasons can also appear on a signed retry after a prior request settled. After payment, week_taken_after_payment means an earlier payment took the week; your payment is recorded and refunded by hand. Do not pay again. HTTP 201 returns data with id, weekStart, status in_review, priceUsdc, and txHash, plus provenance and a PAYMENT-RESPONSE settlement receipt header. HTTP 409 with error.reason week_taken_after_payment and HTTP 500 with error.reason settled_but_not_saved both mean payment settled and carry PAYMENT-RESPONSE. If the booking could not be saved, email the transaction hash. Do not pay again after either response. A valid request for an open week receives HTTP 503 when sales are paused or the payment layer is not configured. Invalid fields and week conflicts are returned first. The price of the first open week starts at 25 USDC. Each sold week raises the price of the next one by 12.5 percent; each week that goes unsold lowers it by 12.5 percent, never below 25 USDC. Booking further ahead adds 12.5 percent for each week in between. Prices are rounded to whole USDC, and a week priced above 100 USDC cannot be booked. Every booking is reviewed by hand before the row goes live. Anyone can book, and we may decline a booking. A booking that is declined in review, or that loses its week to an earlier payment, is refunded by hand to the wallet that paid. The sponsor row is not part of the directory data served by the API, the MCP server, or llms.txt, and it never changes rankings, scores, or badges.
Request
- Base URL: https://x402-list.com/api/v1
- URL: https://x402-list.com/api/v1/sponsor/bookings
- Auth: none declared
Request body
Response
Sponsor booking paid and awaiting review
Example response
{
"provenance": {
"attribution": "Data: x402-list.com (CC BY 4.0)",
"cite_as": "https://x402-list.com/services/acme-generate",
"source": "https://x402-list.com"
}
}Changes
No recorded changes to this operation across all 1 revision of this API.