Routes & pricing

​

The builder

serve
  .route({ path: 'search', description: 'Shown in discovery docs + listings' })
  .paid('0.02')                        // or .unprotected()
  .body(schema, jsonSchema)            // optional
  .response(responseJsonSchema)        // optional
  .handler(async ({ body, req, payer }) => result);

​

.paid(price)

• Human-unit USDC string: '0.02' = 2 cents. Max 6 decimals (USDC atomic precision).
• ≤ 5 USDC to list — higher prices work over the protocol but won’t pass the catalog’s price-cap gate (serve warns at build time). Work priced above $5 belongs in [escrowed services](/commerce/sell-services) (up to$50).
• The price is enforced on-chain at settlement: the balance change to your payTo must cover it, or the request is refused before your response ships.

​

.unprotected()

​

.body(schema, jsonSchema?)

• schema validates at runtime: zod v4, valibot, arktype (anything Standard Schema), or any object with a zod-style safeParse. serve has no schema dependency of its own.
• Validation runs before payment settles. Invalid input → 422, buyer keeps their money. This kills the worst seller bug class: charging for errors.
• jsonSchema (optional second arg) is published in /openapi.json + /llms.txt so buyers’ agents build request bodies without guessing — with zod v4 it’s one call: z.toJSONSchema(schema).

​

.response(jsonSchema)

const output = z.object({
  logoSvg: z.string().meta({ contentMediaType: 'image/svg+xml' }), // rendered as an image
  palette: z.array(
    z.object({ name: z.string(), hex: z.string().meta({ format: 'color' }) }), // rendered as swatches
  ),
  report: z.string().meta({ contentMediaType: 'text/markdown' }),
});

.response(z.toJSONSchema(output))

​

The handler context

.handler(async ({ body, req, payer }) => { ... })

​

The paid request lifecycle

1. No X-PAYMENT → 402 with the x402 accepts[] envelope (fresh challenge, live epoch window).
2. Retry with X-PAYMENT → structural verification (right recipient, right terms, gasless-only, challenge-bound nonce).
3. Body validation → 422 if invalid, nothing settled.
4. Your handler runs → 500 if it throws, nothing settled.
5. Settlement — serve submits the buyer-signed gasless transaction, confirms the USDC balance change on-chain, records digest + challenge in the replay store.
6. Response ships with the X-PAYMENT-RESPONSE receipt header.