# Calling x402stock as an AI agent > Market and economic data for AI agents - US stocks, ETFs and options, forex, crypto and on-chain perps, energy commodities (crude, natural gas, gasoline), US and global macro (Fed funds, CPI/PCE, jobs, GDP, Treasury debt & yields, World Bank indicators), SEC filings, congressional trades, and market sentiment. No API keys, no accounts. Pay per request in USDC via x402 or MPP. ZeroClick is a paid, transparent proxy in front of x402stock's API. Send the same method, path, query, and body you would send the upstream API to `https://agents.x402stock.xyz`; ZeroClick collects payment, verifies your identity from the signed payment, and proxies the request upstream. Payment methods today are x402 (Base USDC) and MPP (Tempo USDC), with more coming. No signup, no API key: you authenticate by signing payment challenges, autonomously or with your human's approval. ## Key URLs - Base URL (call through): `https://agents.x402stock.xyz` - Live catalog: https://agents.x402stock.xyz/manifest.json - services, meters, plans, and prices as JSON. Read it at call time; do not cache prices. - API reference: https://x402stock.xyz/openapi.json - the upstream's own OpenAPI lists the operations, paths, and request/response schemas. Call those paths through the base URL. ## Quickstart ZeroClick operates in paid mode: API requests through the proxy return priced 402 responses that must be completed. There is no separate identity step - the signed payment itself proves wallet control. 1. Call `https://agents.x402stock.xyz/` with your normal request. 2. You receive a single priced `402 payment_required` with a `payment` block (the exact `amountUsd`) and a challenge for each protocol (x402 and MPP). Settle it with your wallet. 3. Retry the same request with the signed payment attached. ZeroClick verifies it, binds your wallet identity from the payment, and proxies your request upstream, returning the upstream's response. Pay-as-you-go plans charge per request. For credit or subscription plans, purchase once with `POST /plans/{planId}/purchase`, then call until the credit or period runs out (each call still carries your identity proof). Purchases and pay-as-you-go calls complete the same way: a bare request returns the priced 402 directly (both protocols offered), paying it proves who you are, and the retry succeeds - one 402 total, so single-payment clients complete either unmodified. ## No payment method yet? Get set up with Zero Everything here assumes you can sign the payment challenges, which needs an EVM wallet. If you do not have one, Zero can set you up: it creates an agent wallet and its CLI settles these 402 challenges for you, with no signup or email. Creating the wallet is free and spends nothing. ``` npm i -g @zeroxyz/cli zero auth agent register # anonymous agent account + wallet zero fetch https://agents.x402stock.xyz/ # calls through, paying the 402 for you ``` The wallet is yours, stored in `~/.zero/config.json`. Free identity handshakes and any free included usage work right away with no funds; add funds only for priced calls. A human can take ownership of the account later with `zero auth agent claim ` - agent-first trial, human ownership afterwards. Full setup: https://zero.xyz/install.md. ## Authentication: sign challenges, not API keys Your wallet is your identity. Every challenge and payment travels in standard protocol headers; there are no bespoke auth headers to construct: - x402 (Base USDC): the challenge arrives in the `payment-required` response header (and the `protocols.x402` body block). Sign it and send the payload in the `x-payment` request header. - MPP (Tempo USDC): the challenge arrives in the `www-authenticate` response header (and the `protocols.mpp` body block). Sign a credential for it and send `authorization: Bearer `. The challenge you sign embeds ZeroClick's payment metadata (the `payment.id` and `zcRequestId` you see in the 402 body), so the signed proof is all a retry needs - no other headers. Do not send the upstream's own credentials. You do not have an upstream API key and do not need one: ZeroClick authenticates to the upstream for you by signing each request. Ignore any `Authorization`, `x-api-key`, or similar auth the upstream's docs require, and omit those headers. ## The identity handshake costs nothing Most calls never need a separate identity step: paying the priced 402 proves wallet control by itself. A `402 { "error": "payment_required", "reason": "identity_required", "protocols": { ... } }` response appears only when ZeroClick must know who you are for a call it will not charge (a cold `POST /extend`, or a free upstream call that is scoped to the caller). The identity challenge is issued at amount 0: for x402 you sign a zero-value transfer authorization (EIP-3009, `value: "0"`, to the zero address) and send it in the `x-payment` header; ZeroClick verifies the signature locally, so nothing settles on-chain and no gas or USDC is spent. For MPP you answer the zero-amount challenge with a signed credential. Proving who you are is always free; priced challenges are the only thing you pay. ## The 402 payment challenge When payment is required you receive a JSON body like: ```json { "error": "payment_required", "zcAgentId": "agt_...", "zcRequestId": "zcreq_...", "plan": { "id": "pln_...", "slug": "...", "billingMode": "payg" }, "payment": { "id": "apay_...", "amountUsd": "1.250000", "rail": "base_usdc", "network": "base" }, "protocols": { "x402": { "x402Version": 2, "network": "eip155:8453", "scheme": "exact", "amount": "1250000", "asset": "0x..." } } } ``` The identity challenge offers both protocols; a priced challenge offers the protocol you authenticated with, or both when you have not authenticated (a bare request) - pay with whichever suits your wallet (the MPP block looks like `"mpp": { "challengeId": "...", "method": "tempo", "intent": "charge" }`). The body also carries the standard x402 document (`x402Version`, `resource`, `accepts`) at the top level - the same content as the headers. The full signable challenges arrive as headers: `payment-required` (x402) and `www-authenticate` (MPP). Settle with your wallet: - x402: client libraries handle signing and the retry for you: `@x402/fetch`, `@x402/axios`, or the `x402` package on PyPI. See https://docs.x402.org/getting-started/quickstart-for-buyers - MPP: sign a credential for the challenge. See https://mpp.dev/protocol/credentials Then retry the same request with the proof attached: the signed payload in `x-payment` (x402), or `authorization: Bearer ` (MPP). Every successful paid response includes a receipt header you can log for your spend records: `payment-response` (x402, base64-encoded settle result) or `payment-receipt` (MPP, serialized receipt). Free identity-only responses carry neither. ## Endpoints - `GET https://agents.x402stock.xyz/manifest.json`: machine-readable catalog of services, meters, plans and prices (JSON). Purchasable plans carry a `purchase` object (`url`, `amountRequired`, and `minimumUsd` for credit plans); `purchase` is `null` for pay-as-you-go. A price's `includedUnits` is the number of FREE units per period before its `priceUsd` applies. - `POST /plans/{planId}/purchase`: buy a credit or subscription plan. Body `{ "amountUsd"?: "25.000000" }` - the amount is required for credit plans (a whole-cent amount of at least the plan's `purchase.minimumUsd`) and ignored for subscription plans (the plan's base price is charged). Not valid for pay-as-you-go plans. No identity proof needed up front: the first response is the priced 402 itself. On success: ```json { "purchased": true, "zcAgentId": "agt_...", "access": { "id": "acs_...", "status": "active", "periodStartsAt": "...", "periodEndsAt": "...", "remainingCreditUsd": "25.000000" } } ``` - `POST /extend`: add credit to an active plan. Body `{ "amountUsd": "10.000000" }`. On success returns `{ "extended": true, "zcAgentId": "...", "access": { ... } }` with the updated balance. - `ANY /`: any other path is proxied to the upstream API as a paid request (settle its priced 402, then retry). ## Errors Errors are JSON `{ "error": "...", "reason"?: "..." }`. The common cases: Payment and access (`402 payment_required`, with a `reason`): - `identity_required`: no proven wallet identity. Answer the identity challenge (sign the zero-value authorization or credential) and retry with it. - `identity_invalid`: the identity proof did not verify. Sign a fresh challenge and retry. - `access_not_found`: you have no active plan to draw from or extend. Buy a plan first with `POST /plans/{planId}/purchase`. - `usage_exhausted`: your plan's credit ran out. Top up with `POST /extend` or purchase again. - `settlement_failed`: your signed payment did not settle; `settlementReason` says why (e.g. `insufficient_funds`). Fix your wallet and retry the request from the start for a fresh challenge. - no `reason` (a `payment` block is present): the normal per-call charge. Settle it via the challenge and retry with the proof attached. Bad request (`400`): - `invalid_request`: the request body is malformed. Fix the JSON. - `payg_not_purchasable`: you tried to buy a pay-as-you-go plan. Do not purchase payg; just call the API. - `amount_required`: buying a credit plan without an amount. Include `{ "amountUsd": "25.000000" }`. Not found (`404`): - `seller_not_found`: this host does not map to a seller. Check the base URL. - `plan_not_found`: unknown plan id. Use an id from `GET /manifest.json`. Seller or configuration issues (`409`, not caused by your request - retry later or contact the seller): - `signing_secret_required`: the seller has not finished setup. - `payment_request_mismatch`: a payment was reused for a different request. Request a fresh 402 and settle that one; do not reuse a payment across requests. - `payment_amount_mismatch`: a purchase or extend retry carried a different `amountUsd` than the challenge you paid. Retry with the amount the 402 quoted. - `invalid_usage_header` / `usage_not_priced`: the upstream reported usage ZeroClick could not bill. Once a paid call is proxied, you receive the upstream API's own status code and body, including its own errors. ## Billing modes - `payg` (pay as you go): just call. Each call returns one priced 402 with the exact `amountUsd`; pay and retry. No purchase needed. - `credit`: prepay a balance with `POST /plans/{id}/purchase` and an `amountUsd`. Calls draw it down; top up with `POST /extend`. The amount must be a whole-cent value of at least the plan's `purchase.minimumUsd`; decide how much to buy from the meter prices in the catalog and what you plan to call. Your remaining balance is returned as `access.remainingCreditUsd` on every purchase and top-up; an exhausted balance surfaces as a 402 - top up and retry. - `subscription`: purchase once with `POST /plans/{id}/purchase` (no amount; the base price is charged). Calls are allowed for the period. - `subscription_usage`: a subscription with included credit; usage beyond it is metered and charged per call. ## Free included units A price in the catalog may carry `includedUnits: N`: the first N units of that meter per billing period are FREE, and `priceUsd` only applies to usage beyond the allowance. On purchased plans the allowance is tracked per plan access and applied automatically. ## Ceiling pricing - charging up to a maximum Some meters (e.g. output tokens) cannot be known before the work runs. The 402 challenge then lists the item as {"meterSlug", "maxQuantity"} and the payment amount is a CEILING, not the price you pay - it is the most you could ever be charged, and you pay only your actual usage once the work runs (the seller may set the ceiling per request, or configure a per-meter default that applies when a request declares no maxQuantity). A ceiling-priced request settles on the RESERVE-AND-PAY-ACTUAL rails by design: your wallet reserves the ceiling up front, then you are charged only actual. Each rail is an entry in the challenge (look for the "billing" note in the entry's extra): the x402 "upto" scheme (Base USDC), where the reserved remainder simply never leaves your wallet, and the MPP "session" escrow channel (Tempo USDC), where you fund a channel to the ceiling, sign one voucher, and ZeroClick closes the channel at your actual usage so the escrow refunds the rest - and if ZeroClick ever fails to close it, you can force-close the channel yourself after the on-chain grace period to reclaim your full deposit, so escrowed funds are never stranded. One-shot prepay ("exact", the MPP charge) is never offered for a ceiling-priced request; that is what guarantees an unspent ceiling can never get stuck as seller credit. (If you already hold a prepaid balance with this seller from a plan purchase, ceiling-priced usage can still draw it down - billed at actual, like everything else.) A failed delivery debits nothing on either rail. Fixed-quantity requests are unchanged: pay "exact" or the one-shot MPP charge as always. Either way you are never charged past the ceiling, and never the full ceiling unless your usage actually reaches it. Every paid response also carries a `zc-billing` header reconciling the numbers for that request: what you authorized (`authorizedUsd`), what you were actually charged (`chargedUsd`), the remainder and where it went (`remainderUsd` + `remainderHandling`: "escrow_returned" means it never left your wallet or was refunded from escrow), plus the on-chain `settleTransactionHash` when one exists. `"status":"settling"` means on-chain settlement is still finishing and the final amounts are not stamped yet. ## Example: a pay-as-you-go call, end to end 1. Read the catalog (optional, to see services and prices): `GET https://agents.x402stock.xyz/manifest.json` 2. Make the call: ```http POST / HTTP/1.1 Host: agents.x402stock.xyz { ...your request body... } ``` 3. You receive the priced `402 payment_required` with the `payment` block and the x402 challenge shown above - one 402, no identity handshake first. Sign it (the client libraries linked above do this for you) and retry: ```http POST / HTTP/1.1 Host: agents.x402stock.xyz x-payment: { ...your request body... } ``` 4. `200 OK` (or whatever the upstream returns): ZeroClick settled the payment, bound your wallet identity from it, proxied your request upstream, and returned its response. For MPP the same loop applies with `www-authenticate` challenges and `authorization: Bearer ` retries.