Agentic payments (x402)

┌──────────────┐                            ┌────────────────────────┐
│   AI agent   │ ── POST /v1/fetch ───────▶ │  request.usestring.ai  │
│  (wallet     │                            │                        │
│  with USDC)  │ ◀── 402 + price ────────── │                        │
│              │                            │                        │
│              │ ── POST /v1/fetch ───────▶ │                        │
│              │    + signed payment        │                        │
│              │                            │                        │
│              │ ◀── 200 + response ─────── │                        │
│              │     + receipt              │                        │
└──────────────┘                            └────────────────────────┘

# Install purl
brew install stripe/purl/purl

# Create or import a wallet
purl wallet add

# Show the price without paying
purl --dry-run --json '{"url":"https://example.com","format":"markdown"}' https://request.usestring.ai/v1/fetch

# Pay and fetch
purl --json '{"url":"https://example.com","format":"markdown"}' https://request.usestring.ai/v1/fetch

npm install @x402/fetch @x402/evm viem

import { decodePaymentResponseHeader, wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { UptoEvmScheme } from "@x402/evm/upto/client";
import { privateKeyToAccount } from "viem/accounts";

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

const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [
    {
      network: "eip155:8453",
      client: new UptoEvmScheme(account, { rpcUrl: "https://mainnet.base.org" })
    }
  ]
});

const response = await fetchWithPayment("https://request.usestring.ai/v1/fetch", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com", format: "markdown" })
});

console.log(await response.text());

const receipt = response.headers.get("PAYMENT-RESPONSE");
if (receipt) console.log(decodePaymentResponseHeader(receipt));

---
name: string-x402
description: Fetch web pages through String Web Access and pay for each request with x402 (USDC on Base) using purl. Use when asked to read, fetch, or scrape a URL, especially a site that blocks bots.
---

# String Web Access over x402

String fetches any URL, including sites behind bot protection or JavaScript rendering, and
returns it as Markdown or JSON. Each request is paid with x402 through `purl`, so no API key is
needed.

## Endpoint

`POST https://request.usestring.ai/v1/fetch`, $0.006 per request through `purl`.

Body: `{"url": "https://example.com", "format": "markdown"}`

- `format`: `markdown` is best for reading; `json` (the default) and `raw` are also available.
- `mainContentOnly: true` strips navigation, headers, and footers from Markdown.
- `executeJS: true` renders the page in a browser first.
- `jsonSchema`, `actions`, and `screenshot` need an API key. Don't send them.

All parameters: https://portal.usestring.ai/docs/api-reference/fetch

## Calling it

```bash
purl --json '{"url":"https://example.com","format":"markdown"}' https://request.usestring.ai/v1/fetch
```

- Add `--dry-run` to see the price without paying.
- Add `--max-amount 6000` to refuse anything above $0.006. USDC has six decimals.
- A `402` after paying means the payment failed. Check the wallet with `purl balance`.
- A `403` means the site needs an approved String account. Tell the user rather than retrying.
- Failed requests, with a status of 400 or above, are not charged.

## Cost and etiquette

Every successful fetch is paid. Fetch the page you need rather than crawling around it, and don't
re-fetch a URL you already have in context.