API 레퍼런스

API 레퍼런스 & x402 연동

AZNP v2.1 API 엔드포인트, 파라미터, 응답 헤더 및 AI 에이전트 x402 결제 프로토콜 명세를 확인하세요.

엔드포인트

GET https://aznp-proxy.kerberos79.workers.dev/?url={target_url}

별도의 회원가입이나 API Key가 필요 없습니다. 기본 요청은 Free 티어로 처리되며, 고급 연동 시 x402 프로토콜을 통해 지갑으로 자동 승인됩니다.

쿼리 파라미터

파라미터	필수	구분	설명
`url`	필수	Free/x402	대상 웹페이지 URL (필수)
`mode`	선택	auto: Free, summary: x402	auto (기본) / summary (요약 모드)
`max_tokens`	선택	x402	반환 Markdown 최대 토큰 수
`render`	선택	x402	true → JS 렌더링 강제 (Tier 3 Browser Rendering)
`format`	선택	markdown: 모두, json: x402	markdown (기본) / json (구조화 JSON)
`fresh`	선택	Free/x402	1 → 캐시 무시하고 강제 갱신
`images`	선택	Free/x402	0 → 이미지 관련 텍스트 최소화

응답 헤더

X-AZNP-Plan사용 플랜 (free | x402)

X-AZNP-Source변환 소스 (cloudflare-native | aznp-self | browser-rendering | cache | kv)

X-AZNP-Cache캐시 상태 (HIT | MISS)

X-Token-Reduction추정 토큰 절감률 (예: Estimated 82%)

X-Markdown-Tokens반환 Markdown 토큰 수 (추정)

X-RateLimit-Remaining남은 Free Rate Limit (분당)

PAYMENT-REQUIREDHTTP 402 반환 시 x402 소액 결제 스펙 JSON (금액, 통화, 수신 지갑 주소)

Cache-Control캐시 정책 (public, max-age=..., stale-while-revalidate=...)

💳 x402 (402 Payment Required) 프로토콜 흐름

요청 시도: AI 에이전트가 AZNP에 요청합니다.
402 응답: Free 한도 초과 또는 고급 기능 사용 시 `HTTP 402 Payment Required` 반환
PAYMENT-REQUIRED 헤더 확인: 수신 지갑 주소(`payTo`), 금액(`amount`), 네트워크(`network`) 확인
자동 온체인 서명/결제: 에이전트 지갑이 USDC 결제 후 `PAYMENT-SIGNATURE` 헤더 포함하여 재요청
Markdown 반환: AZNP Worker가 서명 검증 후 고품질 Markdown 응답 반환

코드 예시

TypeScript (AI Agent x402 SDK)

import { x402fetch } from "@x402/fetch";

const response = await x402fetch(
  "https://aznp-proxy.kerberos79.workers.dev/?url=https://example.com&mode=summary",
  {
    wallet: agentWallet, // USDC 잔액이 있는 에이전트 지갑
    maxAmount: "0.05",   // 지불 허용 상한 (USDC)
  }
);

const markdown = await response.text();
console.log("Token reduction:", response.headers.get("X-Token-Reduction"));

Python (AI Agent / LangChain / AutoGen)

import httpx

# 1. 402 응답 및 결제 정보 수신 핸들러 예시
async def fetch_aznp_markdown(target_url: str):
    async with httpx.AsyncClient() as client:
        res = await client.get(
            f"https://aznp-proxy.kerberos79.workers.dev/?url={target_url}&render=true"
        )
        if res.status_code == 402:
            payment_info = res.headers.get("PAYMENT-REQUIRED")
            # 에이전트 지갑이 payment_info 스펙대로 USDC 온체인 결제 진행 후 재요청
            tx_signature = await sign_and_pay(payment_info)
            res = await client.get(
                f"https://aznp-proxy.kerberos79.workers.dev/?url={target_url}&render=true",
                headers={"PAYMENT-SIGNATURE": tx_signature}
            )
        return res.text

에러 코드

400

Bad Request

url 파라미터 누락 또는 유효하지 않은 URL

402

Payment Required (x402)

Free 한도 초과 또는 고급 기능(JS 렌더링, 요약 등) 요청 시 x402 소액 결제 요구

429

Rate Limit Exceeded

분당 요청 한도 초과 (x402 결제 시 즉시 해제)

500

Internal Error

변환 중 내부 오류 발생

502

Bad Gateway

대상 URL fetch 실패