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

# Metering & credits

> How ECN bills metered work in credits at real cost-plus — and why a call can never be billed below cost.

ECN bills metered work in **credits**, pegged at **\$0.10 / credit**
(`ECN_CREDIT_USD_VALUE`). Pricing is **cost-plus**: credits track the *real* cost of
each action, so a call can never be billed below what it actually cost to run.

## What gets metered

| Cost type                                      | How it's priced                 | What's recorded                                                                                                                                                   |
| ---------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **LLM / embeddings** (via OpenRouter)          | real provider cost × markup     | `UsageEvent` (with `cost_usd`) + `CreditTransaction` spend, written by `ai/gateway.py`                                                                            |
| **Paid external APIs** (e.g. Apify actor runs) | real run cost × the same markup | `UsageEvent` (`provider="apify"`, `feature="lead_signal_fetch"`), plus a `CreditTransaction` when a managed wallet is charged, via `metering.meter_external_cost` |
| **Free public data** (e.g. Socrata permits)    | not billed                      | `DataQueryLog` only                                                                                                                                               |

Because paid external spend flows through the **same** cost-plus path and ledger as
LLM spend, `python manage.py check_margins` can audit realized gross margin per
feature across both. There is no un-metered paid-API expense.

## How a call is metered

<Steps>
  <Step title="Preflight">
    The gateway estimates the credit cost from the rate card and checks it against
    your org's budgets. Over budget → rejected before any provider call.
  </Step>

  <Step title="Execute">
    The provider call runs through managed ECN keys.
  </Step>

  <Step title="Meter">
    A `UsageEvent` records the real `cost_usd`, tokens, model, and feature; a
    `CreditTransaction` debits your wallet. Both are immutable — an audit trail.
  </Step>
</Steps>

## Rate card

The rate card sets a **preflight floor** per feature; the actual charge is the
real cost-plus amount. Features include (non-exhaustive):

`profile_draft`, `context_author`, `context_refresh`, `context_pack_compile`,
`lead_enrichment`, `lead_qualify`, `outreach_draft`, `lead_signal_fetch` (paid
data, priced from real cost), `x_reply_draft`, `funnel_generate`.

The authoritative, current list is whatever `GET /api/v1/credits/rate-cards/`
returns for your environment — treat this as illustrative, not exhaustive.

Query the live rate card at `GET /api/v1/credits/rate-cards/` and your balance at
`GET /api/v1/credits/wallet/` (or the `get_wallet_balance` MCP tool).

## Managed credits, not BYOK

The hosted product uses **ECN-managed provider keys** (`OPENROUTER_API_KEY`,
`APIFY_API_TOKEN`, …) and meters usage to your org's wallet. There is **no
customer-facing bring-your-own-key** in the hosted product.

<Note>
  Self-hosting your own keys (so you pay providers directly, \$0 to ECN) is a
  **self-host / Community edition** capability, gated by `ECN_DEPLOYMENT_MODE` — see
  [BYOK & self-host](/self-host/byok). It is not a hosted billing feature.
</Note>