Vend 🎰

Monetizable Blockchain Data API via x402 & Alchemy

Blockchain data on demand - like a vending machine. Insert payment (USDC), get instant access to NFTs, tokens, transactions, and more. No accounts, no API keys, just pay per query.

Vend Project Structure

Vend Server API (Express + x402):

Transaction History - Asset transfers (ETH, ERC20, ERC721, ERC1155)
NFT Data - Owned NFTs, metadata, floor prices
Token Balances - ERC20 holdings and metadata
Webhooks - Real time notifications for new transactions
x402 Payments - USDC micropayments with on chain verification
Production Ready - Deploy to mainnet

Vend CLI Tool (@asimfiles/vend-cli):

8 Commands - query, nfts, tokens, balance, info, config, saved, webhook
Output Formats - Table, JSON, CSV
Saved Queries - Create reusable query templates
Automatic Payments - Optional wallet integration for hands free payments
Multi-Network - Base, Ethereum, Polygon, Arbitrum, Optimism

Powered by: x402-onchain-verification - Open-source middleware for direct on-chain payment verification. No facilitator servers needed. Built by Alchemy.

┌─────────────────────────────────┐
│         🎰 VEND                 │
│   Blockchain Data Vending       │
│                                 │
│  [Insert 0.01 USDC]             │
│         ↓                       │
│  [Get Data]                     │
└─────────────────────────────────┘

Fork & Deploy in 5 Minutes

Vend is production-ready with real on-chain payment verification.

# 1. Fork & clone
git clone https://github.com/yourusername/vend.git
cd vend && npm install

# 2. Configure (get free Alchemy key from dashboard.alchemy.com)
cp .env.example .env
# Edit .env: Add ALCHEMY_API_KEY and PAYMENT_ADDRESS

# 3. Deploy to mainnet
export PAYMENT_NETWORK=base-mainnet
export NODE_ENV=production
npm start

# 4. Done! 🎉 Accept USDC payments on Base

Real USDC payments work immediately - no additional setup needed. Payment verification happens automatically on chain via Alchemy.

📖 Full Deployment Guide | Supports Base, Ethereum, Polygon, Arbitrum, Optimism

##Why Vend?

Traditional APIs:

Sign up for account ❌
Manage API keys ❌
Monthly subscriptions ❌
Rate limits ❌

Vend:

Pay USDC → Get data ✅
That's it. 💰

Perfect for:

AI Agents - No API key management, just send USDC
Developers - Pay per use, no subscriptions, create buisnesses from your API key
Data Analytics - Access blockchain data on demand
Researchers - Query without account setup

How x402 Works

x402 is an open protocol that revives the HTTP 402 Payment Required status code for instant micropayments.

The Flow

┌─────────────┐                           ┌─────────────┐
│   Client    │                           │    Vend     │
└──────┬──────┘                           └──────┬──────┘
       │                                          │
       │  1. GET /api/nfts?owner=0x...           │
       │─────────────────────────────────────────>│
       │                                          │
       │  2. 402 Payment Required                 │
       │     {                                    │
       │       recipient: "0x742d...",            │
       │       amount: "0.01 USDC",               │
       │       network: "base-mainnet"            │
       │     }                                    │
       │<─────────────────────────────────────────│
       │                                          │
       │  3. [Client sends 0.01 USDC on Base]    │
       │                                          │
       │  4. GET /api/nfts?owner=0x...           │
       │     Header: X-Payment-Hash: 0xabc123... │
       │─────────────────────────────────────────>│
       │                                          │
       │     [Vend verifies payment on-chain]    │
       │     [Vend queries Alchemy for NFTs]     │
       │                                          │
       │  5. 200 OK                               │
       │     { nfts: [...] }                      │
       │<─────────────────────────────────────────│

API Endpoints/Calls

All endpoints require USDC payment via x402. Payment is verified on chain before returning data.

Transaction History

GET /api/transfers?address=0x...&category=erc20

# Returns
{
  "payment": {
    "hash": "0xabc123...",
    "amount": "0.01",
    "currency": "USDC",
    "verified": true
  },
  "data": {
    "transfers": [
      {
        "blockNum": "0x163fcf9",
        "hash": "0x5a1882bb...",
        "from": "0xd8da6bf...",
        "to": "0x742d35cc...",
        "value": 1000000,
        "asset": "USDC",
        "category": "erc20"
      }
    ],
    "totalCount": 1523,
    "pageKey": "..."
  }
}

Price: $0.01 USDC Categories: external, internal, erc20, erc721, erc1155

