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

# Agent Billing

> Patterns for agents to inspect billing posture, quote expensive steps, and behave safely before running repeated or heavy SEC API workflows.

## Principle

Agents should not treat billing as an afterthought. They should inspect billing posture before expensive loops, preserve billing metadata in outputs, and warn before they cross from cheap reads into repeated or heavy workflows.

## Required checks

Before a multi-step workflow:

* `GET /v1/billing`
* `GET /v1/limits`
* `POST /v1/billing/quote` for the expensive step you are about to repeat

## Agent-safe behavior

* prefer one targeted request over a wide fan-out
* keep `Request-Id`, `traceparent`, `SECAPI-Meter-Class`, `SECAPI-Plan-Key`, `SECAPI-Billing-State`, `SECAPI-Free-Grant-Remaining`, `SECAPI-Token-Count`, and `SECAPI-Estimated-Cost`
* warn before repeated section extraction, compare workflows, or artifact generation
* stop and ask for card attachment if the org is in `payg_pending_card`
* stop and ask for admin approval if the server returns `billing_budget_approval_required`
* stop immediately if the server returns `billing_budget_hard_cap_exceeded`

## Sponsored bootstrap

* administrators create sponsor tokens with `POST /v1/agent/bootstrap_tokens`
* agents exchange those tokens exactly once with `POST /v1/agent/bootstrap`
* the bootstrap response returns the first API key, billing posture, limits, and MCP install metadata in one payload

## Good pattern

```text theme={null}
Check billing posture first. Quote the expensive step before repeating it. If the org is still on the starter grant, use the smallest high-signal request sequence possible. If the org is in payg_pending_card, stop and ask an administrator to activate PAYG before continuing. If the server requires approval or reports a hard cap, stop instead of retrying blindly.
```