Skip to content
ClawHosters ClawHosters
Login Get Started
Subs -25% LAUNCH-SUB
Claws -25% LAUNCH-CLAWS

API: Billing Endpoints

5 min read API Last updated February 10, 2026

Overview

The billing endpoints let you check your Claws balance, view usage breakdowns, browse transaction history, and purchase Claws packages. All billing endpoints require authentication.

Get Billing Summary

text 
GET /api/v1/billing/summary

Returns your current balance, daily costs, and subscription status.

Example:

bash 
curl -X GET https://clawhosters.com/api/v1/billing/summary \
  -H "Authorization: Bearer oc_live_your_api_key_here"

Success Response (200 OK):

json 
{
  "data": {
    "claws_balance": 1500,
    "daily_claw_cost": 225,
    "days_remaining": 6,
    "low_balance": false,
    "subscription_status": "active",
    "subscription_tier": "balanced",
    "instances_count": 2,
    "running_instances_count": 1
  }
}

Response Fields

Field Type Description
claws_balance integer Current Claws balance
daily_claw_cost integer Total daily Claws consumed by all running instances and add-ons
days_remaining integer Estimated days until balance runs out at current rate
low_balance boolean Whether balance is below the warning threshold
subscription_status string Current subscription state: active, paused, or canceled
subscription_tier string Pricing tier if subscribed: budget, balanced, pro, or none
instances_count integer Total number of instances on your account
running_instances_count integer Number of instances currently running

Get Usage Details

text 
GET /api/v1/billing/usage

Returns a breakdown of daily Claws costs by instance and add-on.

Example:

bash 
curl -X GET https://clawhosters.com/api/v1/billing/usage \
  -H "Authorization: Bearer oc_live_your_api_key_here"

Success Response (200 OK):

json 
{
  "data": {
    "daily_total": 270,
    "instances": [
      {
        "id": 42,
        "name": "my-ai-bot",
        "tier": "balanced",
        "daily_claws": 225,
        "status": "running",
        "billing_mode": "daily"
      }
    ],
    "addons": [
      {
        "id": 7,
        "addon_type": "llm",
        "instance_name": "my-ai-bot",
        "tier": "gpt4",
        "current_usage": 5000,
        "usage_limit": 10000,
        "daily_claws": 45
      }
    ]
  }
}

Instance Fields

Field Type Description
id integer Instance ID
name string Instance name
tier string Instance tier: budget, balanced, or pro
daily_claws integer Daily Claws cost for this instance
status string Current instance status
billing_mode string daily or subscription

Add-on Fields

Field Type Description
id integer Add-on ID
addon_type string Type: llm, voice, embeddings, or backup
instance_name string Name of the associated instance
tier string Add-on tier or pack size
current_usage integer Current monthly usage count
usage_limit integer Monthly usage limit
daily_claws integer Daily Claws cost for this add-on

List Transactions

text 
GET /api/v1/billing/transactions

Returns a paginated list of billing transactions. Supports date filtering.

Query Parameters

Parameter Type Default Description
page integer 1 Page number
per_page integer 20 Results per page (max 100)
start_date string — Filter from this date (YYYY-MM-DD)
end_date string — Filter until this date (YYYY-MM-DD)

Example:

bash 
curl -X GET "https://clawhosters.com/api/v1/billing/transactions?page=1&per_page=10" \
  -H "Authorization: Bearer oc_live_your_api_key_here"

Success Response (200 OK):

