Vlexivo Documentation

HTTP 402 micropayments for any API, article, or AI application. Choose your path:

⚡ API Developer Quickstart

Monetize your API in under 5 minutes. No billing system to build.

1. Get your API key

   Register at vlexivo.online/register. You'll get a key like vlx_live_abc123.... Save it as an environment variable:

   export VLEXIVO_API_KEY=vlx_live_abc123...

2. Install the SDK

   Node.js Python

   npm install @vlexivo/sdk

   pip install vlexivo

3. Add the middleware

   Node.js / Express Python / FastAPI

   const express = require('express');
   const { Vlexivo } = require('@vlexivo/sdk');
   
   const app = express();
   const mp = new Vlexivo({ apiKey: process.env.VLEXIVO_API_KEY });
   
   // Protect any route — $0.01 per call
   app.use('/api/data', mp.protect({ price: '0.01' }));
   
   app.get('/api/data', (req, res) => {
     res.json({ result: 'your data here' });
   });
   
   app.listen(3000);

   from fastapi import FastAPI, Request
   from vlexivo.fastapi import require_payment
   import os
   
   app = FastAPI()
   
   @app.get("/api/data")
   @require_payment(
       api_key=os.environ["VLEXIVO_API_KEY"],
       price={"amount": "0.01", "currency": "USDC"},
       resource_id="/api/data",
   )
   async def get_data(request: Request):
       return {"result": "your data here"}

4. Test it

   # Unpaid request → 402 Payment Required
   curl http://localhost:3000/api/data
   # { "challenge_nonce": "...", "payment_address": "0x...", "amount": "0.01" }
   
   # Paid request (with valid entitlement token)
   curl http://localhost:3000/api/data \
     -H "X-Entitlement: eyJ..."
   # { "result": "your data here" }

✍️ Content Publisher Quickstart

Paywall any article, blog post, or newsletter in 5 minutes.

1. Get your publisher key

   Register at vlexivo.online/register. Your key will look like vlx_live_....

2. Wrap your content

   Wrap the premium portion of your article in a data-vlexivo div:

   <!-- Free preview —show this to everyone -->
   <p>This is the free part of your article...</p>
   
   <!-- Paid content — hidden until payment -->
   <div data-vlexivo
        data-price="0.05"
        data-resource-id="/posts/my-article">
     <p>This is the premium content revealed after payment.</p>
     <p>Can be as long as you like.</p>
   </div>

3. Add the script tag

   <script
     src="https://vlexivo.online/sdk/vlexivo.js"
     data-key="vlx_live_YOUR_KEY_HERE"
     data-auto-paywall="true">
   </script>

   That's it. Vlexivo finds all data-vlexivo elements and gates them automatically.

4. Preview the experience

   Open your article in a browser. You'll see a blurred paywall overlay with a "Unlock for $0.05" button. Click it — the payment modal appears. After payment, the content is revealed instantly.

   Try the live demo to see it in action.

WordPress / Ghost Integration

<!-- Add to your theme's footer (before </body>) -->
<script
  src="https://vlexivo.online/sdk/vlexivo.js"
  data-key="vlx_live_YOUR_KEY_HERE"
  data-auto-paywall="true">
</script>

Then wrap premium content in your posts with the data-vlexivo HTML block. Works with any CMS that lets you add custom HTML.

🏢 Creator Platform Guide

Add direct creator payments to your platform. Pay-per-DM, timed sessions, tips — non-custodial settlement. Your payment processor can cut you off. Vlexivo can't.

Payment Flow

Your platform generates 402 challenges when fans initiate paid actions. The Vlexivo widget renders payment UI — no install required for fans or creators.

Generate a Challenge (Server-side)

# Generate a per-message challenge
curl -X POST https://vlexivo.online/v1/challenge \
  -H "Authorization: Bearer vlx_sec_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "per-message",
    "amount": "1.00",
    "creator_id": "creator_abc",
    "tip_enabled": true
  }'

# Response
{
  "challenge_nonce": "a1b2c3d4-e5f6-...",
  "payment_address": "0xCreatorWallet...",
  "amount": "1.00",
  "currency": "USDC",
  "expires_at": "2026-04-01T14:35:00.000Z"
}

Supported Scope Types for Creator Platforms

