Credit System

Credits are HiveForge's fungible unit for metered usage across all proxy services. Every billable action -- AI completions, email sends, vector searches, webhook deliveries, and MCP tool calls -- consumes credits from the deployment's balance.

How Credits Work

Each deployment has two credit pools:

Pool	Source	Rollover
Period balance	Monthly allocation included with the tier	No -- resets each billing period
Purchased balance	Credit packs bought separately	Yes -- persists until used

Credits are deducted in order: period balance first, then purchased balance.

Credit Costs by Action

Credits are consumed at different rates depending on the service and action type.

AI Proxy

Action	Description	Credits
`standard`	GPT-4o-mini, Claude Haiku	Low
`advanced`	GPT-4o, Claude Sonnet	Medium
`premium`	GPT-4.5, Claude Opus	High

Email

Action	Description	Credits
`send`	Send a transactional email	Low

Vectors

Action	Description	Credits
`search`	Vector similarity search	Low
`upsert`	Insert/update vector records	Low

Webhooks

Action	Description	Credits
`send`	Deliver a webhook event	Low

MCP Tools

Action	Mapped Tools	Credits
`task_basic`	Basic CRUD (list, create, update, delete)	Low
`task_advanced`	AI-powered operations (chat, create instance, promote)	Medium
`crew_execute`	Multi-agent crew execution	High
`generate`	Content generation	Medium
`rag_query`	RAG vector search	Low-Medium
`rag_ingest`	Document ingestion	Low-Medium
`tao_trace`	Trace logging	Low
`tao_evaluate`	AI evaluation	Medium
`tao_analytics`	Analytics queries	Low-Medium
`platform_basic`	Read-only platform queries	Low

Exact credit values are stored in the database and can change. Use the /credit-costs endpoint to retrieve current values at runtime. See MCP Credit Costs for the MCP-specific endpoint.

Credit Packs

When the monthly allocation runs out, credit packs provide additional capacity.

Purchasing Credit Packs

Credit packs are one-time purchases available through the billing dashboard or API:

curl -X POST https://api.hiveforge.dev/api/v1/credits/purchase \
  -H "X-Deployment-ID: d9f2a1b4-..." \
  -H "X-Deployment-Secret: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "pack_type_id": "pack-starter"
  }'

Auto-Purchase

Deployments can configure automatic credit pack purchases to avoid service interruptions:

curl -X PATCH https://api.hiveforge.dev/api/v1/credits/settings \
  -H "X-Deployment-ID: d9f2a1b4-..." \
  -H "X-Deployment-Secret: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "overage_mode": "auto_purchase",
    "auto_purchase_pack_id": "pack-starter"
  }'

Overage Modes

Mode	Behavior
`block`	Reject requests when credits are exhausted (default)
`allow`	Allow requests; track negative balance for invoicing
`auto_purchase`	Automatically buy a credit pack when balance hits zero

⚠️

With auto_purchase enabled, ensure a valid payment method is on file. Failed auto-purchases fall back to block behavior.

Credit Balance API

Get Balance

curl https://api.hiveforge.dev/api/v1/credits/balance \
  -H "X-Deployment-ID: d9f2a1b4-..." \
  -H "X-Deployment-Secret: sk_live_..."

Response:

{
  "deployment_id": "d9f2a1b4-...",
  "period_balance": 7500,
  "purchased_balance": 2000,
  "total_available": 9500,
  "monthly_allocation": 10000,
  "period_end": "2026-04-01T00:00:00Z",
  "overage_mode": "block"
}

Usage Summary

Get aggregated credit usage by service and action:

curl "https://api.hiveforge.dev/api/v1/credits/usage?deployment_id=d9f2a1b4-..." \
  -H "Authorization: Bearer hf_live_..."

Response:

{
  "total_credits_used": 5550,
  "by_service": {
    "ai": 4200,
    "mcp": 1300,
    "email": 50
  },
  "by_action": {
    "ai/standard": 3000,
    "ai/advanced": 1200,
    "mcp/crew_execute": 500,
    "mcp/task_basic": 300,
    "mcp/rag_query": 500,
    "email/send": 50
  },
  "period_start": "2026-03-01T00:00:00Z",
  "period_end": "2026-03-28T23:59:59Z"
}

Credit Deduction Flow

The credit deduction process is atomic -- it uses a database function to prevent race conditions:

Request arrives
       │
       ▼
┌──────────────┐
│ Look up cost │  (service + action → credits)
└──────┬───────┘
       │
       ▼
┌──────────────────┐     ┌───────────────┐
│ Period balance    │────►│ Deduct from   │
│ >= cost?          │ Yes │ period balance│
└──────┬───────────┘     └───────────────┘
       │ No
       ▼
┌──────────────────┐     ┌───────────────┐
│ Purchased balance │────►│ Deduct from   │
│ >= cost?          │ Yes │ purchased     │
└──────┬───────────┘     └───────────────┘
       │ No
       ▼
┌──────────────────┐     ┌───────────────┐
│ Auto-purchase    │────►│ Buy pack,     │
│ enabled?         │ Yes │ then deduct   │
└──────┬───────────┘     └───────────────┘
       │ No
       ▼
┌──────────────────┐
│ Reject: credits  │
│ insufficient     │
└──────────────────┘

The atomic deduction ensures that concurrent requests cannot overdraw the balance. Each deduction is logged in the credit_usage table for full audit trail.

Relationship to Tiers

Tiers determine the monthly credit allocation -- the number of credits added to the period balance at each billing cycle. Higher tiers receive larger allocations. Purchased credits work identically across all tiers.

Tier	Feature Gating	Monthly Credits
Sandbox	Most services disabled	Minimal
Trial	All services enabled	Starter allocation
Launch	All services + custom domain	Standard allocation
Growth	All services + white label	High allocation
Enterprise	All services, unlimited quotas	Custom allocation

Best Practices

Monitor total_available -- Alert when credits drop below 20% of monthly allocation
Use auto_purchase -- For production deployments where service interruption is unacceptable
Review usage by action -- Identify which services consume the most credits and optimize accordingly
Cache credit costs -- The cost table changes infrequently; cache for up to 1 hour
Check before execute -- For expensive operations (crew execution, premium AI), always check entitlement first

Quotas & Limits Adding a New Feature