Skip to main content
Bring Pulse to autonomous agents: no signup, no API key — pay per document with USDC on Tempo using the open Machine Payments Protocol (MPP).
Every Pulse endpoint normally requires an API key. MPP adds a second door for agents: call POST /extract with no credentials, receive an HTTP 402 Payment Required challenge, pay the quoted amount on the Tempo blockchain, and retry to get your extraction — plus a 24-hour session key for follow-up work on the same document.
MPP payments use push mode: your client broadcasts the stablecoin transfer itself and presents the transaction hash as proof. Clients that only send pull-mode credentials (for example pympp 0.9.1, or the Tempo CLI’s tempo request as of v0.6.7) cannot pay Pulse today — use mppx configured for push mode, or the manual flow below.

Before you start

You need a Tempo wallet holding enough USDC to cover your extractions (a few cents per document) plus gas:
  • Wallet + funds: create a wallet and buy or bridge USDC by following the Tempo docs, or use the Tempo CLI (tempo wallet login, tempo wallet fund).
  • RPC: broadcast transactions through https://rpc.tempo.xyz (or your own node).

How it works

The challenge quotes a price for your exact document and parameters — the server counts the pages before charging you. The paid retry must re-send the same document (byte-identical bytes, uploaded the same way with the same filename extension, or the same file_url serving unchanged bytes) with the same model and pages parameters; the challenge is cryptographically bound to them. Both JSON file_url requests and multipart file uploads are supported — re-send the full request body on every retry.
The server re-fetches file_url on the paid retry. If the bytes behind the URL change — or a pre-signed URL expires — verification fails and your payment cannot be applied. Use content-stable URLs with a lifetime comfortably beyond the 10-minute challenge window, or upload the file directly.

Pricing

MPP charges the same credits as authenticated pay-as-you-go, settled in USDC at $0.015 per credit, rounded up to the next whole cent per payment. For example, extracting a 2-page PDF costs 2 credits = $0.03, quoted in the challenge as 30000 base units of USDC (6 decimals).

Quick start

1

Request an extraction with no credentials

The response is 402 Payment Required with the challenge in the WWW-Authenticate header:
2

Decode the challenge

request is base64url JSON with the = padding stripped (re-pad to a multiple of 4 before decoding):
amount is in USDC base units (divide by 10⁶ for dollars), currency is the USDC token contract, and recipient is a one-time deposit address minted for this challenge only. Pay on the chain the challenge names — chainId 4217 is Tempo mainnet — using the currency and recipient values exactly as given.
3

Pay on Tempo

Transfer exactly amount of the currency token to recipient on the challenge’s chainId, and keep the transaction hash. The challenge expires 10 minutes after it was minted; a payment broadcast in time stays redeemable for roughly 10 more minutes after expiry.
4

Retry with the payment credential

Re-send the identical request with an Authorization: Payment <credential> header (format below). On success you get the normal extraction response plus an mpp_session object and a Payment-Receipt header:
Payment-Receipt is unsigned base64url JSON — {"status": "success", "method": "tempo", "timestamp": …, "reference": "<tx hash>"} — keep it with your records; you don’t need it for later calls.
Pay the exact amount to the exact recipient of the challenge you will present, within its window. Deposit matching is exact-match per challenge: funds sent to a different challenge’s address, or an over- or underpaid transfer, do not fulfill your challenge and are not automatically returned. An underpaid deposit to the correct address is a terminal failure — never top it up or pay the same challenge twice. If you strand funds, contact support with your transaction hash.

The payment credential

The Authorization header value is Payment followed by base64url JSON (padding stripped):
Echo the challenge fields verbatim as received — keep request and opaque as their original base64url strings. payload.hash is your Tempo transaction hash. Only payload.type: "hash" is accepted; pull-mode transaction payloads are rejected. You may additionally include a source field (did:pkh:eip155:<chainId>:<address>) identifying the payer — it is optional and not validated.

Paying from an agent with the Tempo wallet

If your agent uses the Tempo Wallet CLI, it can complete the whole flow with wallet commands — no signing code required. Set it up once:
Then hand the agent this recipe along with your document:
Cap what an agent can spend with your wallet’s access-key spending limits (tempo wallet keys) — the key it holds cannot move more than the limit you set, whatever the agent does.

The session key

A successful payment returns mpp_session.api_key — a real API key scoped to an ephemeral organization created just for your payment. Use it as x-api-key for 24 hours to continue working with the document you paid for: Chained calls authenticate with the session key and pay per call: the key proves who you are, the 402 flow settles each new charge. The credential format is identical to the first payment, and paid responses carry a Payment-Receipt header. The session key cannot start extractions of new documents — begin a fresh anonymous 402 flow for those.
Session limits: synchronous requests only, /schema works on one extraction at a time (no batch or split mode), and up to 5 unpaid /tables computations per session. New chained challenges are refused in the last ~20 minutes of the session. Results are purged when the session’s retention window ends, so collect everything you need within 24 hours.

Errors and retries

Payment errors are 402 responses in RFC 9457 application/problem+json format ({"title", "detail", "status", "type"}); other validation and rate-limit errors use the standard {"error": {"code", "message"}} envelope. The rule that matters: only a 402 that carries a WWW-Authenticate challenge is payable. For a 402 without a challenge, follow the table — never pay again.
On /tables paid retries, verification failures are returned without a fresh challenge — re-present the same credential if the cause was transient, or start a new /tables request.
Anonymous requests are also rate-limited to 30 per hour per IP (429 GENERAL_004; during busy periods a shared limit can briefly return 429s as well — honor Retry-After). Anonymous files are capped at 50 MB regardless of model (FILE_002), and async mode is not available for anonymous requests (REQ_003).

Next steps

Authentication

Prefer a standing account? Get an API key instead.

Extract endpoint

Full request and response reference for POST /extract.

Pipeline steps

Chain split, schema, and tables on your paid extraction.

Error handling

Error codes and retry guidance for the whole API.