# Buy Talkshi Ads and Independent Evaluations with x402 or MPP

Talkshi exposes four fixed-price products payable through x402 v2 or MPP Tempo.
x402 uses the `exact` scheme because every package has a known price before
purchase; Base mainnet is the default network. Read the public catalog first:

```txt
GET https://talkshi.com/api/shop
```

The catalog returns current prices, fulfillment terms, and the four purchase
endpoints. No Talkshi account is required. A stable `request_id` makes the paid
retry idempotent.

## Sponsored placement packages

Choose a fixed package:

| Endpoint | Default price | Expected views |
| --- | ---: | ---: |
| `POST /api/shop/ads/micro` | $0.50 | 5 |
| `POST /api/shop/ads/starter` | $1.00 | 10 |
| `POST /api/shop/ads` | $5.00 | 50 |

Every package uses the same request body. The placement is reviewed before it
runs, always carries a visible `Sponsored` label, and never changes organic
marketplace ordering, ratings, or reviews.

```sh
curl -i -X POST https://talkshi.com/api/shop/ads \
  -H "content-type: application/json" \
  -d '{
    "request_id": "ad_acme_launch_001",
    "advertiser_name": "Acme Security",
    "destination_url": "https://acme.example/security-review",
    "headline": "Security reviews for growing software teams",
    "body": "Independent application-security reviews with scoped findings and remediation support.",
    "placement": "marketplace",
    "contact_email": "ads@acme.example",
    "acknowledge_sponsored": true
  }'
```

`placement` is `marketplace`, `profiles`, or `blog`. Supply either
`contact_email` or a public HTTPS `callback_url`. The first request returns
`402 Payment Required` with both `PAYMENT-REQUIRED` and `WWW-Authenticate`.
Choose one rail and repeat the same method, URL, and JSON:

- For x402, sign `PAYMENT-REQUIRED` and send `PAYMENT-SIGNATURE`.
- For MPP, satisfy the Tempo challenge and send `Authorization: Payment ...`.

Send only one payment credential.

## Independent review request

`POST /api/shop/reviews` costs **$50.00** by default. The fee funds an
independent first-hand evaluation attempt and a private outcome report. It does
not buy a rating, recommendation, publication, marketplace position, or removal
of an existing review.

```sh
curl -i -X POST https://talkshi.com/api/shop/reviews \
  -H "content-type: application/json" \
  -d '{
    "request_id": "review_acme_api_001",
    "company": "Acme API",
    "test_url": "https://api.acme.example/public-demo",
    "evaluation_goal": "Test whether the documented public demo returns a usable result with clear pricing and recovery guidance.",
    "contact_email": "research@acme.example",
    "acknowledge_independence": true
  }'
```

`test_url` must be a public HTTPS surface that can support a concrete first-hand
test without credentials in the request. Fields that request a rating,
sentiment, or verdict are rejected. Talkshi publishes an evaluation only when it
can complete a qualifying test; any published result is labeled
`Commissioned evaluation` and excluded from community rating aggregates.

## Success and private status

Successful settlement returns `201` and the queued order. x402 responses include
`PAYMENT-RESPONSE`; MPP responses include `PAYMENT-RECEIPT`.

```json
{
  "ok": true,
  "order": {
    "id": "sho_0123456789abcdef0123456789abcdef",
    "product": "ads",
    "requestId": "ad_acme_launch_001",
    "status": "queued",
    "priceUsd": "5.00",
    "statusUrl": "https://talkshi.com/api/shop/orders/sho_0123456789abcdef0123456789abcdef",
    "statusAuthorization": "Bearer shop_..."
  }
}
```

Save `statusAuthorization`; it is required for private status reads:

```sh
curl -H "authorization: Bearer shop_..." \
  https://talkshi.com/api/shop/orders/sho_0123456789abcdef0123456789abcdef
```

Repeating the same body and payment with the same `request_id` returns the stored
order without another settlement. Reusing `request_id` with changed details or
a different payment returns `409`.

## AgentCash, x402scan, and mppscan discovery

The canonical AgentCash discovery document is:

```txt
GET https://talkshi.com/openapi.json
```

It is OpenAPI 3.1 and advertises all four paid operations with `info.x-guidance`,
complete JSON request and successful-response schemas, realistic examples,
`responses.402`, and dual-protocol `x-payment-info`. Each
`x-payment-info.price.amount` is the current decimal USD price. The live
challenges remain authoritative: x402 encodes USDC in token atomic units, while
MPP advertises `method="tempo"`, `intent="charge"`, and the public
`realm="talkshi.com"`. An unauthenticated request reaches the payment challenge
before Talkshi validates the order body.

## Coinbase Bazaar discovery

All paid routes declare `extensions.bazaar` metadata with realistic inputs,
JSON Schemas, output examples, an `application/json` response MIME type, service
metadata, and an optional Base Builder Code. Coinbase indexes a route after its
first successful settlement through the CDP Facilitator. The server requires
`CDP_API_KEY_ID`, `CDP_API_KEY_SECRET`, `X402_RECIPIENT_ADDRESS`, and
`DATABASE_URL`, plus a stable `SHOP_TOKEN_SECRET` (or existing
`MPP_SECRET_KEY`) of at least 32 characters; Base mainnet is the default.

Set `TALKSHI_X402_TESTNET=true` to use Base Sepolia. An optional
comma-separated `TALKSHI_X402_NETWORKS` can enable supported EVM networks:
Base, Polygon, Arbitrum, and World on mainnet, or Base Sepolia and World
Sepolia on testnet. `GET /api/shop` reports every enabled network.

Set `TALKSHI_X402_BUILDER_CODE` only to a registered Base Builder Code using
1–32 lowercase letters, numbers, or underscores. To add a Permit2 payment
choice for another ERC-20, set `TALKSHI_X402_PERMIT2_ASSETS` to a JSON array:

```json
[
  {
    "network": "eip155:8453",
    "asset": "0xTokenAddress",
    "amounts": {
      "ads-micro": "500000",
      "ads-starter": "1000000",
      "ads": "5000000",
      "reviews": "50000000"
    }
  }
]
```

Amounts are token atomic units and must be set deliberately for every product.
The ordinary USDC EIP-3009 choice remains available. CDP supplies its supported
gas-sponsoring extensions for EVM routes.

MPP Tempo requires `TALKSHI_MPP_TEMPO_ENABLED=true`, a stable
`MPP_SECRET_KEY` of at least 32 characters, `TEMPO_RECIPIENT_ADDRESS`, and
`DATABASE_URL`. Set `TALKSHI_MPP_TEMPO_TESTNET=true` only for testnet; Tempo
mainnet is the default.

Optional price overrides are `TALKSHI_AD_MICRO_PRICE_USD`,
`TALKSHI_AD_STARTER_PRICE_USD`, `TALKSHI_AD_PACKAGE_PRICE_USD`, and
`TALKSHI_REVIEW_REQUEST_PRICE_USD`.

## Payment-free production verification

Run `bun run check:x402-shop` to inspect every live `402` challenge and submit
each route to Coinbase's endpoint validator and settlement simulation. This
does not sign a payment or transfer USDC. A protected daily Vercel cron runs
the same check at `/api/x402-health`, returns a failure status when a required
check fails, and emails the shop operator when Resend is configured; it
requires `CRON_SECRET`.

Bazaar indexing is reported but does not fail the check because Coinbase
indexes each route after its first genuine successful settlement. A real
$0.50 Base-mainnet settlement already verified the production payment path;
routine tests use the payment-free check rather than paying the receiver again.