Data Models Reference

Type definitions and models used throughout the SDK.

Core Types

PaymentOptions

PaymentOptions

Bases: BaseModel

Options for initializing the Payments class.

PARAMETER	DESCRIPTION
environment	Nevermined environment (e.g. "sandbox", "live").
nvm_api_key	NVM API key used to authenticate against the backend.
return_url	Optional URL to return to after login (browser flows).
app_id	Optional application identifier stamped on registered assets.
version	Optional SDK version reported to the backend.
headers	Optional default headers to merge into every request.
organization_id	Optional organization id (e.g. "org-...") used as the active workspace for every authenticated backend call. When set, the SDK forwards it as the X-Current-Org-Id request header so the backend scopes published agents, plans, and other workspace-aware resources to this organization. If omitted, the backend falls back to the API key's org tag or the caller's most-recent active membership (see CurrentOrgContextGuard in nvm-monorepo). Override per-call via the organization_id argument on publish methods.

AgentMetadata

AgentMetadata

Bases: BaseModel

Metadata for an agent.

Used when registering agents with :meth:payments.agents.register_agent or :meth:payments.agents.register_agent_and_plan.

PARAMETER	DESCRIPTION
name	The name of the agent (required)
description	A description of the agent
author	The author of the agent
license	License information
tags	List of tags for categorization
integration	Integration type
sample_link	Link to a sample/demo
api_description	Description of the API
date_created	ISO date string of creation date

Example:: agent_metadata = AgentMetadata( name="My AI Agent", description="A helpful AI assistant", tags=["ai", "assistant"], author="John Doe" )

AgentAPIAttributes

AgentAPIAttributes

Bases: BaseModel

API attributes for an agent.

All fields are optional. Provide endpoints and/or agent_definition_url only when you want the platform to enforce a route-level allowlist as Additional Security (defense-in-depth on top of any per-route gating the Payments library applies in your agent), or when you want a discoverable agent definition. Otherwise omit them — your library middleware remains the sole gate.

Used when registering agents with :meth:payments.agents.register_agent or :meth:payments.agents.register_agent_and_plan.

PARAMETER	DESCRIPTION
endpoints	Optional allowlist of endpoint dictionaries with HTTP verb as key and URL as value. When provided, the Nevermined platform enforces this list as Additional Security on x402 verify. URLs can include placeholders like :agentId.
open_endpoints	Optional list of endpoints that don't require subscription.
agent_definition_url	Optional URL to a discoverable agent definition (OpenAPI spec, MCP Manifest, or A2A agent card). Stored as metadata; not consumed at runtime by the platform.
auth_type	Authentication type (default: AuthType.NONE)
username	Username for basic auth (if auth_type is BASIC)
password	Password for basic auth (if auth_type is BASIC)
token	Token for bearer auth (if auth_type is BEARER)
api_key	API key for authentication
headers	Additional headers to include in requests

Example::

# Minimal (recommended): your library middleware handles per-route gating
agent_api = AgentAPIAttributes(
    auth_type=AuthType.BEARER,
    token="sk-test",
)

# With Additional Security: platform enforces a route allowlist
agent_api = AgentAPIAttributes(
    endpoints=[
        {"verb": "POST", "url": "https://example.com/api/v1/agents/:agentId/tasks"},
    ],
    agent_definition_url="https://example.com/api/v1/openapi.json",
    auth_type=AuthType.BEARER,
)

PlanMetadata

PlanMetadata

Bases: AgentMetadata

Metadata for a payment plan, extends AgentMetadata.

Used when registering payment plans with methods like :meth:payments.plans.register_credits_plan, :meth:payments.plans.register_time_plan, or :meth:payments.agents.register_agent_and_plan.

PARAMETER	DESCRIPTION
name	The name of the plan (required, inherited from AgentMetadata)
description	A description of the plan (inherited from AgentMetadata)
is_trial_plan	Whether this is a trial plan (can only be purchased once per user)
All other fields from	class:AgentMetadata are also available

Example:: plan_metadata = PlanMetadata( name="Basic Plan", description="100 credits plan", is_trial_plan=False )

