AgentScout

Open-source clients for AgentScout — an agent-native web read/extract/crawl service paid per fetch over x402. Give it a URL and get back clean markdown (read), structured JSON validated against your schema (extract), a free price probe (quote), or a whole-site crawl — every paid fetch settling in USDC on Base, with no signup and no API keys.

There are two ways to pay, auto-detected by the client:

• Wallet-as-payer (the default): a signable EVM wallet pays each fetch inline via x402. AgentScout mints and manages a local wallet on first use, so an agent "just works" once that wallet is funded.
• Account-key (for managed wallets that can't sign — e.g. awal): an opaque ak_… bearer token identifies the account and debits prepaid credits. Credits are funded out-of-band via AgentKV, so any signing wallet can fund the account and fetches carry only the bearer.

Scout content is not encrypted — it is public web data by definition (unlike AgentKV, which encrypts values client-side). A scout response is plaintext; do not treat it as private.

This repository holds the client surface — the SDK, CLI, MCP server, and Claude plugin. The AgentScout service (the backend) is operated separately; these clients talk to it over the public x402 + EIP-712 protocol.

Packages

Path	Package	What
client/	@agentscout/client	TypeScript SDK — sign + pay + fetch
cli/	@agentscout/cli	the agentscout command-line, and agentscout mcp (MCP server)
plugin/	—	Claude Code plugin (wraps the MCP server)

npm scopes

Two npm scopes separate the platform from the service:

• @agentx402-ai/* — the platform scope: @agentx402-ai/core, a shared SDK for auth, payment, usage tracking, error handling, and retry logic, consumed by every agentx402 service. It lives in its own repo (agentx402-ai/core) and is a published dependency of the packages here.
• @agentscout/* — the scout service scope: @agentscout/client and @agentscout/cli (this repo), which depend on @agentx402-ai/core for shared plumbing.

Keeping @agentx402-ai/core in its own repo lets sibling services (e.g. @agentkv/client) share it without depending on the AgentScout repo.

Quick start (SDK)

npm install @agentscout/client

import { AgentScout } from "@agentscout/client";
import { privateKeyToAccount } from "viem/accounts";

const scout = new AgentScout({
  signer: privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`),
  endpoint: "https://api.agentx402.ai",
  maxSpendUsd: 0.05, // optional: refuse any single fetch over $0.05
});

// quote → FREE price probe (never signs, never spends)
const price = await scout.quote("https://example.com");

// read → clean markdown (paid per fetch in USDC via x402)
const { markdown, title } = await scout.read("https://example.com");

// extract → JSON validated against a JSON Schema you supply
const { data } = await scout.extract("https://example.com", {
  type: "object",
  properties: { headline: { type: "string" } },
});

// crawl → walk a site up to max_pages, get a results manifest
const result = await scout.crawl("https://example.com", { maxPages: 10 });

CLI

npm install -g @agentscout/cli
export AGENTSCOUT_PRIVATE_KEY=0x...           # endpoint defaults to https://api.agentx402.ai
agentscout quote https://example.com          # free price probe
agentscout read https://example.com           # → clean markdown (paid per fetch)
agentscout extract https://example.com --schema ./schema.json
agentscout crawl https://example.com --max-pages 10

No wallet? Leave AGENTSCOUT_PRIVATE_KEY unset and AgentScout mints and manages a local wallet on first use (a 0600 keystore under ~/.agentscout), printing its address — fund that address with USDC on Base, then retry. Cap spend any time with AGENTSCOUT_MAX_SPEND_USD (per fetch) and AGENTSCOUT_MAX_SESSION_SPEND_USD (cumulative); a malformed value fails closed.

Account-key mode (works with awal / any managed wallet)

For a managed wallet that can't sign (e.g. awal), use an account key funded out-of-band via AgentKV; every fetch then carries only the bearer and debits the account's prepaid credits:

export AGENTSCOUT_ACCOUNT_KEY=ak_...          # a bearer minted + funded via AgentKV
agentscout read https://example.com           # debits the account's prepaid credits

The client auto-selects account-key mode when AGENTSCOUT_ACCOUNT_KEY is set (or a stored account key exists and no AGENTSCOUT_PRIVATE_KEY is set); otherwise it uses the wallet. Publisher tolls (--max-toll-usd) are wallet-mode only — an ak_ caller cannot front a real-USDC toll, so setting one in account-key mode fails fast (tolls_require_x402) before any request is issued.

MCP server / Claude plugin

agentscout mcp exposes the service as MCP tools — scout_read, scout_extract, and scout_crawl (the three paid fetch verbs), plus the free scout_quote (price a fetch before spending) and scout_crawl_status (resume a long crawl by jobId) — for Claude Desktop / Code / Cursor. The paid verbs are annotated as state-changing (never readOnlyHint) so a client knows to prompt a human before spending.

The plugin/ directory packages this as an installable Claude Code plugin. In Claude Code:

/plugin marketplace add agentx402-ai/claude-plugins
/plugin install agentscout@agentx402

Claude Code then prompts for your wallet private key (stored in your OS keychain) and the optional AgentScout endpoint (defaults to the hosted service), and auto-starts the MCP server — verify with /mcp. Full steps: plugin/README.md.

How it works

• Pay per fetch over x402. Each paid verb (read, extract, crawl) is priced by the server's 402 challenge and settled in USDC on Base via x402 (EIP-3009 transferWithAuthorization). The SDK signs the challenge's exact quoted amount — never a self-computed sum — pinning the network, the canonical USDC token, and (when you set expectedPayTo) the recipient before signing. quote is free: it prices a URL without ever signing or spending.
• Wallet-as-payer, or account-key credits. In wallet mode a signable wallet pays each fetch inline and is itself the identity. In account-key mode an opaque ak_… bearer is the identity and fetches debit prepaid credits funded out-of-band via AgentKV — so any signing wallet can fund the account, decoupled from the fetches.
• Publisher tolls. Some publishers charge a per-fetch toll on top of the base price; the SDK pays it only up to your maxTollUsd ceiling, and only in wallet mode (an ak_ caller cannot front a real-USDC toll, so tolls are refused client-side in account-key mode).
• Client-side spend caps. maxSpendUsd (per call) and maxSessionSpendUsd (cumulative) refuse — never silently cap — any op that would exceed them, checked before the challenge is signed.
• No encryption. Scout returns public web content in the clear; there is no encryption key and nothing zero-knowledge about a response (unlike AgentKV).

License

MIT