# Integrator quickstart

> **Live prices:** unpaid `402` `payment-required`, or `GET /v1/models?bundle=<name>` → `price_usd` (bodyless) and `worst_case_price_usd` (ceiling).

Pay GEDX402 from **your** wallet on Base. No MCP, no API keys.

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

**Agentic Wallet (no private key):** [AGENTIC-WALLET.md](./AGENTIC-WALLET.md) — `npx awal@2.12.0 x402 pay <endpoint>` with the same JSON bodies below. Heroes already ship awal + `@x402/fetch` examples on `GET /heroes/*`.

Discovery: [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)

The `402` response quotes the price of **the request you sent**. Token, image and unified routes are priced from the body (model, input size, `max_tokens`, image size and steps). Requests over a route's input limit, or clearly invalid JSON / missing required fields (non-empty body), get a 400 before payment. Empty body and `{}` still return the full unpaid 402 for discovery. `worst_case_price_usd` per route is the most an accepted request can cost; fund to that.

**If a paid call fails after verify:** handler or upstream 4xx/5xx cancels settlement — you are not charged for that failed call. There is no separate refund path beyond that cancel.

## Job bundles — copy-paste discovery

Task-shaped `?bundle=` filters (client-side orchestration, separate x402 per step):

| Job | Discovery | Steps |
| --- | --- | --- |
| Market research | [agents.json?bundle=market-research](https://gedx402.com/.well-known/agents.json?bundle=market-research) | embed ping → Tavily → Exa → scrape → RAG answer |
| Lead intel | [agents.json?bundle=lead-intel](https://gedx402.com/.well-known/agents.json?bundle=lead-intel) | Exa search → Exa contents → TikTok profile |
| Content extraction | [agents.json?bundle=content-extraction](https://gedx402.com/.well-known/agents.json?bundle=content-extraction) | Firecrawl scrape or Exa contents → optional translate |

Docs: [MARKET-RESEARCH-BUNDLE.md](./MARKET-RESEARCH-BUNDLE.md) · [LEAD-INTEL-BUNDLE.md](./LEAD-INTEL-BUNDLE.md) · [CONTENT-EXTRACTION-BUNDLE.md](./CONTENT-EXTRACTION-BUNDLE.md)

## Winner SKUs — copy-paste `@x402/fetch`

Four recommended routes. Use the install block above, then paste any example below (`PRIVATE_KEY` = Base-funded EVM wallet).

```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);
```

### Chat completions — `{ messages, max_tokens? }`

```typescript
const res = await fetchWithPayment("https://chat.gedx402.com/v1/chat/completions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    messages: [{ role: "user", content: "Hello" }],
    max_tokens: 128,
  }),
});
const data = await res.json();
```

### Search (Tavily) — `{ query, max_results? }`

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

### Exa neural search — `{ query, num_results?, type? }`

```typescript
const res = await fetchWithPayment("https://search.gedx402.com/v1/exa/search", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ query: "x402 agent marketplace APIs", num_results: 5, type: "auto" }),
});
const data = await res.json();
```

### Exa contents — `{ urls[], max_characters? }`

```typescript
const res = await fetchWithPayment("https://search.gedx402.com/v1/exa/contents", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ urls: ["https://example.com/docs"], max_characters: 3000 }),
});
const data = await res.json();
```

### Scrape (Firecrawl) — `{ url }`

```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" }),
});
const data = await res.json();
```

`linkedin.com` (any subdomain), `lnkd.in`, `x.com`, and `twitter.com` URLs are refused before payment (`400` `over_route_bound`, not quoted). Host rules and Firecrawl search targeting: [browser bundle](./BROWSER-BUNDLE.md).

### Translate — `{ text, source_lang, target_lang }`

```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" }),
});
const data = await res.json();
```

## Winner endpoints

**Live wire prices:** [GET /v1/models] [GET /v1/models?bundle=winners](https://gedx402.com/v1/models?bundle=winners) (`price_usd`, `worst_case_price_usd` per tool).

| API | URL |
| --- | --- |
| OpenAI chat | `POST https://chat.gedx402.com/v1/chat/completions` |
| Tavily search | `POST https://search.gedx402.com/v1/search` |
| Exa search | `POST https://search.gedx402.com/v1/exa/search` |
| Exa contents | `POST https://search.gedx402.com/v1/exa/contents` |
| Firecrawl scrape | `POST https://browser.gedx402.com/v1/firecrawl/scrape` |
| Social profile | `POST https://social.gedx402.com/v1/social/outcome/profile` |
| Translate | `POST https://embed.gedx402.com/v1/translate` |

Prefer manifest `example_request` over static docs. SociaVault catalog: `/v1/sociavault/*` — [SOCIAL-SHARD.md](./SOCIAL-SHARD.md). Search bundle: [SEARCH-BUNDLE.md](./SEARCH-BUNDLE.md).

## Social profile (SociaVault)

**Preferred route:** `POST /v1/social/outcome/profile` with `{ "platform": "tiktok", "handle": "…" }` (Bazaar-indexed).

```typescript
const res = await fetchWithPayment("https://social.gedx402.com/v1/social/outcome/profile", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ platform: "tiktok", handle: "example" }),
});
```

**Catalog route** (same upstream, same wire — see GET /v1/models):

```typescript
const res = await fetchWithPayment("https://social.gedx402.com/v1/sociavault/tiktok/profile", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ handle: "example" }),
});
```

**Legacy convenience route:**

```typescript
const res = await fetchWithPayment("https://social.gedx402.com/v1/social/outcome/profile", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ platform: "tiktok", handle: "example" }),
});
```

Full catalog: [GET /v1/models?full=1](https://gedx402.com/v1/models?full=1)

## Frontier models (gateway shard)

OpenAI/Anthropic/Google chat and third-party text-to-image via unified billing — **per-model** x402 wire (not ~$1.85 max-across-allowlist). No operator BYOK keys.

Discovery: [GET /.well-known/agents.json?shard=gateway&bundle=frontier](https://gedx402.com/.well-known/agents.json?shard=gateway&bundle=frontier)

| API | URL | Wire |
| --- | --- | --- |
| OpenAI chat (frontier) | `POST https://gateway.gedx402.com/v1/chat/completions` | per model — manifest |
| Unified run | `POST https://gateway.gedx402.com/v1/unified/run` | per `model` in body |
| Unified image | `POST https://gateway.gedx402.com/v1/unified/image` | per `model` (flat Per image) |
| Unified image-edit | `POST https://gateway.gedx402.com/v1/unified/image-edit` | per `model` (flat Per image) |
| Unified TTS | `POST https://gateway.gedx402.com/v1/unified/tts` | per `model` × characters |

```typescript
const res = await fetchWithPayment("https://gateway.gedx402.com/v1/chat/completions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "openai/gpt-4o-mini",
    messages: [{ role: "user", content: "Hello" }],
    max_tokens: 128,
  }),
});
```

```typescript
const img = await fetchWithPayment("https://gateway.gedx402.com/v1/unified/image", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "pruna/p-image",
    prompt: "A small furry elephant pet looks out from a cat house",
    aspect_ratio: "1:1",
  }),
});
```

```typescript
const edited = await fetchWithPayment("https://gateway.gedx402.com/v1/unified/image-edit", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "pruna/p-image-edit",
    prompt: "Transform the subject into a watercolor painting style with vibrant colors",
    images: ["https://example.com/subject.jpg"],
    aspect_ratio: "1:1",
  }),
});
```

```typescript
const speech = await fetchWithPayment("https://gateway.gedx402.com/v1/unified/tts", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "openai/tts-1",
    text: "Hello! Welcome to GEDX402 unified text-to-speech.",
    voice: "alloy",
    response_format: "mp3",
  }),
});
```

Gateway catalog: `GET https://gateway.gedx402.com/openapi.json`. Workers AI image gen stays on `image.gedx402.com` (`/v1/image/*`); Workers AI TTS and Moondream vision stay on `media.gedx402.com` (`/v1/tts/*`, `POST /v1/vision/moondream`).

## Moondream vision (media shard)

Task-based Workers AI vision (`@cf/moondream/moondream3.1-9B-A2B`) — query / caption / point / detect. x402 priced from the input token bound and `max_tokens` (default 768, cap 2048).

| API | URL | Wire |
| --- | --- | --- |
| Moondream | `POST https://media.gedx402.com/v1/vision/moondream` | per request (tokens) |

```typescript
const vision = await fetchWithPayment("https://media.gedx402.com/v1/vision/moondream", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    task: "query",
    image: "https://example.com/scene.png",
    question: "How many vehicles are on the road?",
    max_tokens: 256,
  }),
});
```