# x402tools.xyz — Complete API Reference
# Last updated: 2025-05-25

> 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.001 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 2: SCREENSHOT CAPTURE

Endpoint: POST https://snap.x402tools.xyz/v1/capture
Price: $0.005 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           |

### Example Request

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

{
  "url": "https://example.com",
  "width": 1280,
  "height": 720,
  "fullPage": 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.002 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.001 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

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.001     | POST   | https://qr.x402tools.xyz/v1/generate      |
| Screenshot Capture   | $0.005     | POST   | https://snap.x402tools.xyz/v1/capture     |
| DNS Lookup           | $0.002     | GET    | https://dns.x402tools.xyz/v1/lookup       |
| DocParse             | $0.001     | POST   | https://docparse.x402tools.xyz/parse      |

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