# For trial plans
trial_metadata = PlanMetadata(
    name="Free Trial",
    description="10 free credits",
    is_trial_plan=True
)

PlanPriceConfig

PlanPriceConfig

Bases: BaseModel

Definition of the price configuration for a Payment Plan.

Use helper functions from :mod:payments_py.plans to create instances: - :func:payments_py.plans.get_fiat_price_config for fiat payments - :func:payments_py.plans.get_erc20_price_config for ERC20 token payments - :func:payments_py.plans.get_native_token_price_config for native token (ETH) payments - :func:payments_py.plans.get_free_price_config for free plans

PARAMETER	DESCRIPTION
token_address	Address of the ERC20 token (ZeroAddress for native token or fiat)
amounts	List of payment amounts in smallest unit
receivers	List of receiver addresses
contract_address	Smart contract address (usually ZeroAddress)
fee_controller	Fee controller address (usually ZeroAddress)
external_price_address	External price oracle address (usually ZeroAddress)
template_address	Template address (usually ZeroAddress)
is_crypto	Whether this is a crypto payment (False for fiat)
currency	Optional currency code for off-chain denomination. For fiat payments, use an uppercase ISO-4217 code (e.g. "USD", "EUR"). For stablecoins, use the token symbol (e.g. "EURC"). For pure ERC20 or native token plans, this is typically None.

Example:: # Don't create directly - use helper functions instead: from payments_py.plans import get_erc20_price_config

price_config = get_erc20_price_config(20, ERC20_ADDRESS, builder_address)

model_dump

model_dump(**kwargs: Any) -> Dict[str, Any]

Override to serialize amounts as strings for backend BigInt compatibility.

Source code in payments_py/common/types.py

def model_dump(self, **kwargs: Any) -> Dict[str, Any]:
    """Override to serialize amounts as strings for backend BigInt compatibility."""
    d = super().model_dump(**kwargs)
    if "amounts" in d:
        d["amounts"] = [str(a) for a in d["amounts"]]
    return d

PlanCreditsConfig

PlanCreditsConfig

Bases: BaseModel

Definition of the credits configuration for a payment plan.

Use helper functions from :mod:payments_py.plans to create instances: - :func:payments_py.plans.get_fixed_credits_config for fixed credits per request - :func:payments_py.plans.get_dynamic_credits_config for variable credits per request - :func:payments_py.plans.get_expirable_duration_config for time-limited plans - :func:payments_py.plans.get_non_expirable_duration_config for non-expiring plans

PARAMETER	DESCRIPTION
is_redemption_amount_fixed	Whether credits consumed per request is fixed (True) or variable (False)
redemption_type	Who can redeem credits (PlanRedemptionType enum)
onchain_mirror	Whether burns of these credits are mirrored on-chain. Defaults to False — keeps the ledger off-chain in the API's Postgres, and recovers gracefully when API responses omit the field entirely. True enables the API-side OnchainMirrorWorker that replays each burn to NFT1155Credits for audit. Accepts the camelCase alias onchainMirror so plans deserialized from API JSON also resolve cleanly into this field regardless of casing.
duration_secs	Duration in seconds (0 for non-expirable, >0 for expirable)
amount	Total credits granted as string
min_amount	Minimum credits consumed per request
max_amount	Maximum credits consumed per request
nft_address	Optional NFT address

Example:: # Don't create directly - use helper functions instead: from payments_py.plans import get_fixed_credits_config, ONE_DAY_DURATION, get_expirable_duration_config

# Fixed credits plan
credits_config = get_fixed_credits_config(100, credits_per_request=1)

# Time-limited plan
time_config = get_expirable_duration_config(ONE_DAY_DURATION)

model_dump

model_dump(**kwargs: Any) -> Dict[str, Any]

Serialize uint256-typed fields as decimal strings.

The Nevermined backend tightened uint256 validation on plan and agent-and-plan registration. JSON numbers are rejected for fields that map to Solidity uint256 (durationSecs, amount, minAmount, maxAmount) because numbers larger than Number.MAX_SAFE_INTEGER lose precision in transit. The TypeScript SDK gets this for free via the BigInt jsonReplacer; Python emits the same wire shape by stringifying here.

