Skip to content

Payments and Balance

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_id str Plan identifier
plan_name str Plan display name
plan_type str "credits" or "time"
balance int Current credit balance
is_subscriber bool Whether user has access
holder_address str Wallet address checked
price_per_credit float Cost 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}")

Token Approval Required

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

┌──────────────────────────────────────────────────────────┐
│                     BUILDER                               │
│  1. Create Plan (register_credits_plan)                  │
│  2. Register Agent with Plan                             │
│  3. Optionally mint credits to users                     │
└──────────────────────────────────────────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────┐
│                    SUBSCRIBER                             │
│  1. Check Balance (get_plan_balance)                     │
│  2. Order Plan (order_plan)                              │
│  3. Get Access Token (get_x402_access_token)             │
│  4. Query Agent (with access token)                      │
└──────────────────────────────────────────────────────────┘

Next Steps