NFT Ownership

GET /api/nfts?owner=0x...

# Returns NFTs owned by address

Price: $0.01 USDC Features: Pagination, metadata, contract filtering

NFT Metadata

GET /api/nfts/metadata?contractAddress=0x...&tokenId=1

# Returns single NFT metadata

Price: $0.005 USDC

NFT Floor Price

GET /api/nfts/floor-price?contractAddress=0x...

# Returns collection floor price

Price: $0.005 USDC Source: OpenSea, LooksRare

Token Balances

GET /api/tokens/balances?address=0x...

# Returns all ERC20 token balances

Price: $0.01 USDC

Token Metadata

GET /api/tokens/metadata?contractAddress=0x...

# Returns token info (name, symbol, decimals, logo)

Price: $0.005 USDC

Webhooks

Create webhook subscriptions to get notified of new transactions:

# Create webhook
POST /api/webhooks
{
  "address": "0x...",
  "webhookUrl": "https://webhook.site/...",
  "categories": ["erc20", "erc721"]
}

# List webhooks
GET /api/webhooks

# Delete webhook
DELETE /api/webhooks/:id

Price: Free (no payment required for webhook management) Monitoring: Server checks every 5 minutes for new transactions

🛠️ CLI Usage

Install globally:

npm install -g @asimfiles/vend-cli

Or use with npx:

npx @asimfiles/vend-cli --help

Query Transaction History

# Table format (default)
vend query https://yourapi.com/api/transfers \
  --address 0xVitalik... \
  --tx-hash demo

# JSON format
vend query https://yourapi.com/api/transfers \
  --address 0xVitalik... \
  --format json

# CSV format (pipe to file)
vend query https://yourapi.com/api/transfers \
  --address 0xVitalik... \
  --format csv > transfers.csv

Query NFTs

vend nfts https://yourapi.com/api/nfts \
  --owner 0xVitalik... \
  --tx-hash demo \
  --format table

Query Token Balances

vend tokens https://yourapi.com/api/tokens/balances \
  --address 0xVitalik... \
  --tx-hash demo

Automatic Payments

# Provide private key for automatic USDC payments
vend query https://yourapi.com/api/transfers \
  --address 0xVitalik... \
  --wallet 0xYourPrivateKey

# No manual payment needed! CLI sends USDC automatically

Saved Queries

# Create a saved query
vend saved create whale-watch
# Interactive wizard prompts for details

# Run saved query
vend saved run whale-watch

# List saved queries
vend saved list

# Show query details
vend saved show whale-watch

# Delete query
vend saved delete whale-watch

Webhooks

# Create webhook
vend webhook create https://yourapi.com/api/webhooks \
  --address 0xVitalik... \
  --notify https://webhook.site/your-webhook

# List webhooks
vend webhook list https://yourapi.com/api/webhooks

# Delete webhook
vend webhook delete https://yourapi.com/api/webhooks \
  --id wh_abc123

All CLI Commands

Command	Description
`query`	Query transaction history
`nfts`	Query NFT ownership
`tokens`	Query token balances
`balance`	Get token balances (alias)
`info`	Get endpoint info (no payment)
`config`	Manage CLI configuration
`saved`	Manage saved queries
`webhook`	Manage webhooks

Run vend <command> --help for detailed usage.

Deployment

✅ Production Ready! Vend includes real on-chain USDC payment verification using x402-onchain-verification. Deploy to mainnet now!

Complete Deployment Guide →

The deployment guide includes:

Testnet setup (Base Sepolia) for testing
Mainnet configuration (Base, Ethereum, Polygon, etc.)
Payment verification testing
Security hardening
Production checklist

Quick Deploy Options

Railway

npm i -g @railway/cli
railway login
railway up  # Add env vars in dashboard

Render

Push to GitHub
Connect on Render
Add environment variables
Deploy!

Docker

docker build -t vend .
docker run -p 3000:3000 \
  -e ALCHEMY_API_KEY=your_key \
  -e PAYMENT_ADDRESS=0x... \
  -e PAYMENT_NETWORK=base-mainnet \
  -e NODE_ENV=production \
  vend

VPS (PM2)

npm i -g pm2
pm2 start src/index.js --name vend
pm2 save
pm2 startup

Environment Configuration

Development (Base Sepolia Testnet):

PAYMENT_NETWORK=base-sepolia
NODE_ENV=development

Production (Base Mainnet):

PAYMENT_NETWORK=base-mainnet
NODE_ENV=production