Source code in payments_py/common/types.py

def model_dump(self, **kwargs: Any) -> Dict[str, Any]:
    """Serialize uint256-typed fields as decimal strings.

    The Nevermined backend tightened uint256 validation on plan and
    agent-and-plan registration. JSON numbers are rejected for fields
    that map to Solidity ``uint256`` (``durationSecs``, ``amount``,
    ``minAmount``, ``maxAmount``) because numbers larger than
    ``Number.MAX_SAFE_INTEGER`` lose precision in transit. The
    TypeScript SDK gets this for free via the ``BigInt``
    ``jsonReplacer``; Python emits the same wire shape by
    stringifying here.
    """
    d = super().model_dump(**kwargs)
    for field in ("duration_secs", "amount", "min_amount", "max_amount"):
        if field in d and d[field] is not None:
            d[field] = str(d[field])
    return d

PlanBalance

PlanBalance

Bases: BaseModel

Balance information for a payment plan.

Enums

AuthType

AuthType

Bases: str, Enum

Allowed authentication types for AgentAPIAttributes.

PlanPriceType

PlanPriceType

Bases: Enum

Different types of prices that can be configured for a plan. 0 - FIXED_PRICE, 1 - FIXED_FIAT_PRICE, 2 - SMART_CONTRACT_PRICE

PlanCreditsType

PlanCreditsType

Bases: Enum

Different types of credits that can be obtained when purchasing a plan. 0 - EXPIRABLE, 1 - FIXED, 2 - DYNAMIC

PlanRedemptionType

PlanRedemptionType

Bases: Enum

Different types of redemptions criterias that can be used when redeeming credits. 0 - ONLY_GLOBAL_ROLE, 1 - ONLY_OWNER, 2 - ONLY_PLAN_ROLE, 4 - ONLY_SUBSCRIBER

AgentTaskStatus

AgentTaskStatus

Bases: str, Enum

Status of an agent task.

Utility Types

PaginationOptions

PaginationOptions

Bases: BaseModel

Options for pagination in API requests to the Nevermined API.

TrackAgentSubTaskDto

TrackAgentSubTaskDto

Bases: BaseModel

Data transfer object for tracking agent sub tasks.

Plan Helper Functions

plans

Utility functions for creating and managing payment plans.

get_fiat_price_config

get_fiat_price_config(
    amount: int,
    receiver: Address,
    currency: str = Currency.USD,
) -> PlanPriceConfig

Get a fixed fiat price configuration for a plan.

PARAMETER	DESCRIPTION
amount	The amount in the smallest unit of the fiat currency TYPE: int
receiver	The address that will receive the payment TYPE: Address
currency	Fiat currency code in ISO 4217 format (default: 'USD'). Any code accepted by Stripe. TYPE: str DEFAULT: USD

RETURNS	DESCRIPTION
PlanPriceConfig	A PlanPriceConfig object configured for fiat payments

RAISES	DESCRIPTION
ValueError	If the receiver address is not a valid Ethereum address

Source code in payments_py/plans.py

def get_fiat_price_config(
    amount: int, receiver: Address, currency: str = Currency.USD
) -> PlanPriceConfig:
    """
    Get a fixed fiat price configuration for a plan.

    Args:
        amount: The amount in the smallest unit of the fiat currency
        receiver: The address that will receive the payment
        currency: Fiat currency code in ISO 4217 format (default: 'USD'). Any code accepted by Stripe.

    Returns:
        A PlanPriceConfig object configured for fiat payments

    Raises:
        ValueError: If the receiver address is not a valid Ethereum address
    """
    if not is_ethereum_address(receiver):
        raise ValueError(f"Receiver address {receiver} is not a valid Ethereum address")
    return PlanPriceConfig(
        token_address=ZeroAddress,
        amounts=[amount],
        receivers=[receiver],
        contract_address=ZeroAddress,
        fee_controller=ZeroAddress,
        external_price_address=ZeroAddress,
        template_address=ZeroAddress,
        is_crypto=False,
        currency=currency,
    )

