Wallet & billing

How it works

1. Sign up — your account is created with a $1.00 free signup credit. No card required.
2. Top up — when you're ready, add credit via the dashboard ($5 minimum, $5,000 maximum per transaction). One-time Stripe charges, not subscriptions.
3. Call the API — every call deducts the appropriate cost from your balance UPFRONT (before the LLM runs) so concurrent requests can't drive the balance negative.
4. Partial-success refund — if some providers fail, we refund proportionally before returning the response. x-balance-after-cents always reflects the post-refund balance.
5. Top up again — repeat as needed. Credits never expire. There's no "use it or lose it" pressure.

Pricing

Free signup credit

New accounts get $1.00 ($1 = 100 cents) on first auth, no card required, never expires. That's enough for ~50 quick-mode calls or 4 perplexity_live calls — long enough to wire MentionsAPI into your project and decide whether to top up. Existing accounts are not retroactively credited.

Top-up flow

Top-ups go through Stripe Checkout — single one-time charges, no subscriptions. The dashboard exposes presets at $5, $20, $50, $200, plus a custom amount field. The balance is credited within seconds of Stripe webhook confirmation.

Response headers

Every billed endpoint returns the following headers — your code never has to make a separate balance call:

HTTP/1.1 200 OK
content-type: application/json
x-cost-cents: 25
x-balance-after-cents: 8423
x-cache-status: miss
x-mode: perplexity_live
x-ratelimit-limit: 10
x-ratelimit-remaining: 9

402 Payment Required

When your balance falls below the call's price, we return 402 with a typed body so your code can branch deterministically. The topup_url deep-links to the billing dashboard with a prefilled amount.

HTTP/1.1 402 Payment Required
content-type: application/json

{
  "error": "insufficient_balance",
  "message": "Wallet balance is below this call's price.",
  "balance_cents": 12,
  "required_cents": 25,
  "topup_url": "https://mentionsapi.com/app/billing",
  "request_id": "req_01JBQ2K8H..."
}

Idempotency

Pass an Idempotency-Key header (1–200 chars). Replays within 24h return the original response and DO NOT re-deduct. This is Stripe-style: same key + same body = same response. Same key + different body = 422.

# First call: hits the LLMs, deducts 2¢
curl https://api.mentionsapi.com/v1/check \
  -H "Authorization: Bearer lvk_live_..." \
  -H "Idempotency-Key: my-job-2026-04-25-001" \
  -H "Content-Type: application/json" \
  -d '{"mode":"quick","query":"...","brand":"..."}'

# Replay within 24h: returns the same response, deducts 0¢
curl https://api.mentionsapi.com/v1/check \
  -H "Authorization: Bearer lvk_live_..." \
  -H "Idempotency-Key: my-job-2026-04-25-001" \
  -H "Content-Type: application/json" \
  -d '{"mode":"quick","query":"...","brand":"..."}'

Partial-success refunds

When a multi-provider call (e.g. 4-provider mode:quick) partially fails, we charge proportionally and refund the rest: cost = (success_count / requested_count) × mode_price. The refund hits your wallet before the response returns; the x-balance-after-cents header is always the final post-refund value. If 0 of N providers succeed, the refund is 100% — you only pay for what worked.

Tracking spend

Use GET /v1/usage to pull aggregated cost by endpoint, by provider, by mode, with day or hour granularity. Free, no rate limit. Wire it into your monitoring stack to alert on cost deltas before they become budget surprises.