Credits & Billing

Stable

Manage your credits, billing settings, and view usage.

API Key Support: All billing endpoints support API key authentication. This enables:

Developers to monitor usage and manage billing programmatically
AI Agents to autonomously manage their own budgets and ensure continuous operation
Automation to configure auto-top-up settings without manual intervention

Get Credit Balance

GET/api/v1/credits/balance

Get your current credit balance.

Query Parameters

Parameter	Type	Description
`fresh`	boolean	Set to `true` to bypass cache (use after payment confirmation)

Response


{
  "balance": 50.0
}

Get Credit Summary

GET/api/v1/credits/summary

Get comprehensive credit status including organization balance, agent budgets, app earnings, and redeemable earnings.

Response


{
  "success": true,
  "organization": {
    "id": "org_abc123",
    "name": "My Organization",
    "creditBalance": 50.0,
    "autoTopUpEnabled": false,
    "autoTopUpThreshold": null,
    "autoTopUpAmount": null,
    "hasPaymentMethod": true
  },
  "agents": [
    {
      "id": "agent_xyz789",
      "name": "My Assistant",
      "isPublic": false,
      "monetizationEnabled": false,
      "hasBudget": true,
      "allocated": 10.0,
      "spent": 2.5,
      "available": 7.5,
      "dailyLimit": 5.0,
      "dailySpent": 1.0,
      "dailyRemaining": 4.0,
      "isPaused": false,
      "pauseReason": null,
      "totalEarnings": 0,
      "totalRequests": 150
    }
  ],
  "agentsSummary": {
    "total": 3,
    "withBudget": 2,
    "paused": 0,
    "totalAllocated": 20.0,
    "totalSpent": 5.0,
    "totalAvailable": 15.0
  },
  "apps": [
    {
      "id": "app_def456",
      "name": "Customer Portal",
      "slug": "customer-portal",
      "monetizationEnabled": true,
      "inferenceMarkupPercentage": 20,
      "totalCreatorEarnings": 125.5,
      "totalPlatformRevenue": 31.38
    }
  ],
  "earnings": {
    "availableBalance": 125.5,
    "totalEarned": 200.0,
    "totalRedeemed": 74.5,
    "totalPending": 0,
    "breakdown": {
      "miniapps": 100.0,
      "agents": 75.0,
      "mcps": 25.0
    }
  },
  "recentTransactions": [
    {
      "id": "txn_abc123",
      "type": "usage",
      "amount": -0.05,
      "description": "Chat completion (gpt-4o)",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pricing": {
    "creditsPerDollar": 100,
    "minimumTopUp": 5.0,
    "x402Enabled": true
  }
}

Create Checkout Session

POST/api/v1/credits/checkout

Create a Stripe checkout session to purchase credits.

Request


{
  "amount": 50.0
}

Response


{
  "success": true,
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_xxx...",
  "sessionId": "cs_xxx..."
}

Redirect the user to checkoutUrl to complete the payment.

Verify Payment

POST/api/v1/credits/verify

Verify a completed payment and add credits.

Request


{
  "sessionId": "cs_xxx..."
}

Response


{
  "success": true,
  "creditsAdded": 50.0,
  "newBalance": 100.0
}

Billing Settings

GET/api/v1/billing/settings

Get billing configuration including auto-top-up settings.

Response


{
  "success": true,
  "settings": {
    "autoTopUp": {
      "enabled": true,
      "amount": 25.0,
      "threshold": 5.0,
      "hasPaymentMethod": true
    },
    "limits": {
      "minAmount": 1,
      "maxAmount": 1000,
      "minThreshold": 0,
      "maxThreshold": 1000
    }
  }
}

Update Billing Settings

PUT/api/v1/billing/settings

Configure auto-top-up to automatically replenish credits when balance falls below a threshold.

Why Auto-Top-Up? AI agents operating autonomously need uninterrupted access to credits. Auto-top-up ensures your agents never stop working due to insufficient balance.

Request


{
  "autoTopUp": {
    "enabled": true,
    "amount": 25.0,
    "threshold": 5.0
  }
}

Parameters

Parameter	Type	Description
`autoTopUp.enabled`	boolean	Enable or disable auto-top-up
`autoTopUp.amount`	number	Amount to charge when triggered ($1-$1000)
`autoTopUp.threshold`	number	Balance threshold to trigger top-up ($0-$1000)

Response


{
  "success": true,
  "message": "Billing settings updated successfully",
  "settings": {
    "autoTopUp": {
      "enabled": true,
      "amount": 25.0,
      "threshold": 5.0,
      "hasPaymentMethod": true
    }
  }
}

Auto-top-up requires a saved payment method. Add a payment method via the dashboard before enabling.

Trigger Auto-Top-Up

POST/api/auto-top-up/trigger

Manually trigger an auto-top-up check. Useful for testing or when you want to top up immediately.

Response


{
  "success": true,
  "message": "Auto top-up successful! Added $25.00",
  "amount": 25.0,
  "previousBalance": 3.5,
  "newBalance": 28.5
}

Get Transaction History

GET/api/credits/transactions

Get credit transaction history for your organization.

Query Parameters

Parameter	Type	Description
`limit`	integer	Max results returned (default: 100)
`hours`	integer	Limit results to the last N hours

Response


{
  "transactions": [
    {
      "id": "txn_abc123",
      "organization_id": "org_123",
      "type": "usage",
      "amount": -100,
      "description": "Text to speech generation",
      "metadata": null,
      "stripe_payment_intent_id": null,
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  ],
  "total": 1,
  "period": {
    "start": "2024-01-15T09:30:00.000Z",
    "end": "2024-01-15T10:30:00.000Z"
  }
}

Note: offset is not supported for this endpoint.

Crypto Payments

For cryptocurrency payments, use the crypto payment endpoints:

POST/api/crypto/payments

Create a crypto payment request.

GET/api/crypto/status

Check crypto payment status.

Pricing Reference

Service	Unit	Price
GPT-4o	1M tokens	$2.50 / $10.00
GPT-4o-mini	1M tokens	$0.15 / $0.60
Claude Sonnet 4.6	1M tokens	$3.00 / $15.00
Claude 3.5 Haiku	1M tokens	$1.00 / $5.00
Embeddings (3-small)	1M tokens	$0.02
Image Generation	per image	~$0.02
Container Deployment	per deploy	~$0.50

Input / Output token pricing shown for chat models

Actual pricing is calculated based on model and token usage. Check the Dashboard for real-time pricing.