get_erc20_price_config

get_erc20_price_config(
    amount: int, token_address: Address, receiver: Address
) -> PlanPriceConfig

Get a fixed ERC20 token price configuration for a plan.

PARAMETER	DESCRIPTION
amount	The amount in the smallest unit of the ERC20 token TYPE: int
token_address	The address of the ERC20 token TYPE: Address
receiver	The address that will receive the payment TYPE: Address

RETURNS	DESCRIPTION
PlanPriceConfig	A PlanPriceConfig object configured for ERC20 token payments

Source code in payments_py/plans.py

def get_erc20_price_config(
    amount: int, token_address: Address, receiver: Address
) -> PlanPriceConfig:
    """
    Get a fixed ERC20 token price configuration for a plan.

    Args:
        amount: The amount in the smallest unit of the ERC20 token
        token_address: The address of the ERC20 token
        receiver: The address that will receive the payment

    Returns:
        A PlanPriceConfig object configured for ERC20 token payments
    """
    return get_crypto_price_config(amount, receiver, token_address)

get_native_token_price_config

get_native_token_price_config(
    amount: int, receiver: Address
) -> PlanPriceConfig

Get a fixed native token price configuration for a plan.

PARAMETER	DESCRIPTION
amount	The amount in the smallest unit of the native token TYPE: int
receiver	The address that will receive the payment TYPE: Address

RETURNS	DESCRIPTION
PlanPriceConfig	A PlanPriceConfig object configured for native token payments

Source code in payments_py/plans.py

def get_native_token_price_config(amount: int, receiver: Address) -> PlanPriceConfig:
    """
    Get a fixed native token price configuration for a plan.

    Args:
        amount: The amount in the smallest unit of the native token
        receiver: The address that will receive the payment

    Returns:
        A PlanPriceConfig object configured for native token payments
    """
    return get_crypto_price_config(amount, receiver, ZeroAddress)

get_crypto_price_config

get_crypto_price_config(
    amount: int,
    receiver: Address,
    token_address: Address = ZeroAddress,
) -> PlanPriceConfig

Get a fixed crypto price configuration for a plan.

PARAMETER	DESCRIPTION
amount	The amount in the smallest unit of the token TYPE: int
receiver	The address that will receive the payment TYPE: Address
token_address	The address of the token to use for payment (defaults to native token) TYPE: Address DEFAULT: ZeroAddress

RETURNS	DESCRIPTION
PlanPriceConfig	A PlanPriceConfig object configured for crypto payments

RAISES	DESCRIPTION
ValueError	If the receiver address is not a valid Ethereum address

Source code in payments_py/plans.py

def get_crypto_price_config(
    amount: int, receiver: Address, token_address: Address = ZeroAddress
) -> PlanPriceConfig:
    """
    Get a fixed crypto price configuration for a plan.

    Args:
        amount: The amount in the smallest unit of the token
        receiver: The address that will receive the payment
        token_address: The address of the token to use for payment (defaults to native token)

    Returns:
        A PlanPriceConfig object configured for crypto payments

    Raises:
        ValueError: If the receiver address is not a valid Ethereum address
    """
    if not is_ethereum_address(receiver):
        raise ValueError(f"Receiver address {receiver} is not a valid Ethereum address")
    return PlanPriceConfig(
        token_address=token_address,
        amounts=[amount],
        receivers=[receiver],
        contract_address=ZeroAddress,
        fee_controller=ZeroAddress,
        external_price_address=ZeroAddress,
        template_address=ZeroAddress,
        is_crypto=True,
    )

get_free_price_config

get_free_price_config() -> PlanPriceConfig

Get a free price configuration for a plan.

RETURNS	DESCRIPTION
PlanPriceConfig	A PlanPriceConfig object configured for free plans

Source code in payments_py/plans.py

