Credits - Naïve

CLI First

# Check usage and buy more credits
naive usage --days 30
naive billing packs
naive billing topup --pack medium

How Credits Work

Every company has a credit balance. Operations deduct credits on use. New accounts start with 20 free credits.

Credit Costs

Each credit is worth $0.05 USD.

Fixed-Price Operations

Operation	Credits	Charging
Email send	10	Immediately on success
Web search	10	Immediately on success
URL read	5	Immediately on success
Research (quick)	30	Immediately on success
Research (thorough)	50	On job completion
Research (exhaustive)	80	On job completion
CEO run (pre-check)	5	Pre-check on run start (downstream LLM/tools billed separately)
SEO keywords / on-page	10	Immediately on success
SEO Labs / backlinks (bulk)	20–50	Immediately on success
AEO endpoints	20–30	Immediately on success
app-data / business-data	10–20	Immediately on success
ecommerce	20	Immediately on success
Clips (submagic): create / edit	40 / 30	On completion
Social post	10	Immediately on success
SMS send (phone)	provider cost × 2	Immediately on success
Phone number provision	provider cost × 2	On success (irreversible, approval-gated)
Stock photo search	0	Free
Browser session open	0	Free (time floor billed at close)
Browser navigate / act / extract / observe / screenshot	10 each	Immediately per action
Browser autonomous signup	40	On success (approval-gated)
Browser autonomous login	30	On success
Browser session time floor	10–30	At close, by elapsed time (≤5 / ≤15 / ≤30 min)

SEO / AEO / queue are additionally metered against your plan quota (a separate per-primitive counter surfaced at GET /v1/users/:id/billing/usage) on top of the credit charge above.

Infrastructure (duration-metered)

Anything that runs a server you keep alive is billed by time, not per call — metered continuously by a background scheduler (~every 2 minutes) and debited via the same idempotent ledger. Scale-to-zero means an idle/stopped resource accrues nothing.

Resource	Action type	Rate (default)	What’s billed
Compute (`compute` primitive — your managed compute tasks & services)	`compute_usage`	20 credits / vCPU-hour + 2.5 credits / GB-hour	While a run is `running` or a service has `desiredCount > 0`
Hosted runtime (a Naïve-hosted agent profile agent / `runtime.start`)	`runtime_usage`	20 credits / vCPU-hour + 2.5 credits / GB-hour	While your agent profile’s Hermes container is `running`

The hosted-runtime container is 1 vCPU / 2 GB by default, so a continuously-running hosted agent costs ≈ 20 + (2 × 2.5) = 25 credits/hour (~ $1.25/hr at$ 0.05/credit).
Only claimed containers (your agent profile’s) are billed. The shared warm pool that keeps start-up latency low is platform overhead and is never charged to you.
Bring-your-own-runtime (you run the agent in your own harness with agentProfile.tools()) incurs no runtime_usage — you only pay for the API primitives the agent calls.
A claimed hosted container bills the same whether busy or idle (the task is up), so tear agent profiles down with revoke() when done — revoke releases the slot immediately.

Path A infrastructure is credit-gated. Provisioning via naive up (managed Postgres, object storage buckets, web hosting) is blocked when your credits are exhausted, and when you run out, running infra is shut down (web disabled, runtime/compute stopped). Database and bucket data persists — top up to resume; new provisioning unblocks immediately.

LLM Calls

There are two ways LLM usage is billed, both per-token and deducted after the call completes (after the final SSE event for streams):

