Skip to main content
This guide covers how to order payment plans and manage balances using the Nevermined Payments Python SDK.

Overview

You need to purchase payment plans to gain access to AI agents and resources. This guide explains:
  • How to check plan balances
  • How to order plans (crypto payments)
  • How to mint and burn credits (for plan owners)

Check Plan Balance

Before ordering or using a plan, check the current balance:
from payments_py import Payments, PaymentOptions

payments = Payments.get_instance(
    PaymentOptions(nvm_api_key="nvm:your-key", environment="sandbox")
)

# Check balance for current user
balance = payments.plans.get_plan_balance(plan_id="your-plan-id")

print(f"Plan ID: {balance.plan_id}")
print(f"Plan Name: {balance.plan_name}")
print(f"Plan Type: {balance.plan_type}")
print(f"Balance: {balance.balance}")
print(f"Is Subscriber: {balance.is_subscriber}")
print(f"Price per Credit: {balance.price_per_credit}")

Check Balance for Another User

balance = payments.plans.get_plan_balance(
    plan_id="your-plan-id",
    account_address="0xOtherUserAddress"
)

Balance Response Fields

FieldTypeDescription
plan_idstrPlan identifier
plan_namestrPlan display name
plan_typestr”credits” or “time”
balanceintCurrent credit balance
is_subscriberboolWhether user has access
holder_addressstrWallet address checked
price_per_creditfloatCost per credit

Order Plans

Order with Crypto

Order a plan using cryptocurrency (ERC20 or native tokens):
# Order a plan (requires sufficient token balance)
result = payments.plans.order_plan(plan_id="your-plan-id")

print(f"Success: {result['success']}")
print(f"Order details: {result}")
For ERC20 token payments, ensure you have approved the Nevermined contract to spend your tokens before ordering.

Order Fiat Plans

For plans priced in fiat (USD), use Stripe checkout:
# Get Stripe checkout session
checkout = payments.plans.order_fiat_plan(plan_id="fiat-plan-id")

print(f"Checkout URL: {checkout['checkoutUrl']}")
print(f"Session ID: {checkout['sessionId']}")

# Redirect user to checkout['checkoutUrl'] to complete payment

Mint Credits (Plan Owners)

Plan owners can mint additional credits for plan holders:
# Mint credits to a user
result = payments.plans.mint_plan_credits(
    plan_id="your-plan-id",
    credits_amount=50,
    credits_receiver="0xSubscriberAddress"
)

print(f"Minted: {result}")

Mint Expirable Credits

For time-limited plans, mint credits with an expiration:
result = payments.plans.mint_plan_expirable(
    plan_id="your-plan-id",
    credits_amount=100,
    credits_receiver="0xSubscriberAddress",
    credits_duration=86400  # 1 day in seconds
)

Burn Credits (Plan Owners)

Plan owners can burn credits from the plan:
result = payments.plans.burn_credits(
    plan_id="your-plan-id",
    credits_amount="10"
)

print(f"Burned: {result}")

Redeem Credits

Agents can redeem credits from plan holders for completed work:
result = payments.plans.redeem_credits(
    agent_request_id="request-123",
    plan_id="plan-id",
    redeem_from="0xSubscriberAddress",
    credits_amount_to_redeem="5"
)

Complete Example

from payments_py import Payments, PaymentOptions
from payments_py.common.types import PlanMetadata
from payments_py.plans import get_erc20_price_config, get_fixed_credits_config

# Initialize as builder (plan owner)
payments_builder = Payments.get_instance(
    PaymentOptions(nvm_api_key="nvm:builder-key", environment="sandbox")
)

# Initialize as subscriber
payments_subscriber = Payments.get_instance(
    PaymentOptions(nvm_api_key="nvm:subscriber-key", environment="sandbox")
)

ERC20_TOKEN = "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d"
builder_address = payments_builder.account_address

# 1. Builder creates a plan
plan_result = payments_builder.plans.register_credits_plan(
    plan_metadata=PlanMetadata(name="Premium Plan"),
    price_config=get_erc20_price_config(20, ERC20_TOKEN, builder_address),
    credits_config=get_fixed_credits_config(100)
)
plan_id = plan_result['planId']
print(f"Created plan: {plan_id}")

# 2. Subscriber checks initial balance (should be 0 or not subscribed)
initial_balance = payments_subscriber.plans.get_plan_balance(plan_id)
print(f"Initial balance: {initial_balance.balance}")
print(f"Is subscriber: {initial_balance.is_subscriber}")

# 3. Subscriber orders the plan
order_result = payments_subscriber.plans.order_plan(plan_id)
print(f"Order success: {order_result['success']}")

# 4. Subscriber checks balance after ordering
final_balance = payments_subscriber.plans.get_plan_balance(plan_id)
print(f"Final balance: {final_balance.balance}")
print(f"Is subscriber: {final_balance.is_subscriber}")

# 5. Builder can mint additional credits
if final_balance.is_subscriber:
    mint_result = payments_builder.plans.mint_plan_credits(
        plan_id=plan_id,
        credits_amount=50,
        credits_receiver=payments_subscriber.account_address
    )
    print(f"Minted 50 additional credits")

    # Check updated balance
    updated_balance = payments_subscriber.plans.get_plan_balance(plan_id)
    print(f"Updated balance: {updated_balance.balance}")

Workflow Summary

Next Steps

Querying an Agent

Get access tokens and make requests

Request Validation

How agents validate requests