Creator Platform API Reference

🤖 AI Agent Guide

Add pay-per-call billing to your AI agent or wrapper app. Headless — no browser, no OAuth, no subscription management.

How AI Agent Billing Works

Python SDK — Headless Agent Client

import os
from vlexivo import AgentClient

# Your agent's wallet key (stored securely in env vars)
client = AgentClient(
    api_key=os.environ["AGENT_WALLET_KEY"],
    auto_fund=True,   # automatically top up wallet from balance
)

# Works like requests — auto-handles 402 flows transparently
response = client.get("https://api.example.com/research", params={"q": "AI trends"})
data = response.json()

# Multi-step agent workflow
with client.session() as session:
    step1 = session.get("https://api.example.com/data/step1")
    step2 = session.post("https://api.example.com/process", json=step1.json())
    # Each step pays only if needed; entitlements are cached for the session

JavaScript / Node.js Agent Client

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

const client = new AgentClient({
  walletKey: process.env.AGENT_WALLET_KEY,
  autoFund: true,
});

// Auto-handles 402 — agent pays and retries transparently
const data = await client.fetch('https://api.example.com/research?q=AI+trends');
const json = await data.json();

// LangChain tool integration
const vlexivoTool = {
  name: 'paid_research_api',
  description: 'Query the research API. Costs $0.01 per call.',
  func: async (query) => {
    const res = await client.fetch(`https://api.example.com/research?q=${query}`);
    return await res.text();
  },
};

Funding Your Agent's Wallet

from vlexivo import AgentClient

client = AgentClient(api_key=os.environ["AGENT_WALLET_KEY"])

# Check balance
balance = await client.get_balance()
print(f"Balance: ${balance.usdc} USDC")

# Fund via API (requires pre-authorized on-ramp)
await client.fund(amount="10.00", currency="USDC")

# Set spending limit per session
client.set_spending_limit("1.00")   # max $1.00 per agent run

Environment Variables for Agents

Architecture Overview

Vlexivo is a three-layer system: the protocol layer (HTTP 402), the verification layer (on-chain), and the entitlement layer (JWT).

Settlement

Publisher balances accumulate in real-time. Settlement to your external wallet is available on-demand (manual) or automatically on a daily schedule (Pro/Enterprise). No minimum payout threshold.

Wallet Architecture

Consumers use a hosted wallet provisioned by Vlexivo — no MetaMask required. The wallet is a server-side ETH keypair encrypted with AES-256-GCM. Consumers top up via Stripe (card → USDC) and pay from balance. Full self-custody is also supported for power users.

Modes

FAQ

Do users need a crypto wallet?

No. Users interact with a hosted wallet provisioned by Vlexivo. They top up with a credit card via Stripe and pay from their USDC balance. No MetaMask, no seed phrases, no crypto knowledge required. Power users can optionally use their own external wallet.

What currencies are supported?

USDC (Ethereum mainnet + Base L2), native ETH, USDT, and DAI. USDC on Base is recommended — low fees, instant finality, stable price. Solana support (USDC/SOL) is available in production mode.

Is there a minimum payment amount?

The minimum is $0.0001 (0.0001 USDC). There's no maximum. You set whatever price makes sense for your content.

How do payouts work?

Revenue accumulates in your publisher balance. On Free, you request manual payouts (no minimum). On Pro, payouts run daily automatically. Funds arrive as USDC to your registered wallet address.

What happens if payment fails?

The consumer sees an error in the payment modal. No charge is made. The 402 flow is stateless — they can retry immediately.

Is replay protection built in?

Yes. Each challenge nonce is single-use, expires after 5 minutes, and is stored in a server-side nonce registry. Reusing a nonce returns a 409 Conflict. See Replay Protection for details.

Can I use Vlexivo alongside Stripe or Patreon?

Yes. Vlexivo is additive — it doesn't replace your existing billing. Many publishers use Stripe for subscriptions and Vlexivo for one-time article unlocks or API calls from non-subscribers.

Is the source code available?

The JS and Python SDKs are open-source on GitHub. The server protocol engine is proprietary.

Overview

HTTP 402 micropayments for any API, article, or AI application. Add a paywall in 3 lines. No crypto knowledge required.

How It Works

