API Reference

AZNP v2.1 API endpoint, query parameters, response headers, and the optional Solana Ed25519 signature (identity, not billing).

Conversion Endpoint

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

🔑 Solana Ed25519 Signature (Optional Identity)

Signing is optional. It confirms request identity and lifts the rate limit, so include these headers only when you want to sign with your Solana keypair:

x-wallet-addressSolana Public Key (Base58 format) — optional identity

x-timestampUnix Timestamp (Seconds, within 5 mins) — optional identity

x-signatureEd25519 signature of 'x402:{timestamp}' (Base58) — optional identity

💳 Credit Top-up API (POST /v1/topup)

⚠️ This endpoint is out of grant scope — kept for compatibility.

Submit your Solana transaction hash (tx_hash) after transferring $20 USDC or more:

# Request
curl -X POST "https://aznp-proxy.kerberos79.workers.dev/v1/topup" \
  -H "Content-Type: application/json" \
  -d '{"wallet": "7xKX...SolanaPublicKey", "tx_hash": "5K...SolanaTxHash"}'
# Response (200 OK)
{
  "success": true,
  "wallet": "7xKX...SolanaPublicKey",
  "deposited_usdc": 20.0,
  "added_credits": 12000,
  "total_allowed_requests": 12000
}

Query Parameters

Parameter	Required	Type / Scope	Description
`url`	Required	Required	Target web page URL (Required)
`mode`	Optional	Free / Pro	auto (default) / summary (summary mode, Pro — out of grant scope)
`max_tokens`	Optional	Free	Truncate the output to N tokens (free)
`render`	Optional	Pro	true → force dynamic JS rendering (Tier 3, Pro — out of grant scope)
`format`	Optional	Free	markdown (default) \| json \| toml \| yaml \| json-ld — all free
`fresh`	Optional	Free	1 → bypass cache & force refresh
`images`	Optional	Free	0 → drop images from the output

Response Headers

X-AZNP-PlanExecution plan (free | pro | enterprise)

X-AZNP-CacheCache status (HIT | MISS | BYPASS)

X-AZNP-BypassSet to 'true' on 307 Redirect for files or Free plan OpenAPI requests

X-Token-ReductionEstimated token reduction % (e.g. 88%)

X-Markdown-TokensOutput token count (estimated)

X-RateLimit-RemainingRemaining credit request count

PAYMENT-REQUIREDTop-up spec JSON returned on HTTP 402

AI Agent Code Example (Node.js)

import nacl from 'tweetnacl';
import bs58 from 'bs58';

const AGENT_SOLANA_PRIVATE_KEY_BASE58 = "YOUR_AGENT_SOLANA_PRIVATE_KEY";
const secretKey = bs58.decode(AGENT_SOLANA_PRIVATE_KEY_BASE58);
const keypair = nacl.sign.keyPair.fromSecretKey(secretKey);
const publicKeyBase58 = bs58.encode(keypair.publicKey);

async function callAZNPProxy(targetUrl) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const messageBytes = new TextEncoder().encode(`x402:${timestamp}`);

  // Generate Ed25519 detached signature
  const signatureBytes = nacl.sign.detached(messageBytes, keypair.secretKey);
  const signatureBase58 = bs58.encode(signatureBytes);

  const endpointUrl = `https://aznp-proxy.kerberos79.workers.dev/?url=${encodeURIComponent(targetUrl)}&render=true`;

  const response = await fetch(endpointUrl, {
    method: 'GET',
    headers: {
      'x-wallet-address': publicKeyBase58,
      'x-timestamp': timestamp,
      'x-signature': signatureBase58,
    },
  });

  if (response.status === 402) {
    const errorData = await response.json();
    console.error("402 Payment Required: Insufficient credits. Please top up.", errorData);
    return null;
  }

  const markdown = await response.text();
  console.log("Token reduction:", response.headers.get("X-Token-Reduction"));
  console.log("Clean Markdown output:", markdown.slice(0, 200));
  return markdown;
}

🤖 Programmatic Wallet & Auto-Topup Script (Node.js / Python)

// 1. Programmatic Solana Keypair Generation (Node.js)
import { Keypair } from '@solana/web3.js';
import bs58 from 'bs58';

// Create a new keypair programmatically for AI Agent
const agentKeypair = Keypair.generate();
const secretKeyBase58 = bs58.encode(agentKeypair.secretKey);
const publicKeyBase58 = agentKeypair.publicKey.toBase58();

console.log("Agent Public Key:", publicKeyBase58);
console.log("Agent Secret Key (Store securely in .env):", secretKeyBase58);

// 2. HTTP 402 Auto-Payment Handler Pattern
async function fetchWithAutoTopup(targetUrl) {
  let res = await callAZNPProxy(targetUrl);
  
  // Detect 402 Payment Required (Insufficient credits)
  if (res && res.status === 402) {
    const paymentInfo = await res.json();
    console.warn("HTTP 402 Payment Required received. Executing automated USDC topup...");
    
    // Step 2a: Send $20 USDC via Solana SDK to recipient wallet
    const txHash = await executeUsdcTransfer({
      fromKeypair: agentKeypair,
      toAddress: paymentInfo.receiver_wallet || "RECEIVER_SOLANA_WALLET",
      amountUsdc: 20.0
    });
    
    // Step 2b: Submit transaction hash to AZNP credit topup endpoint
    const topupRes = await fetch("https://aznp-proxy.kerberos79.workers.dev/v1/topup", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ wallet: publicKeyBase58, tx_hash: txHash })
    });
    
    if (topupRes.ok) {
      console.log("Auto-topup successful! Resuming original request...");
      return await callAZNPProxy(targetUrl); // Retry request
    }
  }
  return res;
}

Error Codes

Errors are returned as TOML with an [error] table (code + action_recommendation) by default, and as JSON when format=json is used.

Status	code	action_recommendation
400	missing_url / invalid_url / unsupported_format / max_tokens_too_large / chain_mismatch	fix the parameter
404	not_found	use GET /?url=... or the endpoints above
429	rate_limited	wait Retry-After seconds
502	fetch_failed	check URL reachability and retry
500	internal_error	retry a limited number of times

HTTP 402 is only returned by the out-of-grant-scope credit system (POST /v1/topup) when credits are exhausted. Its body and PAYMENT-REQUIRED header remain JSON.