def get_free_price_config() -> PlanPriceConfig:
    """
    Get a free price configuration for a plan.

    Returns:
        A PlanPriceConfig object configured for free plans
    """
    return PlanPriceConfig(
        token_address=ZeroAddress,
        amounts=[],
        receivers=[],
        contract_address=ZeroAddress,
        fee_controller=ZeroAddress,
        external_price_address=ZeroAddress,
        template_address=ZeroAddress,
        is_crypto=True,
    )

get_fixed_credits_config

get_fixed_credits_config(
    credits_granted: int, credits_per_request: int = 1
) -> PlanCreditsConfig

Get a fixed credits configuration for a plan.

PARAMETER	DESCRIPTION
credits_granted	The total number of credits granted TYPE: int
credits_per_request	The number of credits consumed per request (default: 1) TYPE: int DEFAULT: 1

RETURNS	DESCRIPTION
PlanCreditsConfig	A PlanCreditsConfig object configured for fixed credits

Source code in payments_py/plans.py

def get_fixed_credits_config(
    credits_granted: int, credits_per_request: int = 1
) -> PlanCreditsConfig:
    """
    Get a fixed credits configuration for a plan.

    Args:
        credits_granted: The total number of credits granted
        credits_per_request: The number of credits consumed per request (default: 1)

    Returns:
        A PlanCreditsConfig object configured for fixed credits
    """
    return PlanCreditsConfig(
        is_redemption_amount_fixed=True,
        redemption_type=PlanRedemptionType.ONLY_SUBSCRIBER,
        onchain_mirror=False,
        duration_secs=0,
        amount=str(credits_granted),
        min_amount=credits_per_request,
        max_amount=credits_per_request,
    )

get_dynamic_credits_config

get_dynamic_credits_config(
    credits_granted: int,
    min_credits_per_request: int = 1,
    max_credits_per_request: int = 1,
) -> PlanCreditsConfig

Get a dynamic credits configuration for a plan.

PARAMETER	DESCRIPTION
credits_granted	The total number of credits granted TYPE: int
min_credits_per_request	The minimum number of credits consumed per request (default: 1) TYPE: int DEFAULT: 1
max_credits_per_request	The maximum number of credits consumed per request (default: 1) TYPE: int DEFAULT: 1

RETURNS	DESCRIPTION
PlanCreditsConfig	A PlanCreditsConfig object configured for dynamic credits

Source code in payments_py/plans.py

def get_dynamic_credits_config(
    credits_granted: int,
    min_credits_per_request: int = 1,
    max_credits_per_request: int = 1,
) -> PlanCreditsConfig:
    """
    Get a dynamic credits configuration for a plan.

    Args:
        credits_granted: The total number of credits granted
        min_credits_per_request: The minimum number of credits consumed per request (default: 1)
        max_credits_per_request: The maximum number of credits consumed per request (default: 1)

    Returns:
        A PlanCreditsConfig object configured for dynamic credits
    """
    return PlanCreditsConfig(
        is_redemption_amount_fixed=False,
        redemption_type=PlanRedemptionType.ONLY_SUBSCRIBER,
        onchain_mirror=False,
        duration_secs=0,
        amount=str(credits_granted),
        min_amount=min_credits_per_request,
        max_amount=max_credits_per_request,
    )

get_expirable_duration_config

get_expirable_duration_config(
    duration_of_plan: int,
) -> PlanCreditsConfig

Get an expirable duration configuration for a plan.

PARAMETER	DESCRIPTION
duration_of_plan	The duration of the plan in seconds TYPE: int

RETURNS	DESCRIPTION
PlanCreditsConfig	A PlanCreditsConfig object configured for expirable duration

Source code in payments_py/plans.py

def get_expirable_duration_config(duration_of_plan: int) -> PlanCreditsConfig:
    """
    Get an expirable duration configuration for a plan.

    Args:
        duration_of_plan: The duration of the plan in seconds

    Returns:
        A PlanCreditsConfig object configured for expirable duration
    """
    return PlanCreditsConfig(
        is_redemption_amount_fixed=False,
        redemption_type=PlanRedemptionType.ONLY_SUBSCRIBER,
        onchain_mirror=False,
        duration_secs=duration_of_plan,
        amount="1",
        min_amount=1,
        max_amount=1,
    )

