7 min read3 views

How an AI Agent Pays for a Datasheet Extraction Without an Account

How an agent with no account pays for an extraction: an HTTP 402 challenge, a Stripe credential, a 15 minute result token, and a refund if the paid job fails.

Felix S. Pavel

Founder & Lead Architect

TL;DR: a developer API key comes from a registered account, and an agent that is passing through has none. So the extraction endpoint also accepts payment per call. A request with no credentials gets an HTTP 402 challenge. The agent retries with a Stripe payment credential, the server charges $3.00 per module after it has validated the request, and the reply carries a token that reads the results back for 15 minutes. This post walks the exchange and states what it does not cover.

Sources: the gateway's own code for the challenge, the credential check, the price and the refund, and the published handshake on the For AI agents page. Every value in the examples below is shown as the API returns it, with identifiers replaced by placeholders.

Why an account is the wrong door for an agent

An API key is created in the dashboard, by a person, under an account. That suits a team that runs an agent every day. It does not suit an agent that needs one part's data once, on behalf of someone who never signed up. For that case the same endpoint, POST /api/v1/extract, accepts two kinds of caller: a holder of a developer key, who spends module credits, and an anonymous caller who pays for the request itself.

The status code that carries the challenge is old. RFC 9110 defines 402 Payment Required and says it is reserved for future use. Here it is used the way its name suggests: the answer to a request that needs payment before it can proceed.

The exchange, step by step

1. Ask, with no credentials

POST /api/v1/extract
Content-Type: application/json

{"fileUrl": "https://example.com/stm32h743zi.pdf", "modules": ["pinout"]}

2. Receive the challenge

HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment protocol="mpp_v1", amount="3.00", currency="USD", resource="/api/v1/extract"
X-Machine-Payment-Required: true
X-Machine-Payment-Amount-USD: 3.00
X-Machine-Payment-Protocols: mpp_v1, x402

{ "error": { "code": "PAYMENT_REQUIRED",
    "challenge": { "protocol": "mpp_v1", "amount_cents": 300, "currency": "usd",
                   "accepted_methods": ["card_spt", "payment_intent"] } } }

The body above is abridged; the full challenge also carries a description and the amount as text. The amount is computed from the request. One module is $3.00; the challenge for a request that names two modules says $6.00. The body lists two accepted methods: a shared payment token and a PaymentIntent that has already succeeded.

3. Retry with a payment credential

POST /api/v1/extract
Authorization: Payment spt_...
Content-Type: application/json

{"fileUrl": "https://example.com/stm32h743zi.pdf", "modules": ["pinout"]}

The credential can also arrive in an X-Shared-Payment-Token or X-Stripe-Payment-Credential header. The server verifies it with Stripe. It accepts an id of a payment that has already succeeded (pi_...) when the amount covers the price, or a Stripe payment credential (spt_, tok_ or pm_), which it turns into a charge for exactly the price of the request.

4. Receive the job, not the files

HTTP/1.1 202 Accepted

{ "status": "PROCESSING",
  "job_id": "<job_id>",
  "payment": { "mode": "STRIPE_MACHINE_PAYMENT", "settled": true, "currency": "USD", "amount": "3.00" },
  "retrieval": {
    "status_url": "/api/v1/jobs/<job_id>",
    "module_urls": { "pinout": "/api/v1/jobs/<job_id>/pinout" },
    "session_id": "<token>",
    "session_id_expires_at": "<time>" },
  "guidance": { "poll_interval_seconds": 5 } }

The reply is a 202 because extraction runs after the response. The module URL answers 404 until that module has completed, and the status URL reports overall progress. The agent appends ?session_id=<token> to each URL to read results back.

What the server checks before it takes money

The order of operations is the part worth reading, because an agent cannot ask a human to dispute a charge. The extraction route validates the whole request first and only then authenticates and charges. A request that fails validation is answered with a 400 and costs nothing. The refusals that come before payment include:

  • a body that is not valid JSON, or a fileUrl that is missing or not an https link;
  • module names the API does not know;
  • a fileUrl that points somewhere our servers must not request: a private, loopback or internal address, credentials in the URL, a non-default port, or a name that does not resolve to public addresses.

Once a credential is presented, three more rules apply:

  • Single use. Asking Stripe about a payment that has succeeded gives the same answer every time, so the server records each spent payment id in a table with a unique constraint. Two requests racing with the same credential cannot both win; the loser is told the payment is already spent.
  • Fail closed. If that record cannot be written for any reason other than the payment already being spent, access is refused. An outage does not become free service.
  • No test tokens in production. Development tokens are accepted only when the server is not running in production.

A credential that cannot be verified gets the same 402 challenge back, with a note that verification failed.

What it costs

$3.00 per module requested, never less than one module. Asking for a document map counts as a module. The same per-module price applies on the MCP server when it is paid per call. A caller with a developer key pays in module credits instead, by the same module count.

When a paid job fails

A job can fail after payment: the document cannot be read, or the worker gives up after its retries. A job that was paid with money is refunded in full, to the payment that paid it. A job that never started is refunded at once. A job that ran and failed is refunded after it has stayed failed past the queue's retries.

The refund is made exactly once. The server first claims the job in one conditional update, so two sweeps cannot both proceed. It then asks Stripe whether a refund for that job already exists before it creates one, and the refund request carries an idempotency key built from the job id. A crash between Stripe and the record therefore cannot pay twice.

Stripe can still decline a refund. The outcome is then recorded as not refunded, with Stripe's reason, and a person reads it. An outage leaves the refund pending, and a later sweep retries it.

Limits you should plan for

  • The result token lasts 15 minutes. With no account, the token is the only way to reach the job. The reply says so and gives the expiry time. Read every module URL before it expires; after that the results cannot be reached.
  • Extraction takes time. The agent polls. The reply suggests a five second interval, and a module URL is a 404 until its module has finished.
  • The 402 body lists more methods than the server verifies directly. The credentials it checks are the Stripe forms described above. Read the challenge for what is offered and the For AI agents page for what is supported today.
  • Results are drafts. Paying does not change what the output is: structured data with source pages and review flags, for an engineer to check before it reaches a board.

FAQ

Does an agent need an account to use the API?

No. It can pay per request with a Stripe payment credential and read the results with the token the reply returns. A developer API key is the alternative for teams that run agents regularly.

What does one extraction cost?

$3.00 per module requested, with a minimum of one module. The 402 challenge states the exact amount for the request before anything is charged.

What happens if the job fails after I pay?

A job paid with money is refunded in full to the same payment, once the job is confirmed failed. A job that never started is refunded immediately.

Can the same payment credential be used twice?

No. Each payment id is recorded when it is spent, and a second request with it is refused.

Read the full handshake, or try the API on a datasheet you have.

A new account gets five free passes. Each pass runs up to two modules, pinout and footprint included, on a PDF up to 25 MB.

Sources

  1. IETF, RFC 9110 HTTP Semantics, section 15.5.3: 402 Payment Required (reserved for future use)
  2. DatasheetVend, For AI agents: the published handshake, entry points and price
  3. DatasheetVend, OpenAPI document for /api/v1/extract

Was this useful?

A like tells other engineers it is worth their time.

Keep reading

All articles

Cookies. Strictly necessary cookies keep you signed in and remember this choice. Optional analytics (Google, Microsoft, PostHog) show us how the site is used. Cookie details