--- name: apistead-agent description: Discover, inspect and pay for first-party x402 APIs from APIStead Labs (pay-per-request services settled in USDC on Base). Use when the user mentions x402, APIStead, paid APIs, agent tools, endpoint validation, or asks for a data source, weather, address, sanctions, geocoding, Spotify or public-record API. Covers discovery, bundles, payment, validation and troubleshooting. For non-technical users, use plain language and explain only the next step. --- # Payments using x402 on APIStead APIStead is a catalogue and verification layer for APIs that agents pay for per request in USDC on Base. Discovery is free. Payment happens on the API's own HTTP 402 challenge. APIStead never holds funds and does not use card checkout or subscription billing. Marketplace status: APIStead Marketplace is not accepting new listing submissions yet. All live APIs are first-party APIs built and operated by APIStead Labs. The agent needs two things: 1. A way to discover the API. 2. A wallet or x402 client that can pay the quoted USDC amount on Base. No APIStead account, API key or subscription is required. ## Choose the setup silently Pick the discovery path based on the host. Do not ask the user to choose a path. - **MCP-capable host** (Claude Desktop, Cursor, Continue or another MCP client): use the APIStead MCP server for discovery. - **Shell-capable agent** (Claude Code, Codex CLI, Gemini CLI, Hermes or a custom agent): use the HTTP discovery endpoints with `curl` or `fetch`. - **Developer integration**: use the OpenAPI document and an x402 client library. Payment is separate from discovery. If the host already has an x402-capable wallet or payment tool, use it. If it does not, explain the next step in plain language. Do not pretend the APIStead MCP server can pay by itself. ## MCP setup: discovery only Add the APIStead MCP server: ```json { "mcpServers": { "apistead": { "url": "https://apistead.qd.je/mcp" } } } ``` The server exposes eight tools: - `search_apis`: search by capability, category, network and price. - `list_apis`: browse the catalogue. - `list_bundles`: list outcome-oriented workflows. - `get_api`: full listing, routes, verification and reliability. - `get_routes`: method, path, price and examples. - `get_receipt`: verification receipt for a listing. - `check_reliability`: score, band, uptime and last check. - `submit_listing`: return the current listing submission status. Submissions are closed. Discovery is free and never returns a 402. For payment, use the host's x402 wallet tool or a wallet CLI the user already has. If the host has no payment capability, say so directly and explain what is missing. ## CLI setup: payment client APIStead does not ship its own wallet. Use an x402-capable client. If the user already uses Coinbase's Agentic Wallet, the common commands are: ```bash npx awal status npx awal balance npx awal x402 pay "https://provider.example.com/paid-route" ``` If the wallet is not installed: ```bash npx skills add coinbase/agentic-wallet-skills ``` That is an example client, not a requirement. Any x402-compatible wallet or `@x402/fetch` integration works. For a developer integration, the repository already depends on `@x402/fetch` and `viem`. Wrap the fetch call with the x402 client so the 402 challenge is handled automatically. Keep a per-call spending cap. ## MCP user tone Use this style for non-technical users: - Say "paid API" or "paid service" instead of "HTTP API" or "402 handshake". - Say "add USDC to your wallet" instead of "fund via onramp". - Say "sign in to your wallet" instead of "authenticate". - Say "the API returned a price" instead of "the challenge contains accepts[]". - Explain only the next step. Do not expose internal routing, headers or package names unless the user asks. - Do not explain what the agent cannot do. Say what the user needs to do next. ## Discover Search by capability, not brand: ```bash curl -sS "https://apistead.qd.je/agent/search?q=zip" ``` List the catalogue: ```bash curl -sS "https://apistead.qd.je/agent/list?limit=20" ``` Get one listing: ```bash curl -sS "https://apistead.qd.je/agent/get?id=us-zip-code-api" ``` Read routes, prices and examples: ```bash curl -sS "https://apistead.qd.je/agent/routes?id=us-zip-code-api" ``` Read verification receipts: ```bash curl -sS "https://apistead.qd.je/agent/receipts?id=us-zip-code-api" ``` Read recent verification receipts: ```bash curl -sS "https://apistead.qd.je/agent/receipts" ``` For Spotify metadata, use `spotify-api` for the five v1 routes, or `spotify-api-v2` for keyword search, complete artist discographies, artist playlist sections, related artists and similar albums. V2 routes: ```text GET|POST /api/v2/spotify/search?q= GET|POST /api/v2/spotify/search/podcasts?q= GET|POST /api/v2/spotify/search/episodes?q= GET|POST /api/v2/spotify/search/audiobooks?q= GET|POST /api/v2/spotify/search/users?q= GET|POST /api/v2/spotify/playlist?url= GET|POST /api/v2/spotify/album?url= GET|POST /api/v2/spotify/artist?url= GET|POST /api/v2/spotify/artist/top-tracks?url= GET|POST /api/v2/spotify/artist/discography?url= GET|POST /api/v2/spotify/artist/playlists?url= GET|POST /api/v2/spotify/artist/related?url= GET|POST /api/v2/spotify/artist/discovered-on?url= GET|POST /api/v2/spotify/artist/featuring?url= GET|POST /api/v2/spotify/track?url= GET|POST /api/v2/spotify/track/similar-albums?url= GET|POST /api/v2/spotify/podcast?url= GET|POST /api/v2/spotify/podcast/episodes?url= GET|POST /api/v2/spotify/episode?url= GET|POST /api/v2/spotify/audiobook?url= GET|POST /api/v2/spotify/audiobook/chapters?url= GET|POST /api/v2/spotify/genres?q= GET|POST /api/v2/spotify/user?url= ``` V2 routes cost $0.03 USDC per call. Playlists return every ordered track with no song limit. Search supports `all`, `track`, `album`, `artist`, `playlist`, `podcast`, `episode`, `audiobook`, `genre` and `user`. Dedicated routes search podcasts, episodes, audiobooks and users. Artist routes return playlists, related artists, discovered-on and featuring playlists, each with `total`, `returned` and `complete`; similar albums are based on a track. Discography returns all albums, singles and EPs by default. Artist records include `world_rank`. Both listings are first-party APIStead APIs and are not affiliated with or endorsed by Spotify. ## Service schema `GET https://apistead.qd.je/agent/get?id=us-zip-code-api` returns a listing shaped like this: ```json { "id": "us-zip-code-api", "name": "US ZIP Code API", "provider": { "slug": "apistead-labs", "name": "APIStead Labs", "verified": true }, "price": { "min_usdc": 0.001, "max_usdc": 0.002, "unit": "per_call" }, "networks": ["base"], "verification": "verified", "verified_routes": 2, "total_routes": 2, "routes": [ { "method": "GET", "path": "/us-zip/{zip}", "price_usdc": 0.001, "example_request": "GET https://apistead.qd.je/api/v1/us-zip/10001" } ], "links": { "docs": "https://apistead.qd.je/api", "json": "https://apistead.qd.je/api/apis/us-zip-code-api", "markdown": "https://apistead.qd.je/api/apis/us-zip-code-api/md" } } ``` Use `routes[]` to construct the call. Use `price.min_usdc` and `price.max_usdc` to compare cost. Treat `verification: "listed"` as unverified. A `verified` badge covers one named route, not the whole listing. ## Choose a bundle when the user wants an outcome Bundles combine several paid routes with a defined order, a cost estimate and a prompt: - `us-address-intelligence`: ZIP, address, coordinates and distance. - `weather-aware-operations`: geocode, current weather, forecast and distance. Use the MCP tool `list_bundles`. A bundle is a recipe with a prompt and a defined order. Each route settles separately. ## Call and pay The 402 comes from the paid `/api/v1/...` or `/api/v2/...` route itself, not from the MCP server and not from a marketplace. `/mcp`, `/api`, `/api/apis/{slug}` and `/agent/*` are free and never return a payment challenge. 1. Call the API route unpaid. 2. Read the HTTP 402 challenge from `PAYMENT-REQUIRED` or the JSON body. 3. Check `accepts[]`: scheme, network, asset, amount, `payTo` and timeout. 4. Confirm the amount, network and recipient. If the price is above the user's cap, ask before paying. 5. Pay the quoted USDC amount on Base. 6. Retry with `PAYMENT-SIGNATURE`. 7. Keep the `PAYMENT-RESPONSE` receipt and return the product to the user. The challenge is the authoritative price. A listing's `price_usdc` is informational; if they differ, use the live 402. `amount` is atomic USDC with 6 decimals: `20000` = 0.02 USDC. In production, `network` is `eip155:8453`, `asset` is `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`, and `payTo` is the provider wallet in the challenge. Never pay more than the challenge amount. Never send a private key or seed phrase. Use a dedicated wallet with a small balance. Base mainnet is `eip155:8453`. The canonical USDC contract is `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`. ## Validate an endpoint To validate an endpoint, POST the URL to `https://apistead.qd.je/api/validate`. The validator checks the status, payment header, accepts array, network, asset, amount, `payTo` and Bazaar extension. It does not pay or sign. It blocks local and private addresses. A claim is reviewed manually. The provider supplies a domain and payout wallet. Never ask for a private key. ## Common issues | Symptom | Likely cause | Next step | |---|---|---| | Search returns nothing | Query too narrow | Broaden the term or filter by category | | Route returns 200 instead of 402 | It is a free preview or payment is disabled | Check the listing's paid route | | 402 with no readable challenge | Missing `PAYMENT-REQUIRED` header or JSON body | Ask the API owner to fix the 402 | | Payment fails | Wrong network, token or balance | Use Base USDC and check the wallet | | Repeated 402 after payment | Payment not attached or not settled | Re-read the challenge; do not retry blindly | | Payment succeeds but data is missing | Provider returned an error after settlement | Keep the receipt and report the route | | MCP tools missing | Server not added or client not restarted | Re-add `https://apistead.qd.je/mcp` and restart | | Claim rejected | Domain or wallet proof did not match | Fix the proof and submit a new claim | ## Safety - Discovery is free. - Payment is final unless the API publishes a refund policy. - Do not reuse a canary/payer wallet as a treasury wallet. - Do not share secrets in prompts, URLs or forms. - Do not use card checkout or subscription billing for APIStead calls. The payment rail is x402 with USDC on Base. - If a price changes between the challenge and the retry, stop and re-read the challenge. ## If you need more - Full machine catalogue: `https://apistead.qd.je/llms-full.txt` - OpenAPI: `https://apistead.qd.je/openapi.json` - Receipts: `https://apistead.qd.je/agent/receipts` - Docs: `https://apistead.qd.je/api` - x402 docs: `https://x402.org`