Agents pay per result

An agent with no SpecStream account can buy a list of results with a machine payment: ask, get the price in a 402, pay it, and read the rows. No sign-up, no key, no checkout page. Every value comes back with the page it was read from, and the agent pays for the matches only.

When to use it

Hand SpecStream a list, not a fact: many rows, the page behind each row, or a list that has to stay current. For one fact, search yourself. If the person you work for has a SpecStream account, work on it over MCP or the REST APIinstead. That account carries the balance, the saved lists, schedules, exports, and connected tools.

Buy a list

1. Ask

Send POST https://api.specstream.ai/v1/agent/lists with the list in plain words. request takes 3 to 2,000 characters. count is optional, from 1 to 500.

Terminal
curl -i https://api.specstream.ai/v1/agent/lists \
  -H "Content-Type: application/json" \
  -d '{"request": "coffee shops in Narbonne, France", "count": 3}'

2. Read the 402

Without a payment the answer is 402 Payment Required. The body says how SpecStream read the request, which columns it will bring back, and the most the run can cost. The offer holds for 15 minutes.

JSON
{
  "type": "https://paymentauth.org/problems/payment-required",
  "title": "Payment Required",
  "status": 402,
  "detail": "SpecStream looks for 3 results for this request and charges at most $1.50. You pay for the results found; the rest is refunded when the run ends.",
  "offer": {
    "request": "coffee shops in Narbonne, France",
    "columns_asked_for": ["Name", "Address", "Website"],
    "count": 3,
    "maximum": "1.50",
    "currency": "usd",
    "expires_at": "2026-10-19T14:20:00+00:00"
  }
}

The headers carry the payment challenges: WWW-Authenticate: Payment for a card, and PAYMENT-REQUIRED for USDC.

3. Pay and send the request again

Pay or authorize the maximum the 402 names, then send the same request with the payment attached. The ways to pay below show what to send. The answer is 202 with a purchase and a token.

JSON
{
  "purchase_id": "agp_7Qk2mX9v",
  "token": "agt_...",
  "status_url": "https://api.specstream.ai/v1/agent/lists/agp_7Qk2mX9v",
  "read_with": "Authorization: Bearer <token>",
  "authorized": "1.50",
  "currency": "usd",
  "find_id": "fnd_4Hc8nR2w",
  "status": "running"
}

4
4. Read the rows
Read the status_url with the token as a Bearer credential. The rows are there when the run ends. A run keeps working until it reaches the count, which takes up to four hours on the largest lists, so poll.
Terminal
curl https://api.specstream.ai/v1/agent/lists/agp_7Qk2mX9v \ -H "Authorization: Bearer agt_..."
status is running while it works, and completed, partial, failed, canceled, or expired when it ends. Along the way the response has requested and found. When the run has ended it adds charged and the rows, each with its values and the page each one came from.

GET https://api.specstream.ai/v1/agent/lists returns these steps as JSON, with the ways to pay that are open right now.

Ways to pay

Way to pay	What you send	Details
Card, over MPP	`Authorization: Payment <credential>`	Stripe machine payments. Pay the challenge in `WWW-Authenticate` with a card through Stripe's Link agent wallet, or any MPP client. The smallest card charge is $1.
USDC, over x402	`PAYMENT-SIGNATURE`	USDC on Base, Arbitrum, or Polygon. Appears when the 402 carries a `PAYMENT-REQUIRED` header.
Skyfire Coming soon	Not open yet.	SpecStream is in Skyfire's review.

USDC over x402

The PAYMENT-REQUIRED header offers the upto scheme. Sign a Permit2 authorization for the most the run can cost, which any x402 v2 client does for you, and send the same request again with it in PAYMENT-SIGNATURE. Nothing moves when you sign. When the run ends, SpecStream takes only what the results cost, and a run that finds nothing takes nothing. The status URL then answers with a PAYMENT-RESPONSE header that names the transaction, and the body repeats it under payment.

Card over MPP

The card payment is taken up front. When the run ends, SpecStream refunds the part the results didn't use to the same card, and the status response shows charged and refunded.

What it costs

The 402 names the most the run can cost, and the agent authorizes that and no more. The charge is for matches only: 10¢, 30¢, or $1 a result depending on how much each one carries, plus 10¢ for a person's email and 25¢ for a phone when the request asks for them. Prices has the detail.

A run that finds nothing costs nothing.
If SpecStream can't start the run, nothing runs and nothing is taken.

The OpenAPI document gives the price of a purchase as a range from $1.00 to $500.00: the smallest card charge, up to 500 results at $1.

How agents find it

SpecStream is listed on x402scan, MPPScan, and 402index, where agents look for paid APIs. The OpenAPI document at https://api.specstream.ai/openapi.json describes the routes and carries x-payment-info on the paid one: the price range and the protocols it accepts.

agents.md says the same in plain text for an agent to read first, and llms.txt covers everything else an agent can do.