Skip to main content
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:

​
Free grants

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. Larger packs include bonus credits on the same $0.05 list rate. Current ladder and bonuses: 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(theStripecardflooris0.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

​
Dry-run a challenge

Get a live 402 with a challenge without spending your free grant:
Parse the Payment scheme. Do not hard-code the challenge bytes: they vary per challenge.

​
Retry with a credential

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.
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: