# x402tools.xyz — Complete API Reference
# Last updated: 2025-11-27

> Pay-per-call utility APIs for AI agents. USDC micropayments on Base via x402 protocol.
> No API keys. No subscriptions. No signup. Payment is the authentication.

---

## PROTOCOL OVERVIEW

All endpoints use the x402 protocol:
1. Send a standard HTTP request to the endpoint
2. Receive HTTP 402 Payment Required with payment details in headers
3. Re-send request with X-Payment header containing USDC payment proof
4. Receive the API response

Payment details:
- Token: USDC
- Network: Base mainnet (eip155:8453)
- Facilitator: https://x402.org/facilitator

Libraries that handle payment automatically:
- @x402/fetch (Node.js) — https://www.npmjs.com/package/@x402/fetch
- AgentCash — https://agentcash.dev

---

## SERVICE 1: QR CODE GENERATOR

Endpoint: POST https://qr.x402tools.xyz/v1/generate
Price: $0.01 per call
Content-Type: application/json
Response: image/png | image/svg+xml | application/json (base64)

### Request Body

| Parameter | Type   | Required | Default | Description                    |
|-----------|--------|----------|---------|--------------------------------|
| text      | string | YES      | —       | Content to encode in QR code   |
| size      | number | no       | 256     | Image width/height in pixels   |
| format    | string | no       | "png"   | Output format: png, svg, base64|

### Example Request

```
POST https://qr.x402tools.xyz/v1/generate
Content-Type: application/json

{
  "text": "https://x402tools.xyz",
  "size": 512,
  "format": "png"
}
```

### Response

- format=png: Binary PNG image (Content-Type: image/png)
- format=svg: SVG markup (Content-Type: image/svg+xml)
- format=base64: JSON with base64-encoded image

```json
{
  "data": "iVBORw0KGgo...",
  "format": "base64",
  "size": 512
}
```

### Errors

| Code | Error          | Description                          |
|------|----------------|--------------------------------------|
| 400  | MISSING_TEXT   | "text" parameter is required         |
| 400  | INVALID_FORMAT | format must be png, svg, or base64   |
| 402  | PAYMENT_REQUIRED | x402 payment not provided          |

---

## SERVICE 1B: STYLED QR CODE GENERATOR

Endpoint: POST https://qr.x402tools.xyz/v1/generate/styled
Price: $0.05 per call
Content-Type: application/json
Response: image/png | image/svg+xml | application/json (base64)

Generate artistic QR codes with custom dot shapes (circles, diamonds, rounded squares, stars), color gradients, and finder pattern styling.

### Request Body

| Parameter       | Type   | Required | Default   | Description                                    |
|-----------------|--------|----------|-----------|------------------------------------------------|
| text            | string | YES      | —         | Content to encode in QR code                   |
| size            | number | no       | 512       | Image width/height in pixels                   |
| format          | string | no       | "png"     | Output format: png, svg, base64                |
| dotType         | string | no       | "rounded" | Shape: rounded, dots, diamond, star, square    |
| dotColor        | string | no       | "#000000" | Hex color for dots (ignored if gradient set)   |
| backgroundColor | string | no       | "#ffffff" | Hex background color                           |
| cornerColor     | string | no       | —         | Hex color for finder pattern corners           |
| gradient        | object | no       | —         | Gradient for dot colors                        |
| gradient.type   | string | no       | "linear"  | "linear" or "radial"                           |
| gradient.from   | string | no       | —         | Start hex color                                |
| gradient.to     | string | no       | —         | End hex color                                  |

### Example Request

```
POST https://qr.x402tools.xyz/v1/generate/styled
Content-Type: application/json

{
  "text": "https://x402tools.xyz",
  "size": 512,
  "dotType": "rounded",
  "gradient": { "from": "#6366f1", "to": "#ec4899" },
  "backgroundColor": "#1e1b4b",
  "cornerColor": "#f59e0b"
}
```

### Response

Same as standard QR: binary PNG, SVG markup, or JSON with base64 data depending on format.

### Errors

| Code | Error          | Description                          |
|------|----------------|--------------------------------------|
| 400  | MISSING_TEXT   | "text" parameter is required         |
| 400  | INVALID_FORMAT | format must be png, svg, or base64   |
| 402  | PAYMENT_REQUIRED | x402 payment not provided          |

---

## SERVICE 2: SCREENSHOT CAPTURE

Endpoint: POST https://snap.x402tools.xyz/v1/capture
Price: $0.05 per call
Content-Type: application/json
Response: image/png | image/jpeg

### Request Body

| Parameter | Type    | Required | Default | Description                        |
|-----------|---------|----------|---------|------------------------------------|
| url       | string  | YES      | —       | URL to screenshot                  |
| width     | number  | no       | 1280    | Viewport width in pixels           |
| height    | number  | no       | 720     | Viewport height in pixels          |
| fullPage  | boolean | no       | false   | Capture full scrollable page       |
| format    | string  | no       | "png"   | Output format: png, jpeg           |
| darkMode  | boolean | no       | false   | Emulate prefers-color-scheme: dark |
| delay     | number  | no       | 0       | Wait ms after page load before capture |
| selector  | string  | no       | —       | CSS selector to capture specific element |

### Example Request

```
POST https://snap.x402tools.xyz/v1/capture
Content-Type: application/json

{
  "url": "https://example.com",
  "width": 1280,
  "height": 720,
  "fullPage": true,
  "darkMode": true,
  "format": "png"
}
```

### Response

Binary image data with appropriate Content-Type header.

### Errors

| Code | Error            | Description                          |
|------|------------------|--------------------------------------|
| 400  | MISSING_URL      | "url" parameter is required          |
| 400  | INVALID_URL      | URL must be a valid HTTP(S) URL      |
| 402  | PAYMENT_REQUIRED | x402 payment not provided            |
| 504  | TIMEOUT          | Page took too long to load           |

---

## SERVICE 3: DNS LOOKUP

Endpoint: GET https://dns.x402tools.xyz/v1/lookup
Price: $0.02 per call
Response: application/json

### Query Parameters

| Parameter | Type   | Required | Default | Description              |
|-----------|--------|----------|---------|--------------------------|
| domain    | string | YES      | —       | Domain name to look up   |

### Example Request

```
GET https://dns.x402tools.xyz/v1/lookup?domain=example.com
```

### Response

```json
{
  "domain": "example.com",
  "records": {
    "A": ["93.184.216.34"],
    "AAAA": ["2606:2800:220:1:248:1893:25c8:1946"],
    "MX": [{"priority": 10, "exchange": "mail.example.com"}],
    "NS": ["a.iana-servers.net", "b.iana-servers.net"],
    "TXT": ["v=spf1 -all"],
    "SOA": {
      "nsname": "a.iana-servers.net",
      "hostmaster": "noc.dns.icann.org",
      "serial": 2024012345,
      "refresh": 7200,
      "retry": 3600,
      "expire": 1209600,
      "minttl": 3600
    }
  },
  "query_time_ms": 45
}
```

### Errors

| Code | Error            | Description                          |
|------|------------------|--------------------------------------|
| 400  | MISSING_DOMAIN   | "domain" parameter is required       |
| 400  | INVALID_DOMAIN   | Domain format is invalid             |
| 402  | PAYMENT_REQUIRED | x402 payment not provided            |
| 404  | NXDOMAIN         | Domain does not exist                |

---

## SERVICE 4: DOCPARSE (HTML/PDF → Structured JSON)

Endpoint: POST https://docparse.x402tools.xyz/parse
Price: $0.01 per call
Content-Type: application/json
Response: application/json

### Request Body

| Parameter              | Type   | Required | Default | Description                              |
|------------------------|--------|----------|---------|------------------------------------------|
| url                    | string | YES      | —       | Public URL of HTML page or PDF           |
| options.output_schema  | string | no       | "auto"  | auto, article, invoice, research, generic|
| options.include_raw_text | boolean | no    | false   | Include raw extracted text in response   |
| options.max_sections   | number | no       | 20      | Max sections to extract (1-100)          |
| options.language       | string | no       | —       | Preferred output language (e.g. "en")    |

### Example Request

```
POST https://docparse.x402tools.xyz/parse
Content-Type: application/json

{
  "url": "https://arxiv.org/abs/2301.00001",
  "options": {
    "output_schema": "research"
  }
}
```

### Response (varies by doc_type)

The response shape depends on the detected or requested document type.

#### Article Response
```json
{
  "doc_type": "article",
  "title": "Example Article Title",
  "metadata": {
    "source_url": "https://example.com/article",
    "detected_content_type": "html",
    "author": "John Doe",
    "published_date": "2025-01-15",
    "language": "en",
    "word_count": 1542,
    "truncated": false,
    "parse_duration_ms": 2340
  },
  "content": {
    "summary": "Brief summary of the article...",
    "sections": [
      { "heading": "Introduction", "body": "..." },
      { "heading": "Main Point", "body": "..." }
    ],
    "key_points": ["Point 1", "Point 2"],
    "topics": ["technology", "AI"]
  }
}
```

