SDK

A TypeScript SDK for building payment-gated APIs using the X402 protocol on the Cronos blockchain.

The X402 SDK enables developers to monetize their APIs with per-request micropayments. When a client calls your API without payment, they receive the payment requirements. Once they submit a valid payment, your function executes and settlement happens automatically on-chain.

Key Benefits:

• Simple one-function setup for payment-gated endpoints

• Automatic payment verification and settlement

• USDC stablecoin payments on Cronos

• Built on Hono for high performance

---

Installation

npm install @axicov/x402-cronos-sdk

bun add @axicov/x402-cronos-sdk

yarn add @axicov/x402-cronos-sdk

---

Quick Start

Create a paid API in under 10 lines of code:

import { createx402Tool } from "@axicov/x402-cronos-sdk";

createx402Tool(
  async (input: { prompt: string }) => {
    const response = await generateText(input.prompt);
    return { result: response };
  },
  {
    price: 0.01,
    devWallet: "0xYourWalletAddress",
    port: 8000,
  }
);

Your API is now live at http://localhost:8000/send and requires 0.01 USDC per request.

---

Configuration

X402Config

Property	Type	Required	Description
price	number	Yes	Price per request in USDC (e.g., 0.01 = 1 cent)
devWallet	string	Yes	Your wallet address to receive payments
port	number	No	Server port (default: 3000)
description	string	No	Human-readable payment description

interface X402Config {
  price: number;
  devWallet: string;
  port?: number;
  description?: string;
}

---

API Reference

createx402Tool

Creates a payment-protected HTTP endpoint.

function createx402Tool<TInput, TOutput>(
  fn: (input: TInput) => Promise<TOutput>,
  config: X402Config
): Hono

Parameters:

Parameter	Description
fn	Your async function that processes the request
config	Payment configuration object

Returns: A Hono application instance

Example:

import { createx402Tool } from "@axicov/x402-cronos-sdk";

interface TranslationInput {
  text: string;
  targetLang: string;
}

interface TranslationOutput {
  translated: string;
}

const app = createx402Tool<TranslationInput, TranslationOutput>(
  async (input) => {
    const result = await translateText(input.text, input.targetLang);
    return { translated: result };
  },
  {
    price: 0.005,
    devWallet: "0x419E5aD68d2Ff4d1786FE4bB7ebe7b3563A5A6d7",
    port: 3000,
    description: "Translation service",
  }
);

---

x402Middleware

For custom Hono applications, use the middleware directly.

import { x402Middleware } from "@axicov/x402-cronos-sdk";

Usage:

import { Hono } from "hono";
import { x402Middleware } from "@axicov/x402-cronos-sdk";

const app = new Hono();

// Free endpoint
app.get("/health", (c) => c.json({ status: "ok" }));

// Paid endpoint
app.post(
  "/generate",
  x402Middleware({
    price: 0.02,
    devWallet: "0xYourWallet",
    description: "AI generation",
  }),
  async (c) => {
    const input = await c.req.json();
    const result = await generate(input);
    return c.json(result);
  }
);

export default app;

---

Facilitator

Access the underlying facilitator client for advanced use cases.

import { facilitator, verify, settle } from "@axicov/x402-cronos-sdk";

Generate Payment Requirements:

const requirements = facilitator.generatePaymentRequirements({
  payTo: "0xYourWallet",
  description: "API access",
  maxAmountRequired: "10000", // 0.01 USDC in base units
});

Verify a Payment:

const result = await verify(paymentHeader, requirements);

if (result.isValid) {
  // Payment is valid, process the request
} else {
  // Payment invalid: result.invalidReason
}

Settle a Payment:

await settle(paymentHeader, requirements);
// Payment transferred on-chain

---

Payment Flow

How X402 Works

Client                          Your API                         Cronos
  │                                │                                │
  │  POST /send                    │                                │
  │  (no payment)                  │                                │
  │───────────────────────────────▶│                                │
  │                                │                                │
  │  HTTP 402                      │                                │
  │  X-PAYMENT-REQUIRED: {...}     │                                │
  │◀───────────────────────────────│                                │
  │                                │                                │
  │  POST /send                    │                                │
  │  X-PAYMENT: <signed>           │                                │
  │───────────────────────────────▶│                                │
  │                                │                                │
  │                                │  Verify payment                │
  │                                │───────────────────────────────▶│
  │                                │                                │
  │                                │  Execute your function         │
  │                                │                                │
  │                                │  Settle payment                │
  │                                │───────────────────────────────▶│
  │                                │                                │
  │  200 OK                        │                                │
  │  { result: ... }               │                                │
  │◀───────────────────────────────│                                │

HTTP Headers

Header	Direction	Description
X-PAYMENT-REQUIRED	Response	Base64-encoded payment requirements
X-PAYMENT	Request	Signed payment proof

