v1

latestOpenAPI 3.0.32026-07-24707482.9 KB

Flow Sessions

Submit field values and an action for the current step

Advances the session by submitting user input. Requires an Idempotency-Key header (max 256 chars) to prevent duplicate processing. stateVersion provides optimistic concurrency control — must match the current version.

If the step declares a payment field, the X-Payment header must contain a base64-encoded x402 Permit2 payment proof. On successful settlement the response includes paymentReceipt and a X-Payment-Response header.

post/flow/sessions/{sessionId}/steps/{stepId}

Path parameters

sessionIdstring required

stepIdstring required

Headers

Idempotency-Keystring required

Unique key for idempotent submission. Cached per session.

X-Paymentstring

Base64-encoded x402 Permit2 payment proof (required when step has payment)

Request body

fieldValuesobject required

Key–value map of field IDs to submitted values

actionstring required

Action ID from the StepSpec's actions array

stateVersioninteger required

Must match the current session state version (optimistic lock)

Response

Step submitted — returns next step or completion

sessionIdstring required

appIdstring required

appVersionstring required

status'active' | 'complete' | 'expired' required

stateVersioninteger required

completeboolean required

Example response

{
  "stepSpec": {
    "payment": {
      "currency": "USDC",
      "chain": "base",
      "recipient": "0xAbCd1234AbCd1234AbCd1234AbCd1234AbCd1234",
      "tokenAddress": "0xAbCd1234AbCd1234AbCd1234AbCd1234AbCd1234"
    }
  }
}