json 
{
  "data": {
    "transactions": [
      {
        "id": 301,
        "transaction_type": "daily_deduction",
        "claws_amount": -225,
        "amount_cents": 150,
        "description": "Daily hosting for my-ai-bot (Balanced)",
        "instance_id": 42,
        "created_at": "2026-02-10T00:00:00Z"
      },
      {
        "id": 298,
        "transaction_type": "purchase",
        "claws_amount": 250,
        "amount_cents": 5900,
        "description": "Claws purchase: Popular Pack",
        "instance_id": null,
        "created_at": "2026-02-09T14:22:10Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_count": 47,
      "per_page": 10
    }
  }
}

Transaction Fields

Field Type Description
id integer Transaction ID
transaction_type string Type: daily_deduction, purchase, refund, subscription, or system
claws_amount integer Claws added (positive) or deducted (negative)
amount_cents integer EUR amount in cents
description string Human-readable description
instance_id integer or null Associated instance, if applicable
created_at string ISO 8601 timestamp

Transaction Types

Type Description
daily_deduction Automatic daily billing for running instances and add-ons
purchase Manual Claws package purchase
refund Refund issued to your account
subscription Monthly subscription charge
system Administrative adjustment

List Claws Packages

text 
GET /api/v1/billing/packages

Returns the available Claws packages for purchase.

Example:

bash 
curl -X GET https://clawhosters.com/api/v1/billing/packages \
  -H "Authorization: Bearer oc_live_your_api_key_here"

Success Response (200 OK):

json 
{
  "data": {
    "packages": [
      {
        "index": 0,
        "name": "Starter Pack",
        "price_cents": 2900,
        "price_eur": "29.00",
        "claws": 100,
        "bonus_percent": 0
      },
      {
        "index": 1,
        "name": "Popular Pack",
        "price_cents": 5900,
        "price_eur": "59.00",
        "claws": 250,
        "bonus_percent": 20
      }
    ]
  }
}

Package Fields

Field Type Description
index integer Package identifier used for the purchase endpoint
name string Display name
price_cents integer Price in EUR cents
price_eur string Formatted price in EUR
claws integer Number of Claws in the package
bonus_percent integer Bonus percentage (0 if none)

Purchase Claws

text 
POST /api/v1/billing/buy_claws

Initiates a Claws purchase via Stripe Checkout. Returns a checkout URL to redirect the customer.

Request Body:

json 
{
  "package_index": 1,
  "widerrufsrecht_waived": true
}
Parameter Type Required Description
package_index integer Yes Index from the packages endpoint
widerrufsrecht_waived boolean Yes Must be true (German law: right of withdrawal waiver)

Example:

bash 
curl -X POST https://clawhosters.com/api/v1/billing/buy_claws \
  -H "Authorization: Bearer oc_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"package_index": 1, "widerrufsrecht_waived": true}'

Success Response (200 OK):

json 
{
  "data": {
    "checkout_url": "https://checkout.stripe.com/pay/cs_live_...",
    "package": {
      "name": "Popular Pack",
      "claws": 250,
      "price_cents": 5900
    }
  }
}

The checkout_url redirects the customer to Stripe for payment. After payment, the Claws are credited to the account automatically.

Authentication

All billing endpoints require a valid API key:

text 
Authorization: Bearer oc_live_your_api_key_here

Error Responses

Invalid Package (422)

json 
{
  "error": {
    "code": "unprocessable_entity",
    "message": "Invalid package index. Please select a valid Claw package."
  }
}

Missing Withdrawal Waiver (422)

json 
{
  "error": {
    "code": "unprocessable_entity",
    "message": "You must waive your right of withdrawal to proceed with the purchase."
  }
}

Unauthorized (401)

json 
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Notes

  • The billing summary updates in real time as instances are started or stopped.
  • Transaction history is ordered by most recent first.
  • Daily deductions run at midnight UTC. Each running instance and active add-on generates a separate transaction.
  • The days_remaining field is an estimate based on the current daily cost. It changes when you start or stop instances.
  • Claws purchased via buy_claws are credited to your account once Stripe confirms the payment.

Related Documentation

API Overview

Introduction The ClawHosters API lets you manage your instances, check billing, and control add-...

Billing Overview

How Billing Works ClawHosters offers two billing modes: monthly subscriptions and daily Claws bi...

Adding Funds (Top-up)

When You Need to Add Funds If you use daily billing (Claws), your instances deduct from your bal...