Payment Requirements Format

{
  "payTo": "0x...",
  "description": "Tool access",
  "maxAmountRequired": "10000"
}

Note: maxAmountRequired is in USDC base units (6 decimals). 10000 = 0.01 USDC.

---

Client Integration

Making Paid Requests

async function callPaidAPI(url: string, input: any, signer: Signer) {
  // Step 1: Initial request
  const res = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(input),
  });

  // Step 2: Handle payment requirement
  if (res.status === 402) {
    const encoded = res.headers.get("X-PAYMENT-REQUIRED");
    const requirements = JSON.parse(Buffer.from(encoded, "base64").toString());

    // Step 3: Generate payment
    const payment = await facilitator.generatePaymentHeader({
      to: requirements.payTo,
      value: requirements.maxAmountRequired,
      signer,
      validBefore: Math.floor(Date.now() / 1000) + 600, // 10 min expiry
    });

    // Step 4: Retry with payment
    const paidRes = await fetch(url, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-PAYMENT": payment,
      },
      body: JSON.stringify(input),
    });

    return paidRes.json();
  }

  return res.json();
}

Using ethers.js

import { ethers } from "ethers";
import { facilitator } from "@axicov/x402-cronos-sdk";

const provider = new ethers.JsonRpcProvider("https://evm-t3.cronos.org");
const signer = new ethers.Wallet(PRIVATE_KEY, provider);

const payment = await facilitator.generatePaymentHeader({
  to: "0xDevWallet",
  value: "10000",
  signer,
  validBefore: Math.floor(Date.now() / 1000) + 600,
});

---

Examples

Image Generation API

import { createx402Tool } from "@axicov/x402-cronos-sdk";

interface ImageInput {
  prompt: string;
  size: "256" | "512" | "1024";
}

interface ImageOutput {
  url: string;
}

createx402Tool<ImageInput, ImageOutput>(
  async (input) => {
    const imageUrl = await generateImage(input.prompt, input.size);
    return { url: imageUrl };
  },
  {
    price: 0.05,
    devWallet: process.env.DEV_WALLET!,
    port: 8000,
    description: "AI image generation",
  }
);

Data Lookup Service

import { createx402Tool } from "@axicov/x402-cronos-sdk";

createx402Tool(
  async (input: { address: string }) => {
    const data = await fetchBlockchainData(input.address);
    return {
      balance: data.balance,
      transactions: data.txCount,
      lastActive: data.lastSeen,
    };
  },
  {
    price: 0.001,
    devWallet: process.env.DEV_WALLET!,
    description: "Blockchain data lookup",
  }
);

Multi-Endpoint API with Middleware

import { Hono } from "hono";
import { x402Middleware } from "@axicov/x402-cronos-sdk";

const app = new Hono();
const walletConfig = {
  devWallet: process.env.DEV_WALLET!,
};

// Free tier
app.get("/status", (c) => c.json({ online: true }));

// Basic tier - $0.01
app.post(
  "/basic",
  x402Middleware({ ...walletConfig, price: 0.01 }),
  async (c) => {
    return c.json({ tier: "basic", data: "..." });
  }
);

// Premium tier - $0.10
app.post(
  "/premium",
  x402Middleware({ ...walletConfig, price: 0.1 }),
  async (c) => {
    return c.json({ tier: "premium", data: "..." });
  }
);

export default app;

---

Network

Cronos Testnet

The SDK operates on Cronos Testnet by default.

Property	Value
Chain ID	338
RPC URL	https://evm-t3.cronos.org
Currency	TCRO
Explorer	https://testnet.cronoscan.com

Getting Test Tokens

1. Get TCRO from the Cronos Testnet Faucet

2. Acquire test USDC for payment testing

---

Environment Variables

# Required for receiving payments
DEV_WALLET=0xYourWalletAddress

# Optional
PORT=3000

For client-side payment signing:

PRIVATE_KEY=your_private_key

---

TypeScript Support

The SDK is written in TypeScript and exports full type definitions.

import type { X402Config } from "@axicov/x402-cronos-sdk";

const config: X402Config = {
  price: 0.01,
  devWallet: "0x...",
};

Generic type inference works automatically:

// Input and output types are inferred
createx402Tool(
  async (input: { name: string }) => {
    return { greeting: `Hello ${input.name}` };
  },
  config
);

---

Error Handling

Common Errors

Status	Meaning	Solution
402	Payment required	Include valid X-PAYMENT header
402 + error message	Payment invalid	Check payment signature and expiry
500	Server error	Check your function implementation

Handling in Middleware

app.post(
  "/api",
  x402Middleware(config),
  async (c) => {
    try {
      const result = await riskyOperation();
      return c.json(result);
    } catch (error) {
      // Payment already verified, handle gracefully
      return c.json({ error: "Processing failed" }, 500);
    }
  }
);