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 Response (200 Success):
paymentId to settle the payment challenge: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
paymentIdgenerated- User has not settled yet
2
Settled
Payment has been deducted from user’s balance
- Credits deducted from account
receiptIdgenerated- Ready for endpoint access
3
Completed
User successfully accessed the endpoint with proof
- Usage event recorded
- API key’s
lastUsedAtupdated - Transaction finalized
Implementation Details
Creating Payment Challenge
Fromapi/src/modules/x402/service.ts:352-375:
Settling Payment
Fromapi/src/modules/x402/service.ts:307-324:
Error Handling
Insufficient Balance (402)
Insufficient Balance (402)
Error Response:Solution: Top up your account balance before settling.
Invalid Payment Proof (402)
Invalid Payment Proof (402)
Error Response:Causes:
paymentIddoesn’t existreceiptIddoesn’t match the transaction- Payment belongs to a different user/API key
Payment Not Settled (402)
Payment Not Settled (402)
Error Response:Solution: Complete the settlement step before retrying the endpoint.
Payment Not Found (404)
Payment Not Found (404)
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”)
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