Vlexivo implements the HTTP 402 ("Payment Required") status code — the forgotten standard for web payments.

Problems We Solve

The internet's payment infrastructure is broken in six fundamental ways. Vlexivo fixes each one at the protocol level.

Quick Start

Get from zero to paid API in under 5 minutes.

1. Register as a publisher

   Sign up at vlexivo.online/register or via the API:

   curl -X POST https://vlexivo.online/api/publishers \
     -H "Content-Type: application/json" \
     -d '{
       "name": "My API",
       "wallet_address": "0xYourWalletAddress",
       "domain": "api.example.com"
     }'
   # { "api_key": "vlx_live_...", "publisher": { "id": 1, ... } }

   Save your api_key — you'll need it in the next step.

2. Install the SDK and add the middleware

   Node.js Python cURL

   npm install vlexivo

   const vlexivo = require('vlexivo');
   
   app.use('/api/premium', vlexivo.protect({
     apiKey: process.env.VLEXIVO_API_KEY,
     price: { amount: '0.001', currency: 'USDC' },
   }));

   pip install vlexivo

   from vlexivo.fastapi import require_payment
   
   @app.get("/api/premium")
   @require_payment(price="0.001", resource_id="/api/premium")
   async def premium(request: Request):
       return {"data": "premium content"}

   # Step 1: Generate a challenge
   curl -X POST https://vlexivo.online/v1/challenge \
     -H "X-Api-Key: vlx_live_..." \
     -H "Content-Type: application/json" \
     -d '{"resource_id":"/api/report","scope_type":"per-call","price":{"amount":"0.001","currency":"USDC"}}'
   
   # Step 2: Return the challenge as 402 to the consumer
   # Step 3: Consumer pays on-chain, POSTs to /v1/unlock
   # Step 4: Validate the returned entitlement token
   curl -X POST https://vlexivo.online/api/entitlements/validate \
     -H "X-Api-Key: vlx_live_..." \
     -H "Content-Type: application/json" \
     -d '{"token":"eyJ...","resource_id":"/api/report"}'

3. Add the browser SDK

   <script src="https://vlexivo.online/sdk/vlexivo.js"></script>
   <script>
     Vlexivo.init({ autoIntercept: true });
   </script>

   That's it. Vlexivo.js auto-intercepts all fetch() calls and shows the payment modal when a 402 is received.

JavaScript / Node.js SDK

Installation

npm install vlexivo

Requires Node.js ≥ 18 (uses built-in fetch). Express ≥ 4 as a peer dependency.

Basic Usage

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

const app = express();

// Protect all routes under /api/premium
app.use('/api/premium', vlexivo.protect({
  apiKey: process.env.VLEXIVO_API_KEY,
  price: { amount: '0.01', currency: 'USDC' },
}));

// Your protected endpoint
app.get('/api/premium/report', (req, res) => {
  const { entitlement } = req.vlexivo;
  res.json({
    data: 'Your premium report',
    paid_by: entitlement.buyer_wallet,
  });
});

All Options

vlexivo.protect({
  // Required
  apiKey: 'vlx_live_...',                // Your publisher API key

  // Default pricing
  price: {
    amount: '0.01',                     // Decimal string amount
    currency: 'USDC',                   // ETH | USDC | USDT | DAI
  },

  // Scope type (default: 'per-call')
  scope_type: 'per-call',               // per-call | per-article | per-message | per-session | tip

  // Per-resource pricing overrides
  resources: {
    '/api/reports/daily': {
      price: { amount: '0.05', currency: 'USDC' },
    },
    '/api/chat': {
      price: { amount: '0.001', currency: 'ETH' },
      scope_type: 'per-message',
    },
  },

  // Custom resource ID extractor (default: req.path)
  resourceId: (req) => req.path,

  // Vlexivo API URL (default: 'https://vlexivo.online')
  vlexivoUrl: 'https://vlexivo.online',

  // Auto-register pricing rules (default: true when price is set)
  autoRegister: true,

  // Callbacks
  onSuccess: (req, entitlement) => {},  // Called after valid token
  onChallenge: (req, resourceId) => {}, // Called when 402 is issued
})

TypeScript

import { protect, ProtectOptions, ValidatedEntitlement } from 'vlexivo';

