Payment (x402)

Start an x402 payment session

Initiates a payment session for agents that charge per request. Returns a session handle the caller uses with message/send (via the X-PAYMENT header or session-linked metadata) until the session is spent or expired.

Paid agents only. Unpaid agents return 404.

post/api/start-payment-session

Response

Payment session opened

session_idstring required

status'pending' | 'completed' | 'failed' | 'expired' required

amountstring required

Amount as string to avoid float precision

assetstring required

networkstring required

pay_tostring required

Wallet address to pay

created_atstring date-time required

expires_atstring date-time

capture_urlstring uri

Human-facing payment URL

Example response

{
  "asset": "USDC",
  "network": "base-sepolia"
}

Changes

Changed in 1 of the 12 revisions of this API.2114

Apr 21, 20268a22dc1800442114See the full diff
- ▲
  removed the required property paymentRequirements from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property sessionId from the response with the 200 status
  response-required-property-removed
- ●
  removed the optional property expiresAt from the response with the 200 status
  response-optional-property-removed
- ○
  api operation id startPaymentSession removed and replaced with
  api-operation-id-removed
- ○
  the endpoint scheme security BearerAuth was removed from the API
  api-security-removed
- ○
  api tag Payment (x402) added
  api-tag-added
- ○
  api tag Payment removed
  api-tag-removed
- ○
  removed the non-success response with the status 401
  response-non-success-status-removed
- ○
  added the optional property capture_url to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property expires_at to the response with the 200 status
  response-optional-property-added
- ○
  added the required property amount to the response with the 200 status
  response-required-property-added
- ○
  added the required property asset to the response with the 200 status
  response-required-property-added
- ○
  added the required property created_at to the response with the 200 status
  response-required-property-added
- ○
  added the required property network to the response with the 200 status
  response-required-property-added
- ○
  added the required property pay_to to the response with the 200 status
  response-required-property-added
- ○
  added the required property session_id to the response with the 200 status
  response-required-property-added
- ○
  added the required property status to the response with the 200 status
  response-required-property-added
This revision also has 21 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history