> ## Documentation Index
> Fetch the complete documentation index at: https://docs.actumx.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing

> Manage account credits, top-ups, and billing information

## 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.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.actumx.app/v1/billing/summary \
    -H "Cookie: your_session_cookie"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.actumx.app/v1/billing/summary', {
    credentials: 'include'
  });
  const data = await response.json();
  ```
</CodeGroup>

<Note>
  This endpoint requires session authentication (dashboard login).
</Note>

### Response

<ResponseField name="balanceCents" type="number">
  Current account balance in cents (USD)
</ResponseField>

<ResponseField name="topUpTotalCents" type="number">
  Total amount topped up (all time) in cents
</ResponseField>

<ResponseField name="usageTotalCents" type="number">
  Total amount spent on usage (all time) in cents
</ResponseField>

<ResponseField name="activeApiKeys" type="number">
  Count of active (non-revoked) API keys
</ResponseField>

<ResponseField name="x402Transactions" type="number">
  Total count of x402 payment transactions
</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "balanceCents": 7500,
    "topUpTotalCents": 10000,
    "usageTotalCents": 2500,
    "activeApiKeys": 2,
    "x402Transactions": 142
  }
  ```
</ResponseExample>

<Info>
  Balance = Total Top-Ups - Total Usage
</Info>

***

## Top Up Credits

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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.actumx.app/v1/billing/top-up \
    -H "Cookie: your_session_cookie" \
    -H "Content-Type: application/json" \
    -d '{
      "amountCents": 5000
    }'
  ```

  ```javascript JavaScript theme={null}
  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();
  ```
</CodeGroup>

<Note>
  This endpoint requires session authentication (dashboard login).
</Note>

### Request Body

<ParamField path="amountCents" type="number" required>
  Amount to add in cents (USD)

  * Minimum: 100 cents (\$1.00)
  * Maximum: 100,000 cents (\$1,000.00)
</ParamField>

### Response

<ResponseField name="paymentIntentId" type="string">
  Unique identifier for the payment intent (prefixed with `pi_`)
</ResponseField>

<ResponseField name="addedCents" type="number">
  Amount added to the balance in cents
</ResponseField>

<ResponseField name="balanceCents" type="number">
  Updated account balance in cents
</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "paymentIntentId": "pi_abc123",
    "addedCents": 5000,
    "balanceCents": 12500
  }
  ```
</ResponseExample>

### Error Response

If the amount is outside the allowed range:

```json theme={null}
{
  "error": "amount_must_be_between_100_and_100000_cents"
}
```

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

***

## List Payment Intents

Retrieve recent payment intents (top-up history).

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.actumx.app/v1/billing/payment-intents \
    -H "Cookie: your_session_cookie"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.actumx.app/v1/billing/payment-intents', {
    credentials: 'include'
  });
  const data = await response.json();
  ```
</CodeGroup>

<Note>
  This endpoint requires session authentication (dashboard login).
</Note>

### Response

<ResponseField name="intents" type="array">
  List of payment intent objects (up to 50 most recent)

  <Expandable title="Payment Intent object">
    <ResponseField name="id" type="string">
      Unique payment intent identifier with `pi_` prefix
    </ResponseField>

    <ResponseField name="userId" type="string">
      Associated user ID
    </ResponseField>

    <ResponseField name="amountCents" type="number">
      Amount in cents
    </ResponseField>

    <ResponseField name="status" type="string">
      Payment status (e.g., "settled")
    </ResponseField>

    <ResponseField name="providerReference" type="string">
      Reference from payment provider
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "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"
      }
    ]
  }
  ```
</ResponseExample>

## 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](/concepts/x402-protocol) for details on payment-required endpoints.