Technical Specification · v1.0

HTTP 402 Integration Guide

Complete reference for integrating Vlexivo's micropayment protocol into web applications, APIs, and browser extensions. Publisher SDK, API endpoints, payment flows, and error handling.

Author: Behkish Nassirzadeh, PhD · Last updated: 2026-05-22 · Protocol version: vlexivo/1.0

Overview

Vlexivo implements HTTP 402 Payment Required as a production micropayment protocol. Publishers embed the SDK in their server or frontend, set prices per resource, and receive cryptographically verified access tokens after on-chain payment — without holding funds or requiring user accounts.

Base URL: All API calls go to https://vlexivo.online. The protocol uses X-Api-Key header authentication for publisher endpoints and X-Agent-Key for machine-to-machine agent billing.

Publisher SDK Integration

The Vlexivo SDK works in two modes: server-side middleware (Express.js/Node.js) and browser SDK (vanilla JS). Both intercept 402 responses automatically.

3-Step Setup

Install the SDK

Add the Vlexivo package to your Node.js project. The SDK works with Express.js or any Node HTTP server.

npm install @vlexivo/sdk

Configure with your API key

Register at vlexivo.online/onboard to get your publisher API key. Then configure the SDK with your key and price per resource.

const { Vlexivo } = require('@vlexivo/sdk');

const vlexivo = new Vlexivo({
  apiKey: 'vlx_live_your_api_key_here',
  // Optional: set default price per resource
  scopeType: 'per-call',   // 'per-call' | 'per-article' | 'per-session' | 'tip'
  price: { amount: '0.01', currency: 'USDC' },
  // Auto-register pricing rule if not found
  autoRegister: true,
});

Protect your endpoints

Wrap any Express route with the Vlexivo middleware. When an unprotected request arrives, Vlexivo returns HTTP 402 with the challenge. The browser SDK handles payment and retry automatically.

const express = require('express');
const app = express();

// Protect any endpoint — 3 lines of code
app.use('/api/premium', vlexivo.protect({
  scopeType: 'per-call',
  price: { amount: '0.005', currency: 'USDC' },
}));

app.get('/api/premium/report', (req, res) => {
  res.json({ data: 'your paid content here' });
});

Express Middleware Options

Option	Type	Default	Description
`scopeType`	string	`'per-call'`	Billing model: per-call, per-article, per-session, tip
`price`	object	required	`{ amount: string, currency: string }`
`autoRegister`	boolean	`false`	Automatically create pricing rule if not found
`resourceId`	string	route path	Override the resource identifier
`entitlementHeader`	string	`'X-Entitlement'`	Header to check for existing entitlement tokens
`onPaymentRequired`	function	—	Custom callback when 402 is returned

Browser SDK

For client-side payment handling, embed the Vlexivo browser SDK. It intercepts fetch requests, detects 402 responses, handles wallet connection, and retries automatically.

<script src="https://vlexivo.online/sdk/vlexivo.js"></script>
<script>
  const mp = new Vlexivo({
    publisherId: 42,
    walletProvider: 'phantom', // 'phantom' | 'metamask' | 'hosted'
  });

  // Intercept all fetch calls
  mp.intercept();

  // Or pay manually
  async function fetchPremiumData(url) {
    const res = await fetch(url);
    if (res.status === 402) {
      const challenge = await res.json();
      await mp.pay(challenge);
      return fetch(url); // auto-retry
    }
    return res;
  }
</script>

API Reference

Core Endpoints

Method	Path	Description
POST	/v1/challenge	Generate a payment challenge. Publisher API key auth.
POST	/v1/unlock	Submit payment proof, receive JWT entitlement. No auth required.
POST	/v1/agent/pay	Machine-to-machine payment. Agent API key auth.
GET	/v1/agent/status	Agent key health check.
POST	/api/entitlements/validate	Server-side entitlement token validation.
GET	/api/pricing	List publisher pricing rules.
POST	/api/pricing	Create pricing rule.
GET	/health	Health check. No auth.

POST /v1/challenge

Generates a payment challenge. Returns a Challenge402 object that the SDK wraps in an HTTP 402 response.

// Request
// Headers: X-Api-Key: vlx_live_...

{
  "resource_id": "/api/premium/report",
  "scope_type": "per-call",
  "price": { "amount": "0.01", "currency": "USDC" },
  "auto_register": true
}

