# Integrator quickstart

> **Wires:** `npm run pricing:report` or `GET /v1/models?bundle=<name>` → `worst_case_price_usd`.

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 **`wire_worst_usd`** from the live catalog (`worst_case_price_usd` per route). Fund to that worst-case amount; settlement may be lower.

## 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 AM-winning routes integrators call most often. 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();
```

### 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:** `npm run pricing:report` · [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 `npm run pricing:report`):

```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 via unified billing — **per-model** x402 wire (not ~$1.85 max-across-allowlist).

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 |

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

See [GATEWAY-SHARD.md](./GATEWAY-SHARD.md).