5-Minute Setup

This guide gets you from zero to a working payment integration in 5 minutes. By the end, you’ll have a monetizable service set up with Nevermined — typically an agent API, but the same flow applies to MCP tools/servers and protected assets.

In the code below we use “agent” terminology because it maps to the underlying object model, but you can think of it as the service/resource you’re charging for.

Prerequisites

Get Your API Key

Open nevermined.app, sign in, then go to Settings > Global NVM API Keys and click + New API Key. Copy the key and set it as an environment variable:

export NVM_API_KEY="sandbox:your-api-key-here"

Keys are environment-specific — the prefix matches the SDK environment value you must pass at init.

Key prefix	SDK `environment`	Backend
`sandbox:`	`sandbox`	`https://api.sandbox.nevermined.app`
`live:`	`live`	`https://api.live.nevermined.app`

Use sandbox for testing and live for production. If you see auth errors that look unrelated to the key, double-check that prefix and environment match — a sandbox: key against environment: 'live' lands at the wrong backend and fails with confusing 4xx errors.

Install the SDK

TypeScript
Python

npm install @nevermined-io/payments

pip install payments-py

Register Your Agent

Create a script to register your agent and a payment plan.

You can register your agent and any payment plan using the following code OR using the Nevermined App. No need to code this — just follow the steps in the app to create your agents and plans.

If you’re monetizing an agent, MCP tool/server or a protected resource, you’ll still register the monetizable unit and attach a plan — only the delivery step changes.

TypeScript
Python

import { Payments } from '@nevermined-io/payments'

// 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:
const USDC_ADDRESS = '0x036CbD53842c5426634e7929541eC2318f3dCF7e'

async function main() {
  // 1. Initialize the SDK
  const payments = Payments.getInstance({
    nvmApiKey: process.env.NVM_API_KEY!,
    environment: 'sandbox'
  })

  // 2. Register service + payment plan ("agent" in the SDK)
  const { agentId, planId } = await payments.agents.registerAgentAndPlan(
    // Service metadata
    {
      name: 'My AI Assistant',
      description: 'A paid service (agent API / MCP tool / protected resource)',
      tags: ['ai', 'payments'],
      dateCreated: new Date()
    },
    // Service interface - replace with your endpoint
    {
      endpoints: [{ POST: 'https://your-api.com/query' }]
    },
    // Plan metadata
    {
      name: 'Starter Plan',
      description: '100 requests for $10',
      dateCreated: new Date()
    },
    // Price: 10 USDC
    payments.plans.getERC20PriceConfig(
      10_000_000n, // 10 USDC (6 decimals)
      USDC_ADDRESS,
      process.env.BUILDER_ADDRESS! // Your wallet address
    ),
    // Credits: 100 requests, 1 credit each
    payments.plans.getFixedCreditsConfig(100n, 1n)
  )

  console.log('Registered!')
  console.log(`Service (agent) ID: ${agentId}`)
  console.log(`Plan ID: ${planId}`)
  console.log('\nSave these IDs for your integration.')
}

main().catch(console.error)

import os
from payments_py import Payments, PaymentOptions
from payments_py.plans import get_erc20_price_config, get_fixed_credits_config

# 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'

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

    result = payments.agents.register_agent_and_plan(
        agent_metadata={
            'name': 'My AI Assistant',
            'description': 'A paid service (agent API / MCP tool / protected resource)',
            'tags': ['ai', 'payments']
        },
        agent_api={
            'endpoints': [{'verb': 'POST', 'url': 'https://your-api.com/query'}]
        },
        plan_metadata={
            'name': 'Starter Plan',
            'description': '100 requests for $10'
        },
        price_config=get_erc20_price_config(
            10_000_000,  # 10 USDC (6 decimals)
            USDC_ADDRESS,
            os.environ['BUILDER_ADDRESS']
        ),
        credits_config=get_fixed_credits_config(100, 1),
        access_limit='credits'
    )

    print('Registered!')
    print(f"Service (agent) ID: {result['agentId']}")
    print(f"Plan ID: {result['planId']}")
    print('\nSave these IDs for your integration.')

if __name__ == '__main__':
    main()

Run it:

TypeScript
Python

npx ts-node register-agent.ts

python register_agent.py

Add Payment Validation in the Agent

Add this middleware to your agent to validate if a request is valid (have a payment attached) before delivering your response/resource. The example shows an HTTP API route; the same check can be used before calling an MCP tool handler or before serving a protected asset:

TypeScript
Python

import { Payments, buildPaymentRequired } from '@nevermined-io/payments'

const payments = Payments.getInstance({
  nvmApiKey: process.env.NVM_API_KEY!,
  environment: 'sandbox',
})

const PLAN_ID = process.env.NVM_PLAN_ID!
const AGENT_ID = process.env.NVM_AGENT_ID!

// Build payment required specification
const paymentRequired = buildPaymentRequired(PLAN_ID, {
  endpoint: req.url,
  agentId: AGENT_ID,
  httpVerb: req.method,
})

// Get token from payment-signature header
const x402Token = req.headers['payment-signature'] as string

if (!x402Token) {
  // Return 402 with payment-required header so clients know how to pay
  const paymentRequiredBase64 = Buffer.from(
    JSON.stringify(paymentRequired)
  ).toString('base64')

  return res
    .status(402)
    .setHeader('payment-required', paymentRequiredBase64)
    .json({ error: 'Payment Required' })
}

