Billing - ActumX

Overview

The billing system tracks credit balance, top-ups, and usage. Credits are denominated in cents (USD). The current implementation uses a simulated payment system for development.

Get Billing Summary

Retrieve account balance and usage statistics.

curl https://api.actumx.app/v1/billing/summary \
  -H "Cookie: your_session_cookie"

const response = await fetch('https://api.actumx.app/v1/billing/summary', {
  credentials: 'include'
});
const data = await response.json();

This endpoint requires session authentication (dashboard login).

Response

number

Current account balance in cents (USD)

number

Total amount topped up (all time) in cents

number

Total amount spent on usage (all time) in cents

number

Count of active (non-revoked) API keys

number

Total count of x402 payment transactions

{
  "balanceCents": 7500,
  "topUpTotalCents": 10000,
  "usageTotalCents": 2500,
  "activeApiKeys": 2,
  "x402Transactions": 142
}

Balance = Total Top-Ups - Total Usage

Top Up Credits

Add credits to your account balance. This endpoint simulates payment for development purposes.

curl -X POST https://api.actumx.app/v1/billing/top-up \
  -H "Cookie: your_session_cookie" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 5000
  }'

const response = await fetch('https://api.actumx.app/v1/billing/top-up', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amountCents: 5000
  })
});
const data = await response.json();

This endpoint requires session authentication (dashboard login).

Request Body

number

required

Amount to add in cents (USD)

Minimum: 100 cents ($1.00)
Maximum: 100,000 cents ($1,000.00)

Response

string

Unique identifier for the payment intent (prefixed with pi_)

number

Amount added to the balance in cents

number

Updated account balance in cents

{
  "paymentIntentId": "pi_abc123",
  "addedCents": 5000,
  "balanceCents": 12500
}

Error Response

If the amount is outside the allowed range:

{
  "error": "amount_must_be_between_100_and_100000_cents"
}

The current implementation uses a simulated payment system. In production, this would integrate with a real payment provider.

List Payment Intents

Retrieve recent payment intents (top-up history).

curl https://api.actumx.app/v1/billing/payment-intents \
  -H "Cookie: your_session_cookie"

const response = await fetch('https://api.actumx.app/v1/billing/payment-intents', {
  credentials: 'include'
});
const data = await response.json();

This endpoint requires session authentication (dashboard login).

Response

array

List of payment intent objects (up to 50 most recent)

Show Payment Intent object

string

Unique payment intent identifier with pi_ prefix

string

Associated user ID

number

Amount in cents

string

Payment status (e.g., “settled”)

string

Reference from payment provider

string

ISO 8601 timestamp

string

ISO 8601 timestamp

{
  "intents": [
    {
      "id": "pi_abc123",
      "userId": "user_xyz789",
      "amountCents": 5000,
      "status": "settled",
      "providerReference": "dummy_provider_def456",
      "createdAt": "2024-03-01T10:00:00Z",
      "updatedAt": "2024-03-01T10:00:00Z"
    },
    {
      "id": "pi_def456",
      "userId": "user_xyz789",
      "amountCents": 10000,
      "status": "settled",
      "providerReference": "dummy_provider_ghi789",
      "createdAt": "2024-02-15T14:30:00Z",
      "updatedAt": "2024-02-15T14:30:00Z"
    }
  ]
}

Credit Ledger System

Behind the scenes, ActumX uses a double-entry ledger system:

Credit Entries

Source: top_up
Direction: credit
Reference: Payment intent ID

Debit Entries

Source: api_request
Direction: debit
Reference: x402 transaction ID

The balance is computed by summing all credits and subtracting all debits.

Error Codes

Status	Error	Description
401	`unauthorized`	Not logged in or session expired
400	`amount_must_be_between_100_and_100000_cents`	Top-up amount outside allowed range

Pricing

Current x402 request pricing:

Protected endpoint request: 25 cents ($0.25 USD)

See x402 Protocol for details on payment-required endpoints.

​Overview

​Get Billing Summary

​Response

​Top Up Credits

​Request Body

​Response

​Error Response

​List Payment Intents

​Response

​Credit Ledger System

​Credit Entries

​Debit Entries

​Error Codes

​Pricing

Overview

Get Billing Summary

Response

Top Up Credits

Request Body

Response

Error Response

List Payment Intents

Response

Credit Ledger System

Credit Entries

Debit Entries

Error Codes

Pricing