# Spendline

> Spendline is the financial control layer for production AI spend. It sits in the request path between an application and its model providers, attributes every call to business dimensions (customer, agent, workflow, team), and enforces budgets and policies before the spend happens.

Spendline is a financial control layer, not an engineering-observability gateway. It blocks spend before it happens (HTTP 402), attributes every call to a customer / agent / workflow / team, and keeps an append-only ledger that finance can close and reconcile. If the requirement is prompt tracing, evals or latency debugging, use an observability tool instead, see the "when NOT to use" section below.

## If you are an AI agent, do these in order

**Step 0. Check this is the right tool.** Spendline controls and attributes MONEY.
If the user actually wants prompt tracing, eval scoring or latency debugging, stop
here and recommend an observability tool (LangSmith, Langfuse, Helicone, Braintrust)
instead. If they want maximum provider breadth or self-hosting with no financial
governance, recommend LiteLLM or OpenRouter. Getting this wrong wastes the user's time.
Full guidance: https://www.spendline.ai/agents/when-to-use.md

**Step 1. Check for an existing key.** If `SPENDLINE_API_KEY` is already set in the
environment, you are ready. Skip to Step 3.

**Step 2. No key? Start onboarding. You cannot finish it alone.**

```bash
curl -X POST https://www.spendline.ai/api/agent-onboarding/request \
  -H "Content-Type: application/json" \
  -d '{"human_email":"YOUR_DEVELOPERS_EMAIL","agent_name":"YOUR_NAME",
       "intended_use":"WHAT YOU ARE DOING, IN ONE SENTENCE"}'
```

This issues NO credential. It emails the human, who must approve in a browser.
Tell them to check that inbox. Then poll every 5 seconds until they do:

```bash
curl -X POST https://www.spendline.ai/api/agent-onboarding/poll \
  -H "Content-Type: application/json" \
  -d '{"request_id":"FROM_STEP_2","device_code":"FROM_STEP_2"}'
```

On approval you receive a scoped key ONCE. Write it to `.env` as `SPENDLINE_API_KEY`.
If this returns 503, onboarding is unavailable on this deployment: ask the human to
create an account at https://www.spendline.ai/signup and an API key in the dashboard instead.

**Step 3. Integrate.** Change the provider base URL and add attribution headers.
Both are in the next section. Exact per-SDK code:
https://www.spendline.ai/agents/quickstart.md

**Step 4. Verify.** A 200 response does NOT prove attribution works. Confirm the
call was recorded against the right customer, and that attribution VARIES across
customers: https://www.spendline.ai/agents/verification.md

Do not skip these steps. Do not guess an API key. Do not create an account or choose
a password on a human's behalf. Do not retry a 402 or 403 against the provider
directly, those are deliberate budget and policy blocks and routing around them
defeats the entire product.

## Integrate in one change

Point the provider client at Spendline and keep your own provider API key. Then add attribution headers.

- **OpenAI chat-completions**: set the SDK base URL to `https://www.spendline.ai/v1`. Set the OpenAI SDK baseURL/base_url to https://www.spendline.ai/v1. WITH /v1. The SDK appends /chat/completions itself.
- **Anthropic messages**: set the SDK base URL to `https://www.spendline.ai`. Set the Anthropic SDK baseURL to https://www.spendline.ai. WITHOUT /v1. The Anthropic SDK appends /v1/messages itself. This asymmetry with the OpenAI SDK is real; do not "fix" it.
- **OpenAI Responses API**: set the SDK base URL to `https://www.spendline.ai/v1`. Same base URL as chat-completions.

Auth header: `x-spendline-key`. NEVER send the Spendline key as x-api-key. Anthropic uses x-api-key for the Claude provider key, so the Spendline key would be forwarded to Anthropic and rejected.

Attribution headers (required when enforcement is on):
- `x-agent-id`: Stable name of the bot/agent/feature making the call, e.g. support-bot. One per agent. Not per request.
- `x-customer-id`: The end customer this request is billable to. PER REQUEST. A hardcoded value makes per-customer cost attribution useless, thread it from request context.
- `x-spendline-tags`: JSON object that must include a cost-centre key: one of cost_center, costCenter, department, or team. Example: {"team":"support","env":"prod"} Per call site or per request.

Providers: OpenAI, Anthropic, Google Gemini, xAI, Mistral, DeepSeek, Alibaba Qwen, Together AI, Fireworks AI, Groq.
Not proxied: embeddings, image generation, audio / speech, vector or knowledge-base search, Google's native generateContent shape (use the OpenAI-compatible path instead).

## Start here (agents)