app.get('/api/premium', protect({ apiKey: process.env.VLEXIVO_API_KEY! }), (req, res) => {
  const { entitlement } = req.vlexivo!;
  // entitlement is typed as ValidatedEntitlement
  console.log(entitlement.buyer_wallet, entitlement.scope_type);
  res.json({ ok: true });
});

Python SDK

Installation

pip install vlexivo

# With framework extras
pip install vlexivo[fastapi]   # FastAPI + Starlette middleware
pip install vlexivo[django]    # Django middleware + decorators
pip install vlexivo[jwt]       # PyJWT for local token verification
pip install vlexivo[async]     # aiohttp for async requests
pip install vlexivo[all]       # Everything

FastAPI

from fastapi import FastAPI, Request
from vlexivo.fastapi import require_payment, VlexivoMiddleware

app = FastAPI()

# Option 1: Decorator (per-endpoint)
@app.get("/api/premium/report")
@require_payment(
    api_key=os.environ["VLEXIVO_API_KEY"],
    price={"amount": "0.05", "currency": "USDC"},
    resource_id="/api/premium/report",
)
async def daily_report(request: Request):
    # request.state.vlexivo contains the entitlement
    return {"data": "premium report"}

# Option 2: Middleware (protects all routes under a prefix)
app.add_middleware(
    VlexivoMiddleware,
    api_key=os.environ["VLEXIVO_API_KEY"],
    protected_paths=["/api/premium"],
    default_price={"amount": "0.01", "currency": "USDC"},
)

Django

from django.http import JsonResponse
from vlexivo.django import require_payment

@require_payment(
    api_key=settings.VLEXIVO_API_KEY,
    price={"amount": "0.05", "currency": "USDC"},
    resource_id="/api/reports/daily",
)
def daily_report(request):
    entitlement = request.vlexivo
    return JsonResponse({"data": "premium report"})

Django REST Framework

from vlexivo.drf import VlexivoPermission

class PremiumReportView(APIView):
    permission_classes = [VlexivoPermission]
    vlexivo_price = {"amount": "0.05", "currency": "USDC"}

    def get(self, request):
        return Response({"data": "premium report"})

Raw Client (any framework)

from vlexivo import VlexivoClient, Price

client = VlexivoClient(api_key=os.environ["VLEXIVO_API_KEY"])

# Validate a token from a request header
token = request.headers.get("X-Entitlement") or request.headers.get("Authorization", "").removeprefix("Bearer ")

result = await client.validate_token(
    token=token,
    resource_id="/api/premium/data",
)

if result.valid:
    # serve content
    pass
else:
    # generate challenge and return 402
    challenge = await client.create_challenge(
        resource_id="/api/premium/data",
        scope_type="per-call",
        price=Price(amount="0.01", currency="USDC"),
    )
    return Response(challenge.dict(), status_code=402)

Browser SDK

Zero-dependency vanilla JS. Intercepts 402s, shows the payment modal, caches tokens in localStorage.

Installation

<!-- CDN -->
<script src="https://vlexivo.online/sdk/vlexivo.js"></script>

<!-- Or self-host: download from /sdk/vlexivo.js -->

Initialize

Vlexivo.init({
  // Auto-intercept all fetch() calls (recommended)
  autoIntercept: true,

  // Callbacks
  onTokenIssued: (token, challenge) => {
    console.log('Payment complete, token:', token);
  },
  onPaymentCancelled: () => {
    console.log('User cancelled payment');
  },
});

API Reference

Manual Usage (without autoIntercept)

const response = await fetch('/api/premium/data');

if (response.status === 402) {
  const token = await Vlexivo.handleChallenge(response);
  if (token) {
    // Retry with token
    const data = await fetch('/api/premium/data', {
      headers: { 'X-Entitlement': token }
    });
  }
}

API Reference

{
  "resource_id": "/api/reports/daily",   // required — identifies the resource
  "scope_type": "per-call",              // optional — defaults to "per-call"
  "price": {                             // optional — omit to use saved pricing rule
    "amount": "0.01",
    "currency": "USDC"
  },
  "auto_register": true,                 // optional — save price as a reusable rule
  "require_age": 18                      // optional — age gate (13–100)
}

