Skip to main content

​
Base URL

The ActumX API is organized around REST principles. All API endpoints are prefixed with /v1 for versioning. 
https://api.actumx.app

​
API Versioning

The API uses URL-based versioning. The current version is v1. All endpoints are prefixed with /v1 (e.g., /v1/agents, /v1/billing/summary).

​
Response Format

All API responses are returned in JSON format. Successful responses typically return a 200 status code with the requested data.

​
Success Response

{
  "agents": [
    {
      "id": "agent_abc123",
      "name": "My Agent",
      "publicKey": "7xKz...",
      "createdAt": "2024-03-01T10:00:00Z"
    }
  ]
}

​
Error Response

Error responses include an error field with a machine-readable error code: 
{
  "error": "unauthorized"
}

​
HTTP Status Codes

The API uses standard HTTP status codes:
CodeMeaning
200Success - Request completed successfully
202Accepted - Request accepted (used for JSON-RPC notifications)
400Bad Request - Invalid parameters or request body
401Unauthorized - Missing or invalid authentication
402Payment Required - x402 payment required (see x402 Protocol)
404Not Found - Resource doesn’t exist
500Internal Server Error - Something went wrong on the server

​
Error Codes

Common error codes returned in the error field:
  • unauthorized - Authentication required or invalid
  • missing_or_invalid_api_key - API key missing or not valid
  • payment_required - x402 payment needed for this endpoint
  • insufficient_balance - Not enough credits to complete operation
  • payment_not_found - Payment ID not found
  • invalid_payment_proof - Payment proof doesn’t match
  • agent_not_found - Agent ID doesn’t exist or not owned by user

​
Rate Limiting

Rate limiting is not currently enforced but may be implemented in future versions. Monitor response headers for rate limit information.

​
CORS

The API supports CORS for requests from the dashboard origin. The following headers are allowed:
  • Content-Type
  • Authorization
  • x-api-key
  • x-payment-id
  • x-payment-proof

​
Health Check

The API provides a health check endpoint for monitoring: 
GET /health
Response: 
{
  "status": "ok",
  "service": "x402-api"
}
This endpoint requires no authentication and can be used for uptime monitoring and health checks.

​
Next Steps

Authentication

Learn how to authenticate your API requests

Agents

Create and manage Solana agents

x402 Protocol

Understand payment-required endpoints

Billing

Manage credits and top-ups