// Response — HTTP 200 (SDK wraps as 402)
{
  "challenge": {
    "nonce": "550e8400-e29b-41d4-a716-446655440000",
    "resource_id": "/api/premium/report",
    "scope_type": "per-call",
    "price": { "amount": "0.01", "currency": "USDC" },
    "unlock_url": "https://vlexivo.online/v1/unlock",
    "expires_at": "2026-05-22T12:15:00.000Z",
    "protocol": "vlexivo/1.0",
    "publisher_id": 42
  }
}

POST /v1/unlock

Consumer or agent submits blockchain proof of payment. Server verifies on-chain transaction, issues JWT entitlement.

// Request — no authentication required
{
  "proof": {
    "tx_hash": "4vJ9KabcXYZ...",
    "buyer_wallet": "9mNPabc...",
    "nonce": "550e8400-e29b-41d4-a716-446655440000",
    "signature": "2YbX..."
  },
  "currency": "USDC"
}

// Response
{
  "status": "granted",
  "entitlement_token": "eyJhbGciOiJIUzI1NiJ9...",
  "resource_id": "/api/premium/report",
  "scope_type": "per-call",
  "expires_at": "2026-05-22T12:20:00.000Z",
  "tx_hash": "4vJ9KabcXYZ..."
}

JWT Entitlement Token Structure

Header: alg: "HS256", typ: "JWT" Payload: iss: "vlexivo" sub: "9mNPabc..." // buyer wallet aud: "42" // publisher_id iat: 1743600000 // issued-at unix exp: 1743600300 // expiry unix eid: 7891 // entitlements.id rid: "/api/premium/report" // resource_id scp: "per-call" // scope_type amt: "0.25" // price_paid

HTTP Status Codes

200Success (challenge granted)

402Payment Required (challenge generated)

401Unauthorized (bad API key)

404Pricing rule not found

409Nonce already used (replay attack)

410Challenge expired (TTL exceeded)

422Validation error (bad input)

429Rate limited

500Internal server error

Browser Extension Architecture

The Vlexivo browser extension (Manifest V3) provides automatic 402 interception for any website without requiring publisher SDK installation. It works by wrapping window.fetch and XHR in content scripts.

Components

Browser Extension — Vlexivo MV3 ┌─────────────────────────────────────────┐ background.js — service worker (lifecycle: by events) ├─ Wallet state management (encrypted AES-256-GCM) ├─ Transaction signing via offscreen document └─ Payment proof submission to /v1/unlock │ content.js — injected into all frames ├─ Wraps window.fetch / XHR ├─ Detects HTTP 402 with X-Vlexivo-Protocol header └─ Handles payment modal UI │ popup.html/js — extension popup ├─ Wallet balance display ├─ Recent transactions └─ Settings (auto-pay toggle, RPC endpoint) │ offscreen.html — Solana signing (MV3 requirement) └─ Injects @solana/web3.js, signs transactions │ manifest.json — MV3, permissions: tabs, storage, offscreen

Extension Interception Flow

# Browser Extension — 402 Interception Flow User → visits publisher site → GET /api/premium/report Publisher ← HTTP/1.1 402 Payment Required Extension → detects X-Vlexivo-Protocol: vlexivo/1.0 header Extension → parses challenge from 402 body Extension → shows payment modal (amount, resource, wallet) User → confirms payment in extension popup Background → signs Solana transaction via offscreen document Background → submits proof to https://vlexivo.online/v1/unlock Vlexivo → verifies on-chain, returns entitlement_token Extension → stores token in chrome.storage.local Extension → retries original request with X-Entitlement header Publisher → HTTP/1.1 200 OK (paid content)

Payment Flow Sequence

Complete end-to-end payment flow from publisher middleware through on-chain verification to entitlement delivery.

# End-to-End Payment Flow [Publisher Server] → receives request: GET /api/premium/report [Middleware] → checks X-Entitlement header [Middleware] → no entitlement → POST /v1/challenge [Vlexivo] → returns Challenge402 { nonce, unlock_url, ... } [Middleware] → wraps as HTTP 402 + challenge JSON body [Publisher Server] ← HTTP/1.1 402 Payment Required + challenge # — Browser/Extension handles payment — [Browser SDK] → detects 402, parses challenge [Wallet] → user approves Solana transaction [Solana] → ~400ms finality, tx confirmed on-chain [Browser SDK] → POST /v1/unlock { proof: { tx_hash, nonce, ... } } [Vlexivo] → consumes nonce atomically (replay protection) [Vlexivo] → fetches tx via Solana RPC, verifies amount + recipient [Vlexivo] → issueEntitlement() → sign HS256 JWT [Browser SDK] ← { status: "granted", entitlement_token, ... } # — Automatic retry with entitlement — [Browser SDK] → stores token in localStorage [Browser SDK] → retries original request + X-Entitlement: Bearer <token> [Publisher Server] → validates JWT signature + expiry [Publisher Server] ← HTTP/1.1 200 OK + paid content

