# GEDX402 — External payer

**External payer** means you pay GEDX402 hero SKUs from **your own wallet** on Base — one USDC wire settlement per outcome. No API keys, no operator CDP buyer, no hosted MCP session. You POST a shard URL, get `402` + payment requirements, sign USDC on Base, retry with `payment-signature`, and receive JSON.

Use this path when you are building an agent, script, or product integration and want direct HTTP + x402 on the route that delivers the result. Each hero SKU below is **one payment → one outcome** — scrape a page, search the web, or call an upstream API wrapper.

**When to use external payer vs MCP**

| Path | Who pays | How you call | Best for |
| --- | --- | --- | --- |
| **External payer** (this doc) | Your wallet | `@x402/fetch`, `awal`, or any x402 v2 client on shard URLs | Customer agents, production integrations, wallet-in-your-app |
| **Hosted MCP** | Operator CDP buyer | `mcp.gedx402.com/mcp` + MCP tools | Internal ops only — see [MCP setup](https://gedx402.com/docs/mcp-setup) |

Primary client: **`@x402/fetch`** (TypeScript). Optional CLI: Coinbase Agentic Wallet (`awal`). Every SKU has a matching [hero page](https://gedx402.com/heroes) with the same snippets.

---

## Winner endpoints (default discovery)

Live prices from the manifest — do not trust static docs alone:

- [GET /.well-known/agents.json?bundle=winners](https://gedx402.com/.well-known/agents.json?bundle=winners)
- [GET /v1/models?bundle=winners](https://gedx402.com/v1/models?bundle=winners)

| Shape | Route | Wire (2026-06-21 manifest) |
| --- | --- | --- |
| OpenAI chat | `POST https://chat.gedx402.com/v1/chat/completions` | **$0.003** |
| Tavily search | `POST https://search.gedx402.com/v1/search` `{ "query": "…" }` | **$0.01** |
| Firecrawl scrape | `POST https://browser.gedx402.com/v1/firecrawl/scrape` `{ "url": "https://…" }` | **$0.01–$0.02** |
| Social profile | `POST https://social.gedx402.com/v1/social/outcome/profile` `{ "platform", "handle" }` | **$0.02** |
| Translate (customer revenue) | `POST https://embed.gedx402.com/v1/translate` | **$0.004** |
| Entry probe | `POST https://embed.gedx402.com/v1/embed/ping` `{ "text": "ping" }` | **$0.001** |

Quickstart with `@x402/fetch` snippets: [integrator quickstart](https://gedx402.com/docs/integrator-quickstart).

Competitive funnel (`?bundle=competitive`): embed ping → scrape → search → rag-answer (atom routes only — no orchestration recipes).

---

## Extended hero SKUs

| SKU | Route | USDC wire settlement | Hero |
| --- | --- | --- | --- |
| Entry probe | `POST https://embed.gedx402.com/v1/embed/ping` `{ "text": "ping" }` | **$0.0036** | [embed ping](https://gedx402.com/heroes/embed-ping) |
| Translate | `POST https://embed.gedx402.com/v1/translate` `{ "text": "…", "source_lang": "en", "target_lang": "es" }` | **$0.0125** | [translate](https://gedx402.com/heroes/translate) |
| Scrape Lite | `POST https://browser.gedx402.com/v1/firecrawl/scrape` `{ "url": "https://…" }` | **$0.02** | [scrape-lite](https://gedx402.com/heroes/scrape-lite) |
| Search | `POST https://search.gedx402.com/v1/search` `{ "query": "…" }` | **$0.01** | [search](https://gedx402.com/heroes/search) |
| Social profile | `POST https://social.gedx402.com/v1/social/outcome/profile` | **$0.02** | [social profile](https://gedx402.com/heroes/social-profile) |
| RAG answer | `POST https://rag.gedx402.com/v1/aisearch/outcome/answer` | **$0.625** | [rag answer](https://gedx402.com/heroes/rag-answer) |

### Browser outcomes (Firecrawl parity)

Same `@x402/fetch` pattern as scrape — one payment, one outcome.

| SKU | Route | USDC wire settlement | Hero |
| --- | --- | --- | --- |
| Page snapshot | `POST /v1/firecrawl/scrape` `{ "url", "formats": ["markdown","screenshot"] }` | **varies** | use scrape with formats |
| Site map | `POST /v1/firecrawl/map` `{ "url": "https://…" }` | **$0.12** | [site-map](https://gedx402.com/heroes/site-map) |
| Schema extract | `POST /v1/firecrawl/extract` `{ "urls", "prompt", "schema?" }` | **$0.10** | [schema-extract](https://gedx402.com/heroes/schema-extract) |

Graduated funnel walkthrough: [integrator quickstart](https://gedx402.com/docs/integrator-quickstart).

---

## 1. @x402/fetch (TypeScript)

Industry-standard x402 client — handles `402` → sign USDC on Base → retry with `payment-signature`.

```bash
npm install @x402/fetch @x402/core @x402/evm viem
```

Fund USDC on Base before each SKU. Set `PRIVATE_KEY` to a Base-funded EVM wallet.

**Entry probe** ($0.0036) — [hero](https://gedx402.com/heroes/embed-ping)

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

const signer = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(signer));
const fetchWithPayment = wrapFetchWithPayment(fetch, client);

const res = await fetchWithPayment("https://embed.gedx402.com/v1/embed/ping", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ text: "ping" }),
});
const data = await res.json();
```

**Translate** ($0.0125) — [hero](https://gedx402.com/heroes/translate)

```typescript
const res = await fetchWithPayment("https://embed.gedx402.com/v1/translate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ text: "Hello", source_lang: "en", target_lang: "es" }),
});
```

**Scrape Lite** ($0.02) — [hero](https://gedx402.com/heroes/scrape-lite)

```typescript
const res = await fetchWithPayment("https://browser.gedx402.com/v1/firecrawl/scrape", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com" }),
});
```

**Search** ($0.01) — [hero](https://gedx402.com/heroes/search)

```typescript
const res = await fetchWithPayment("https://search.gedx402.com/v1/search", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ query: "enterprise llm api pricing", max_results: 5 }),
});
```

**RAG answer** ($0.625) — [hero](https://gedx402.com/heroes/rag-answer)

```typescript
const res = await fetchWithPayment("https://rag.gedx402.com/v1/aisearch/outcome/answer", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://example.com/docs",
    question: "How do I configure AI Search?",
    budget: { max_queries: 5 },
  }),
});
```

---

## 2. awal (optional agent convenience)

Coinbase Agentic Wallet CLI — email login, no private key in your app. Same shard URLs as §1.

```bash
npx awal@2.12.0 auth login you@company.com
npx awal@2.12.0 auth verify <code>
npx awal@2.12.0 balance --chain base
```

**Entry probe** ($0.0036) — [hero](https://gedx402.com/heroes/embed-ping)

```bash
npx awal@2.12.0 x402 pay \
  --url https://embed.gedx402.com/v1/embed/ping \
  --method POST \
  --body '{"text":"ping"}'
```

**Translate** ($0.0125) — [hero](https://gedx402.com/heroes/translate)

```bash
npx awal@2.12.0 x402 pay \
  --url https://embed.gedx402.com/v1/translate \
  --method POST \
  --body '{"text":"Hello","source_lang":"en","target_lang":"es"}'
```

**Scrape Lite** ($0.02) — [hero](https://gedx402.com/heroes/scrape-lite)

```bash
npx awal@2.12.0 x402 pay \
  --url https://browser.gedx402.com/v1/firecrawl/scrape \
  --method POST \
  --body '{"url":"https://example.com"}'
```

**Search** ($0.01) — [hero](https://gedx402.com/heroes/search)

```bash
npx awal@2.12.0 x402 pay \
  --url https://search.gedx402.com/v1/search \
  --method POST \
  --body '{"query":"enterprise llm api pricing","max_results":5}'
```

**RAG answer** ($0.625) — [hero](https://gedx402.com/heroes/rag-answer)

```bash
npx awal@2.12.0 x402 pay \
  --url https://rag.gedx402.com/v1/aisearch/outcome/answer \
  --method POST \
  --body '{"url":"https://example.com/docs","question":"How do I configure AI Search?","budget":{"max_queries":5}}'
```

---

## 3. curl + discovery

Any HTTP client that follows x402 payment requirements works:

1. `POST` the route → receive `402` + `payment-required` header
2. Sign USDC transfer on Base to `payTo` in requirements
3. Retry with `payment-signature` header → `200` + JSON body

Unauthenticated `curl` below returns `402` so you can inspect pricing before paying. Use `@x402/fetch` or `awal` for automatic settlement.

**Entry probe** — [hero](https://gedx402.com/heroes/embed-ping)

```bash
curl -X POST https://embed.gedx402.com/v1/embed/ping \
  -H "Content-Type: application/json" \
  -d '{"text":"ping"}'
```

**Translate** — [hero](https://gedx402.com/heroes/translate)

```bash
curl -X POST https://embed.gedx402.com/v1/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello","source_lang":"en","target_lang":"es"}'
```

**Scrape Lite** — [hero](https://gedx402.com/heroes/scrape-lite)

```bash
curl -X POST https://browser.gedx402.com/v1/firecrawl/scrape \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'
```

**Search** — [hero](https://gedx402.com/heroes/search)

```bash
curl -X POST https://search.gedx402.com/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query":"enterprise llm api pricing","max_results":5}'
```

**RAG answer** — [hero](https://gedx402.com/heroes/rag-answer)

```bash
curl -X POST https://rag.gedx402.com/v1/aisearch/outcome/answer \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/docs","question":"How do I configure AI Search?","budget":{"max_queries":5}}'
```

On success, inspect `payment-response` (settlement receipt) and `X-GED-Cache` (`hit` when identical POST was cached ~300s; no second settle).

---

## Advanced — prepaid sessions, batch scrape

Not in the default customer funnel.

| SKU | Route | Settlement | Hero |
| --- | --- | --- | --- |
| Batch scrape | `POST https://browser.gedx402.com/v1/firecrawl/batch/scrape` `{ "urls": ["https://…"] }` | **$0.20** | [batch-scrape](https://gedx402.com/heroes/batch-scrape) |
| Voice session | `POST https://media.gedx402.com/v1/voice/sessions` | scales with `budget` (default caps ~$28) | [voice session](https://gedx402.com/heroes/voice-session) |
| Memory session | `POST https://db.gedx402.com/v1/memory/sessions` | ~$0.69 at default budget | [memory session](https://gedx402.com/heroes/memory-session) |
| Managed RAG session | `POST https://rag.gedx402.com/v1/aisearch/sessions` | ~$0.62 at default budget | [rag session](https://gedx402.com/heroes/rag-session) |

Bundle docs: [voice](https://gedx402.com/docs/voice-bundle) · [memory](https://gedx402.com/docs/D1-SHARD) · [managed RAG](https://gedx402.com/docs/MANAGED-RAG-BUNDLE).

---

## vs MCP (operator)

External payer (this doc) uses **your** wallet on shard origins — `@x402/fetch` primary, `awal` optional. Hosted MCP at `mcp.gedx402.com/mcp` is **operator-only** (CDP buyer pays; not a customer integration path). See [MCP setup](https://gedx402.com/docs/mcp-setup).