{
  "status": 402,
  "protocol": "vlexivo/1.0",
  "publisher_id": "42",
  "resource_id": "/api/reports/daily",
  "scope_type": "per-call",
  "price": { "amount": "0.01", "currency": "USDC" },
  "accept_currencies": ["ETH", "USDC", "SOL", "USDT", "DAI"],
  "payment_address": "0xYour...WalletAddress",
  "challenge_nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "expires_at": "2026-04-01T14:45:00.000Z",
  "unlock_url": "https://vlexivo.online/v1/unlock"
}

curl -X POST https://vlexivo.online/v1/challenge \
  -H "X-Api-Key: vlx_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "resource_id": "/api/reports/daily",
    "scope_type": "per-call",
    "price": { "amount": "0.01", "currency": "USDC" }
  }'

Publishers API

{
  "name": "My API",
  "wallet_address": "0xYourPayoutWallet",
  "domain": "api.example.com"
}

Pricing Rules

Pricing rules define how much to charge for each resource. You can set them upfront or use auto_register: true to create them on the fly.

{
  "scope_type": "per-call",
  "resource_pattern": "/api/reports/.*",
  "price_amount": "0.01",
  "price_currency": "USDC"
}

Webhooks

Get notified in real-time when payments are completed and entitlements are issued or revoked.

Register a webhook endpoint

curl -X POST https://vlexivo.online/api/webhooks \
  -H "X-Api-Key: vlx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-api.com/webhooks/vlexivo",
    "event_types": ["payment.completed", "entitlement.issued"],
    "secret": "your-webhook-secret"
  }'

Event payload

{
  "event": "payment.completed",
  "timestamp": "2026-04-01T14:30:00.000Z",
  "data": {
    "entitlement_id": 99,
    "resource_id": "/api/reports/daily",
    "buyer_wallet": "0xdef456...",
    "amount": "0.01",
    "currency": "USDC",
    "tx_hash": "0xabc123..."
  }
}

Verify signatures

All webhook payloads are signed with X-Vlexivo-Signature: t={timestamp},v1={hmac} using HMAC-SHA256.

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const [tPart, v1Part] = signature.split(',');
  const timestamp = tPart.replace('t=', '');
  const receivedHmac = v1Part.replace('v1=', '');

  const expectedHmac = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${payload}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(receivedHmac),
    Buffer.from(expectedHmac)
  );
}

Event types

Agent API

Headless machine-to-machine endpoints for AI agents. Auth via X-Agent-Key header — no browser, no OAuth, no on-chain transaction required.

{
  "publisher_api_key": "vlx_live_...",   // required — identifies the publisher
  "resource_id": "/api/reports/daily", // optional, defaults to "*"
  "scope_type": "per-call",            // optional, defaults to "per-call"
  "metadata": {}                       // optional context
}

{
  "success": true,
  "entitlement": "eyJhbGciOiJIUzI1NiJ9...",  // pass as X-Entitlement on the target API
  "expires_at": "2026-04-12T12:15:00.000Z",
  "cost_micro_usd": 1000,
  "cost_usd": "0.001000",
  "balance_cents": 4999,
  "balance_usd": "49.9900",
  "resource_id": "/api/reports/daily",
  "scope_type": "per-call",
  "latency_ms": 42
}

{
  "success": false,
  "error": "Insufficient balance to pay for this resource",
  "code": "INSUFFICIENT_BALANCE",
  "balance_cents": 0,
  "balance_usd": "0.0000",
  "required_cents": 1,
  "topup_url": "https://vlexivo.online/dashboard"
}

// Example: agent pays then calls the target API
const { AgentClient } = require('@vlexivo/sdk');
const client = new AgentClient({ walletKey: process.env.AGENT_WALLET_KEY });

// auto-handles the pay+retry loop transparently
const data = await client.fetch('https://api.example.com/reports/daily');
console.log(await data.json());

Pricing & Revenue

You set the price. Vlexivo takes 15%. No monthly fees, no minimums.

Publisher-Set Pricing

You control the price for every resource — per-call, per-article, per-session. There's no minimum or maximum. Common patterns:

Revenue Split

Settlement

Payments accumulate in your publisher balance in real-time. Payouts work as follows:

Funds are sent as USDC to the payout wallet address registered on your account. No banking setup required — just a crypto wallet address.

