This guide covers how to order payment plans and manage balances using the Nevermined Payments Python SDK.
Overview
As a subscriber, you need to order 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 subscribers:
# 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 subscribers 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