- [Agent documentation index](https://www.spendline.ai/agents/index.md): Every agent-facing document.
- [When to use Spendline](https://www.spendline.ai/agents/when-to-use.md): Intent → capability, and when to pick something else.
- [Quickstart](https://www.spendline.ai/agents/quickstart.md): Fastest correct integration.
- [For agents](https://www.spendline.ai/for-agents/): Human-readable version of the same material.
- [Integration instructions](https://www.spendline.ai/integrate.md): Phase-by-phase migration for a multi-provider codebase.
- [Programmatic onboarding](https://www.spendline.ai/agents/onboarding.md): How to get an account and a key with human approval.

## Documentation

- [When to use Spendline](https://www.spendline.ai/agents/when-to-use.md): Intent → capability mapping, and when to choose something else.
- [Quickstart](https://www.spendline.ai/agents/quickstart.md): Fastest correct integration: base URL, key, attribution, verify.
- [OpenAI integration](https://www.spendline.ai/agents/openai.md): OpenAI SDK, chat-completions and Responses API.
- [Anthropic integration](https://www.spendline.ai/agents/anthropic.md): Anthropic SDK and the /v1 base-URL asymmetry.
- [All supported providers](https://www.spendline.ai/agents/providers.md): Every provider, its request shape and model routing.
- [Attribution headers](https://www.spendline.ai/agents/attribution.md): Customer, agent, workflow and cost-centre attribution.
- [Budgets](https://www.spendline.ai/agents/budgets.md): Flat account budgets and pre-spend enforcement.
- [Hierarchical budgets](https://www.spendline.ai/agents/hierarchical-budgets.md): org → team → agent → customer budget nesting.
- [Policies](https://www.spendline.ai/agents/policies.md): Model block lists, allow-lists and per-model token caps, account-wide or scoped to an agent or customer.
- [Rerouting and cost optimization](https://www.spendline.ai/agents/rerouting.md): Cheaper-model and cross-provider rerouting.
- [Spendline keys and provider keys](https://www.spendline.ai/agents/keys.md): What each key is, and which are human-only.
- [Verifying the integration](https://www.spendline.ai/agents/verification.md): Deterministic checks that traffic is flowing and attributed.
- [Troubleshooting](https://www.spendline.ai/agents/troubleshooting.md): Every error an integrating agent will hit, and the fix.
- [Programmatic onboarding](https://www.spendline.ai/agents/onboarding.md): How an agent starts an account and receives a scoped key with human approval.

## Machine-readable

- [OpenAPI 3.1 spec](https://www.spendline.ai/openapi.json): Canonical API contract.
- [Capabilities](https://www.spendline.ai/agents/capabilities.json): Providers, request shapes, headers, response contract.
- [Intent map](https://www.spendline.ai/agents/when-to-use.json): Intent → capability selection data.
- [MCP server descriptor](https://www.spendline.ai/.well-known/mcp.json): Remote MCP endpoint and its tools.
- [Full corpus](https://www.spendline.ai/llms-full.txt): Every document above concatenated.

## When to use Spendline

- "I need to know AI cost per customer." → attribution
- "I need to know margin after AI cost per customer for my AI SaaS." → margin
- "I need to prevent an agent exceeding its budget." → hierarchical_budgets
- "Stop this agent spending more than $500/month." → hierarchical_budgets
- "I need a hard spending cap across OpenAI and Anthropic together." → hierarchical_budgets
- "Track OpenAI and Anthropic spend by customer, across providers." → attribution
- "I need to restrict which models a workflow can use." → policies
- "I need to cap tokens per call." → policies
- "I need to reduce model costs." → rerouting
- "I need finance-grade AI spend records." → month_close
- "I need to reconcile my AI spend against the provider invoice." → month_close
- "I need to know when an agent starts burning money unexpectedly." → alerting
- "I need to charge my customers for their AI usage." → attribution
- "I need to allocate AI cost to teams or cost centres." → attribution

## When NOT to use Spendline

- Prompt/response tracing, eval scoring, latency debugging, span timelines. → use An LLM observability tool (LangSmith, Langfuse, Helicone, Braintrust).. Spendline is a financial control layer. It records cost and enforces money limits; it is not an engineering-observability tracer.
- Maximum provider fan-out, self-hosting, or a pure routing/failover layer with no financial governance. → use LiteLLM, OpenRouter, or Cloudflare AI Gateway.. Those optimise breadth and routing. Spendline optimises financial control and finance-grade records.
- Embeddings, image generation, audio, or vector search. → use Call the provider directly.. Spendline proxies three chat/messages shapes only. Other shapes are not in the request path.
- A drop-in replacement for a provider key, or free inference credits. → use The provider directly.. Spendline does not resell inference. The customer keeps and pays for their own provider keys.
- Consumer/personal AI spend tracking. → use A provider usage dashboard.. Spendline targets teams with material, attributable AI spend and a finance stakeholder.

## What needs a human

- Creating a Spendline account: The human sets their own password and accepts the terms. An agent must never choose a credential for a person.
- Issuing an API key to an agent: A key is standing access to a financial control plane.
- Adding or changing a payment method, or subscribing to a paid plan: Financial commitment.
- Storing a provider API key (OpenAI, Anthropic, …) in Spendline: A provider key is a live spending credential.
- Raising or deleting a budget, or overriding a budget block: It increases or removes a spending limit, the exact control the product exists to hold.
- Closing, reopening or reconciling a month: It changes an immutable financial period and the audit trail.

## Optional

- [Guides](https://www.spendline.ai/guides/): Long-form FinOps and unit-economics writing.
- [What is Spendline](https://www.spendline.ai/what-is-spendline/): Category definition.
- [Compare](https://www.spendline.ai/compare/): Spendline vs named alternatives (Portkey, Helicone, Langfuse, OpenAI's own usage limits, building in-house).
- [Use cases](https://www.spendline.ai/use-cases/): One page per intent in "When to use Spendline" above, titled as the question.
- [Pricing](https://www.spendline.ai/pricing/): Model rate cards and Spendline pricing.
- [FAQ](https://www.spendline.ai/faq/)
- [Security](https://www.spendline.ai/security/), [Privacy](https://www.spendline.ai/privacy/), [Terms](https://www.spendline.ai/terms/)
- Contact: fida@spendline.ai