Python Quick Start

Start here: need to register a service and create a plan first or get your Nevermined API Key? Follow the 5-minute setup.

Complete Python quick start for adding payments to your AI agent or service.

Installation

pip install payments-py fastapi uvicorn

Environment Setup

# Your Nevermined API key (see: /docs/getting-started/get-your-api-key)
export NVM_API_KEY="sandbox:your-api-key"

# Your wallet address to receive payments
export BUILDER_ADDRESS="0xYourWalletAddress"

# After registration, set these
export AGENT_ID="did:nv:your-agent-id"
export PLAN_ID="did:nv:your-plan-id"

Complete Example

import os
from fastapi import FastAPI, Request, HTTPException, Depends
from pydantic import BaseModel
from payments_py import Payments, PaymentOptions
from payments_py.plans import get_erc20_price_config, get_fixed_credits_config

app = FastAPI(title="My AI Agent")

# In this example we require a payment of 10 USDC for 100 requests
# For that USDC payment we use USDC on Base Sepolia, so we need its contract address:
USDC_ADDRESS = '0x036CbD53842c5426634e7929541eC2318f3dCF7e'

# Initialize payments
payments = Payments.get_instance(
    PaymentOptions(
        nvm_api_key=os.environ['NVM_API_KEY'],
        environment='sandbox'
    )
)

# Store IDs after registration
agent_id = os.environ.get('AGENT_ID', '')
plan_id = os.environ.get('PLAN_ID', '')


# ============================================
# MODELS
# ============================================
class QueryRequest(BaseModel):
    prompt: str


class QueryResponse(BaseModel):
    result: str
    credits_remaining: int


# ============================================
# SETUP: Run once to register your agent
# ============================================
@app.post("/setup")
async def register_agent():
    global agent_id, plan_id

    result = payments.agents.register_agent_and_plan(
        agent_metadata={
            'name': 'My Python AI Agent',
            'description': 'AI assistant built with Python',
            'tags': ['ai', 'python']
        },
        agent_api={
            'endpoints': [{'verb': 'POST', 'url': 'http://localhost:8000/query'}]
        },
        plan_metadata={
            'name': 'Starter Plan',
            'description': '100 queries'
        },
        price_config=get_erc20_price_config(
            10_000_000,  # 10 USDC
            USDC_ADDRESS,
            os.environ['BUILDER_ADDRESS']
        ),
        credits_config=get_fixed_credits_config(100, 1),
        access_limit='credits'
    )

    agent_id = result['agentId']
    plan_id = result['planId']

    return {
        'agent_id': agent_id,
        'plan_id': plan_id,
        'message': 'Add these to your .env file!'
    }


# ============================================
# MIDDLEWARE: Validate payments
# ============================================
async def validate_payment(request: Request) -> int:
    """Validate payment and return remaining credits."""
    from payments_py.x402.helpers import build_payment_required

    x402_token = request.headers.get("payment-signature")

    if not x402_token:
        raise HTTPException(status_code=402, detail="Payment required")

    # Build payment requirements
    payment_required = build_payment_required(
        plan_id=plan_id,
        endpoint=str(request.url),
        agent_id=agent_id,
        http_verb=request.method
    )

    # Verify permissions
    verification = payments.facilitator.verify_permissions(
        payment_required=payment_required,
        x402_access_token=x402_token,
        max_amount="1"
    )

    if not verification.get("is_valid"):
        raise HTTPException(status_code=402, detail="Invalid payment")

    return verification.get("remaining_credits", 0)


# ============================================
# ROUTES
# ============================================
@app.get("/health")
async def health():
    """Health check (public)."""
    return {
        'status': 'ok',
        'agent_id': agent_id,
        'plan_id': plan_id
    }


@app.post("/query", response_model=QueryResponse)
async def query(
    request: QueryRequest,
    credits: int = Depends(validate_payment)
):
    """Protected AI endpoint."""
    # Your AI logic here
    result = f'You asked: "{request.prompt}". Here\'s my response...'

    return QueryResponse(
        result=result,
        credits_remaining=credits
    )


# ============================================
# MAIN
# ============================================
if __name__ == '__main__':
    import uvicorn

    print(f"Agent ID: {agent_id or 'Not registered'}")
    print(f"Plan ID: {plan_id or 'Not registered'}")

    if not agent_id or not plan_id:
        print("No agent registered yet. POST to /setup to register.")

    uvicorn.run(app, host='0.0.0.0', port=8000)

Run the Example

# Run the server
python main.py

# Or with uvicorn directly
uvicorn main:app --reload --port 8000

Test the Flow

1) Register your agent (first time only)

curl -X POST http://localhost:8000/setup

Save the returned agent_id and plan_id to your environment. 2) Try without payment

curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello"}'

3) As a subscriber, purchase and query

import os
import requests
from payments_py import Payments, PaymentOptions
from payments_py.x402 import X402TokenOptions, DelegationConfig, CreateDelegationPayload

payments = Payments.get_instance(
    PaymentOptions(
        nvm_api_key=os.environ['SUBSCRIBER_API_KEY'],
        environment='sandbox'
    )
)

