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

# Credits and payments

> One credit ledger for humans and agents: free grants, prepaid packs, and machine payments over the Machine Payments Protocol.

Starcovery has one credit ledger per account. Humans and every agent they run spend from the same prepaid balance. A credit costs \$0.05 and buys one identified search or product action. There are no seats and no subscriptions.

Read your balance at any time:

```bash theme={null}
curl "https://www.starcovery.com/api/billing/state" \
  -H "x-api-key: <access_token>"
```

## Free grants

| Caller                                                                       | Free searches                              |
| ---------------------------------------------------------------------------- | ------------------------------------------ |
| Unsigned (no credential)                                                     | 50 per UTC day per IP                      |
| Claimed account, session, or Settings API key, with an empty prepaid balance | 100 per UTC day                            |
| Pre-claim agent token                                                        | None. Searches spend prepaid credits only. |

When the grant and the balance are both exhausted, identified search answers 402.

## Prepaid packs (humans)

Humans buy packs with Stripe Checkout at [Billing settings](https://www.starcovery.com/app/settings/billing). Larger packs include bonus credits on the same \$0.05 list rate. Current ladder and bonuses: [pricing](https://www.starcovery.com/pricing). Optional auto-reload re-buys your last pack when the balance falls under 20% of that pack.

## Machine payments (agents)

The 402 from search carries a `WWW-Authenticate: Payment` challenge: Stripe Machine Payments Protocol, fiat, over Shared Payment Token. An agent settles it without a human. One payment buys 10 credits for $0.50 (the Stripe card floor is $0.50, so a single search cannot be charged alone). Unspent credits stay on the balance.

Protocol overview: [mpp.dev](https://mpp.dev/)

### Dry-run a challenge

Get a live 402 with a challenge without spending your free grant:

```bash theme={null}
curl "https://www.starcovery.com/api/search?q=coffee&force_payment=1" \
  -H "x-api-key: <access_token>"
```

```http theme={null}
HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment <challenge>
Content-Type: application/json

{ "error": "out_of_credits", "packsUrl": "https://www.starcovery.com/app/settings/billing" }
```

Parse the `Payment` scheme. Do not hard-code the challenge bytes: they vary per challenge.

### Retry with a credential

```bash theme={null}
curl "https://www.starcovery.com/api/search?q=coffee" \
  -H "Authorization: Payment <credential>" \
  -H "x-api-key: <access_token>"
```

<Warning>
  Send identity as `x-api-key` on the paid retry, not as a bearer token. MPP clients overwrite the `Authorization` header when attaching the payment credential, which would destroy a bearer token there.
</Warning>

Rules the rail enforces:

* A payment request without an identifiable caller answers 401 `identity_required`, and nothing is charged. Credits live on an account, so the service must know whose balance the payment funds.
* A credential is bound to the challenged identity. Redeeming it under a different account answers 403 `credential_caller_mismatch`, and nothing is charged. Recover by repeating the search with identity and no payment credential to get a fresh challenge.
* While a free grant or prepaid balance remains, `Authorization: Payment` still routes through the paywall, never a silent 200 settlement.

### Receipts and recovery

A paid response carries the search result plus a `Payment-Receipt` header. Keep the receipt as proof the payment settled. Two receipted failures exist, and neither needs a second payment:

* 503 `search_failed`: the credits are on the balance; only the search broke. Retry without the payment credential.
* 503 `credit_pending`: the charge succeeded and the credit grant is still landing through the Stripe webhook. Wait, then retry without the payment credential. A plain 402 after `credit_pending` with no receipt means the grant is still in flight, not lost.

A 402 that carries a `Payment-Receipt` means the earlier payment settled and its 10 credits are already spent. A fresh payment is needed.

### CLI

Settle the challenge externally, then:

```bash theme={null}
starcovery search "coffee" --payment '<credential>'
```