Plan Tiers

Scope Types

Scope types control how entitlement tokens are consumed and how access is metered.

Tips and Donations Flow

Tips are user-initiated — no 402 challenge required. The user clicks a tip button; Vlexivo routes payment directly to the creator's wallet.

// Server: register tip endpoint
app.post('/api/tip/:creatorId', vlexivo.acceptTip({
  apiKey: process.env.VLEXIVO_API_KEY,
  minAmount: '0.25',
  maxAmount: '100.00',
}));

// Browser: tip button
Vlexivo.tip({
  creatorId: 'alice',
  suggestedAmount: '5.00',
  message: 'Great content',   // optional
});

Creator Platform Integration (Track 2)

If you run a creator platform: your platform generates a 402 challenge when a fan initiates a paid action (DM, session, etc). The Vlexivo widget handles payment UI — no install required for fans.

Error Codes

All error responses return JSON with a code field and a human-readable message (or error) field. Error objects for unlock/payment failures include status, resource_id, scope_type, and reason.

Challenge Errors (POST /v1/challenge, POST /v1/consumer-challenge)

Unlock / Payment Errors (POST /v1/unlock)

Agent API Errors (POST /v1/agent/pay)

General

Rate Limiting

All API endpoints are protected by in-memory sliding-window rate limits. Exceeding any limit returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

Per-Endpoint Limits

Response Headers

Every rate-limited response includes these headers regardless of whether the limit was hit:

Agent API endpoints use per-key minute and day windows and return additional headers: X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day.

429 Response Body

{
  "success": false,
  "error": "Too many requests. Please slow down.",
  "code": "RATE_LIMITED",
  "retry_after": 42
}

Best Practices

• Check X-RateLimit-Remaining to back off proactively before hitting 0.
• On 429, wait exactly Retry-After seconds before retrying — do not hammer with immediate retries.
• Publisher server-to-server calls to /v1/challenge are generous at 60/min. If your traffic exceeds this, batch challenges client-side or contact support for higher limits.
• Agent key limits are configurable per key in the dashboard. Increase rate_limit_per_minute and rate_limit_per_day for high-volume AI pipelines.

Replay Protection

Every challenge has a UUID nonce that:

• Expires after 15 minutes
• Can only be used once (atomic SELECT FOR UPDATE prevents double-spend)
• Is tied to a specific publisher and resource

Creator SDK

Extended features for content creators: tips, fan leaderboards, subscriptions, and gated chat.

Server-side

const { creatorSdk } = require('vlexivo/creator');

// Protect a chat message (per-message pricing)
app.use('/api/chat', creatorSdk.protectMessage({
  apiKey: process.env.VLEXIVO_API_KEY,
  price: { amount: '0.001', currency: 'USDC' },
}));

// Protect a subscription resource (monthly)
app.use('/api/newsletter', creatorSdk.protectSubscription({
  apiKey: process.env.VLEXIVO_API_KEY,
  interval: 'monthly',
  price: { amount: '5.00', currency: 'USDC' },
}));

Browser — tip modal

<script src="https://vlexivo.online/sdk/vlexivo-creator.js"></script>

<!-- Auto-wire a tip button -->
<button data-vlx-tip data-vlx-creator="alice" data-vlx-suggested="5.00">
  ☕ Tip Alice
</button>

Examples

Pay-per-call API (Express)

const express = require('express');
const vlexivo = require('vlexivo');
require('dotenv').config();

const app = express();
app.use(express.json());

// Add the browser SDK hint header
app.use((req, res, next) => {
  res.setHeader('X-Vlexivo-SDK', 'https://vlexivo.online/sdk/vlexivo.js');
  next();
});

// Protect all premium routes
app.use('/api/premium', vlexivo.protect({
  apiKey: process.env.VLEXIVO_API_KEY,
  price: { amount: '0.001', currency: 'USDC' },
}));

// Your endpoints
app.get('/api/premium/weather', (req, res) => {
  res.json({ city: 'Tokyo', temp: 22, condition: 'Sunny' });
});

app.get('/api/premium/joke', (req, res) => {
  res.json({ joke: 'Why do programmers prefer dark mode? Light attracts bugs.' });
});

