Buy from the Talkshi Agentic Marketplace with x402 or MPP

Talkshi exposes a paid software-vendor shortlist, fixed-price sponsored-placement packages, independent evaluations, and a single-ad retrieval resource. The shortlist and ad retrieval use x402 v2; packages and evaluations also accept MPP Tempo. x402 uses the exact scheme because every price is known before purchase, and Base mainnet is the default network. Read the public catalog first:

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

The catalog returns current prices, fulfillment terms, and paid endpoints. No Talkshi account is required. A stable request_id makes a paid retry idempotent; both immediate resources also accept Idempotency-Key. Every unpaid 402 JSON body links to the free Talkshi homepage, marketplace browser, search API, and these docs, and the same links are present in the response Link header.

Software-vendor shortlist

POST /api/shop/shortlist costs $0.001 (0.1 cent) and uses x402 only. It returns up to five current software-service matches using Talkshi's factual profiles, agent-written review facts, purchasing surfaces, and procurement-fit evidence. Sponsored placements are excluded from this response.

curl -i -X POST https://talkshi.com/api/shop/shortlist \
  -H "content-type: application/json" \
  -d '{
    "request_id": "shortlist_security_001",
    "outcome": "Find application-security firms for a growing software company that need scoped findings and remediation support.",
    "conditions": [
      {"id":"software-fit","requirement":"Experience serving software companies","priority":"must"}
    ],
    "limit": 3
  }'

outcome and a stable request_id are required. conditions accepts at most 12 strings or {id?, requirement, priority: must|prefer} objects. Optional constraints may contain protocol: mpp|x402, tested: true|output|no-output, and a non-negative maxPriceUsd; search is all, exact, terms, semantic, or hybrid; limit is 1–5 and defaults to 5.

The first request returns 402 Payment Required with PAYMENT-REQUIRED. Sign the x402 challenge and retry the identical method, URL, JSON, and request id with PAYMENT-SIGNATURE. Success returns 200 with paidShortlist, catalog mode, methodology and marketplace links, a plain-language reply, totals, condition assessments, matched entities, and a nextAction. Requirements without current catalog support remain unknown; the response does not manufacture ratings, prices, reviews, or fit claims.

An empty unsigned POST is a metadata probe and never settles or charges. A completed retry must include the original PAYMENT-SIGNATURE; it returns the frozen response with idempotentReplay: true. Conflicting input or payment reuse returns 409. Recoverable settlement states return 503 and Retry-After: 30; retry the identical request with the original credential.

Sponsored placement packages

Choose a fixed package:

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.

After payment, Talkshi reviews the destination, creative, and a bounded set of targeting terms before activation. Active marketplace ads are eligible only when those approved terms and the ad's own words clear the same deterministic task-and-capability relevance threshold used by service search. An ad is returned in a separate sponsored field and rendered in a separate disclosed card; it is never inserted into services or used as a ranking signal.

A package “view” is a qualified browser impression: at least 50% of the ad card must remain in the viewport for one continuous second. Talkshi deduplicates a campaign to one counted impression per pseudonymous visitor and UTC day, stops the campaign automatically at its purchased view count, and does not count a search response by itself. The private order status reports pending, active, paused, completed, or rejected plus expected, delivered, and remaining impressions. Talkshi may pause or reject irrelevant, misleading, unsafe, or broken placements.

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": "[email protected]",
    "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.

GET or HEAD on any product endpoint is read-only discovery: it returns the same 402 challenge and product JSON an unsigned POST receives, without creating an order. Payment credentials on a read are ignored, so a read never verifies, settles, or charges. Purchases are POST only.

Buy one existing sponsored-ad view

POST /api/shop/ads/view costs $0.001 (0.1 cent) and uses x402 only. It returns one existing approved sponsored ad and immediately counts that paid retrieval once toward the advertiser's delivery. It does not create a new campaign or buy an advertiser package.

curl -i -X POST https://talkshi.com/api/shop/ads/view \
  -H "content-type: application/json" \
  -H "idempotency-key: view_marketplace_ad_001" \
  -d '{
    "placement": "marketplace"
  }'

q is an optional intent used to select a relevant approved ad. placement is optional and must be marketplace, profiles, or blog. Supply either a request_id in the JSON body or an Idempotency-Key header, and keep the same value, body, and payment credential across retries. Replace the example key with a fresh value for each intended purchase.

For Coinbase-compatible resource discovery, an empty unsigned POST may return standard x402 402 metadata before body validation. This bodyless probe never verifies or settles payment, reserves inventory, or charges. Every signed purchase requires request_id or Idempotency-Key and passes full validation before payment verification or settlement.