def purchase_and_query():
    plan_id = os.environ['PLAN_ID']
    agent_id = os.environ['AGENT_ID']

    # 1. Order the plan (buys credits up front)
    print('Purchasing plan...')
    order_result = payments.plans.order_plan(plan_id)

    # 2. Get access token
    print('Getting access token...')

    # Create the delegation first (provider + currency required), then request
    # the token by its delegationId. Reuse the delegation for later requests.
    delegation = payments.delegation.create_delegation(
        CreateDelegationPayload(
            provider="erc4337",  # "stripe" | "braintree" | "visa" for fiat plans
            spending_limit_cents=1000,
            duration_secs=86_400,
            currency="usdc",  # "usd" for fiat plans
        )
    )
    token_res = payments.x402.get_x402_access_token(
        plan_id,
        agent_id,
        token_options=X402TokenOptions(
            scheme="nvm:erc4337",
            delegation_config=DelegationConfig(delegation_id=delegation.delegation_id),
        ),
    )
    access_token = token_res['accessToken']

    # 3. Query the agent
    print('Querying agent...')
    response = requests.post(
        'http://localhost:8000/query',
        headers={
            'Content-Type': 'application/json',
            'payment-signature': f'{access_token}'
        },
        json={'prompt': 'What is 2+2?'}
    )

    result = response.json()
    print(f'Result: {result}')

if __name__ == '__main__':
    purchase_and_query()

For agents that run continuously, set up a delegation when generating the access token — the facilitator tops up credits automatically when the balance runs out, with no manual order_plan() loop needed. See Automatic Credit Top-Ups.

Flask Alternative

import os
from flask import Flask, request, jsonify
from functools import wraps
from payments_py import Payments, PaymentOptions
from payments_py.plans import get_erc20_price_config, get_fixed_credits_config

app = Flask(__name__)

USDC_ADDRESS = '0x036CbD53842c5426634e7929541eC2318f3dCF7e'

payments = Payments.get_instance(
    PaymentOptions(
        nvm_api_key=os.environ['NVM_API_KEY'],
        environment='sandbox'
    )
)

agent_id = os.environ.get('AGENT_ID', '')
plan_id = os.environ.get('PLAN_ID', '')


def require_payment(f):
    """Decorator to validate payment."""
    from payments_py.x402.helpers import build_payment_required

    @wraps(f)
    def decorated(*args, **kwargs):
        x402_token = request.headers.get("payment-signature")

        if not x402_token:
            return {"error": "Payment Required"}, 402

        # Get request body for validation (Flask synchronous method)
        body = request.get_json()

        # Build payment requirements
        payment_required = build_payment_required(
            plan_id=plan_id,
            endpoint=request.url,
            agent_id=agent_id,
            http_verb=request.method
        )

        # Verify permissions
        verification = payments.facilitator.verify_permissions(
            payment_required=payment_required,
            x402_access_token=x402_token,
            max_amount="1"
        )

        if not verification.get("is_valid"):
            return {"error": "Invalid payment"}, 402

        # Get balance
        balance = payments.plans.get_plan_balance(plan_id)

        # Pass credits to the handler
        kwargs['credits'] = balance.get('balance', 0)
        return f(*args, **kwargs)

    return decorated


@app.route('/health')
def health():
    return jsonify({'status': 'ok', 'agent_id': agent_id, 'plan_id': plan_id})


@app.route('/query', methods=['POST'])
@require_payment
def query(credits=0):
    prompt = request.json.get('prompt', '')

    # Your AI logic here
    result = f'You asked: "{prompt}". Here\'s my response...'

    return jsonify({
        'result': result,
        'credits_remaining': credits
    })


if __name__ == '__main__':
    app.run(port=8000, debug=True)

Project Structure

my-ai-agent/
├── main.py              # FastAPI server
├── requirements.txt
├── .env
└── src/
    ├── middleware/
    │   └── payments.py  # Payment validation
    ├── routes/
    │   └── query.py     # AI endpoints
    └── services/
        └── ai.py        # Your AI logic

Requirements File

payments-py>=1.0.0
fastapi>=0.100.0
uvicorn>=0.23.0
python-dotenv>=1.0.0

Next Steps

FastAPI Integration

Complete FastAPI patterns and best practices

Python SDK Reference

Full API documentation

Payment Patterns

Advanced patterns for production

x402 Protocol

Implement HTTP 402 payment flows

Learn

Build

Payments

Solutions

Integrations

Payment Patterns

Components

Specs

Installation

Environment Setup

Complete Example

Run the Example

Test the Flow

Flask Alternative

Project Structure

Requirements File

Next Steps

FastAPI Integration

Python SDK Reference

Payment Patterns

x402 Protocol

​Installation

​Environment Setup

​Complete Example

​Run the Example

​Test the Flow

​Flask Alternative

​Project Structure

​Requirements File

​Next Steps

FastAPI Integration

Python SDK Reference

Payment Patterns

x402 Protocol

Installation

Environment Setup

Complete Example

Run the Example

Test the Flow

Flask Alternative

Project Structure

Requirements File

Next Steps