app.listen(3000, () => console.log('API running on :3000'));

Pay-per-article Blog (HTML)

<!DOCTYPE html>
<html>
<head>
  <script src="https://vlexivo.online/sdk/vlexivo.js"></script>
</head>
<body>
  <div id="preview">
    <h1>Premium Article Title</h1>
    <p>Introduction paragraph visible to everyone...</p>
    <button id="unlock-btn">Read full article — $0.50 USDC</button>
  </div>

  <div id="content" style="display:none">
    <!-- Full article content here -->
  </div>

  <script>
    Vlexivo.init({ autoIntercept: true });

    document.getElementById('unlock-btn').onclick = async () => {
      const response = await fetch('/api/articles/premium-article', {
        headers: { 'Accept': 'application/json' }
      });
      // Vlexivo.js handles the 402 automatically if autoIntercept: true
      if (response.ok) {
        const { html } = await response.json();
        document.getElementById('content').innerHTML = html;
        document.getElementById('content').style.display = 'block';
        document.getElementById('preview').style.display = 'none';
      }
    };
  </script>
</body>
</html>

AI Chatbot (per-message pricing)

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

const app = express();
app.use(express.json());

app.use('/api/chat/message', vlexivo.protect({
  apiKey: process.env.VLEXIVO_API_KEY,
  price: { amount: '0.002', currency: 'USDC' },
  scope_type: 'per-message',
}));

app.post('/api/chat/message', async (req, res) => {
  const { message } = req.body;
  const { entitlement } = req.vlexivo;

  // Call your AI provider
  const reply = await callOpenAI(message);

  res.json({
    reply,
    paid_by: entitlement.buyer_wallet,
    amount_paid: '0.002 USDC',
  });
});

WordPress Plugin

The Vlexivo WordPress plugin lets you gate any post, page, or WooCommerce product behind a crypto micropayment — no coding required.

Installation

1. Download vlexivo-wp.zip from your publisher dashboard → Integration → WordPress plugin
2. In WordPress Admin: Plugins → Add New → Upload Plugin
3. Upload vlexivo-wp.zip → Install → Activate
4. Go to Settings → Vlexivo and paste your API key

Configuration

Gating a Post

In the WordPress block editor, add the Vlexivo Paywall block anywhere in your post. Everything below the block will be locked until payment.

<!-- Shortcode alternative -->
[vlexivo_gate price="0.50" currency="USDC" scope="per-article"]

Your premium content goes here. Readers must pay to see this.

[/vlexivo_gate]

Per-Post Price Override

In the post sidebar → Vlexivo panel:

• Enable paywall: toggle on
• Price: enter custom amount (leave blank for default)
• Currency: USDC / ETH / SOL
• Resource ID: auto-set to post slug (/p/{post-id})

WooCommerce Integration

Gate digital downloads or membership content with a one-time crypto payment instead of (or alongside) Stripe.

// functions.php — custom gate check
add_filter('vlexivo_should_gate', function($gate, $post_id) {
    // Gate only posts in "Premium" category
    return has_category('premium', $post_id);
}, 10, 2);

Python SDK — Publisher Side

Use the Vlexivo Python SDK to protect Flask/Django/FastAPI routes or integrate programmatic API metering from any Python backend.

Install

pip install vlexivo

Flask — API Metering

from flask import Flask, jsonify
from vlexivo import protect

app = Flask(__name__)

# Decorate any route to require payment
@app.route("/api/premium/data")
@protect(
    api_key="vlx_sec_...",
    price={"amount": "0.001", "currency": "USDC"},
    scope="per-call"
)
def premium_data():
    return jsonify({"data": "Your premium content"})

if __name__ == "__main__":
    app.run()

Django Middleware

# settings.py
MIDDLEWARE = [
    ...
    'vlexivo.django.VlexivoMiddleware',
]

VLEXIVO = {
    'API_KEY': os.environ['VLEXIVO_API_KEY'],
    'DEFAULT_PRICE': {'amount': '0.001', 'currency': 'USDC'},
    'DEFAULT_SCOPE': 'per-call',
}

# views.py
from vlexivo.django import vlexivo_required

@vlexivo_required(price='0.50', scope='per-article')
def premium_article(request, slug):
    article = Article.objects.get(slug=slug)
    return JsonResponse({"content": article.body})