Retry Logic

The browser SDK implements automatic retry with backoff. If the initial unlock fails due to network or chain latency, it retries before presenting an error to the user.

// Unlock retry schedule (exponential backoff)
const UNLOCK_RETRY_DELAY_MS = [
  1000,   // attempt 1: 1s
  3000,   // attempt 2: 3s
  8000,   // attempt 3: 8s
];
// After 3 failed attempts: show error to user

The Vlexivo server requires confirmed commitment for transaction verification. This means the server waits ~2–4 seconds after broadcast before accepting the payment proof. Plan for this latency in UX design.

Error Handling

Vlexivo returns structured error responses with machine-readable codes. All error bodies follow the same shape:

{ "success": false, "error": { "code": "NONCE_EXPIRED", "message": "Challenge expired — TTL of 15 minutes exceeded" }, "status": 410 }

Challenge Errors

INVALID_API_KEY (401)

API key not found or malformed. Check your X-Api-Key header format: vlx_live_<64-hex>

PRICING_RULE_NOT_FOUND (404)

No matching pricing rule for this resource. Either create a pricing rule in the dashboard or pass auto_register: true with a price.

RATE_LIMITED (429)

Too many challenge requests. Limit: 100/min per IP. Back off and retry after the Retry-After header duration.

VALIDATION_ERROR (422)

Malformed request body. Check that resource_id is a non-empty string and price.amount is a decimal > 0.

Unlock Errors

NONCE_NOT_FOUND (404)

Nonce doesn't exist in the server's nonce store. Either the challenge was never created or the nonce was already consumed. Retry from the challenge step.

NONCE_ALREADY_USED (409)

Nonce has already been consumed. Payment proof was already submitted for this challenge. This is a replay attack — the original transaction was valid.

NONCE_EXPIRED (410)

Challenge TTL exceeded (15 minutes). Generate a new challenge and retry payment.

UNDERPAYMENT (402)

On-chain amount is less than the required price. The buyer sent funds but the amount is insufficient. Full amount must be sent.

TX_NOT_FOUND (404)

Transaction hash not found on-chain. The transaction may not have propagated yet — retry after a few seconds.

TX_FAILED (402)

On-chain transaction failed (meta.err is non-null). Check the blockchain explorer for the specific failure reason.

WRONG_RECIPIENT (402)

Transaction did not transfer funds to the publisher's wallet address. Payment was sent to the wrong address.

NO_CURRENCY_MATCH (402)

No on-chain transfer detected to the publisher's wallet in the specified currency (USDC, USDT, SOL). Check the currency and retry.

Edge Cases

Concurrent Unlock Requests

Two requests arriving simultaneously with the same nonce. Server uses SELECT FOR UPDATE for atomic nonce consumption. First request succeeds (200), second gets 409 Nonce Already Used.

Zero-Confirmation Transactions

Vlexivo requires at least 1 slot confirmation before accepting payment proof. Uncommitted transactions are rejected. No workaround — wait for confirmation.

Wallet Disconnection Mid-Flow

If the user disconnects their wallet during the payment modal, the SDK shows a "wallet disconnected" error and offers a "retry" button that re-triggers the payment flow.

Token Expiry During Read

If an entitlement token expires while the user is reading content (per-call tokens expire in 5 minutes), the next request returns 402 again. The SDK auto-retries — the user sees a brief "re-authenticating" moment.

Publisher Key Rotation

When a publisher rotates their API key, existing SDK instances receive 401 errors. The SDK detects this, alerts the publisher via console.error, and halts automatic retry. The publisher must update their key.

Solana RPC Outage

If the configured Solana RPC endpoint is unreachable or returns errors, verification falls back to a secondary RPC if configured. If no fallback exists, unlock returns 502 Bad Gateway with BLOCKCHAIN_VERIFICATION_ERROR.

Test Mode: While developing, set VLEXIVO_BASE_URL to your test environment and use test API keys. In demo mode, the SDK uses StubVerifier — any well-formed proof is accepted without blockchain verification.

Vlexivo HTTP 402 Technical Specification · v1.0 · 2026-05-22
Questions? legal@vlexivo.online · Full Whitepaper · Pitch Deck