See DEPLOYMENT.md for complete configuration guide.

Hypothetical Economics

Development (Free)

Alchemy: 300M compute units/month
~2M queries/month
Cost: $0

Production

Queries/Day	Alchemy Cost	Revenue @ $0.01	Profit
1,000	$49/mo	$300/mo	$251/mo
10,000	$199/mo	$3,000/mo	$2,801/mo
100,000	$499/mo	$30,000/mo	$29,501/mo

Architecture

┌──────────────────────────────────────────────┐
│                   Client                      │
│  (CLI, cURL, Browser, AI Agent)               │
└───────────────────┬──────────────────────────┘
                    │
              HTTP + x402
                    │
┌───────────────────┴──────────────────────────┐
│              Vend API Server                  │
│                                               │
│  ┌─────────────────────────────────────┐    │
│  │  x402 Payment Middleware            │    │
│  │  • Check for X-Payment-Hash header  │    │
│  │  • Verify USDC payment on-chain     │    │
│  │  • Parse Transfer events            │    │
│  │  • Validate amount & recipient      │    │
│  └─────────────────────────────────────┘    │
│                    │                          │
│  ┌─────────────────┴─────────────────┐      │
│  │  Express Routes                    │      │
│  │  • /api/transfers                  │      │
│  │  • /api/nfts                       │      │
│  │  • /api/tokens                     │      │
│  │  • /api/webhooks                   │      │
│  └────────────────────────────────────┘      │
└───────────────────┬──────────────────────────┘
                    │
           ┌────────┴─────────┐
           │                  │
    ┌──────┴──────┐    ┌──────┴──────┐
    │  Alchemy    │    │    Base     │
    │     SDK     │    │  Blockchain │
    │             │    │             │
    │  • NFTs     │    │ • Verify    │
    │  • Tokens   │    │   USDC      │
    │  • Transfers│    │   payments  │
    └─────────────┘    └─────────────┘

Key Components

x402 Middleware (src/middleware/payment.js) - Handles 402 responses and verification
USDC Verifier (packages/x402-onchain-verification) - On-chain payment verification
Alchemy Service (src/services/alchemy.js) - Blockchain data queries
Routes (src/routes/) - API endpoint handlers
CLI (packages/vend-cli) - Command-line interface

Security

✅ On-chain payment verification (no trust required)
✅ ERC20 Transfer event parsing
✅ Amount and recipient validation
✅ HTTPS support
✅ Rate limiting ready
✅ Input validation
✅ No private keys stored on server

Documentation

Getting Started - Setup guide
x402 Integration - Payment protocol deep dive
Alchemy Guide - Advanced blockchain queries
Deployment - Go to production
CLI Guide - Command line usage
Value Prop - Why Vend?

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

📝 License

MIT License - see LICENSE for details.

Vend - Insert payment, get data. 🎰💰

Name		Name	Last commit message	Last commit date
docs		docs
packages		packages
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
DEPLOYMENT.md		DEPLOYMENT.md
Dockerfile		Dockerfile
LICENSE		LICENSE
PAYMENT_VERIFICATION_IMPLEMENTATION.md		PAYMENT_VERIFICATION_IMPLEMENTATION.md
README.md		README.md
SETUP_GUIDE.md		SETUP_GUIDE.md
START_HERE.md		START_HERE.md
UNDERSTANDING_ARCHITECTURE.md		UNDERSTANDING_ARCHITECTURE.md
VALUE_PROPOSITION.md		VALUE_PROPOSITION.md
configure.sh		configure.sh
demo.js		demo.js
docker-compose.yml		docker-compose.yml
jest.config.js		jest.config.js
package.json		package.json
quickstart.sh		quickstart.sh
send-payment.js		send-payment.js
setup.sh		setup.sh
test-payment-verification.js		test-payment-verification.js

Latest commit

History

Folders and files

Repository files navigation

Vend 🎰

Vend Project Structure

Fork & Deploy in 5 Minutes

How x402 Works

The Flow

API Endpoints/Calls

Transaction History

NFT Ownership

NFT Metadata

NFT Floor Price

Token Balances

Token Metadata

Webhooks

🛠️ CLI Usage

Query Transaction History

Query NFTs

Query Token Balances

Automatic Payments

Saved Queries

Webhooks

All CLI Commands

Deployment

Quick Deploy Options

Railway

Render

Docker

VPS (PM2)

Environment Configuration

Hypothetical Economics

Development (Free)

Production

Architecture

Key Components

Security

Documentation

Contributing

📝 License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages