A feeless per-call settlement option for hosted endpoints and agent workers #1928

A feeless per-call settlement option for hosted endpoints and agent workers

Your hosted-endpoint and agent work is converging on per-call billing: token billing for
hosted decision endpoints (issue #1888, #1908), metering endpoint charges and agent workers
directly in OpenMeter (#1899), and a 402-style "fail fast at run/deploy" gate (#1827) plus an
agent interface / MCP surface (#1920, #1921). Beam already treats a single call by an agent as
the unit that should be metered and charged. This proposes a complementary settlement option for
exactly that unit.

The gap a feeless rail fills

When the unit of value is one cheap agent call, a credit / top-up model has fixed overhead:
an account, a minimum balance, a card on file, a top-up. For an agent that wants to call one
endpoint once, that is disproportionate to the value of the call. The smaller the payment, the
more the settlement rail itself matters.

The HTTP 402 Payment Required challenge-response (x402, https://x402.org) lets an endpoint
answer 402 with a pay_to address and an amount when the caller hasn't paid, and serve the
result when the caller retries with a payment receipt. Paired with a feeless settlement network
(Nano — no transaction fees, sub-second finality), a single request priced in fractions of a cent
settles for the value of the call — same HTTP round-trip, no account, no card, no minimum.

Why it fits Beam specifically

• Beam is already metering per-call usage in OpenMeter and settling on its own credit/token
  ledger; a 402 rail is the same metered surface, but the settlement moves to the caller's
  wallet instead of Beam's ledger — the caller pays exactly what one call is worth, and you
  eliminate the top-up minimum for that caller.
• Your hosted endpoints are callable over public HTTP
  (https://docs.beam.cloud/v2/topics/public-endpoints) and your endpoint inverse is already
  per-invocation serverless, so the smallest useful paid unit is a single request — the case
  credit-card and token-minimum rails fit worst.
• The seller-side flow is a small middleware / header shape for ordinary HTTP servers
  (https://docs.x402.org/getting-started/quickstart-for-sellers), so a reference example for a
  @app.endpoint("/...") handler can stay tiny.
• Live, public examples of this exact shape already exist: an agent calls an endpoint, sees the
  402, settles on-chain (milliseconds, feeless), and retries to a 200. I can share a runnable
  example against a live nano:mainnet endpoint.

Proposed shape

1. A short reference example under examples/ (or a docs guide) showing a hosted endpoint that
   returns 402 with an x402 challenge when the caller hasn't paid, verifies the receipt on the
   retry, and serves the paid result — documented for the HTTP @app.endpoint surface.
2. Optionally note it alongside the OpenMeter / token-billing work as one more settlement option,
   so an agent with a wallet can call a hosted endpoint with no Beam account at all.

This is additive — your credit/token ledger stays the tier for teams that want it. The rail
simply makes the fractional-cent, no-account caller addressable. If the direction is welcome,
I'm glad to draft the example and open the PR.

Live references (all 200)

• Beam beta9 repo: https://github.com/beam-cloud/beta9
• Hosted endpoint / public endpoints docs: https://docs.beam.cloud/v2/topics/public-endpoints
• Endpoint overview: https://docs.beam.cloud/v2/endpoint/overview
• Pricing: https://beam.cloud/pricing
• OpenMeter (per-call metering they already use): https://www.openmeter.io
• x402 spec: https://x402.org
• x402 seller quickstart: https://docs.x402.org/getting-started/quickstart-for-sellers