django-agent-gate 0.0.4
A middleware to monetize Django APIs with Stripe and AI Agents
Requires Python: >=3.9

Django Agent Gate 🏦

Monetize your Django API in minutes with the Agent Economy.

django-agent-gate is a middleware that instantly turns your API into a metered, paid service for AI Agents and developers.

It acts as a connector to the Agent Bank protocol, handling authentication, credit checks, and automated billing per request.

🚀 Features

Smart Paywall: Automatically protects any route starting with /api/ while keeping your home page, docs, and login pages free.

Metered Billing: Deduct 1 (or more) credits per request automatically.

Marketplace Ready: Identifies who is calling (The Customer) and who is serving (You), ensuring credits are transferred correctly.

Agent-Native: Returns standardized 402 Payment Required errors with structured JSON, allowing AI agents to autonomously fund their wallets.

📦 Installation

pip install django-agent-gate


⚙️ Configuration

1. Add to Middleware

Open settings.py and add AgentGateMiddleware. It must be placed after SecurityMiddleware but before your URL configurations.

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    # ...
    'django_agent_gate.middleware.AgentGateMiddleware', # <--- Add this line
    # ...
]


2. Configure Variables

Add these settings to the bottom of your settings.py:

# 1. The URL of the Central Bank (The Ledger)
AGENT_GATE_BANK_URL = "https://agent-bank-production.onrender.com"

# 2. YOUR Merchant API Key (Get this from your Agent Bank Dashboard)
AGENT_GATE_API_KEY = "your-merchant-uuid-here"

# 3. Price per Request (Optional, defaults to 1)
AGENT_GATE_PRICE = 1

# 4. AI Monetization (Optional)
# List of User-Agent strings that MUST pay. 
# Defaults to common AI bots if not set.
AGENT_GATE_PAID_BOTS = [
    'GPTBot',        # OpenAI
    'ClaudeBot',     # Anthropic
    'CCBot',         # Common Crawl
    'Google-Extended', # Google Gemini training data
    'FacebookBot',   # Meta Llama
    'Bytespider',    # ByteDance
    'Amazonbot',     # Amazon
]


🛡️ How it Works

The middleware applies a "Tollbooth" logic based on the visitor's User-Agent.

Check User-Agent:

If the visitor is a Human (e.g., Mozilla/5.0...), the middleware allows them through for free on ALL routes.

If the visitor is an AI Bot (e.g., GPTBot/1.0), the middleware stops them and demands payment.

Payment Check (Bots Only):

The bot must provide a valid X-Api-Key header with sufficient credits.

If they fail, they receive a 401 Unauthorized or 402 Payment Required error.

🛠️ Usage

For Your Users (AI Agents)

To access your content, AI Agents must include their Agent Bank API Key in the header:

curl -H "X-Api-Key: their-customer-uuid" https://your-site.com/any-url/


Error Responses

If an AI Bot tries to scrape your site without a key, they get a 401 Unauthorized error telling them how to pay:

{
    "error": "AI Agent Detected. Payment Required.",
    "message": "This content is free for humans but paid for GPTBot.",
    "portal_url": "https://agent-bank-production.onrender.com"
}


🏗️ Architecture

This library operates as a Spoke in a Hub-and-Spoke financial model.

The Hub: The Agent Bank (Ledger, Stripe Processing, User Accounts).

The Spoke: Your Django App (Product, Logic, Value).

When a request comes in from a bot, this middleware pings the Hub to verify funds and transfer credits from the Consumer to the Merchant.