Docs

Back to home

Documentation hub for integrating AI agent APIs with x402 payment flows. You can review endpoints, buyer payment flow, and download a reusable markdown skill file directly.

API endpoints

MethodPathStatusNotes
GET/api/healthliveService health check
GET/api/v1/capabilitiesliveCapability discovery for agents
POST/api/v1/qrcode/generateliveFast qrcode generate
POST/api/v1/image/uploadliveImage hosting upload (10MB max)
POST/api/v1/news/searchliveGlobal news search via upstream provider (x402 protected)
POST/api/v1/image/ocrplannedText extraction
POST/api/v1/video/object-detectionplannedVideo analysis

Buyer flow

  1. Call a protected endpoint and expect HTTP 402.
  2. Read payment requirements from response headers.
  3. Create and sign payment payload using x402 buyer SDK.
  4. Retry request with payment header and parse settlement response.
Open buyer quickstartOpen seller quickstart

Error codes

Validation error codes for live protected endpoints. Use these codes for agent retry and user-facing guidance.

POST /api/v1/image/upload

  • image_file_required (400)
  • image_file_empty (400)
  • image_file_too_large (413)
  • image_mime_not_supported (400)
  • invalid_image_request (400)

POST /api/v1/qrcode/generate

  • invalid_json_body (400)
  • invalid_request_body (400)
  • qrcode_content_required (400)
  • qrcode_content_too_long (400)
  • qrcode_format_not_supported (400)
  • invalid_qrcode_request (400)

Skill document

Markdown preview for a general-purpose API skill. Download and use it directly in your agent workflow.

---
name: x402-agent-api-skill
description: AI agent skill for x402 paid APIs with live image-hosting, qrcode-generate, and news-search, plus planned image/video/vision APIs (colorize, super-resolution, enhance, smart-redact, smart-crop, inpaint, qrcode-decode, tags, game-scene-detect, quality-score, face/human/pet/plate-detect, OCR, idcard-ocr, background-remove, video object-detection, portrait-segmentation).
version: 1.2.0
---

# x402 Agent API Skill

Use this skill to let your AI agent call paid endpoints on `https://www.x402api.app/` with x402.

## Quick start for AI agents

1. Place this file in your OpenClaw, Codex, or Claude project root.
2. Tell your AI agent: "Help me convert this text into a QR code." or "Help me upload this image and return an online URL."
3. The agent should follow x402 payment flow automatically.

## Install dependencies

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

## Required environment variables

```bash
EVM_PRIVATE_KEY=0x_your_private_key
```

Only `EVM_PRIVATE_KEY` is required for buyer usage.  
`API_BASE_URL` is optional because this skill defaults to `https://www.x402api.app/`.

## Out-of-the-box usage

1. Put this `SKILL.md` in your project root (OpenClaw, Codex, or Claude).
2. Set only one env var:


...
Download full skill (.zip)