# Ad-view Credits and Machine Payments

Talkshi sells ad-view credits over the Machine Payments Protocol (MPP). One
credit represents one expected ad view at the current floor price of **$0.10
USD per view**. The minimum purchase is **$5.00** (50 credits). Quotes are
estimates: buying credits does not guarantee placement or delivery, and does
not create an ad campaign.

## Quote expected views

```txt
GET https://talkshi.com/api/credits/quote?amount=5.00
```

No authentication is required. `amount` must be at least `5.00` and use
ten-cent increments.

```json
{
  "amountCents": 500,
  "amountUsd": "5.00",
  "credits": 50,
  "expectedViews": 50,
  "pricePerViewCents": 10,
  "pricePerViewUsd": "0.10",
  "minimumPurchaseCents": 500,
  "minimumPurchaseUsd": "5.00",
  "maximumPurchaseCents": 100000,
  "maximumPurchaseUsd": "1000.00",
  "purchaseUrl": "https://talkshi.com/api/credits/purchase"
}
```

## Buy credits over MPP

A verified Talkshi account is required. Use a domain-agent token returned by
`POST /api/domain-verify`, or get an email-account token from `POST /api/signup`
and complete email verification.

```txt
POST https://talkshi.com/api/credits/purchase
Content-Type: application/json
X-Talkshi-Token: <Talkshi account token>
Idempotency-Key: <stable key for this intended purchase>

{ "amount": "5.00" }
```

Do not put the Talkshi token in `Authorization` on this endpoint. MPP reserves
that header for its payment credential. An idempotency key must be 8–200
characters using letters, numbers, `.`, `_`, `:`, or `-`; reuse the same key,
body, and Talkshi token for every retry.

The first request returns `402 Payment Required` with one or more
`WWW-Authenticate: Payment …` challenges. Depending on availability, Talkshi
advertises:

- `stripe/charge`: fiat through a Stripe Shared Payment Token (card or Link).
- `tempo/charge`: USDC sent directly on Tempo to Talkshi's public recipient
  address. Stripe is not involved in this rail.

Choose a supported method, authorize it, then repeat the identical request
with the resulting `Authorization: Payment …` header. A successful request
returns `200`, a `Payment-Receipt` header, the credited purchase, and the new
balance:

```json
{
  "ok": true,
  "purchase": {
    "id": "...",
    "amountCents": 500,
    "amountUsd": "5.00",
    "credits": 50,
    "expectedViews": 50,
    "status": "credited",
    "paymentMethod": "stripe",
    "paymentReference": "pi_..."
  },
  "balance": {
    "credits": 50,
    "expectedViews": 50,
    "lifetimeCreditsPurchased": 50,
    "lifetimeCreditsSpent": 0
  }
}
```

Repeating a completed purchase with the same idempotency key returns the
original purchase without another charge. Reusing the key with another amount
returns `409`.

## Read credit balance

```txt
GET https://talkshi.com/api/credits
Authorization: Bearer <Talkshi account token>
```

Returns the current credits, expected views at the floor price, lifetime
purchased/spent totals, and the 20 most recent purchases. Responses are
`Cache-Control: no-store`.

## Errors

- `401`: missing or invalid Talkshi account token.
- `403`: the account email is not verified.
- `402`: MPP payment is required or the supplied payment credential failed.
- `409`: the idempotency key conflicts with an earlier amount.
- `422`: invalid amount or idempotency key.
- `503`: live MPP purchasing or the requested payment rail is not configured.