#### Invoice Response
```json
{
  "doc_type": "invoice",
  "title": "Invoice #12345",
  "metadata": { ... },
  "content": {
    "vendor": { "name": "Acme Corp", "address": "123 Main St" },
    "client": { "name": "Client Inc" },
    "invoice_number": "INV-12345",
    "issue_date": "2025-01-15",
    "due_date": "2025-02-15",
    "line_items": [
      { "description": "Service A", "quantity": 1, "unit_price": 100, "total": 100, "currency": "USD" }
    ],
    "total_due": 100,
    "currency": "USD"
  }
}
```

#### Research Response
```json
{
  "doc_type": "research",
  "title": "Research Paper Title",
  "metadata": { ... },
  "content": {
    "abstract": "Paper abstract...",
    "authors": ["Author A", "Author B"],
    "institution": "University",
    "published": "2025-01",
    "methodology": "Description of methods...",
    "findings": ["Finding 1", "Finding 2"],
    "limitations": ["Limitation 1"],
    "doi": "10.1234/example"
  }
}
```

#### Generic Response
```json
{
  "doc_type": "generic",
  "title": "Document Title",
  "metadata": { ... },
  "content": {
    "sections": [
      { "heading": "Section 1", "content": "..." }
    ],
    "key_entities": [
      { "type": "person", "value": "John Doe" },
      { "type": "org", "value": "Acme Corp" },
      { "type": "date", "value": "2025-01-15" }
    ]
  }
}
```

### Errors

| Code | Error              | Description                          |
|------|--------------------|--------------------------------------|
| 400  | MISSING_URL        | "url" parameter is required          |
| 400  | INVALID_URL        | URL must be a valid HTTP(S) URL      |
| 400  | UNSUPPORTED_TYPE   | Content type not supported           |
| 402  | PAYMENT_REQUIRED   | x402 payment not provided            |
| 504  | FETCH_TIMEOUT      | URL took too long to respond         |
| 422  | EXTRACTION_FAILED  | Could not extract content from URL   |

---

## HEALTH ENDPOINTS

All services expose a free (no payment) health endpoint:

- GET https://qr.x402tools.xyz/health
- GET https://snap.x402tools.xyz/health
- GET https://dns.x402tools.xyz/health
- GET https://docparse.x402tools.xyz/health
- GET https://guard.x402tools.xyz/health
- GET https://mailcheck.x402tools.xyz/health
- GET https://rendex.x402tools.xyz/health
- GET https://visionex.x402tools.xyz/health

Response: `{ "status": "ok", "service": "<name>", "version": "1.0.0" }`

---

## AGENT INTEGRATION

### Discovery
- Service catalog (JSON): https://x402tools.xyz/agents.json
- Well-known discovery: https://x402tools.xyz/.well-known/x402-services.json

### Using with @x402/fetch

```javascript
import { fetchWithPayment } from "@x402/fetch";

const response = await fetchWithPayment("https://qr.x402tools.xyz/v1/generate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ text: "hello", format: "base64" }),
  walletPrivateKey: process.env.WALLET_KEY,
});

const data = await response.json();
```

### Using with AgentCash

Tell your agent:
> Use AgentCash to fetch https://dns.x402tools.xyz/v1/lookup?domain=example.com

AgentCash handles the full 402 payment flow automatically.

---

## PRICING SUMMARY

| Service              | Price/call | Method | Endpoint                                        |
|----------------------|------------|--------|-------------------------------------------------|
| QR Code Generator    | $0.01      | POST   | https://qr.x402tools.xyz/v1/generate            |
| Styled QR Generator  | $0.05      | POST   | https://qr.x402tools.xyz/v1/generate/styled     |
| Screenshot Capture   | $0.05      | POST   | https://snap.x402tools.xyz/v1/capture           |
| DNS Lookup           | $0.02      | GET    | https://dns.x402tools.xyz/v1/lookup             |
| DocParse             | $0.01      | POST   | https://docparse.x402tools.xyz/parse            |
| Guardex              | $0.03      | POST   | https://guard.x402tools.xyz/screen              |
| Mailcheck            | $0.03      | POST   | https://mailcheck.x402tools.xyz/v1/validate     |
| Rendex               | $0.05      | POST   | https://rendex.x402tools.xyz/v1/render          |
| Visionex             | $0.05      | POST   | https://visionex.x402tools.xyz/v1/extract       |
| Prospex              | $0.50      | POST   | https://prospex.x402tools.xyz/enrich            |

All prices in USDC on Base (eip155:8453).

