x402 Payments

Pricing an Endpoint

import { BaseAgent, Skill, http, pricing } from 'webagents';
import { PaymentSkill } from 'webagents/skills/payments';

class Quotes extends Skill {
  @pricing({ creditsPerCall: 0.01, reason: 'A quote' })
  @http({ path: '/quote', method: 'GET', description: 'A price quote' })
  async quote(): Promise<Response> {
    return Response.json({ price: 42 });
  }
}

const agent = new BaseAgent({
  name: 'quotes',
  instructions: 'You quote prices.',
  skills: [new Quotes(), new PaymentSkill({ x402: { nonceSecret: process.env.X402_NONCE_SECRET } })],
});

What a Caller Sees

Feedback
No payment: 402 Payment Required, with the offers in the PAYMENT-REQUIRED header (x402 v2, base64 JSON) and a v1 JSON body, and Cache-Control: no-store. Each offer in accepts names a scheme, a network, an amount, an asset and who is paid.
Feedback
The retry carries the payment for one of the offers, in PAYMENT-SIGNATURE (v2) or X-PAYMENT (v1). The paywall matches it to the offer, verifies it, and only then runs the handler.
Feedback
The handler answered below 400: the payment is settled, once, and the answer goes out with PAYMENT-RESPONSE (v2) or X-PAYMENT-RESPONSE (v1). A handler that answers 400 or above is not charged, and its answer goes out as it is.
Feedback
The settle failed: 402, with the failed settle in the response header and an empty body.

The Credits Scheme

Metered Endpoints

from webagents import Skill
from webagents.agents.skills.robutler.payments import PricingInfo, pricing
from webagents.agents.tools.decorators import http


class Reports(Skill):
    @http("/report", method="get")
    @pricing(lock=0.05)
    async def report(self) -> tuple:
        """A report, priced by its size."""
        return {"rows": 7}, PricingInfo(credits=0.002, reason="7 rows")

On-Chain Payments on a Self-Hosted Agent

Describing the Endpoint

Hosted Agents

Chat Turns

The machine-payments buyer

Feedback
A paid 2xx is handed to you unread. A streamed answer is the common case for a paid call, so the buyer does not consume the body it is supposed to give back. It reads a 2xx only when the response declares a length, and then only through a clone, bounded at 64 KiB; anything else reaches you still streaming. Python puts back whatever it had to peek at.
Feedback
A purchase pointer is followed only under a daily cap. Some answers carry an mpp requirement that names a purchase_url and no challenge, because whatever sent it had not verified who was asking. That is a pointer, not a challenge: purchaseAt / purchase_at asks the purchase URL itself with a signed POST, is challenged there as its own identity, and pays under the same policy as any other purchase. Nothing is sent unless the hosts of both the purchase URL and whatever named it are on policy.realms, and nothing is sent unless a daily cap is set (dailyCapCents / daily_cap_cents); without one the refusal reason is pointer_needs_daily_cap. A pointer carries no secret, so any peer reachable through an allowed host can write one, and the per-call purchase limit bounds one call while only the daily cap bounds the total across calls.
Feedback
The replayed call drops your payment token. After a purchase the buyer re-sends the original request without the exhausted token, in all three of its spellings (x-payment-token, x-payment, ?payment_token=), and keeps the body and your other headers. A resource serves a newly purchased balance to a signed request that names no token, so re-sending the spent one could only be refused again.
Feedback
A redirect is never followed. Every send refuses redirects outright, and a redirect that some other transport already followed is caught too. The refusal reason is redirect_refused. A challenge is bound to the resource that issued it, so following a redirect would offer your payment credential to whatever the Location header named.
Feedback
Every send is bounded. The default purchase timeout is 60 seconds, settable as purchase_timeout_seconds / purchaseTimeoutSeconds on the policy. In TypeScript the buyer enforces that bound itself; in Python it holds for a client the buyer opens, so a client you pass in brings its own timeout.
Feedback
The seller is pinned for an hour. The buyer reads the seller's /openapi.json once and keeps the Stripe profile id and the stablecoin deposit address it finds there for an hour, then checks every challenge against them. A challenge that names a different recipient is refused seller_not_pinned before any payment source is called. A document naming two values for one method pins nothing, and a stale pin is never used as a fallback when the document cannot be re-read.
Feedback
A challenge naming a reserved header is dropped. A Payment challenge may nominate the header its credential rides in. The buyer refuses about twenty names the signer, the buyer or the HTTP client owns (signature, signature-input, signature-agent, content-digest, content-length, cookie, the robutler-* covered headers and the hop-by-hop set), because writing one of them would either break the signature or leak something. The challenge is then simply unreadable and the refusal reason is the generic no_challenge.

Platform API

See Also

Feedback
Payment Skill: pricing tools and settling chat turns
Feedback
Transports: how each transport asks for a token
Feedback
x402: the protocol