Data Models Reference

Type definitions and models used throughout the SDK.

Core Types

PaymentOptions

PaymentOptions

Bases: BaseModel

Options for initializing the Payments class.

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.

Defines the API endpoints and authentication configuration for an agent. Used when registering agents with :meth:payments.agents.register_agent or :meth:payments.agents.register_agent_and_plan.

PARAMETER	DESCRIPTION
endpoints	List of endpoint dictionaries with HTTP verb as key and URL as value. URLs can include placeholders like :agentId which will be replaced.
open_endpoints	List of endpoints that don't require authentication
agent_definition_url	URL to the agent definition. Can be an OpenAPI spec, MCP Manifest, or A2A agent card. This field is mandatory.
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:: agent_api = AgentAPIAttributes( endpoints=[ {"POST": "https://example.com/api/v1/agents/:agentId/tasks"}, {"GET": "https://example.com/api/v1/agents/:agentId/tasks/:taskId"} ], agent_definition_url="https://example.com/api/v1/openapi.json", # OpenAPI spec, MCP Manifest, or A2A agent card 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)

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)

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)
proof_required	Whether proof is required for redemption
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)

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
) -> 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

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) -> 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

    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,
    )

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,
        proof_required=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,
        proof_required=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,
        proof_required=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(
        credits_type=credits_config.credits_type,
        redemption_type=redemption_type,
        proof_required=credits_config.proof_required,
        duration_secs=credits_config.duration_secs,
        amount=credits_config.amount,
        min_amount=credits_config.min_amount,
        max_amount=credits_config.max_amount,
    )

set_proof_required

set_proof_required(
    credits_config: PlanCreditsConfig,
    proof_required: bool = True,
) -> PlanCreditsConfig

Set whether proof is required for a credits configuration.

PARAMETER	DESCRIPTION
credits_config	The credits configuration to modify TYPE: PlanCreditsConfig
proof_required	Whether proof is required (default: True) TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
PlanCreditsConfig	A new PlanCreditsConfig with the updated proof requirement

Source code in payments_py/plans.py

def set_proof_required(
    credits_config: PlanCreditsConfig, proof_required: bool = True
) -> PlanCreditsConfig:
    """
    Set whether proof is required for a credits configuration.

    Args:
        credits_config: The credits configuration to modify
        proof_required: Whether proof is required (default: True)

    Returns:
        A new PlanCreditsConfig with the updated proof requirement
    """
    return PlanCreditsConfig(
        credits_type=credits_config.credits_type,
        redemption_type=credits_config.redemption_type,
        proof_required=proof_required,
        duration_secs=credits_config.duration_secs,
        amount=credits_config.amount,
        min_amount=credits_config.min_amount,
        max_amount=credits_config.max_amount,
    )