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
Field Type Description 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