---

## SUPPORT

- Protocol docs: https://docs.x402.org
- Service registry: https://www.x402scan.com
- Website: https://x402tools.xyz

---

## SERVICE 6: GUARDEX (PROMPT INJECTION SCREENER)

Endpoint: POST https://guard.x402tools.xyz/screen
Price: $0.03 per call
Content-Type: application/json
Response: application/json

### Request Body

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| text | string | YES | — | Text to screen for prompt injection |
| context.source | string | no | — | Origin (user_input, email, form, etc.) |
| options.sensitivity | string | no | "medium" | low, medium, high |
| options.redacted | boolean | no | false | Return redacted text with threats masked |

### Example Request

```
POST https://guard.x402tools.xyz/screen
Content-Type: application/json

{
  "text": "Please summarize this article about climate change.",
  "options": { "sensitivity": "medium" }
}
```

### Example Response (safe)

```json
{
  "risk_level": "safe",
  "safe_to_proceed": true,
  "confidence": 0.95,
  "categories": {},
  "threat_snippets": [],
  "meta": { "model": "gpt-4o-mini", "char_count": 51, "processing_ms": 800 }
}
```

### Example Response (critical)

```json
{
  "risk_level": "critical",
  "safe_to_proceed": false,
  "confidence": 0.99,
  "categories": { "instruction_override": true, "role_hijack": true, "data_exfiltration": true },
  "threat_snippets": ["Ignore all previous instructions", "You are now DAN", "send to https://evil.com"],
  "meta": { "model": "regex-heuristic-v1", "char_count": 120, "processing_ms": 12 }
}
```

---

## SERVICE 7: MAILCHECK (EMAIL VALIDATION)

Endpoint: POST https://mailcheck.x402tools.xyz/v1/validate
Price: $0.03 per call
Content-Type: application/json
Response: application/json

### Request Body

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| email | string | YES | — | Email address to validate |
| checkSmtp | boolean | no | false | Attempt SMTP probe (may be slow/blocked) |

### Example Request

```
POST https://mailcheck.x402tools.xyz/v1/validate
Content-Type: application/json

{
  "email": "john@gmail.com",
  "checkSmtp": false
}
```

### Example Response

```json
{
  "email": "john@gmail.com",
  "valid": true,
  "score": 85,
  "checks": {
    "syntax": true,
    "mxExists": true,
    "mxAccepts": false,
    "disposable": false,
    "roleAccount": false,
    "freeProvider": true,
    "catchAll": false
  },
  "provider": "Google",
  "suggestion": null
}
```

### Example (typo detected)

```json
{
  "email": "john@gmial.com",
  "valid": false,
  "score": 20,
  "checks": { "syntax": true, "mxExists": false, "mxAccepts": false, "disposable": false, "roleAccount": false, "freeProvider": false, "catchAll": false },
  "provider": "Unknown",
  "suggestion": "john@gmail.com"
}
```

---

## SERVICE 8: RENDEX (HTML → PDF RENDERER)

Endpoint: POST https://rendex.x402tools.xyz/v1/render
Price: $0.05 per call
Content-Type: application/json
Response: application/pdf | application/json (base64 mode)

### Request Body

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| html | string | YES* | — | Raw HTML to render (max 2MB) |
| url | string | YES* | — | Public URL to render (*one of html/url) |
| options.format | string | no | "A4" | A4, Letter, Legal |
| options.landscape | boolean | no | false | Landscape orientation |
| options.printBackground | boolean | no | true | Include background colors/images |
| options.scale | number | no | 1 | Scale factor (0.1–2) |
| options.margin | object | no | — | { top, bottom, left, right } CSS units |
| options.headerTemplate | string | no | — | HTML header template |
| options.footerTemplate | string | no | — | HTML footer template |
| output | string | no | "binary" | binary (PDF stream) or base64 (JSON) |

### Example Request

```
POST https://rendex.x402tools.xyz/v1/render
Content-Type: application/json

{
  "html": "<html><body><h1>Invoice #123</h1><p>Total: $99.00</p></body></html>",
  "options": { "format": "Letter", "printBackground": true },
  "output": "base64"
}
```

### Example Response (base64 mode)

```json
{
  "pdf": "JVBERi0xLjQKMSAwIG9iago8PC...",
  "pages": 1
}
```

Binary mode returns raw PDF bytes with Content-Type: application/pdf.

---

## SERVICE 9: VISIONEX (IMAGE OCR)

Endpoint: POST https://visionex.x402tools.xyz/v1/extract
Price: $0.05 per call
Content-Type: application/json
Response: application/json