// 1. Verify permissions (does NOT burn credits)
const verification = await payments.facilitator.verifyPermissions({
  paymentRequired,
  x402AccessToken: x402Token,
  maxAmount: 1n,
})

if (!verification.isValid) {
  return res.status(402).json({ error: verification.invalidReason })
}

// 2. Execute your logic here — payment is verified
const result = await handleRequest(req)

// 3. Settle (burn credits) after successful processing
await payments.facilitator.settlePermissions({
  paymentRequired,
  x402AccessToken: x402Token,
  maxAmount: 1n,
})

return res.json({ result })

import base64
import os
from payments_py import Payments, PaymentOptions
from payments_py.x402.helpers import build_payment_required

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

PLAN_ID = os.environ["NVM_PLAN_ID"]
AGENT_ID = os.environ["NVM_AGENT_ID"]

# Build payment required specification
payment_required = build_payment_required(
    plan_id=PLAN_ID,
    endpoint=request.url,
    agent_id=AGENT_ID,
    http_verb=request.method
)

# Get token from payment-signature header
x402_token = request.headers.get("payment-signature")

if not x402_token:
    # Return 402 with payment-required header so clients know how to pay
    pr_base64 = base64.b64encode(
        payment_required.model_dump_json(by_alias=True).encode()
    ).decode()
    return JSONResponse(
        status_code=402,
        content={"error": "Payment Required"},
        headers={"payment-required": pr_base64}
    )

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

if not verification.is_valid:
    return JSONResponse(
        status_code=402,
        content={"error": verification.invalid_reason}
    )

# 2. Execute your logic here — payment is verified
result = handle_request(request)

# 3. Settle (burn credits) after successful processing
payments.facilitator.settle_permissions(
    payment_required=payment_required,
    x402_access_token=x402_token,
    max_amount="1",
)

return {"result": result}

Integrate the validation code in your agent/server

Integrate the above validation code into your agent/server code at the very beginning of your request handling logic. The payment validation should occur before any processing of the request and can be complemented by any other authorization logic you may have.

Test It

1) Try without payment (should fail)

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

Response:

{
  "error": "Payment Required",
  "message": "Purchase a plan to access this API",
  "plans": [{"planId": "did:nv:...", "agentId": "did:nv:..."}]
}

2) Purchase a plan and get an access token

TypeScript
Python

// As a subscriber
const payments = Payments.getInstance({ nvmApiKey: subscriberKey, environment: 'sandbox' })

// Order the plan
await payments.plans.orderPlan(PLAN_ID)

// Get your balance about the plan you just ordered
const balance = await payments.plans.getPlanBalance(PLAN_ID)

// Create a delegation first (provider + currency required; 'usdc' for
// erc4337), then request the token by its delegationId. `delegationConfig`
// is required for both crypto and fiat plans — omitting it surfaces
// BCK.X402.0030 at runtime.
const delegation = await payments.delegation.createDelegation({
  provider: 'erc4337',
  spendingLimitCents: 1000, // $10 cap
  durationSecs: 86_400, // 1 day
  currency: 'usdc',
})
const { accessToken } = await payments.x402.getX402AccessToken(PLAN_ID, AGENT_ID, {
  scheme: 'nvm:erc4337',
  delegationConfig: { delegationId: delegation.delegationId },
})

// Use this token in the next request
// HTTP header: 'payment-signature'
// value: `${accessToken}`

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

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

  # Order the plan
  order_result = payments.plans.order_plan(plan_id)

  # Get your balance about the plan you just ordered
  balance = payments.plans.get_plan_balance(plan_id)

  # Create a delegation first (provider + currency required), then request
  # the token by its delegation_id.
  delegation = payments.delegation.create_delegation(
      CreateDelegationPayload(
          provider='erc4337',
          spending_limit_cents=1000,
          duration_secs=86_400,
          currency='usdc',
      )
  )
  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 with payment

curl -X POST http://localhost:3000/query \
  -H "Content-Type: application/json" \
  -H "payment-signature: ${accessToken}" \
  -d '{"prompt": "Hello"}'

Response:

{
  "result": "Hello! How can I help you today?",
  "creditsRemaining": 99
}

Want subscribers to pay with a regular credit card instead of stablecoins? Card delegation lets subscribers enroll a Visa, Stripe, or Braintree card and create spending delegations that agents charge directly.

What’s Next?

Express Integration

Complete Express.js integration guide

FastAPI Integration

Complete FastAPI integration guide

Payment Patterns

Advanced validation and charging patterns

x402 Protocol

Implement HTTP 402 payment flows

Learn

Build

Payments

Solutions

Integrations

Payment Patterns

Components

Specs

Prerequisites

Register Your Agent

Add Payment Validation in the Agent

Integrate the validation code in your agent/server

Test It

What’s Next?

Express Integration

FastAPI Integration

Payment Patterns

x402 Protocol

​Prerequisites

​Register Your Agent

​Add Payment Validation in the Agent

​Integrate the validation code in your agent/server

​Test It

​What’s Next?

Express Integration

FastAPI Integration

Payment Patterns

x402 Protocol

Prerequisites

Register Your Agent

Add Payment Validation in the Agent

Integrate the validation code in your agent/server

Test It

What’s Next?