Skip to main content

What is x402?

x402 is a protocol for HTTP payment-required responses that enables:
  • Machine-readable payment challenges using HTTP 402 status
  • Automatic payment settlement without custom billing logic
  • Retry mechanisms after successful payment
  • Transparent pricing embedded in API responses
ActumX implements a simplified x402 flow. The protocol is inspired by HTTP 402 Payment Required and designed for AI agent interactions.

The x402 Flow

1

Make Initial Request

Request a paid endpoint without payment proof:
Response (402 Payment Required):
The system automatically creates a pending transaction in the database with a unique paymentId.
2

Settle the Payment

Use the paymentId to settle the payment challenge:
Response (200 Success):
The settlement deducts 25 cents from your account balance and generates a receiptId as proof of payment.
3

Retry with Payment Proof

Make the original request again, this time including payment proof headers:
Response (200 Success):
Success! The transaction is marked as completed and a usage event is recorded.

Complete Example: Automated Flow

Here’s a complete example that handles the entire x402 flow automatically:

Payment States

An x402 transaction goes through these states:
1

Pending

Initial state when payment challenge is issued
  • Transaction created in database
  • paymentId generated
  • User has not settled yet
2

Settled

Payment has been deducted from user’s balance
  • Credits deducted from account
  • receiptId generated
  • Ready for endpoint access
3

Completed

User successfully accessed the endpoint with proof
  • Usage event recorded
  • API key’s lastUsedAt updated
  • Transaction finalized

Implementation Details

Creating Payment Challenge

From api/src/modules/x402/service.ts:352-375:

Settling Payment

From api/src/modules/x402/service.ts:307-324:

Error Handling

Error Response:
Solution: Top up your account balance before settling.
Error Response:
Causes:
  • paymentId doesn’t exist
  • receiptId doesn’t match the transaction
  • Payment belongs to a different user/API key
Solution: Verify you’re using the correct IDs from the settlement response.
Error Response:
Solution: Complete the settlement step before retrying the endpoint.
Error Response:
Causes:
  • Invalid paymentId
  • Payment belongs to different user
  • Payment was already consumed and expired

Best Practices

Automate the Flow

Build helper functions that handle the 3-step flow automatically

Cache Receipt IDs

Store receipt IDs to avoid duplicate charges for the same request

Handle Retries

Implement exponential backoff for network errors during settlement

Monitor Balance

Check your balance before making paid requests to avoid 402 errors

Available Paid Endpoints

Quote Endpoint

Endpoint: GET /v1/protected/quoteCost: 25 cents per requestQuery Parameters:
  • topic (optional): Topic for the quote (default: “general”)
Example:
More paid endpoints will be added. Each will follow the same x402 protocol.

Next Steps

API Reference

Complete x402 API documentation

Monitor Usage

Track your spending and usage patterns