A payment-enabled proxy for HuggingFace Inference API using X402 micropayments. Pay per request with USDC on Base blockchain.

• HuggingFace Compatible: Same API as HuggingFace (POST /models/{org}/{model})
• X402 Micropayments: Pay-per-request with USDC on Base
• Per-Model Pricing: Different prices for different models
• 10 Supported Tasks: Classification, detection, segmentation, embeddings, image generation, speech-to-text, and more
• Playground UI: React frontend with wallet integration

Models not in the pricing list use the default price of $0.01.

npm install

cp .dev.vars.example .dev.vars

Edit .dev.vars:

HF_TOKEN=your_huggingface_token

Update wrangler.toml with your payment address:

PAYMENT_ADDRESS = "0xYourWalletAddress"

npm run dev

API available at http://localhost:8787

# Set HuggingFace token secret
wrangler secret put HF_TOKEN

# Deploy to testnet (Base Sepolia)
npm run deploy:testnet

# Deploy to mainnet (Base)
npm run deploy:mainnet

POST /models/{org}/{model}

Matches HuggingFace Inference API exactly.

curl -X POST http://localhost:8787/models/distilbert/distilbert-base-uncased-finetuned-sst-2-english \
  -H "Content-Type: application/json" \
  -d '{"inputs": "I love this product!"}'

First request returns 402 Payment Required with payment details. After signing payment with your wallet, include the signature:

curl -X POST http://localhost:8787/models/distilbert/distilbert-base-uncased-finetuned-sst-2-english \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: <base64-encoded-payment>" \
  -d '{"inputs": "I love this product!"}'

curl -X POST http://localhost:8787/models/google/vit-base-patch16-224 \
  -H "PAYMENT-SIGNATURE: <base64-encoded-payment>" \
  --data-binary @image.jpg

• GET / - API information
• GET /pricing - Current pricing policy

Pricing is configured in src/pricing/policy.ts. Add models to the endpoints object:

endpoints: {
  "org/model-name": {
    basePrice: "3000",  // $0.003 (1 USDC = 1,000,000 units)
    description: "Model description",
  },
}

Models not listed use defaultPrice ($0.01).

React frontend for testing the API with wallet integration.

cd playground
npm install
cp .env.example .env.local
# Edit .env.local
npm run dev

VITE_API_URL=http://localhost:8787
VITE_NETWORK=base-sepolia
VITE_WALLETCONNECT_PROJECT_ID=  # Optional - works without it for browser extension wallets

├── src/
│   ├── index.ts              # Main entry point
│   ├── x402/
│   │   ├── middleware.ts     # X402 payment middleware
│   │   └── types.ts          # Environment types
│   ├── pricing/
│   │   ├── engine.ts         # Pricing calculation
│   │   ├── policy.ts         # Per-model prices
│   │   └── types.ts          # Pricing types
│   └── routes/
│       ├── models.ts         # HF-compatible /models route
│       └── pricing.ts        # Pricing endpoints
├── playground/               # React frontend
├── wrangler.toml            # Cloudflare Workers config
└── package.json

1. Client sends request without payment
2. Server returns 402 Payment Required with price and payment details
3. Client signs EIP-712 payment authorization with wallet
4. Client retries with PAYMENT-SIGNATURE header
5. Server verifies and processes request
6. Server settles payment on-chain
7. Response includes X-Payment-Transaction header with tx hash

MIT