Technical Docs

🧩 Overview

Link402 is a decentralized paywall infrastructure built on BNB CHAIN, powered by the x402 protocol — a framework for programmable payments between users and AI agents.

It enables:

• Instant BNB-based paywalled content delivery

• Autonomous AI-agent payments and rebilling

• Encrypted content access tied to on-chain transactions

• Real-time analytics and webhook integration for developers

---

🔶 Architecture Overview

Core components:

1. Frontend (Link402 App)

   • Built with Next.js + TailwindCSS

   • API interaction with Link402 backend via REST

2. Backend (Link402 Core)

   • Node.js + Express-based middleware

   • Handles link creation, encryption, payment validation, and webhook triggers

3. Smart Contract Layer

   • On-chain payment verification

   • Emits transaction receipts to off-chain webhook processors

4. x402 Engine

   • Handles “Agent <-> Paywall” logic

   • Enables autonomous transactions where agents can:

     • Create links

     • Purchase content

     • Rebuy or renew access

---

🧠 x402 Protocol Explained

x402 is Link402’s internal standard for paywall communication between:

• Human users (buyers)

• AI agents (automated buyers)

• Webhooks or smart contracts (verifiers)

It defines how a paywalled resource is priced, bought, and verified using BNBtransaction metadata.

🧩 Data Model

{
  "link_id": "l402_0x1a2b3c",
  "owner": "7bwJJEgC5U...",
  "agent_enabled": true,
  "resource": {
    "title": "Premium Research Alpha",
    "price_usd": 10.00,
    "target_url": "https://example.com/secret"
  },
  "x402": {
    "version": "1.2",
    "txn_hash": "4qsnzYfM...",
    "status": "paid",
    "access_token": "enc_54bbd9d...",
    "expiry": "2025-12-31T23:59:59Z"
  }
}

---

🔄 Data Flow Diagrams

1️⃣ Human Payment Flow

User → Link402 Frontend → Link402 API → BNB TXN→ Webhook → Access Granted

Steps:

1. User selects paywalled content

2. Link402 backend generates a link_id and awaits BNB transaction

3. Wallet signs and sends BNB → Smart contract verifies receipt

4. Backend confirms payment → Generates encrypted access token

5. Redirects user to target_url

---

2️⃣ Agent Integration Flow (x402)

AI Agent → Link402 Agent API → Auth Key Validation → BNB Payment → Webhook Response

1. Agent posts JSON payload to /api/agent/create-link

2. Backend authenticates via x-agent-api-key

3. Transaction initiated and confirmed on-chain

4. Webhook triggers → Response contains status + purchase receipt

5. Agent consumes unlocked data (or rebuys if allowed)

---

3️⃣ Analytics Flow

Frontend → Metrics Collector → DB (PostgreSQL) → Analytics Dashboard

• Tracks:

  • views, clicks, conversions

  • Transaction count and average order value

  • Agent rebuy frequency

Stack: Supabase / PostgreSQL + Prisma + Next.js

---

🔐 Security & Validation

• All payments validated via on-chain BNB transactions

• Webhook payloads signed with HMAC-SHA256

• Access URLs are time-bound and AES-encrypted

• Agents require API key rotation every 30 days

---

🧰 Developer Guide

Create a Link (API)

POST /api/agent/create-link
Content-Type: application/json
x-agent-api-key: <YOUR_API_KEY>

{
  "title": "Dataset Alpha",
  "description": "Premium agent-only dataset",
  "price_usd": 15.0,
  "target_url": "https://example.com/data",
  "agentResourceId": "dataset-2025-10",
  "webhookUrl": "https://your.app/webhooks/link402",
  "allowRepeat": true
}

---

Verify Payment (Webhook)

Webhook payload structure:

{
  "event": "payment_success",
  "link_id": "l402_0x1234",
  "bnb_txn": "3XEjfP...",
  "amount": 0.4,
  "buyer": "3sY78Nf...",
  "timestamp": "2025-10-28T20:19:00Z"
}

---

🧬 Future Expansion

• x402 v2: On-chain NFT token access

• Token-gated paywalls (based on SPL holdings)

• Cross-agent billing network for shared data models

• Linkchain analytics SDK for 3rd-party platforms

---

📊 Example Agent Workflow

[Agent Node.js Script]
↓
Authenticate → Generate Link → Confirm Txn → Fetch Webhook → Parse Data
↓
Rebuy on Expiry or Trigger Automated Renewal