> SpecStream is the live web data engine for teams and agents. This is the Markdown copy of https://specstream.ai/docs/agent-payments. Every page, with what SpecStream does and costs: https://specstream.ai/llms.txt # 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 its source URL, and the agent pays for the results found, never more than the price it agreed to. ## When to use it Hand SpecStream a list, not a fact: many rows, a source URL on each value, 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](https://specstream.ai/docs/mcp.md) or the [REST API](https://specstream.ai/docs/api.md)instead. That account carries the balance, the saved lists, schedules, exports, and connected tools. ## Buy a list 1. 1 ## 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 ```bash curl -i https://api.specstream.ai/v1/agent/lists \ -H "Content-Type: application/json" \ -d '{"request": "coffee shops in Narbonne, France", "count": 3}' ``` 2. 2 ## 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 ```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. 3 ## 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](#ways-to-pay) below show what to send. The answer is `202` with a purchase and a token. JSON ```json { "purchase_id": "agp_7Qk2mX9v", "token": "agt_...", "status_url": "https://api.specstream.ai/v1/agent/lists/agp_7Qk2mX9v", "read_with": "Authorization: Bearer ", "authorized": "1.50", "currency": "usd", "find_id": "fnd_4Hc8nR2w", "status": "running" } ``` 4. 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 ```bash 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 its source URLs. `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 ` | 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 the results found: 5¢, 15¢, or $1 a result depending on how much each one carries, plus 5¢ for a person's email and 15¢ for a phone when the request asks for them. A company left out costs nothing. [Prices](https://specstream.ai/pricing.md) 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](https://mppscan.com), and 402index, where agents look for paid APIs. The OpenAPI document at [https://api.specstream.ai/openapi.json](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](https://specstream.ai/agents.md) says the same in plain text for an agent to read first, and [llms.txt](https://specstream.ai/llms.txt) covers everything else an agent can do.