### Request Body

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| url | string | YES* | — | Public image URL to fetch |
| image | string | YES* | — | Base64-encoded image (*one of url/image) |
| options.language | string | no | "eng" | OCR language (ISO 639-3) |
| options.format | string | no | "text" | text, json (with blocks), hocr |
| options.dpi | number | no | — | Resize hint before OCR (72–600) |

### Example Request

```
POST https://visionex.x402tools.xyz/v1/extract
Content-Type: application/json

{
  "url": "https://example.com/receipt.png",
  "options": { "format": "json", "dpi": 300, "language": "eng" }
}
```

### Example Response (json format)

```json
{
  "text": "Invoice #12345\nTotal Due: $199.00",
  "confidence": 96.2,
  "blocks": [
    {
      "text": "Invoice #12345",
      "confidence": 97.4,
      "bbox": { "x0": 24, "y0": 18, "x1": 240, "y1": 54 },
      "level": "line"
    },
    {
      "text": "Total Due: $199.00",
      "confidence": 95.0,
      "bbox": { "x0": 24, "y0": 62, "x1": 280, "y1": 98 },
      "level": "line"
    }
  ],
  "meta": {
    "width": 1600,
    "height": 2200,
    "language": "eng",
    "duration_ms": 482
  }
}
```

### Example Response (text format)

```json
{
  "text": "Invoice #12345\nTotal Due: $199.00",
  "confidence": 96.2,
  "meta": { "width": 1600, "height": 2200, "language": "eng", "duration_ms": 320 }
}
```

---

## SERVICE 10: PROSPEX (SALES PROSPECT ENRICHMENT)

Endpoint: POST https://prospex.x402tools.xyz/enrich
Price: $0.50 per call
Content-Type: application/json
Response: application/json

Turn a name + company domain into a sales-ready prospect profile: seniority, buyer
persona, decision-maker probability, company intel, email pattern, and a
personalised cold-email opener. Built for AI SDRs and outbound automation. Works
with just a name and domain — LinkedIn URL and company name are optional accuracy
boosters.

### Request Body

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| name | string | YES | — | Full name of the prospect |
| domain | string | YES | — | Company domain (e.g. stripe.com) |
| company_name | string | no | derived | Company name; inferred from the domain when omitted |
| linkedin_url | string | no | — | Prospect LinkedIn URL (improves title/seniority accuracy) |
| options.include_raw_sources | boolean | no | false | Include the raw gathered signals in the response |

### Example Request

```
POST https://prospex.x402tools.xyz/enrich
Content-Type: application/json

{
  "name": "Patrick Collison",
  "domain": "stripe.com"
}
```

### Example Response

```json
{
  "person": {
    "name": "Patrick Collison",
    "current_title": "Chief Executive Officer",
    "current_company": "Stripe",
    "linkedin_url": null,
    "linkedin_headline": null,
    "location": "San Francisco, CA",
    "seniority": "c_suite",
    "buyer_persona": "Economic buyer / final decision maker for company-wide platform bets",
    "decision_maker_probability": 1.0
  },
  "company": {
    "name": "Stripe",
    "domain": "stripe.com",
    "industry": "Financial Technology",
    "sub_industry": "Payments Infrastructure",
    "employee_count_range": "5000-10000",
    "founded_year": 2010,
    "hq_location": "San Francisco, CA",
    "company_type": "private",
    "funding_stage": "Late Stage / Private",
    "description": "Payments infrastructure for the internet, used by millions of businesses to accept payments and manage revenue online.",
    "tech_signals": ["stripe", "react", "typescript"]
  },
  "contact": {
    "email_pattern": "{first}.{last}@stripe.com",
    "email_pattern_confidence": 0.6,
    "inferred_email": "patrick.collison@stripe.com"
  },
  "outreach": {
    "recommended_opener": "Patrick — with Stripe processing hundreds of billions in payment volume, even a fractional lift in authorization rates is a nine-figure line item...",
    "personalisation_signals": ["payment volume scale", "developer-first product", "global expansion"]
  },
  "meta": {
    "sources_used": ["company_site", "llm"],
    "confidence": 0.72,
    "enrichment_duration_ms": 2140,
    "data_freshness": "live",
    "truncated": false,
    "model": "gpt-4o-mini"
  }
}
```

When `options.include_raw_sources` is true, the response also includes a
`raw_sources` object with the underlying snippets used for synthesis. Fields that
cannot be determined are returned as `null` (or `"unknown"` for seniority /
company_type) — Prospex does not fabricate data.

---