Skip to main content

​
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"
This endpoint requires session authentication (dashboard login).

​
Response

​
balanceCents
number
Current account balance in cents (USD)
​
topUpTotalCents
number
Total amount topped up (all time) in cents
​
usageTotalCents
number
Total amount spent on usage (all time) in cents
​
activeApiKeys
number
Count of active (non-revoked) API keys
​
x402Transactions
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
  }'
This endpoint requires session authentication (dashboard login).

​
Request Body

​
amountCents
number
required
Amount to add in cents (USD)
  • Minimum: 100 cents ($1.00)
  • Maximum: 100,000 cents ($1,000.00)

​
Response

​
paymentIntentId
string
Unique identifier for the payment intent (prefixed with pi_)
​
addedCents
number
Amount added to the balance in cents
​
balanceCents
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"
This endpoint requires session authentication (dashboard login).

​
Response

​
intents
array
List of payment intent objects (up to 50 most recent)
{
  "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

StatusErrorDescription
401unauthorizedNot logged in or session expired
400amount_must_be_between_100_and_100000_centsTop-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.