get_non_expirable_duration_config

get_non_expirable_duration_config() -> PlanCreditsConfig

Get a non-expirable duration configuration for a plan.

RETURNS	DESCRIPTION
PlanCreditsConfig	A PlanCreditsConfig object configured for non-expirable duration

Source code in payments_py/plans.py

def get_non_expirable_duration_config() -> PlanCreditsConfig:
    """
    Get a non-expirable duration configuration for a plan.

    Returns:
        A PlanCreditsConfig object configured for non-expirable duration
    """
    return get_expirable_duration_config(0)

set_redemption_type

set_redemption_type(
    credits_config: PlanCreditsConfig,
    redemption_type: PlanRedemptionType,
) -> PlanCreditsConfig

Set the redemption type for a credits configuration.

PARAMETER	DESCRIPTION
credits_config	The credits configuration to modify TYPE: PlanCreditsConfig
redemption_type	The new redemption type TYPE: PlanRedemptionType

RETURNS	DESCRIPTION
PlanCreditsConfig	A new PlanCreditsConfig with the updated redemption type

Source code in payments_py/plans.py

def set_redemption_type(
    credits_config: PlanCreditsConfig, redemption_type: PlanRedemptionType
) -> PlanCreditsConfig:
    """
    Set the redemption type for a credits configuration.

    Args:
        credits_config: The credits configuration to modify
        redemption_type: The new redemption type

    Returns:
        A new PlanCreditsConfig with the updated redemption type
    """
    return PlanCreditsConfig(
        is_redemption_amount_fixed=credits_config.is_redemption_amount_fixed,
        redemption_type=redemption_type,
        onchain_mirror=credits_config.onchain_mirror,
        duration_secs=credits_config.duration_secs,
        amount=credits_config.amount,
        min_amount=credits_config.min_amount,
        max_amount=credits_config.max_amount,
        nft_address=credits_config.nft_address,
    )

set_onchain_mirror

set_onchain_mirror(
    credits_config: PlanCreditsConfig,
    onchain_mirror: bool = True,
) -> PlanCreditsConfig

Set whether burns of these credits are mirrored on-chain.

When False (the structural default of all credits-config builders) the credits ledger lives in the API's Postgres and burns are recorded off-chain only. When True an on-chain audit mirror replays each burn to NFT1155Credits.

PARAMETER	DESCRIPTION
credits_config	The credits configuration to modify TYPE: PlanCreditsConfig
onchain_mirror	Whether on-chain mirroring is enabled. Defaults to True so calling set_onchain_mirror(config) enables the mirror; pass False explicitly to disable it. TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
PlanCreditsConfig	A new PlanCreditsConfig with the updated on-chain mirror flag

Source code in payments_py/plans.py

def set_onchain_mirror(
    credits_config: PlanCreditsConfig, onchain_mirror: bool = True
) -> PlanCreditsConfig:
    """
    Set whether burns of these credits are mirrored on-chain.

    When ``False`` (the structural default of all credits-config builders)
    the credits ledger lives in the API's Postgres and burns are recorded
    off-chain only. When ``True`` an on-chain audit mirror replays each
    burn to ``NFT1155Credits``.

    Args:
        credits_config: The credits configuration to modify
        onchain_mirror: Whether on-chain mirroring is enabled. Defaults to
            ``True`` so calling ``set_onchain_mirror(config)`` enables the
            mirror; pass ``False`` explicitly to disable it.

    Returns:
        A new PlanCreditsConfig with the updated on-chain mirror flag
    """
    return PlanCreditsConfig(
        is_redemption_amount_fixed=credits_config.is_redemption_amount_fixed,
        redemption_type=credits_config.redemption_type,
        onchain_mirror=onchain_mirror,
        duration_secs=credits_config.duration_secs,
        amount=credits_config.amount,
        min_amount=credits_config.min_amount,
        max_amount=credits_config.max_amount,
        nft_address=credits_config.nft_address,
    )