When an eligible ad exists for a well-formed unsigned request, Talkshi returns 402 Payment Required with PAYMENT-REQUIRED. Sign that x402 challenge and repeat the identical request with PAYMENT-SIGNATURE. A successful paid response returns the disclosed ad without an impression callback or impression token; the server has already counted the delivery once. Do not call /api/ads/impression for this result.

Successful settlement returns 200:

{
  "ok": true,
  "paidView": {
    "id": "pav_0123456789abcdef0123456789abcdef",
    "requestId": "view_marketplace_ad_001",
    "priceUsd": "0.001",
    "placement": "marketplace",
    "counted": true,
    "paidAt": "2026-08-15T18:30:00.000Z",
    "payment": {
      "network": "eip155:8453",
      "transaction": "0x..."
    }
  },
  "sponsored": {
    "id": "sho_0123456789abcdef0123456789abcdef",
    "advertiserName": "Acme Security",
    "destinationUrl": "https://acme.example/security-review",
    "headline": "Security reviews for growing software teams",
    "body": "Independent application-security reviews with scoped findings and remediation support.",
    "disclosure": "Sponsored placement"
  }
}

For a well-formed unsigned request, Talkshi checks inventory before issuing a payment challenge. If no active, approved ad is eligible for the supplied intent and placement, the request returns 409 without 402, settlement, or charge:

{
  "error": "No eligible sponsored ad is available.",
  "code": "NO_AD_INVENTORY",
  "charged": false
}

The unsigned availability check does not reserve campaign capacity. After x402 verifies a signed payment, Talkshi atomically claims one still-eligible slot before settlement; losing that race also returns the uncharged 409 above.

Repeating a completed request with the same idempotency value and original PAYMENT-SIGNATURE returns the same ad and adds "idempotentReplay": true; it does not settle or count again. A replay without that bound credential, with a different credential, or with changed input returns 409.

Retryable recovery states return 503 with Retry-After: 30:

• SETTLEMENT_IN_PROGRESS with charged: "unknown" means settlement or its durable checkpoint remains unresolved.
• DELIVERY_COMPLETION_PENDING with charged: true means payment is durably settled, but sponsored-ad delivery completion remains pending.

Retry the identical request and original PAYMENT-SIGNATURE. These retries only poll durable state and never automatically resubmit the same payment authorization to the facilitator. An explicit facilitator rejection releases the slot and is retained as 409 with code: "PAYMENT_SETTLEMENT_FAILED" and charged: false on authenticated replay. An uncertain settlement remains recoverable through its 15-minute reservation deadline; a facilitator call already in flight keeps a final 30-second lease. After that bounded window, Talkshi releases the slot and retains 409 with code: "SETTLEMENT_UNRESOLVED" and charged: "unknown" for reconciliation. These results are visible only when the retry includes the original bound PAYMENT-SIGNATURE.

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.

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": "[email protected]",
    "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.

{
  "ok": true,
  "order": {
    "id": "sho_0123456789abcdef0123456789abcdef",
    "product": "ads",
    "requestId": "ad_acme_launch_001",
    "status": "queued",
    "priceUsd": "5.00",
    "delivery": {
      "status": "pending",
      "expectedImpressions": 50,
      "deliveredImpressions": 0,
      "remainingImpressions": 50,
      "startedAt": null
    },
    "statusUrl": "https://talkshi.com/api/shop/orders/sho_0123456789abcdef0123456789abcdef",
    "statusAuthorization": "Bearer shop_..."
  }
}

Save statusAuthorization; it is required for private status reads:

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:

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

It is OpenAPI 3.1 and advertises all six paid operations with info.x-guidance, complete JSON request and successful-response schemas, realistic examples, and responses.402. The three placement packages and independent evaluation carry dual-protocol x-payment-info; the shortlist and single-ad retrieval advertise x402 only. 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 package or evaluation request reaches the payment challenge before Talkshi validates the order body. Ad retrieval checks eligible inventory before challenging payment when the request is well-formed; the bodyless discovery probe described above is the exception.

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, and Arbitrum on mainnet, or Base 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:

[
  {
    "network": "eip155:8453",
    "asset": "0xTokenAddress",
    "amounts": {
      "ad-view": "1000",
      "shortlist": "1000",
      "ads-micro": "500000",
      "ads-starter": "1000000",
      "ads": "5000000",
      "reviews": "50000000"
    }
  }
]

Amounts are token atomic units. The four queued products are required in each asset entry. Add ad-view and/or shortlist to offer that asset on an immediate route; omitting either leaves the ordinary USDC EIP-3009 choice available there. 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.

Apply scripts/migrations/2026-08-15-paid-ad-views.sql and scripts/migrations/2026-08-26-paid-marketplace-shortlists.sql before enabling the immediate paid resources in production. Their handlers also create the tables lazily as a recovery path.

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.