The llm primitive & OpenRouter proxy (POST /v1/llm/chat/completions, naive.llm.chat(), and the /v1/proxy/openrouter/* drop-in). These route through OpenRouter, which returns the exact USD cost of each call. Naive bills that returned usage.cost × markup, converted to credits — so there’s no per-model rate table and pricing always tracks OpenRouter. See the LLM primitive.
Orchestration LLM calls (CEO agent / employees). These flow through the Anthropic/OpenAI/Google proxies and are billed per-token using the rates below, with cache read tokens billed at a discount and cache creation at a premium.

Model	Input (per 1M tokens)	Output (per 1M tokens)
Claude Opus 4.5	125 credits	625 credits
Claude Opus 4	375 credits	1875 credits
Claude Sonnet 4 / 4.5	75 credits	375 credits
Claude Haiku 4.5	25 credits	125 credits
Claude Haiku 3.5	20 credits	100 credits
GPT-4o	62.5 credits	250 credits
GPT-4o Mini	3.75 credits	15 credits
Gemini 2.0 Flash	1.875 credits	7.5 credits
Gemini 2.5 Pro	31.25 credits	250 credits

LLM costs are deducted automatically after each API call completes. For streaming responses, usage is extracted from the final SSE event and deducted post-stream. Built-in web search tool use is also billed when used.

Dynamic-Price Operations (Image/Video Generation)

Image and video generation costs are model-dependent and calculated dynamically. Use the pricing endpoints to preview costs before submitting:

GET /v1/images/pricing?model=fal-ai/flux/schnell&num_images=2
GET /v1/video/pricing?model=fal-ai/kling-video/v3/pro/text-to-video&duration=5

Response:

{
  "model": "fal-ai/flux/schnell",
  "estimated_credits": 1.2,
  "unit_price_usd": 0.02,
  "credit_value_usd": 0.05
}

Two different “budgets” — don’t confuse them

Naïve has two independent ledgers. Keep them straight:

	Platform credits	AgentProfile budget
Question it answers	”What do I owe Naïve for usage?"	"How much real-world money may this agent spend?”
Unit	Credits ($0.05 each)	USD cents
Ledger	`credit_transactions` (company-wide)	`tenant_spend_events` (per agent profile)
Covers	LLM, search, email, images, compute, hosted runtime, …	Card limits, card top-ups, trading notional
Set by	Your plan + top-ups	An agent profile template’s `policy.budget`
Enforced by	`checkCredits` (402 `insufficient_credits`)	The governance gateway (`403 budget_exceeded` / approval)

An agent profile’s budget.cap is a combined cost ceiling: it caps the agent profile’s real-world spend (cards/trading) plus the platform credits it burns (LLM, search, compute, hosted runtime — counted at $0.05/credit) against one number. It is still distinct from your company-wide Naïve credit balance (the budget is per agent profile, in USD). A hard cap denies over-budget actions (and auto-stops the agent profile’s hosted runtime); a soft cap routes them to approval. See IaC policy and the Governance Gateway.

Running out of credits

When a company’s credit balance is exhausted, new API calls return 402 insufficient_credits and hosted-runtime containers are automatically stopped by the meter (a runtime.stopped event with reason: out_of_credits) — so a non-paying account stops incurring cloud cost. Top up or upgrade to resume.

Sync vs Async Charging

Synchronous operations (email, search, URL read, quick research):

Credits deducted immediately when the operation succeeds
If it fails, no credits are charged

Asynchronous operations (images, video, thorough research):

On submission: pre-check that balance ≥ estimated cost (returns 402 if not)
Job runs in background
On success: credits deducted and transaction recorded
On failure: no charge

Concurrent async jobs can temporarily exceed your balance since pre-checks pass independently. The balance may go slightly negative — subsequent submissions will be blocked once balance drops below threshold.

Checking Your Balance

GET /v1/status

Returns your current balance, tier, and resource counts.

Usage History

GET /v1/usage?days=30&limit=50

Returns transaction history with action type, amount, and reference IDs. Every charge type appears here keyed by action_type — e.g. llm_call, web_search, email_send, job_completion, compute_usage, runtime_usage, subscription_renewal, credit_topup. The dashboard’s GET /v1/dashboard/usage-summary groups the same ledger by action_type so you can see exactly where credits went (including infrastructure time).

Credit Responses

Every operation that costs credits includes the charge in its response:

{
  "credits_used": 10,
  "credits_remaining": 990
}

For async jobs, the estimated cost is shown on submission:

{
  "job_id": "uuid",
  "estimated_credits": 20,
  "hint": "Credits charged on completion only."
}

Credit Enforcement

All billable operations check your credit balance before executing. When your balance drops to zero or below:

API primitives (email send, search, URL read) return 402 insufficient_credits
CEO runs are blocked with a credit pre-check (5 credits)
LLM proxy calls from the container are rejected, stopping agent work
The balance has a small negative buffer (-100 credits) to avoid cutting off mid-stream responses

Credits are enforced at every layer — the API, the LLM proxy, and individual primitive endpoints.

Running Low on Credits?

When your balance hits zero, operations fail with an insufficient_credits error that includes available credit packs. You can buy more anytime:

# See available packs
naive billing packs

# Buy credits
naive billing topup --pack medium   # 500 credits for $23

Or upgrade your plan for more monthly credits:

naive billing upgrade --plan pro    # 2000 credits/mo

See Billing & Credits for full details on plans and pricing.

Configuration reference (rates & metering)

The credit value and the duration-meter rates are deployment configuration. On the managed cloud these use the defaults below; self-hosters can override them via environment variables.

Setting	Env var	Default	Notes
Credit value	—	$0.05 / credit	Retail value used across the rate tables.
Compute vCPU rate	`NAIVE_COMPUTE_CREDITS_PER_VCPU_HOUR`	`20`	`compute` primitive duration meter.
Compute GB rate	`NAIVE_COMPUTE_CREDITS_PER_GB_HOUR`	`2.5`	`compute` primitive duration meter.
Runtime vCPU rate	`NAIVE_RUNTIME_CREDITS_PER_VCPU_HOUR`	`20`	Hosted-runtime (Hermes) duration meter.
Runtime GB rate	`NAIVE_RUNTIME_CREDITS_PER_GB_HOUR`	`2.5`	Hosted-runtime (Hermes) duration meter.
Hosted task size	`ORCH_TASK_CPU` / `ORCH_TASK_MEMORY`	`1024` / `2048`	vCPU-millis / MB of the orchestration task; used to compute runtime vCPU/GB-hours.
LLM markup	—	×1.25	Applied to OpenRouter’s returned USD cost.
Image/Video margin	—	×1.5	Applied to the live fal.ai price.

Both duration meters tick every ~2 minutes, key each charge to a time window (<resource_id>:<windowStart>) so a double-tick can’t double-charge, and cap a single tick’s back-charge at 3 intervals if the scheduler was paused. Compute is gated on NAIVE_COMPUTE_*; hosted-runtime metering is gated on ORCH_CLUSTER (hosted runtime being enabled at all).

​CLI First

​How Credits Work

​Credit Costs

​Fixed-Price Operations

​Infrastructure (duration-metered)

​LLM Calls

​Dynamic-Price Operations (Image/Video Generation)

​Two different “budgets” — don’t confuse them

​Running out of credits

​Sync vs Async Charging

​Checking Your Balance

​Usage History

​Credit Responses

​Credit Enforcement

​Running Low on Credits?

​Configuration reference (rates & metering)

CLI First

How Credits Work

Credit Costs

Fixed-Price Operations

Infrastructure (duration-metered)

LLM Calls

Dynamic-Price Operations (Image/Video Generation)

Two different “budgets” — don’t confuse them

Running out of credits

Sync vs Async Charging

Checking Your Balance

Usage History

Credit Responses

Credit Enforcement

Running Low on Credits?

Configuration reference (rates & metering)