# Credits and limits

Acquestor is priced per action in prepaid credits, and an action costs the same on acquestor.com, the API and MCP. 100 credits cost $1 at the pay-as-you-go price.

**During the beta everything is free**, within a monthly credit allowance: 500 credits for buyers, 1,000 for sellers, 2,500 for brokers and 5,000 for founding brokers. Nothing can be bought until public launch. The prices below are the ones that start then; `GET /pricing` publishes the price book in force, with the date it took effect.

## Price classes

Every operation in the API definition carries `x-price`, and every MCP tool description ends with its price.

| Class | Credits | Covers |
| --- | --- | --- |
| `free` | 0 | Listing work, inquiries, closed-deal contributions, deals, figures, your account. Saving a run is free; `save_to_deal` runs the computation it saves, at that tool's price |
| `lookup` | Free for the first 1,000 API and MCP calls a month, then 0.5 a call; free on acquestor.com | Rates, market salary, lenders, listing search and detail, sources, deal reads |
| `quick_tool` | 5 a run | SBA price ceiling, stress test, capital stack, after-tax proceeds, offer comparison |
| `deep_tool` | 50 a run | Proof of cash |
| `ai_job` | 3 a page | Reading an uploaded document for figures, quoted from the page count before it starts |

A run that fails, or that returns no result and only a gap, isn't charged.

## What every response says it charged

| Header | Meaning |
| --- | --- |
| `Acquestor-Credits-Charged` | Credits this call charged; `0` for free calls and errors |
| `Acquestor-Credits-Balance` | Your balance after the call |

Results also carry `charge`:

```json
"charge": {"credits": 0, "price_class": "lookup", "free_call": true}
```

`free_call: true` means a lookup was covered by the month's 1,000 free API and MCP calls. `GET /credits` returns your balance by bucket and `GET /credits/ledger` every grant, charge and expiry.

## Capping a call

Send `Acquestor-Max-Credits` with the most a call may charge. If its price is higher, it returns 402 `over_max_credits` and runs nothing.

```sh
curl https://api.acquestor.com/v1/diligence/proof-of-cash \
  -H "Authorization: Bearer $ACQUESTOR_API_KEY" \
  -H "Acquestor-Max-Credits: 10" \
  -H "Content-Type: application/json" \
  -d '{"deal_id": "…", "variance_threshold": 0.05}'
```

## 402: nothing ran

A priced call checks your balance and limits before it runs. When it can't pay, it returns 402 and charges nothing.

| `code` | Meaning |
| --- | --- |
| `insufficient_credits` | Your balance is below the price |
| `over_max_credits` | The price is above your `Acquestor-Max-Credits` |
| `over_limit` | A monthly limit was reached: the API key's, or the AI client's deal grant |

The problem body carries `price` and `balance`, and the response still carries `Acquestor-Credits-Charged: 0` and your balance:

```json
{
  "type": "https://docs.acquestor.com/problems/over_max_credits",
  "title": "Payment required",
  "status": 402,
  "code": "over_max_credits",
  "detail": "This call costs 5 credits, above your Acquestor-Max-Credits of 1. Nothing ran.",
  "price": 5,
  "balance": 4990,
  "instance": "/api/v1/value/sba-ceiling"
}
```

In an AI host, the tool result says "Nothing ran and nothing was charged."

## Limits

| Limit | Value | When you pass it |
| --- | --- | --- |
| A key's or a deal grant's monthly credits | 1,000 unless the owner sets another | 402 `over_limit` |
| Inquiries per buyer in any 24 hours | 20 | 429 `quota_exhausted` |
| Listing drafts from files, per broker per month | 30, free; more on request | 429 `quota_exhausted` |
| Document size | 25 MB | 413 `file_too_large` |

Acquestor doesn't publish per-second request limits during the beta. A 429 `quota_exhausted` carries `Retry-After`, the seconds until the quota resets; retrying sooner fails the same way.