Menu

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

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.

{
  "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.

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:

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:

{
  "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

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