Overview

Block402 is a minimal layer for one-time unlocks using the x402 pattern. Gate any endpoint, file, or feature behind a verifiable payment—perfect for AI agents, APIs, dashboards, and premium tools.

Installation

pip install block402-core
pip install block402-client
pip install block402-fastapi
pip install block402-langchain
pip install block402-langgraph

npm install @block402/core
npm install @block402/client
npm install @block402/express
npm install @block402/nextjs
npm install @block402/langchain
npm install @block402/langgraph

Quick Start

from fastapi import FastAPI
from block402_fastapi import payment_required

app = FastAPI()

@app.get("/premium-data")
@payment_required(
    amount="0.10",
    payment_address="YOUR_WALLET_ADDRESS",
    token_mint="USDC_MINT_ADDRESS"
)
async def get_premium_data():
    return {"data": "Hello, premium user!"}

from block402_client import X402AutoClient
from solders.keypair import Keypair

client = X402AutoClient(wallet_keypair=Keypair())
resp = await client.fetch("https://api.example.com/premium-data")
print(resp.json())

REST API

Base URL (example): https://api.block402.app

{"productId":"prod_basic","userRef":"user_123"}

{"sessionId":"sess_abc123","expiresAt":"2025-12-01T00:00:00Z"}

{"sessionId":"sess_abc123"}

{"accessToken":"jwt_here","expiresAt":"2026-01-01T00:00:00Z"}

{"valid":true,"productId":"prod_basic","expiresAt":"2026-01-01T00:00:00Z"}

JS SDK

<script src="/sdk/block402.js"></script>
<script>
  block402.init({ apiKey: "YOUR_PUBLIC_KEY" })
</script>

block402.init({ apiKey:"KEY" })

await block402.unlock("prod_basic")

const ok = await block402.checkAccess(jwt)

Middleware

import express from "express";
import { paymentRequired } from "@block402/express";

const app = express();
app.get("/premium-data",
  paymentRequired({ amount:"0.10", tokenMint:"USDC_MINT_ADDRESS" }),
  (req,res)=> res.json({ data:"premium" })
);
app.listen(3000);

from fastapi import FastAPI
from block402_fastapi import payment_required

app = FastAPI()

@app.get("/report")
@payment_required(amount="0.25", token_mint="USDC_MINT_ADDRESS")
async def report():
    return {"ok": True}

Webhooks

Receive events at your endpoint (e.g., POST https://example.com/webhooks/block402).

{"event":"payment.succeeded","sessionId":"sess_1","tx":"...","amount":"0.10"}

{"event":"access.issued","userRef":"user_123","productId":"prod_basic","jwt":"..."}

{"event":"access.expired","jwt":"...","expiredAt":"..."}

Examples

app.get("/download",
  paymentRequired({ amount:"1.00", tokenMint:"USDC" }),
  (req, res) => res.download("./files/report.pdf")
);

from block402_client import X402AutoClient
client = X402AutoClient()
data = await client.fetch("https://api.example.com/alpha-feed").json()

FAQ