Blocks402

A minimal x402 layer for one-time unlocks. Integrate in minutes with a boxed pay modal, a tiny JS SDK, and REST endpoints. Perfect for AI agents, APIs, dashboards, files, and premium tools.

Contract : coming soon on four.meme

PYTHON (PYPI)

block402-core

Core implementation of x402 unlock protocol for autonomous agent payments.

block402-client

HTTP client for x402 protocol with automatic payment session handling.

block402-fastapi

FastAPI middleware & decorators for protecting routes with x402 unlocks.

block402-langchain

LangChain integration to gate tools/chains behind x402 payments.

Quick Start

Add the script: <script src="/sdk/block402.js"></script>, then call block402.init({apiKey: "YOUR_KEY"}) andblock402.unlock("product_123") to open the pay modal.

QUICK START

SERVER (FASTAPI)
from fastapi import FastAPI
from block402_fastapi import payment_required

app = FastAPI()

@app.get("/premium-data")
@payment_required(
    amount="0.10",                     # amount in USDC
    payment_address="YOUR_WALLET_ADDRESS",
    token_mint="USDC_MINT_ADDRESS"
)
async def get_premium_data():
    return {"data": "Premium content"}
CLIENT (AUTO-PAYMENT)
from block402_client import X402AutoClient
from bnb.keypair import Keypair

client = X402AutoClient(wallet_keypair=Keypair())

# Automatically handles 402 and pays
response = await client.fetch(
    "https://api.example.com/premium-data"
)
data = response.json()

AI AGENT INTEGRATION

LANGCHAIN AGENT
from langchain.chat_models import ChatOpenAI
from block402_langchain import create_x402_agent
from bnb.keypair import Keypair

# Load wallet
keypair = Keypair()

# Create agent with X402 support
agent = create_x402_agent(
    wallet_keypair=keypair,
    llm=ChatOpenAI(),
    max_payment="5.0"   # USD-equivalent cap for a single task
)

# Agent can now autonomously pay for API access
response = agent.run(
    "Get the latest market data from https://api.example.com/premium-data "
    "and summarize the key trends"
)
LANGGRAPH WORKFLOW
from typing import TypedDict
from langgraph.graph import StateGraph, END
from block402_langgraph import payment_node, check_payment_required
from bnb.keypair import Keypair

class AgentState(TypedDict):
    api_url: str
    api_response: str
    payment_required: bool
    payment_completed: bool
    wallet_keypair: Keypair

# Build workflow
workflow = StateGraph(AgentState)

def fetch_data(state: AgentState) -> AgentState:
    # call the API; if it returns 402, mark it
    required = check_payment_required(state["api_url"])
    return {**state, "payment_required": required}

# Nodes
workflow.add_node("fetch_data", fetch_data)
workflow.add_node("pay", payment_node)   # handles x402 payment & receipt

# Edges
workflow.set_entry_point("fetch_data")
workflow.add_conditional_edges(
    "fetch_data",
    lambda s: "pay" if s["payment_required"] else END,
    {"pay": "fetch_data", END: END}
)

graph = workflow.compile()

INSTALLATION

PYTHON
pip install block402-core
pip install block402-client
pip install block402-fastapi
pip install block402-langchain
pip install block402-langgraph
NODE.JS / TYPESCRIPT
npm install @block402/core
npm install @block402/client
npm install @block402/express
npm install @block402/nextjs
npm install @block402/langchain
npm install @block402/langgraph

KEY FEATURES

One-Line Integration

Add unlocks with a single decorator.

AI-Native

Built for autonomous agent workflows.

Instant Settlement

Payments settle in ~200ms.

No Accounts

No API keys or subscriptions needed.

Framework Support

FastAPI, Express, LangChain, LangGraph.

Chain-Agnostic

BNB first, multi-chain ready.

HOW IT WORKS

AI
AI Agent
(Client)
API
API Server
(Server)
◎◎
Blockchain
(BNB)
  1. 1

    GET /data

    AI Agent requests premium content

  2. 2

    402 Payment Required

    Server returns payment request

  3. 3

    Broadcast Payment

    Agent sends payment to blockchain

  4. 4

    Verify Transaction

    Server confirms payment on-chain (~200ms)

  5. 5

    GET /data + Auth

    Agent retries with payment proof

  6. 6

    200 OK + Data

    Server returns premium content

FULLY AUTOMATED PAYMENT FLOW
No user intervention required • Instant settlement • Sub-cent fees

OPEN SOURCE • BUILT FOR BNB