# Spendline

> Spendline is a financial control layer for production AI spend. It routes supported AI requests, records attributed costs and applies configured controls, and covers only traffic actually routed through it. Your application supplies the customer, agent, workflow and team labels; configured budgets and policies are checked before a supported request is forwarded.

Spendline is a financial control layer, not an engineering-observability gateway. For supported requests routed through it, strict budgets refuse a request whose estimated cost would exceed a limit (HTTP 402) before it reaches the provider, cost is recorded against the customer / agent / workflow / team labels the application supplies, and the append-only ledger can be closed month by month. Requests sent directly to a provider are outside its controls and records. 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://staging.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://staging.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://staging.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
book a 30-minute call at https://staging.spendline.ai/book/ to start a guided pilot, or accept an invite to their team's existing Spendline account; once they can sign in at https://staging.spendline.ai/ (the "Sign in" button on the homepage), they create an API key at Dashboard → API Keys instead.

**Step 3. Integrate.** Change the provider base URL and add attribution headers.
Both are in the next section. Exact per-SDK code:
https://staging.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://staging.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://staging.spendline.ai/v1`. Set the OpenAI SDK baseURL/base_url to https://staging.spendline.ai/v1. WITH /v1. The SDK appends /chat/completions itself.
- **Anthropic messages**: set the SDK base URL to `https://staging.spendline.ai`. Set the Anthropic SDK baseURL to https://staging.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://staging.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://staging.spendline.ai/agents/index.md): Every agent-facing document.
- [When to use Spendline](https://staging.spendline.ai/agents/when-to-use.md): Intent → capability, and when to pick something else.
- [Quickstart](https://staging.spendline.ai/agents/quickstart.md): Fastest correct integration.
- [For agents](https://staging.spendline.ai/for-agents/): Human-readable version of the same material.
- [Integration instructions](https://staging.spendline.ai/integrate.md): Phase-by-phase migration for a multi-provider codebase.
- [Programmatic onboarding](https://staging.spendline.ai/agents/onboarding.md): How to get a key with human approval, and where a human with no account starts.
- [Connect flow](https://staging.spendline.ai/agents/connect.md): Sent from the dashboard's Connect page? Analyse locally, propose attribution, wait for the human, install, verify.

## Documentation

- [When to use Spendline](https://staging.spendline.ai/agents/when-to-use.md): Intent → capability mapping, and when to choose something else.
- [Quickstart](https://staging.spendline.ai/agents/quickstart.md): Fastest correct integration: base URL, key, attribution, verify.
- [OpenAI integration](https://staging.spendline.ai/agents/openai.md): OpenAI SDK, chat-completions and Responses API.
- [Anthropic integration](https://staging.spendline.ai/agents/anthropic.md): Anthropic SDK and the /v1 base-URL asymmetry.
- [All supported providers](https://staging.spendline.ai/agents/providers.md): Every provider, its request shape and model routing.
- [Attribution headers](https://staging.spendline.ai/agents/attribution.md): Customer, agent, workflow and cost-centre attribution.
- [Budgets](https://staging.spendline.ai/agents/budgets.md): Flat account budgets and pre-spend enforcement.
- [Hierarchical budgets](https://staging.spendline.ai/agents/hierarchical-budgets.md): org → team → agent → customer budget nesting.
- [Policies](https://staging.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://staging.spendline.ai/agents/rerouting.md): Cheaper-model and cross-provider rerouting.
- [Spendline keys and provider keys](https://staging.spendline.ai/agents/keys.md): What each key is, and which are human-only.
- [Verifying the integration](https://staging.spendline.ai/agents/verification.md): Deterministic checks that traffic is flowing and attributed.
- [Troubleshooting](https://staging.spendline.ai/agents/troubleshooting.md): Every error an integrating agent will hit, and the fix.
- [Programmatic onboarding](https://staging.spendline.ai/agents/onboarding.md): How an agent requests a scoped key that a human approves, and where a human with no account starts.
- [Connect flow](https://staging.spendline.ai/agents/connect.md): Analyse the repo locally, propose attribution, wait for the human to confirm in the dashboard, install, verify.

## Machine-readable

- [OpenAPI 3.1 spec](https://staging.spendline.ai/openapi.json): Canonical API contract.
- [Capabilities](https://staging.spendline.ai/agents/capabilities.json): Providers, request shapes, headers, response contract.
- [Intent map](https://staging.spendline.ai/agents/when-to-use.json): Intent → capability selection data.
- [MCP server descriptor](https://staging.spendline.ai/.well-known/mcp.json): Remote MCP endpoint and its tools.
- [Full corpus](https://staging.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.

## How a team starts

- A guided 30-day free pilot, scoped on a 30-minute call. Public self-serve signup is not the way in for new teams; people invited to an existing account keep the invite flow. Book a call: https://staging.spendline.ai/book/
- No public Spendline price. Paid pricing combines a platform fee with a capped charge based on managed AI spend; scope, included features and paid terms are agreed before the pilot starts. There is no Spendline subscription fee during the pilot; model-provider charges still apply.
- https://staging.spendline.ai/pricing/ lists model-provider token rates as reference data. They are not Spendline fees.

## 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 seals a financial period and writes to the audit trail.

## Optional

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