Developer quickstart

Connect an agent in minutes.

Discovery is free. Payment happens on the provider's own x402 route. You need a USDC wallet on Base, an x402-capable client, and one URL.

MCP server OpenAPI llms.txt Agent skill Bundles Receipts x402 guide

1. Connect over MCP

Add the server to Claude Desktop, Cursor, Continue or any MCP-compatible client. The endpoint is stateless Streamable HTTP and requires no authentication for discovery. See the MCP server guide for client configuration and a curl test.

claude desktop / cursor

{
  "mcpServers": {
    "apistead": {
      "url": "https://apistead.qd.je/mcp"
    }
  }
}

The server exposes search_apis, list_apis, list_bundles, get_api, get_routes, get_receipt, check_reliability and submit_listing. Discovery never costs anything and never returns a 402.

2. Route lifecycle

Draft and testing routes bypass x402 so they can be built and checked. Live routes return a payment challenge and are the only routes in the public catalogue. Paused routes return 503. Uptime comes from scheduled health checks, not from the verification badge.

3. Discover over HTTP

Agents that do not speak MCP can use the same catalogue over plain HTTP. Every response is JSON with a stable shape.

Method	Endpoint	Purpose
POST	/mcp	MCP JSON-RPC: search, list, bundles, get, submit
GET	/agent/search?q=	Free-text catalogue search
GET	/agent/list	Paginated catalogue
GET	/agent/get?id=	One listing with routes and receipts
GET	/agent/routes?id=	Routes, examples and prices
GET	/agent/receipts	Recent receipts, or one listing with ?id=
GET	/receipts	Public verification receipts
GET	/bundles	Outcome-oriented API workflows
GET	/openapi.json	OpenAPI 3.1 discovery contract
GET	/llms.txt	Short map for LLMs
GET	/llms-full.txt	Full catalogue and bundle prompts
GET	/skill	Agent playbook for discovery and payment

4. First-party APIs

APIStead Labs is the first provider in the catalogue. Every listed first-party route is live under /api/v1 and returns an x402 challenge. The listing states the active network and price.

API	Route	Price
US ZIP Code API	/us-zip/{zip}	$0.001
IP Geolocation API	/ip/{ip}	$0.001
Geocoding & Reverse Geocoding API	/geocode?address={address}	$0.001
Coordinates & Distance API	/distance?from={lat},{lon}&to={lat},{lon}	$0.001
Email Verification API	/email/verify	$0.001
Sanctions & PEP Screening API	/sanctions/screen	$0.01
US Building Permits API	/permits?city={city}&query={query}	$0.01
Global Weather API	/weather/current?lat={lat}&lon={lon}	$0.001
Spotify API for AI Agents	/spotify/playlist	$0.02
Spotify API v2 for AI Agents	/spotify/search	$0.03

5. Read the 402

Call a provider endpoint without payment. The unpaid response tells you the price, network, token and wallet before anything moves.

unpaid request

curl -i "https://apistead.qd.je/api/v1/weather/current?lat=52.52&lon=13.405"

# HTTP/2 402
# payment-required: eyJ4NDAyVmVyc2lvbiI6IDIsIC...
# { "x402Version": 2, "accepts": [{ "scheme": "exact",
#   "network": "eip155:8453", "asset": "USDC",
#   "amount": "1000", "payTo": "0x..." }] }

6. Pay with an x402 client

The official client libraries handle the 402 → sign → retry loop. The example below is illustrative; check docs.x402.org for the current package names and version.

typescript

import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { wrapFetchWithPayment } from "@x402/fetch";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const client = new x402Client();

client.register("eip155:8453", new ExactEvmScheme(account));

const paidFetch = wrapFetchWithPayment(fetch, client);
const res = await paidFetch("https://apistead.qd.je/api/v1/weather/current?lat=52.52&lon=13.405");

console.log(await res.json());

python

from eth_account import Account
from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client

account = Account.from_key("0x...")
client = x402Client()
register_exact_evm_client(client, EthAccountSigner(account))

async with x402HttpxClient(client) as http:
    response = await http.get("https://apistead.qd.je/api/v1/weather/current?lat=52.52&lon=13.405")
    print(response.json())

7. Spend safety

x402 payments are final. Treat an agent wallet like a corporate card with a limit:

Use a dedicated wallet with a small USDC balance.
Set a per-call cap and a daily cap in your agent.
Allowlist providers and networks.
Log every 402 and every receipt.
Start with settlement-verified listings.
Handle settlement_pending by reconciling the tx hash, not by retrying blindly.

MCP tool surface

Tool	What it does
search_apis	Free-text search across the catalogue.
list_bundles	Outcome-oriented workflows with a route sequence and prompt.
list_apis	Browse by category, network and verification state.
get_api	Full listing: routes, prices, networks, receipts, reliability.
get_routes	Method, path, input schema, output schema, example.
get_receipt	On-chain verification receipt for a verified route.
check_reliability	Score, band, uptime and last check.
submit_listing	Submit a paid route for review. Free.

Payments and wallets

x402 pays USDC directly to the provider's payTo wallet on Base. APIStead never holds the funds. x402 with USDC on Base is the only payment rail; there is no card checkout or subscription billing.

Read the payments and wallets guide

Every listed first-party route is live and x402-gated. Verified routes link to a public settlement receipt. The 402 challenge on the provider route is the authoritative price quote.

Next: pick an API

Start with a ZIP code, sanctions or compliance call.

Browse the catalogue