API Overview - ActumX

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:

Code	Meaning
200	Success - Request completed successfully
202	Accepted - Request accepted (used for JSON-RPC notifications)
400	Bad Request - Invalid parameters or request body
401	Unauthorized - Missing or invalid authentication
402	Payment Required - x402 payment required (see x402 Protocol)
404	Not Found - Resource doesn’t exist
500	Internal 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

​Base URL

​API Versioning

​Response Format

​Success Response

​Error Response

​HTTP Status Codes

​Error Codes

​Rate Limiting

​CORS

​Health Check

​Next Steps