Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
State-machine integration · Boson Protocol
Skip to content

State-machine integration

A plain x402b commit moves the exchange to COMMITTED. But many digital-goods sellers want to atomically redeem in the same request, or to advertise a follow-up action the buyer should take. x402-actions is the layer that exposes this.

nextActions envelope

In the 402 response (and in some 200 responses), the server can include nextActions[] — a list of state transitions the buyer could take next, with the endpoint to call.

Example:

{
  "accepts": [{ "scheme": "escrow", "...": "..." }],
  "nextActions": [
    {
      "action": "boson-redeem",
      "channel": "facilitator",
      "endpoint": "https://facilitator.bosonprotocol.io/perform-action?action=boson-redeem"
    }
  ]
}

Channels and adapters

nextActions[] entries have a channel (onchain, facilitator, server, mcp). Each channel has a ChannelAdapter that knows how to execute the action via its endpoint.

import { FacilitatorChannelAdapter } from "@bosonprotocol/x402-actions"
 
const adapter = new FacilitatorChannelAdapter({ endpoint: "..." })
await adapter.perform({ action: "boson-redeem", payload })

Computing legal next actions

x402-actions ships the state tables from x402-core. Given the current exchange state, it returns which actions are legal — so the server doesn't advertise illegal transitions.

import { computeNextActions } from "@bosonprotocol/x402-actions"
 
const next = computeNextActions({
  state: "COMMITTED",
  role: "buyer",
})
// → ["redeem", "cancel"]

When to use atomic redeem

Atomic commit-and-redeem is the right call when:

  • The asset is digital and delivered in the response.
  • The buyer doesn't need a redemption window (no physical goods).
  • You're optimizing for one round-trip.

For physical goods, keep commit and redeem separate; the buyer redeems when they physically receive the package.

Common gotchas

  • nextActions order matters. The client picks the first one whose channel it can speak.
  • Action endpoints can be stale. Always include a fresh endpoint per response, not a static URL.

Next