FastAPI

from fastapi import FastAPI, Depends
from vlexivo.fastapi import VlexivoDep

app = FastAPI()

vlexivo = VlexivoDep(
    api_key=os.environ["VLEXIVO_API_KEY"],
    price={"amount": "0.001", "currency": "USDC"},
)

@app.get("/api/premium/report")
async def get_report(access=Depends(vlexivo.require)):
    return {"data": "premium report", "buyer": access.buyer_wallet}

Raw REST (any Python client)

No SDK required — use requests directly against the Vlexivo API.

import requests, os

VLEXIVO_BASE = "https://vlexivo.polsia.app"
API_KEY = os.environ["VLEXIVO_API_KEY"]

# 1. Generate a challenge for a buyer
challenge = requests.post(
    f"{VLEXIVO_BASE}/v1/challenge",
    headers={"X-Api-Key": API_KEY},
    json={
        "resource_id": "/api/reports/daily",
        "scope_type": "per-call",
        "price_override": {"amount": "0.01", "currency": "USDC"},
    }
).json()

print(challenge["nonce"])  # e.g. "vlx_nonce_abc123..."

# 2. Validate an entitlement token sent by the buyer
validation = requests.post(
    f"{VLEXIVO_BASE}/api/entitlements/validate",
    headers={"X-Api-Key": API_KEY},
    json={
        "token": request_headers["X-Entitlement"],
        "resource_id": "/api/reports/daily",
    }
).json()

if validation["valid"]:
    return {"data": "your premium data"}

FAQ & Troubleshooting

Why am I getting 400 NO_PRICING_RULE?

You haven't created a pricing rule for this resource yet. Log in to your publisher dashboard → Resources → Add Rule. Use * as the resource pattern to match all routes.

My challenge returns 401 — is my API key wrong?

Check that you're sending the secret key (vlx_sec_…), not the publishable key (vlx_pub_…). The challenge endpoint requires the secret key. Publishable keys are for browser SDKs only.

The payment popup doesn't appear on mobile

Ensure your page doesn't block popups. The Vlexivo widget opens in a popup window (window.open). On iOS Safari, popups are only allowed from direct user gesture handlers (click, touchend). Make sure Vlexivo.init() is called from a click handler, not on page load.

I paid but didn't get a JWT entitlement

This usually means on-chain verification is still pending. The unlock endpoint polls the blockchain for up to 30 seconds. If the tx confirms after that window, use the retry endpoint:

curl -X POST https://vlexivo.polsia.app/v1/unlock/retry \
  -H "Content-Type: application/json" \
  -d '{"nonce": "vlx_nonce_...", "tx_hash": "0x..."}'

How do I test without spending real funds?

Set DEMO_MODE=true in your environment. In demo mode, Vlexivo skips on-chain verification and issues a test JWT immediately. Demo entitlements are marked with "demo": true in the payload. Never use demo mode in production.

Can I issue refunds?

Blockchain transactions are irreversible. Vlexivo doesn't support automatic refunds. If you need to compensate a buyer, you can send USDC directly from your settlement wallet. We recommend offering a "try before buy" preview for article content, and clearly communicating no-refund policies for digital goods.

What if my webhook keeps failing?

Vlexivo retries failed webhook deliveries with exponential backoff: 1min, 5min, 30min, 2hr, 8hr. To debug, check your webhook delivery logs in Dashboard → Webhooks → Deliveries. Common issues:

• Endpoint returns non-2xx status → fix your webhook handler to return 200
• Request times out (>10s) → process asynchronously, return 200 immediately
• Signature verification fails → ensure you're using the correct signing secret from the dashboard

My entitlement token expires too fast

Default TTL for per-call is 300 seconds. For per-article it's 24 hours. For per-session, you set the duration when creating the pricing rule. Extend via the duration_seconds field on your pricing rule — or request a per-article scope for longer-lived access.

Rate limits — what are they?

Rate limit responses return HTTP 429 with a Retry-After header. If you're hitting limits in production, contact us to discuss higher tiers.

Still stuck?

Email support@vlexivo.io with your publisher ID, the exact endpoint you're calling, and the error response body. We respond within 24 hours on weekdays.