Payments Class Reference¶

The main entry point for the Nevermined Payments Python SDK.

Payments¶

Payments ¶

Payments(
    options: PaymentOptions,
    is_browser_instance: bool = False,
)

Bases: BasePaymentsAPI

Main class that interacts with the Nevermined payments API. Use Payments.get_instance for server-side usage.

The library provides methods to manage AI Agents, Plans & process AI Agent Requests.

Each of these functionalities is encapsulated in its own API class: - plans: Manages AI Plans, including registration and ordering and retrieving plan details. - orders: Browser-fiat Orders - merchant-initiated, off-plan charges for an arbitrary amount. - agents: Handles AI Agents, including registration of AI Agents and access token generation. - requests: Manages requests received by AI Agents, including validation and tracking. - facilitator: Handles X402 permission verification and settlement for AI Agents acting as facilitators.

Initialize the Payments class.

PARAMETER	DESCRIPTION
`options`	The initialization options TYPE: `PaymentOptions`
`is_browser_instance`	Whether this is a browser instance (default False) TYPE: `bool` DEFAULT: `False`

Source code in payments_py/payments.py

def __init__(self, options: PaymentOptions, is_browser_instance: bool = False):
    """
    Initialize the Payments class.

    Args:
        options: The initialization options
        is_browser_instance: Whether this is a browser instance (default False)
    """
    super().__init__(options)
    self.is_browser_instance = is_browser_instance
    self._initialize_api(options)

get_instance `classmethod` ¶

get_instance(options: PaymentOptions) -> Payments

Get an instance of the Payments class for server-side usage.

PARAMETER	DESCRIPTION
`options`	The options to initialize the payments class TYPE: `PaymentOptions`

RETURNS	DESCRIPTION
`Payments`	An instance of Payments

RAISES	DESCRIPTION
`PaymentsError`	If nvm_api_key is missing

Source code in payments_py/payments.py

@classmethod
def get_instance(cls, options: PaymentOptions) -> "Payments":
    """
    Get an instance of the Payments class for server-side usage.

    Args:
        options: The options to initialize the payments class

    Returns:
        An instance of Payments

    Raises:
        PaymentsError: If nvm_api_key is missing
    """
    if not options.nvm_api_key:
        raise PaymentsError.unauthorized("Nevermined API Key is required")
    return cls(options, False)

get_browser_instance `classmethod` ¶

get_browser_instance(options: PaymentOptions) -> Payments

Get an instance of the Payments class for browser usage.

PARAMETER	DESCRIPTION
`options`	The options to initialize the payments class TYPE: `PaymentOptions`

RETURNS	DESCRIPTION
`Payments`	An instance of Payments

RAISES	DESCRIPTION
`PaymentsError`	If return_url is missing

Source code in payments_py/payments.py

@classmethod
def get_browser_instance(cls, options: PaymentOptions) -> "Payments":
    """
    Get an instance of the Payments class for browser usage.

    Args:
        options: The options to initialize the payments class

    Returns:
        An instance of Payments

    Raises:
        PaymentsError: If return_url is missing
    """
    if not options.return_url:
        raise PaymentsError.validation("return_url is required")
    return cls(options, True)

Plans API¶

PlansAPI ¶

PlansAPI(options: PaymentOptions)

Bases: BasePaymentsAPI

The PlansAPI class provides methods to register and interact with payment plans on Nevermined.

Initialize the PlansAPI class.

PARAMETER	DESCRIPTION
`options`	The options to initialize the payments class TYPE: `PaymentOptions`

Source code in payments_py/api/plans_api.py

def __init__(self, options: PaymentOptions):
    """
    Initialize the PlansAPI class.

    Args:
        options: The options to initialize the payments class
    """
    super().__init__(options)
    self.contracts_api = ContractsAPI(options)

get_instance `classmethod` ¶

get_instance(options: PaymentOptions) -> PlansAPI

Get a singleton instance of the PlansAPI class.

PARAMETER	DESCRIPTION
`options`	The options to initialize the payments class TYPE: `PaymentOptions`

RETURNS	DESCRIPTION
`PlansAPI`	The instance of the PlansAPI class

Source code in payments_py/api/plans_api.py

@classmethod
def get_instance(cls, options: PaymentOptions) -> "PlansAPI":
    """
    Get a singleton instance of the PlansAPI class.

    Args:
        options: The options to initialize the payments class

    Returns:
        The instance of the PlansAPI class
    """
    return cls(options)

register_plan ¶

register_plan(
    plan_metadata: PlanMetadata,
    price_config: PlanPriceConfig,
    credits_config: PlanCreditsConfig,
    nonce: Optional[int] = None,
    access_limit: Optional[
        Literal["credits", "time"]
    ] = None,
    organization_id: Optional[str] = None,
) -> Dict[str, str]

Allows an AI Builder to create a Payment Plan on Nevermined in a flexible manner. A Nevermined Credits Plan limits access based on plan usage. With them, AI Builders control the number of requests that can be made to an agent or service. Every time a user accesses any resource associated with the Payment Plan, the usage consumes from a capped amount of credits. When the user consumes all the credits, the plan automatically expires and the user needs to top up to continue using the service.

PARAMETER	DESCRIPTION
`plan_metadata`	Plan metadata TYPE: `PlanMetadata`
`price_config`	Plan price configuration TYPE: `PlanPriceConfig`
`credits_config`	Plan credits configuration TYPE: `PlanCreditsConfig`
`nonce`	Optional nonce for the transaction TYPE: `Optional[int]` DEFAULT: `None`
`access_limit`	Optional access limit for the plan TYPE: `Optional[Literal['credits', 'time']]` DEFAULT: `None`
`organization_id`	Optional org id (e.g. `"org-..."`) to publish into for this call only. Sends an `X-Current-Org-Id` header without mutating the instance-level pin. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Dict[str, str]`	The unique identifier of the plan (Plan ID) of the newly created plan

RAISES	DESCRIPTION
`PaymentsError`	If registration fails

Source code in payments_py/api/plans_api.py

def register_plan(
    self,
    plan_metadata: PlanMetadata,
    price_config: PlanPriceConfig,
    credits_config: PlanCreditsConfig,
    nonce: Optional[int] = None,
    access_limit: Optional[
        Literal["credits", "time"]
    ] = None,  # 'credits' or 'time'
    organization_id: Optional[str] = None,
) -> Dict[str, str]:
    """
    Allows an AI Builder to create a Payment Plan on Nevermined in a flexible manner.
    A Nevermined Credits Plan limits access based on plan usage.
    With them, AI Builders control the number of requests that can be made to an agent or service.
    Every time a user accesses any resource associated with the Payment Plan, the usage consumes from a capped amount of credits.
    When the user consumes all the credits, the plan automatically expires and the user needs to top up to continue using the service.

    Args:
        plan_metadata: Plan metadata
        price_config: Plan price configuration
        credits_config: Plan credits configuration
        nonce: Optional nonce for the transaction
        access_limit: Optional access limit for the plan
        organization_id: Optional org id (e.g. ``"org-..."``) to publish
            into for this call only. Sends an ``X-Current-Org-Id``
            header without mutating the instance-level pin.

    Returns:
        The unique identifier of the plan (Plan ID) of the newly created plan

    Raises:
        PaymentsError: If registration fails
    """
    if access_limit and access_limit not in ["credits", "time"]:
        raise PaymentsError.validation(
            "Invalid access limit",
            "accessLimit must be either 'credits' or 'time'",
        )
    if not access_limit:
        access_limit = "time" if credits_config.duration_secs > 0 else "credits"

    if nonce is None:
        nonce = get_random_big_int()

    price_dict = self.pydantic_to_dict(price_config)
    body = {
        "metadataAttributes": self.pydantic_to_dict(plan_metadata),
        "priceConfig": price_dict,
        "creditsConfig": self.pydantic_to_dict(credits_config),
        # Send `nonce` as a decimal string so the backend's uint256
        # validator (BCK.COMMON.0026) accepts it for very large
        # values that would overflow JSON's safe-integer range.
        # The TypeScript SDK gets this for free via the BigInt
        # `jsonReplacer`; Python needs the explicit cast.
        "nonce": str(nonce),
        "isTrialPlan": getattr(plan_metadata, "is_trial_plan", False),
        "accessLimit": access_limit,
    }
    if price_dict.get("currency"):
        body["currency"] = price_dict["currency"]

    options = self.get_backend_http_options(
        "POST", body, extra_headers=resolve_publication_headers(organization_id)
    )
    url = f"{self.environment.backend}{API_URL_REGISTER_PLAN}"

    response = requests.post(url, **options)
    if not response.ok:
        raise PaymentsError.internal(
            f"Unable to register plan. {response.status_code} - {response.text}"
        )

    return response.json()

register_credits_plan ¶

register_credits_plan(
    plan_metadata: PlanMetadata,
    price_config: PlanPriceConfig,
    credits_config: PlanCreditsConfig,
    organization_id: Optional[str] = None,
) -> Dict[str, str]

Allows an AI Builder to create a Payment Plan on Nevermined based on Credits. A Nevermined Credits Plan limits the access by the access/usage of the Plan. With them, AI Builders control the number of requests that can be made to an agent or service. Every time a user accesses any resource associated with the Payment Plan, the usage consumes from a capped amount of credits. When the user consumes all the credits, the plan automatically expires and the user needs to top up to continue using the service.

PARAMETER	DESCRIPTION
`plan_metadata`	Plan metadata TYPE: `PlanMetadata`
`price_config`	Plan price configuration TYPE: `PlanPriceConfig`
`credits_config`	Plan credits configuration TYPE: `PlanCreditsConfig`
`organization_id`	Optional org id to publish into for this call. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Dict[str, str]`	The unique identifier of the plan (Plan ID) of the newly created plan

RAISES	DESCRIPTION
`PaymentsError`	If the credits configuration is invalid

Source code in payments_py/api/plans_api.py

def register_credits_plan(
    self,
    plan_metadata: PlanMetadata,
    price_config: PlanPriceConfig,
    credits_config: PlanCreditsConfig,
    organization_id: Optional[str] = None,
) -> Dict[str, str]:
    """
    Allows an AI Builder to create a Payment Plan on Nevermined based on Credits.
    A Nevermined Credits Plan limits the access by the access/usage of the Plan.
    With them, AI Builders control the number of requests that can be made to an agent or service.
    Every time a user accesses any resource associated with the Payment Plan, the usage consumes from a capped amount of credits.
    When the user consumes all the credits, the plan automatically expires and the user needs to top up to continue using the service.

    Args:
        plan_metadata: Plan metadata
        price_config: Plan price configuration
        credits_config: Plan credits configuration
        organization_id: Optional org id to publish into for this call.

    Returns:
        The unique identifier of the plan (Plan ID) of the newly created plan

    Raises:
        PaymentsError: If the credits configuration is invalid
    """

    if credits_config.min_amount > credits_config.max_amount:
        raise PaymentsError.validation(
            "The creditsConfig.minAmount can not be more than creditsConfig.maxAmount"
        )

    return self.register_plan(
        plan_metadata,
        price_config,
        credits_config,
        access_limit="credits",
        organization_id=organization_id,
    )

register_time_plan ¶

register_time_plan(
    plan_metadata: PlanMetadata,
    price_config: PlanPriceConfig,
    credits_config: PlanCreditsConfig,
    organization_id: Optional[str] = None,
) -> Dict[str, str]

Allows an AI Builder to create a Payment Plan on Nevermined limited by duration. A Nevermined Credits Plan limits the access by the access/usage of the Plan. With them, AI Builders control the number of requests that can be made to an agent or service. Every time a user accesses any resource associated with the Payment Plan, the usage consumes from a capped amount of credits. When the user consumes all the credits, the plan automatically expires and the user needs to top up to continue using the service.

PARAMETER	DESCRIPTION
`plan_metadata`	Plan metadata TYPE: `PlanMetadata`
`price_config`	Plan price configuration TYPE: `PlanPriceConfig`
`credits_config`	Plan credits configuration TYPE: `PlanCreditsConfig`
`organization_id`	Optional org id to publish into for this call. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Dict[str, str]`	The unique identifier of the plan (Plan ID) of the newly created plan

RAISES	DESCRIPTION
`PaymentsError`	If the credits configuration is invalid

Source code in payments_py/api/plans_api.py

def register_time_plan(
    self,
    plan_metadata: PlanMetadata,
    price_config: PlanPriceConfig,
    credits_config: PlanCreditsConfig,
    organization_id: Optional[str] = None,
) -> Dict[str, str]:
    """
    Allows an AI Builder to create a Payment Plan on Nevermined limited by duration.
    A Nevermined Credits Plan limits the access by the access/usage of the Plan.
    With them, AI Builders control the number of requests that can be made to an agent or service.
    Every time a user accesses any resource associated with the Payment Plan, the usage consumes from a capped amount of credits.
    When the user consumes all the credits, the plan automatically expires and the user needs to top up to continue using the service.

    Args:
        plan_metadata: Plan metadata
        price_config: Plan price configuration
        credits_config: Plan credits configuration
        organization_id: Optional org id to publish into for this call.

    Returns:
        The unique identifier of the plan (Plan ID) of the newly created plan

    Raises:
        PaymentsError: If the credits configuration is invalid
    """

    return self.register_plan(
        plan_metadata,
        price_config,
        credits_config,
        access_limit="time",
        organization_id=organization_id,
    )

register_credits_trial_plan ¶

register_credits_trial_plan(
    plan_metadata: PlanMetadata,
    price_config: PlanPriceConfig,
    credits_config: PlanCreditsConfig,
    organization_id: Optional[str] = None,
) -> Dict[str, str]

Allows an AI Builder to create a Trial Payment Plan on Nevermined based on Credits. A Nevermined Trial Plan allow subscribers of that plan to test the Agents associated to it. A Trial plan is a plan that only can be purchased once by a user.

PARAMETER	DESCRIPTION
`plan_metadata`	Plan metadata TYPE: `PlanMetadata`
`price_config`	Plan price configuration TYPE: `PlanPriceConfig`
`credits_config`	Plan credits configuration TYPE: `PlanCreditsConfig`
`organization_id`	Optional org id to publish into for this call. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Dict[str, str]`	The unique identifier of the plan (Plan ID) of the newly created plan

Source code in payments_py/api/plans_api.py

def register_credits_trial_plan(
    self,
    plan_metadata: PlanMetadata,
    price_config: PlanPriceConfig,
    credits_config: PlanCreditsConfig,
    organization_id: Optional[str] = None,
) -> Dict[str, str]:
    """
    Allows an AI Builder to create a Trial Payment Plan on Nevermined based on Credits.
    A Nevermined Trial Plan allow subscribers of that plan to test the Agents associated to it.
    A Trial plan is a plan that only can be purchased once by a user.

    Args:
        plan_metadata: Plan metadata
        price_config: Plan price configuration
        credits_config: Plan credits configuration
        organization_id: Optional org id to publish into for this call.

    Returns:
        The unique identifier of the plan (Plan ID) of the newly created plan
    """
    plan_metadata.is_trial_plan = True
    return self.register_credits_plan(
        plan_metadata,
        price_config,
        credits_config,
        organization_id=organization_id,
    )

register_time_trial_plan ¶

register_time_trial_plan(
    plan_metadata: PlanMetadata,
    price_config: PlanPriceConfig,
    credits_config: PlanCreditsConfig,
    organization_id: Optional[str] = None,
) -> Dict[str, str]

Allows an AI Builder to create a Trial Payment Plan on Nevermined limited by duration. A Nevermined Trial Plan allow subscribers of that plan to test the Agents associated to it. A Trial plan is a plan that only can be purchased once by a user.

PARAMETER	DESCRIPTION
`plan_metadata`	Plan metadata TYPE: `PlanMetadata`
`price_config`	Plan price configuration TYPE: `PlanPriceConfig`
`credits_config`	Plan credits configuration TYPE: `PlanCreditsConfig`
`organization_id`	Optional org id to publish into for this call. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Dict[str, str]`	The unique identifier of the plan (Plan ID) of the newly created plan

Source code in payments_py/api/plans_api.py

def register_time_trial_plan(
    self,
    plan_metadata: PlanMetadata,
    price_config: PlanPriceConfig,
    credits_config: PlanCreditsConfig,
    organization_id: Optional[str] = None,
) -> Dict[str, str]:
    """
    Allows an AI Builder to create a Trial Payment Plan on Nevermined limited by duration.
    A Nevermined Trial Plan allow subscribers of that plan to test the Agents associated to it.
    A Trial plan is a plan that only can be purchased once by a user.

    Args:
        plan_metadata: Plan metadata
        price_config: Plan price configuration
        credits_config: Plan credits configuration
        organization_id: Optional org id to publish into for this call.

    Returns:
        The unique identifier of the plan (Plan ID) of the newly created plan
    """
    plan_metadata.is_trial_plan = True
    return self.register_time_plan(
        plan_metadata,
        price_config,
        credits_config,
        organization_id=organization_id,
    )

get_plan ¶

get_plan(plan_id: str) -> Dict[str, Any]

Get the metadata for a given Plan identifier.

PARAMETER	DESCRIPTION
`plan_id`	The unique identifier of the plan TYPE: `str`

RETURNS	DESCRIPTION
`Dict[str, Any]`	The plan's metadata

RAISES	DESCRIPTION
`PaymentsError`	If the plan is not found

Source code in payments_py/api/plans_api.py

def get_plan(self, plan_id: str) -> Dict[str, Any]:
    """
    Get the metadata for a given Plan identifier.

    Args:
        plan_id: The unique identifier of the plan

    Returns:
        The plan's metadata

    Raises:
        PaymentsError: If the plan is not found
    """
    url = f"{self.environment.backend}{API_URL_GET_PLAN.format(plan_id=plan_id)}"
    response = requests.get(url, **self.get_public_http_options("GET"))
    if not response.ok:
        raise PaymentsError.validation(
            f"Plan not found. {response.status_code} - {response.text}"
        )
    return response.json()

get_user_plans ¶

get_user_plans(
    org_id: Optional[str] = None,
    pagination: Optional[PaginationOptions] = None,
) -> Dict[str, Any]

List the payment plans published by the current user.

Returns only the plans the authenticated account created — this is account management ("my plans"), not a marketplace search, and never returns other users' plans. Pass org_id to list every plan in an organization you are a member of instead.

Analogous to plans.getPlans() in the TypeScript SDK; this method also accepts org_id to scope the listing to an organization.

PARAMETER	DESCRIPTION
`org_id`	Optional organization id. When set, returns every plan in that organization (the backend rejects orgs you are not an active member of); when omitted, returns the plans authored by the caller. TYPE: `Optional[str]` DEFAULT: `None`
`pagination`	Optional pagination options (page, offset, sort_by, sort_order). TYPE: `Optional[PaginationOptions]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Dict[str, Any]`	A paginated result of the shape
`Dict[str, Any]`	`{"total", "page", "offset", "plans": [...]}`.

RAISES	DESCRIPTION
`PaymentsError`	If the request fails.

Source code in payments_py/api/plans_api.py

def get_user_plans(
    self,
    org_id: Optional[str] = None,
    pagination: Optional[PaginationOptions] = None,
) -> Dict[str, Any]:
    """
    List the payment plans published by the current user.

    Returns only the plans the authenticated account created — this is
    account management ("my plans"), not a marketplace search, and never
    returns other users' plans. Pass ``org_id`` to list every plan in an
    organization you are a member of instead.

    Analogous to ``plans.getPlans()`` in the TypeScript SDK; this method
    also accepts ``org_id`` to scope the listing to an organization.

    Args:
        org_id: Optional organization id. When set, returns every plan in
            that organization (the backend rejects orgs you are not an
            active member of); when omitted, returns the plans authored by
            the caller.
        pagination: Optional pagination options (page, offset, sort_by,
            sort_order).

    Returns:
        A paginated result of the shape
        ``{"total", "page", "offset", "plans": [...]}``.

    Raises:
        PaymentsError: If the request fails.
    """
    if pagination is None:
        pagination = PaginationOptions()

    url = f"{self.environment.backend}{API_URL_GET_USER_PLANS}"
    params: Dict[str, Any] = {
        "page": pagination.page,
        "offset": pagination.offset,
    }
    if pagination.sort_by:
        params["sortBy"] = pagination.sort_by
    if pagination.sort_order:
        params["sortOrder"] = pagination.sort_order
    if org_id:
        params["orgId"] = org_id

    response = requests.get(
        url, params=params, **self.get_backend_http_options("GET")
    )
    if not response.ok:
        try:
            error = response.json()
        except ValueError:
            # Non-JSON error body (e.g. a gateway HTML 502).
            error = {"message": response.text, "code": response.status_code}
        raise PaymentsError.from_backend("Unable to get user plans", error)
    return response.json()

get_plan_balance ¶

get_plan_balance(
    plan_id: str, account_address: Optional[str] = None
) -> Dict[str, Any]

Get the balance of a plan for a specific account.

PARAMETER	DESCRIPTION
`plan_id`	The unique identifier of the plan TYPE: `str`
`account_address`	The account address to check balance for (defaults to current user) TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Dict[str, Any]`	The plan balance information with properly typed fields (balance as int)

RAISES	DESCRIPTION
`PaymentsError`	If unable to get plan balance

Source code in payments_py/api/plans_api.py

def get_plan_balance(
    self, plan_id: str, account_address: Optional[str] = None
) -> Dict[str, Any]:
    """
    Get the balance of a plan for a specific account.

    Args:
        plan_id: The unique identifier of the plan
        account_address: The account address to check balance for (defaults to current user)

    Returns:
        The plan balance information with properly typed fields (balance as int)

    Raises:
        PaymentsError: If unable to get plan balance
    """

    if not is_ethereum_address(account_address):
        account_address = self.get_account_address()

    url = f"{self.environment.backend}{API_URL_PLAN_BALANCE.format(plan_id=plan_id, holder_address=account_address)}"
    response = requests.get(url, **self.get_public_http_options("GET"))
    if not response.ok:
        raise PaymentsError.internal(
            f"Unable to get plan balance. {response.status_code} - {response.text}"
        )

    # Parse and validate response using Pydantic model to ensure type conversion
    response_data = response.json()
    return PlanBalance(**response_data)

order_plan ¶

order_plan(plan_id: str) -> Dict[str, bool]

Order a plan by its ID.

PARAMETER	DESCRIPTION
`plan_id`	The ID of the plan to order TYPE: `str`

RETURNS	DESCRIPTION
`Dict[str, bool]`	The result of the order operation

RAISES	DESCRIPTION
`PaymentsError`	If unable to order the plan

Source code in payments_py/api/plans_api.py

def order_plan(self, plan_id: str) -> Dict[str, bool]:
    """
    Order a plan by its ID.

    Args:
        plan_id: The ID of the plan to order

    Returns:
        The result of the order operation

    Raises:
        PaymentsError: If unable to order the plan
    """
    options = self.get_backend_http_options("POST")
    url = f"{self.environment.backend}{API_URL_ORDER_PLAN}".format(plan_id=plan_id)

    response = requests.post(url, **options)
    if not response.ok:
        raise PaymentsError.internal(
            f"Unable to order plan. {response.status_code} - {response.text}"
        )
    return response.json()

mint_plan_credits ¶

mint_plan_credits(
    plan_id: str, credits_amount: int, credits_receiver: str
) -> Dict[str, Any]

Mint credits for a plan.

PARAMETER	DESCRIPTION
`plan_id`	The unique identifier of the plan TYPE: `str`
`credits_amount`	The amount of credits to mint TYPE: `int`
`credits_receiver`	The address that will receive the credits TYPE: `str`

RETURNS	DESCRIPTION
`Dict[str, Any]`	The result of the mint operation

RAISES	DESCRIPTION
`PaymentsError`	If unable to mint credits

Source code in payments_py/api/plans_api.py

def mint_plan_credits(
    self, plan_id: str, credits_amount: int, credits_receiver: str
) -> Dict[str, Any]:
    """
    Mint credits for a plan.

    Args:
        plan_id: The unique identifier of the plan
        credits_amount: The amount of credits to mint
        credits_receiver: The address that will receive the credits

    Returns:
        The result of the mint operation

    Raises:
        PaymentsError: If unable to mint credits
    """
    body = {
        "planId": plan_id,
        "amount": credits_amount,
        "creditsReceiver": credits_receiver,
    }
    options = self.get_backend_http_options("POST", body)
    url = f"{self.environment.backend}{API_URL_MINT_PLAN}"

    response = requests.post(url, **options)
    if not response.ok:
        raise PaymentsError.internal(
            f"Unable to mint credits. {response.status_code} - {response.text}"
        )
    return response.json()

mint_plan_expirable ¶

mint_plan_expirable(
    plan_id: str,
    credits_amount: int,
    credits_receiver: str,
    credits_duration: int = 0,
) -> Dict[str, Any]

Mint expirable credits for a plan.

PARAMETER	DESCRIPTION
`plan_id`	The unique identifier of the plan TYPE: `str`
`credits_amount`	The amount of credits to mint TYPE: `int`
`credits_receiver`	The address that will receive the credits TYPE: `str`
`credits_duration`	The duration of the credits in seconds TYPE: `int` DEFAULT: `0`

RETURNS	DESCRIPTION
`Dict[str, Any]`	The result of the mint operation

RAISES	DESCRIPTION
`PaymentsError`	If unable to mint credits

Source code in payments_py/api/plans_api.py

def mint_plan_expirable(
    self,
    plan_id: str,
    credits_amount: int,
    credits_receiver: str,
    credits_duration: int = 0,
) -> Dict[str, Any]:
    """
    Mint expirable credits for a plan.

    Args:
        plan_id: The unique identifier of the plan
        credits_amount: The amount of credits to mint
        credits_receiver: The address that will receive the credits
        credits_duration: The duration of the credits in seconds

    Returns:
        The result of the mint operation

    Raises:
        PaymentsError: If unable to mint credits
    """
    body = {
        "planId": plan_id,
        "creditsAmount": credits_amount,
        "creditsReceiver": credits_receiver,
        "creditsDuration": credits_duration,
    }
    options = self.get_backend_http_options("POST", body)
    url = f"{self.environment.backend}{API_URL_MINT_EXPIRABLE_PLAN}"

    response = requests.post(url, **options)
    if not response.ok:
        raise PaymentsError.internal(
            f"Unable to mint expirable credits. {response.status_code} - {response.text}"
        )
    return response.json()

burn_credits ¶

burn_credits(
    plan_id: str, credits_amount: str
) -> Dict[str, Any]

Burn credits from a plan.

PARAMETER	DESCRIPTION
`plan_id`	The unique identifier of the plan TYPE: `str`
`credits_amount`	The amount of credits to burn TYPE: `str`

RETURNS	DESCRIPTION
`Dict[str, Any]`	The result of the burn operation

RAISES	DESCRIPTION
`PaymentsError`	If unable to burn credits

Source code in payments_py/api/plans_api.py

def burn_credits(self, plan_id: str, credits_amount: str) -> Dict[str, Any]:
    """
    Burn credits from a plan.

    Args:
        plan_id: The unique identifier of the plan
        credits_amount: The amount of credits to burn

    Returns:
        The result of the burn operation

    Raises:
        PaymentsError: If unable to burn credits
    """
    body = {
        "planId": plan_id,
        "creditsAmount": credits_amount,
    }
    options = self.get_backend_http_options("POST", body)
    url = f"{self.environment.backend}{API_URL_BURN_PLAN}"

    response = requests.post(url, **options)
    if not response.ok:
        raise PaymentsError.internal(
            f"Unable to burn credits. {response.status_code} - {response.text}"
        )
    return response.json()

get_agents_associated_to_plan ¶

get_agents_associated_to_plan(
    plan_id: str,
    pagination: Optional[PaginationOptions] = None,
) -> Dict[str, Any]

Gets the list of agents that can be accessed with a plan.

PARAMETER	DESCRIPTION
`plan_id`	The unique identifier of the plan TYPE: `str`
`pagination`	Optional pagination options to control the number of results returned TYPE: `Optional[PaginationOptions]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Dict[str, Any]`	The list of all different agents giving access to the plan

RAISES	DESCRIPTION
`PaymentsError`	If the plan is not found

Source code in payments_py/api/plans_api.py

def get_agents_associated_to_plan(
    self, plan_id: str, pagination: Optional[PaginationOptions] = None
) -> Dict[str, Any]:
    """
    Gets the list of agents that can be accessed with a plan.

    Args:
        plan_id: The unique identifier of the plan
        pagination: Optional pagination options to control the number of results returned

    Returns:
        The list of all different agents giving access to the plan

    Raises:
        PaymentsError: If the plan is not found
    """
    if pagination is None:
        pagination = PaginationOptions()

    url = f"{self.environment.backend}{API_URL_GET_PLAN_AGENTS.format(plan_id=plan_id)}"
    params = {
        "page": pagination.page,
        "offset": pagination.offset,
    }
    response = requests.get(
        url, params=params, **self.get_public_http_options("GET")
    )
    if not response.ok:
        raise PaymentsError.internal(
            f"Unable to get agents associated to plan. {response.status_code} - {response.text}"
        )
    return response.json()

get_fiat_price_config `staticmethod` ¶

get_fiat_price_config(
    amount: int, receiver: str, currency: str = "USD"
) -> PlanPriceConfig

Build a fiat price configuration.

Source code in payments_py/api/plans_api.py

@staticmethod
def get_fiat_price_config(
    amount: int, receiver: str, currency: str = "USD"
) -> PlanPriceConfig:
    """Build a fiat price configuration."""
    return plan_utils.get_fiat_price_config(amount, receiver, currency)

get_eurc_price_config `staticmethod` ¶

get_eurc_price_config(
    amount: int,
    receiver: str,
    eurc_address: str = plan_utils.EURC_TOKEN_ADDRESS,
) -> PlanPriceConfig

Build an EURC (Euro stablecoin) price configuration.

Source code in payments_py/api/plans_api.py

@staticmethod
def get_eurc_price_config(
    amount: int,
    receiver: str,
    eurc_address: str = plan_utils.EURC_TOKEN_ADDRESS,
) -> PlanPriceConfig:
    """Build an EURC (Euro stablecoin) price configuration."""
    return plan_utils.get_eurc_price_config(amount, receiver, eurc_address)

get_crypto_price_config `staticmethod` ¶

get_crypto_price_config(
    amount: int,
    receiver: str,
    token_address: str = "0x0000000000000000000000000000000000000000",
) -> PlanPriceConfig

Build a crypto (native/ERC20) price configuration.

Source code in payments_py/api/plans_api.py

@staticmethod
def get_crypto_price_config(
    amount: int,
    receiver: str,
    token_address: str = "0x0000000000000000000000000000000000000000",
) -> PlanPriceConfig:
    """Build a crypto (native/ERC20) price configuration."""
    return plan_utils.get_crypto_price_config(amount, receiver, token_address)

get_erc20_price_config `staticmethod` ¶

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

Build an ERC20 price configuration.

Source code in payments_py/api/plans_api.py

@staticmethod
def get_erc20_price_config(
    amount: int, token_address: str, receiver: str
) -> PlanPriceConfig:
    """Build an ERC20 price configuration."""
    return plan_utils.get_erc20_price_config(amount, token_address, receiver)

get_free_price_config `staticmethod` ¶

get_free_price_config() -> PlanPriceConfig

Build a free price configuration.

Source code in payments_py/api/plans_api.py

@staticmethod
def get_free_price_config() -> PlanPriceConfig:
    """Build a free price configuration."""
    return plan_utils.get_free_price_config()

get_native_token_price_config `staticmethod` ¶

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

Build a native token price configuration.

Source code in payments_py/api/plans_api.py

@staticmethod
def get_native_token_price_config(amount: int, receiver: str) -> PlanPriceConfig:
    """Build a native token price configuration."""
    return plan_utils.get_native_token_price_config(amount, receiver)

get_expirable_duration_config `staticmethod` ¶

get_expirable_duration_config(
    duration_of_plan: int,
) -> PlanCreditsConfig

Build an expirable duration credits configuration.

Source code in payments_py/api/plans_api.py

@staticmethod
def get_expirable_duration_config(duration_of_plan: int) -> PlanCreditsConfig:
    """Build an expirable duration credits configuration."""
    return plan_utils.get_expirable_duration_config(duration_of_plan)

get_non_expirable_duration_config `staticmethod` ¶

get_non_expirable_duration_config() -> PlanCreditsConfig

Build a non-expirable duration credits configuration.

Source code in payments_py/api/plans_api.py

@staticmethod
def get_non_expirable_duration_config() -> PlanCreditsConfig:
    """Build a non-expirable duration credits configuration."""
    return plan_utils.get_non_expirable_duration_config()

get_fixed_credits_config `staticmethod` ¶

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

Build a fixed credits configuration.

Source code in payments_py/api/plans_api.py

@staticmethod
def get_fixed_credits_config(
    credits_granted: int, credits_per_request: int = 1
) -> PlanCreditsConfig:
    """Build a fixed credits configuration."""
    return plan_utils.get_fixed_credits_config(credits_granted, credits_per_request)

get_dynamic_credits_config `staticmethod` ¶

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

Build a dynamic credits configuration.

Source code in payments_py/api/plans_api.py

@staticmethod
def get_dynamic_credits_config(
    credits_granted: int,
    min_credits_per_request: int = 1,
    max_credits_per_request: int = 1,
) -> PlanCreditsConfig:
    """Build a dynamic credits configuration."""
    return plan_utils.get_dynamic_credits_config(
        credits_granted, min_credits_per_request, max_credits_per_request
    )

set_redemption_type `staticmethod` ¶

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

Set redemption type on a credits configuration (returns new object).

Source code in payments_py/api/plans_api.py

@staticmethod
def set_redemption_type(
    credits_config: PlanCreditsConfig, redemption_type: PlanRedemptionType
) -> PlanCreditsConfig:
    """Set redemption type on a credits configuration (returns new object)."""
    return plan_utils.set_redemption_type(credits_config, redemption_type)

set_onchain_mirror `staticmethod` ¶

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

Set the on-chain mirror flag on a credits configuration (returns new object).

Source code in payments_py/api/plans_api.py

@staticmethod
def set_onchain_mirror(
    credits_config: PlanCreditsConfig, onchain_mirror: bool = True
) -> PlanCreditsConfig:
    """Set the on-chain mirror flag on a credits configuration (returns new object)."""
    return plan_utils.set_onchain_mirror(credits_config, onchain_mirror)

get_pay_as_you_go_price_config ¶

get_pay_as_you_go_price_config(
    amount: int,
    receiver: str,
    token_address: str = plan_utils.ZeroAddress,
) -> PlanPriceConfig

Build a pay-as-you-go price configuration using contract address from API.

This method fetches the PayAsYouGoTemplate contract address from the API info endpoint and uses it to create the price configuration. The address is cached for subsequent calls.

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

RETURNS	DESCRIPTION
`PlanPriceConfig`	A PlanPriceConfig object configured for pay-as-you-go payments

RAISES	DESCRIPTION
`PaymentsError`	If unable to fetch contract address from API
`ValueError`	If the receiver address is not a valid Ethereum address

Source code in payments_py/api/plans_api.py

def get_pay_as_you_go_price_config(
    self,
    amount: int,
    receiver: str,
    token_address: str = plan_utils.ZeroAddress,
) -> PlanPriceConfig:
    """
    Build a pay-as-you-go price configuration using contract address from API.

    This method fetches the PayAsYouGoTemplate contract address from the API info endpoint
    and uses it to create the price configuration. The address is cached for subsequent calls.

    Args:
        amount: The amount per usage 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 pay-as-you-go payments

    Raises:
        PaymentsError: If unable to fetch contract address from API
        ValueError: If the receiver address is not a valid Ethereum address
    """
    # Get contract address from contracts API
    template_address = self.contracts_api.contracts.pay_as_you_go_template

    return get_pay_as_you_go_price_config(
        amount, receiver, token_address, template_address=template_address
    )

get_pay_as_you_go_credits_config `staticmethod` ¶

get_pay_as_you_go_credits_config() -> PlanCreditsConfig

Build a pay-as-you-go credits configuration.

Source code in payments_py/api/plans_api.py

@staticmethod
def get_pay_as_you_go_credits_config() -> PlanCreditsConfig:
    """Build a pay-as-you-go credits configuration."""
    return get_pay_as_you_go_credits_config()

order_fiat_plan ¶

order_fiat_plan(plan_id: str) -> Dict[str, Any]

Order a fiat plan using Stripe checkout.

PARAMETER	DESCRIPTION
`plan_id`	The unique identifier of the plan TYPE: `str`

RETURNS	DESCRIPTION
`Dict[str, Any]`	The Stripe checkout result

RAISES	DESCRIPTION
`PaymentsError`	If unable to order the fiat plan

Source code in payments_py/api/plans_api.py

def order_fiat_plan(self, plan_id: str) -> Dict[str, Any]:
    """
    Order a fiat plan using Stripe checkout.

    Args:
        plan_id: The unique identifier of the plan

    Returns:
        The Stripe checkout result

    Raises:
        PaymentsError: If unable to order the fiat plan
    """
    body = {"planId": plan_id, "sessionType": "embedded"}
    options = self.get_backend_http_options("POST", body)
    url = f"{self.environment.backend}{API_URL_STRIPE_CHECKOUT}"

    response = requests.post(url, **options)
    if not response.ok:
        raise PaymentsError.internal(
            f"Unable to order fiat plan. {response.status_code} - {response.text}"
        )
    return response.json()

redeem_credits ¶

redeem_credits(
    agent_request_id: str,
    plan_id: str,
    redeem_from: str,
    credits_amount_to_redeem: str,
) -> Dict[str, Any]

Redeem credits from a plan for a specific agent request.

PARAMETER	DESCRIPTION
`agent_request_id`	The unique identifier of the agent request TYPE: `str`
`plan_id`	The unique identifier of the plan TYPE: `str`
`redeem_from`	The address to redeem credits from TYPE: `str`
`credits_amount_to_redeem`	The amount of credits to redeem TYPE: `str`

RETURNS	DESCRIPTION
`Dict[str, Any]`	The result of the redeem operation

RAISES	DESCRIPTION
`PaymentsError`	If unable to redeem credits

Source code in payments_py/api/plans_api.py

def redeem_credits(
    self,
    agent_request_id: str,
    plan_id: str,
    redeem_from: str,
    credits_amount_to_redeem: str,
) -> Dict[str, Any]:
    """
    Redeem credits from a plan for a specific agent request.

    Args:
        agent_request_id: The unique identifier of the agent request
        plan_id: The unique identifier of the plan
        redeem_from: The address to redeem credits from
        credits_amount_to_redeem: The amount of credits to redeem

    Returns:
        The result of the redeem operation

    Raises:
        PaymentsError: If unable to redeem credits
    """
    body = {
        "agentRequestId": agent_request_id,
        "planId": plan_id,
        "redeemFrom": redeem_from,
        "amount": credits_amount_to_redeem,
    }
    options = self.get_backend_http_options("POST", body)
    url = f"{self.environment.backend}{API_URL_REDEEM_PLAN}"

    response = requests.post(url, **options)
    if not response.ok:
        raise PaymentsError.internal(
            f"Unable to redeem credits. {response.status_code} - {response.text}"
        )
    return response.json()

Agents API¶

AgentsAPI ¶

AgentsAPI(options: PaymentOptions)

Bases: BasePaymentsAPI

The AgentsAPI class provides methods to register and interact with AI Agents on Nevermined.

Source code in payments_py/api/base_payments.py

def __init__(self, options: PaymentOptions):
    """
    Initialize the base payments API.

    Args:
        options: The options to initialize the payments class
    """
    self.nvm_api_key = options.nvm_api_key
    self.return_url = options.return_url or ""
    # Preserve the raw (possibly None) ``environment`` option so internal
    # re-inits (e.g. ``Payments._build_options``) reproduce the caller's
    # intent without re-deriving ``custom`` into a spurious deprecation
    # warning.
    self._environment_option = options.environment
    self.environment_name = self._resolve_environment(
        options.nvm_api_key, options.environment
    )
    self.environment = get_environment(self.environment_name)
    self.app_id = options.app_id
    self.version = options.version
    # Backend API version (monorepo MAJOR.MINOR) declared on every
    # request via the ``Nevermined-Version`` header. Defaults to the
    # version this SDK release is built/tested against.
    self.api_version: str = options.api_version or LOCKED_API_VERSION
    self.account_address: Optional[str] = None
    self.helicone_api_key: str = None
    self.is_browser_instance = True
    self.current_organization_id: Optional[str] = options.organization_id
    self._parse_nvm_api_key()

get_instance `classmethod` ¶

get_instance(options: PaymentOptions) -> AgentsAPI

Get a singleton instance of the AgentsAPI class.

PARAMETER	DESCRIPTION
`options`	The options to initialize the payments class TYPE: `PaymentOptions`

RETURNS	DESCRIPTION
`AgentsAPI`	The instance of the AgentsAPI class

Source code in payments_py/api/agents_api.py

@classmethod
def get_instance(cls, options: PaymentOptions) -> "AgentsAPI":
    """
    Get a singleton instance of the AgentsAPI class.

    Args:
        options: The options to initialize the payments class

    Returns:
        The instance of the AgentsAPI class
    """
    return cls(options)

register_agent ¶

register_agent(
    agent_metadata: AgentMetadata,
    agent_api: AgentAPIAttributes,
    payment_plans: List[str],
    organization_id: Optional[str] = None,
) -> Dict[str, str]

Registers a new AI Agent on Nevermined. The agent must be associated to one or multiple Payment Plans. Users that are subscribers of a payment plan can query the agent. Depending on the Payment Plan and the configuration of the agent, the usage of the agent/service will consume credits. When the plan expires (because the time is over or the credits are consumed), the user needs to renew the plan to continue using the agent.

PARAMETER	DESCRIPTION
`agent_metadata`	Agent metadata TYPE: `AgentMetadata`
`agent_api`	Agent API attributes TYPE: `AgentAPIAttributes`
`payment_plans`	The list of payment plans giving access to the agent TYPE: `List[str]`
`organization_id`	Optional org id (e.g. `"org-..."`) to publish into for this call only. Sends an `X-Current-Org-Id` header without mutating the instance-level pin (set via :meth:`Payments.set_organization_id`). TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Dict[str, str]`	The unique identifier of the newly created agent (Agent Id)

RAISES	DESCRIPTION
`PaymentsError`	If registration fails

Source code in payments_py/api/agents_api.py

def register_agent(
    self,
    agent_metadata: AgentMetadata,
    agent_api: AgentAPIAttributes,
    payment_plans: List[str],
    organization_id: Optional[str] = None,
) -> Dict[str, str]:
    """
    Registers a new AI Agent on Nevermined.
    The agent must be associated to one or multiple Payment Plans. Users that are subscribers of a payment plan can query the agent.
    Depending on the Payment Plan and the configuration of the agent, the usage of the agent/service will consume credits.
    When the plan expires (because the time is over or the credits are consumed), the user needs to renew the plan to continue using the agent.

    Args:
        agent_metadata: Agent metadata
        agent_api: Agent API attributes
        payment_plans: The list of payment plans giving access to the agent
        organization_id: Optional org id (e.g. ``"org-..."``) to publish
            into for this call only. Sends an ``X-Current-Org-Id``
            header without mutating the instance-level pin (set via
            :meth:`Payments.set_organization_id`).

    Returns:
        The unique identifier of the newly created agent (Agent Id)

    Raises:
        PaymentsError: If registration fails
    """
    body = {
        "metadataAttributes": self.pydantic_to_dict(agent_metadata),
        "agentApiAttributes": self.pydantic_to_dict(agent_api),
        "plans": payment_plans,
    }

    options = self.get_backend_http_options(
        "POST", body, extra_headers=resolve_publication_headers(organization_id)
    )
    url = f"{self.environment.backend}{API_URL_REGISTER_AGENT}"

    response = requests.post(url, **options)
    if not response.ok:
        try:
            error = response.json()
        except Exception:
            error = {"message": response.text, "code": response.status_code}
        raise PaymentsError.from_backend("Unable to register agent", error)
    agent_data = response.json()
    return {"agentId": agent_data["data"]["agentId"]}

register_agent_and_plan ¶

register_agent_and_plan(
    agent_metadata: AgentMetadata,
    agent_api: AgentAPIAttributes,
    plan_metadata: PlanMetadata,
    price_config: PlanPriceConfig,
    credits_config: PlanCreditsConfig,
    access_limit: Optional[
        Literal["credits", "time"]
    ] = None,
    organization_id: Optional[str] = None,
) -> Dict[str, str]

Registers a new AI Agent and a Payment Plan associated to this new agent. Depending on the Payment Plan and the configuration of the agent, the usage of the agent/service will consume credits. When the plan expires (because the time is over or the credits are consumed), the user needs to renew the plan to continue using the agent.

PARAMETER	DESCRIPTION
`agent_metadata`	Agent metadata TYPE: `AgentMetadata`
`agent_api`	Agent API attributes TYPE: `AgentAPIAttributes`
`plan_metadata`	Plan metadata TYPE: `PlanMetadata`
`price_config`	Plan price configuration TYPE: `PlanPriceConfig`
`credits_config`	Plan credits configuration TYPE: `PlanCreditsConfig`
`access_limit`	Optional access limit for the plan TYPE: `Optional[Literal['credits', 'time']]` DEFAULT: `None`
`organization_id`	Optional org id (e.g. `"org-..."`) to publish into for this call only. Sends an `X-Current-Org-Id` header without mutating the instance-level pin. TYPE: `Optional[str]` DEFAULT: `None`

Returns: Dictionary containing agentId, planId, and txHash

RAISES	DESCRIPTION
`PaymentsError`	If registration fails

Source code in payments_py/api/agents_api.py

def register_agent_and_plan(
    self,
    agent_metadata: AgentMetadata,
    agent_api: AgentAPIAttributes,
    plan_metadata: PlanMetadata,
    price_config: PlanPriceConfig,
    credits_config: PlanCreditsConfig,
    access_limit: Optional[Literal["credits", "time"]] = None,
    organization_id: Optional[str] = None,
) -> Dict[str, str]:
    """
    Registers a new AI Agent and a Payment Plan associated to this new agent.
    Depending on the Payment Plan and the configuration of the agent, the usage of the agent/service will consume credits.
    When the plan expires (because the time is over or the credits are consumed), the user needs to renew the plan to continue using the agent.

    Args:
        agent_metadata: Agent metadata
        agent_api: Agent API attributes
        plan_metadata: Plan metadata
        price_config: Plan price configuration
        credits_config: Plan credits configuration
        access_limit: Optional access limit for the plan
        organization_id: Optional org id (e.g. ``"org-..."``) to publish
            into for this call only. Sends an ``X-Current-Org-Id``
            header without mutating the instance-level pin.
    Returns:
        Dictionary containing agentId, planId, and txHash

    Raises:
        PaymentsError: If registration fails
    """
    if access_limit and access_limit not in ["credits", "time"]:
        raise PaymentsError.validation(
            "Invalid access limit",
            "accessLimit must be either 'credits' or 'time'",
        )
    if not access_limit:
        access_limit = "time" if credits_config.duration_secs > 0 else "credits"

    body = {
        "plan": {
            "metadataAttributes": self.pydantic_to_dict(plan_metadata),
            "priceConfig": self.pydantic_to_dict(price_config),
            "creditsConfig": self.pydantic_to_dict(credits_config),
            "accessLimit": access_limit,
        },
        "agent": {
            "metadataAttributes": self.pydantic_to_dict(agent_metadata),
            "agentApiAttributes": self.pydantic_to_dict(agent_api),
        },
    }

    options = self.get_backend_http_options(
        "POST", body, extra_headers=resolve_publication_headers(organization_id)
    )
    url = f"{self.environment.backend}{API_URL_REGISTER_AGENTS_AND_PLAN}"

    response = requests.post(url, **options)
    if not response.ok:
        try:
            error = response.json()
        except Exception:
            error = {"message": response.text, "code": response.status_code}
        raise PaymentsError.from_backend("Unable to register agent & plan", error)
    result = response.json()

    return {
        "agentId": result["data"]["agentId"],
        "planId": result["data"]["planId"],
        "txHash": result["txHash"],
    }

get_agent ¶

get_agent(agent_id: str) -> Dict[str, Any]

Gets the metadata for a given Agent identifier.

PARAMETER	DESCRIPTION
`agent_id`	The unique identifier of the agent TYPE: `str`

RETURNS	DESCRIPTION
`Dict[str, Any]`	The agent's metadata

RAISES	DESCRIPTION
`PaymentsError`	If the agent is not found

Source code in payments_py/api/agents_api.py

def get_agent(self, agent_id: str) -> Dict[str, Any]:
    """
    Gets the metadata for a given Agent identifier.

    Args:
        agent_id: The unique identifier of the agent

    Returns:
        The agent's metadata

    Raises:
        PaymentsError: If the agent is not found
    """
    url = f"{self.environment.backend}{API_URL_GET_AGENT.format(agent_id=agent_id)}"
    response = requests.get(url, **self.get_public_http_options("GET"))
    if not response.ok:
        try:
            error = response.json()
        except Exception:
            error = {"message": response.text, "code": response.status_code}
        raise PaymentsError.from_backend("Agent not found", error)
    return response.json()

get_agent_plans ¶

get_agent_plans(
    agent_id: str,
    pagination: Optional[PaginationOptions] = None,
) -> Dict[str, Any]

Gets the list of plans that can be ordered to get access to an agent.

PARAMETER	DESCRIPTION
`agent_id`	The unique identifier of the agent TYPE: `str`
`pagination`	Optional pagination options to control the number of results returned TYPE: `Optional[PaginationOptions]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Dict[str, Any]`	The list of all different plans giving access to the agent

RAISES	DESCRIPTION
`PaymentsError`	If the agent is not found

Source code in payments_py/api/agents_api.py

def get_agent_plans(
    self, agent_id: str, pagination: Optional[PaginationOptions] = None
) -> Dict[str, Any]:
    """
    Gets the list of plans that can be ordered to get access to an agent.

    Args:
        agent_id: The unique identifier of the agent
        pagination: Optional pagination options to control the number of results returned

    Returns:
        The list of all different plans giving access to the agent

    Raises:
        PaymentsError: If the agent is not found
    """
    if pagination is None:
        pagination = PaginationOptions()

    url = f"{self.environment.backend}{API_URL_GET_AGENT_PLANS.format(agent_id=agent_id)}"
    params = {
        "page": pagination.page,
        "offset": pagination.offset,
    }
    response = requests.get(
        url, params=params, **self.get_public_http_options("GET")
    )
    if not response.ok:
        try:
            error = response.json()
        except Exception:
            error = {"message": response.text, "code": response.status_code}
        raise PaymentsError.from_backend("Unable to get agent plans", error)
    return response.json()

get_user_agents ¶

get_user_agents(
    org_id: Optional[str] = None,
    pagination: Optional[PaginationOptions] = None,
) -> Dict[str, Any]

List the AI agents published by the current user.

Returns only the agents the authenticated account created — this is account management ("my agents"), not a marketplace search, and never returns other users' agents. Pass org_id to list every agent in an organization you are a member of instead.

PARAMETER	DESCRIPTION
`org_id`	Optional organization id. When set, returns every agent in that organization (the backend rejects orgs you are not an active member of); when omitted, returns the agents authored by the caller. TYPE: `Optional[str]` DEFAULT: `None`
`pagination`	Optional pagination options (page, offset, sort_by, sort_order). TYPE: `Optional[PaginationOptions]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Dict[str, Any]`	A paginated result of the shape
`Dict[str, Any]`	`{"total", "page", "offset", "agents": [...]}`.

RAISES	DESCRIPTION
`PaymentsError`	If the request fails.

Source code in payments_py/api/agents_api.py

def get_user_agents(
    self,
    org_id: Optional[str] = None,
    pagination: Optional[PaginationOptions] = None,
) -> Dict[str, Any]:
    """
    List the AI agents published by the current user.

    Returns only the agents the authenticated account created — this is
    account management ("my agents"), not a marketplace search, and never
    returns other users' agents. Pass ``org_id`` to list every agent in an
    organization you are a member of instead.

    Args:
        org_id: Optional organization id. When set, returns every agent in
            that organization (the backend rejects orgs you are not an
            active member of); when omitted, returns the agents authored by
            the caller.
        pagination: Optional pagination options (page, offset, sort_by,
            sort_order).

    Returns:
        A paginated result of the shape
        ``{"total", "page", "offset", "agents": [...]}``.

    Raises:
        PaymentsError: If the request fails.
    """
    if pagination is None:
        pagination = PaginationOptions()

    url = f"{self.environment.backend}{API_URL_GET_USER_AGENTS}"
    params: Dict[str, Any] = {
        "page": pagination.page,
        "offset": pagination.offset,
    }
    if pagination.sort_by:
        params["sortBy"] = pagination.sort_by
    if pagination.sort_order:
        params["sortOrder"] = pagination.sort_order
    if org_id:
        params["orgId"] = org_id

    response = requests.get(
        url, params=params, **self.get_backend_http_options("GET")
    )
    if not response.ok:
        try:
            error = response.json()
        except ValueError:
            # Non-JSON error body (e.g. a gateway HTML 502).
            error = {"message": response.text, "code": response.status_code}
        raise PaymentsError.from_backend("Unable to get user agents", error)
    return response.json()

add_plan_to_agent ¶

add_plan_to_agent(
    plan_id: str, agent_id: str
) -> Dict[str, Any]

Add a plan to an agent.

PARAMETER	DESCRIPTION
`plan_id`	The unique identifier of the plan TYPE: `str`
`agent_id`	The unique identifier of the agent TYPE: `str`

RETURNS	DESCRIPTION
`Dict[str, Any]`	The result of the operation

RAISES	DESCRIPTION
`PaymentsError`	If unable to add plan to agent

Source code in payments_py/api/agents_api.py

def add_plan_to_agent(self, plan_id: str, agent_id: str) -> Dict[str, Any]:
    """
    Add a plan to an agent.

    Args:
        plan_id: The unique identifier of the plan
        agent_id: The unique identifier of the agent

    Returns:
        The result of the operation

    Raises:
        PaymentsError: If unable to add plan to agent
    """
    options = self.get_backend_http_options("POST")
    url = f"{self.environment.backend}{API_URL_ADD_PLAN_AGENT.format(agent_id=agent_id, plan_id=plan_id)}"

    response = requests.post(url, **options)
    if not response.ok:
        try:
            error = response.json()
        except Exception:
            error = {"message": response.text, "code": response.status_code}
        raise PaymentsError.from_backend("Unable to add plan to agent", error)
    return response.json()

remove_plan_from_agent ¶

remove_plan_from_agent(
    plan_id: str, agent_id: str
) -> Dict[str, Any]

Remove a plan from an agent.

PARAMETER	DESCRIPTION
`plan_id`	The unique identifier of the plan TYPE: `str`
`agent_id`	The unique identifier of the agent TYPE: `str`

RETURNS	DESCRIPTION
`Dict[str, Any]`	The result of the operation

RAISES	DESCRIPTION
`PaymentsError`	If unable to remove plan from agent

Source code in payments_py/api/agents_api.py

def remove_plan_from_agent(self, plan_id: str, agent_id: str) -> Dict[str, Any]:
    """
    Remove a plan from an agent.

    Args:
        plan_id: The unique identifier of the plan
        agent_id: The unique identifier of the agent

    Returns:
        The result of the operation

    Raises:
        PaymentsError: If unable to remove plan from agent
    """
    url = f"{self.environment.backend}{API_URL_REMOVE_PLAN_AGENT.format(agent_id=agent_id, plan_id=plan_id)}"
    options = self.get_backend_http_options("DELETE")

    response = requests.delete(url, **options)
    if not response.ok:
        try:
            error = response.json()
        except Exception:
            error = {"message": response.text, "code": response.status_code}
        raise PaymentsError.from_backend("Unable to remove plan from agent", error)
    return response.json()

update_agent_metadata ¶

update_agent_metadata(
    agent_id: str,
    agent_metadata: AgentMetadata,
    agent_api: AgentAPIAttributes,
) -> Dict[str, Any]

Updates the metadata and API attributes of an existing AI Agent.

PARAMETER	DESCRIPTION
`agent_id`	The unique identifier of the agent TYPE: `str`
`agent_metadata`	The new metadata attributes for the agent TYPE: `AgentMetadata`
`agent_api`	The new API attributes for the agent TYPE: `AgentAPIAttributes`

RETURNS	DESCRIPTION
`Dict[str, Any]`	The result of the update operation

RAISES	DESCRIPTION
`PaymentsError`	If the agent is not found or if the update fails

Source code in payments_py/api/agents_api.py

def update_agent_metadata(
    self,
    agent_id: str,
    agent_metadata: AgentMetadata,
    agent_api: AgentAPIAttributes,
) -> Dict[str, Any]:
    """
    Updates the metadata and API attributes of an existing AI Agent.

    Args:
        agent_id: The unique identifier of the agent
        agent_metadata: The new metadata attributes for the agent
        agent_api: The new API attributes for the agent

    Returns:
        The result of the update operation

    Raises:
        PaymentsError: If the agent is not found or if the update fails
    """
    body = {
        "metadataAttributes": self.pydantic_to_dict(agent_metadata),
        "agentApiAttributes": self.pydantic_to_dict(agent_api),
    }
    url = f"{self.environment.backend}{API_URL_UPDATE_AGENT.format(agent_id=agent_id)}"
    options = self.get_backend_http_options("PUT", body)
    response = requests.put(url, **options)
    if not response.ok:
        try:
            error = response.json()
        except Exception:
            error = {"message": response.text, "code": response.status_code}
        raise PaymentsError.from_backend("Error updating agent", error)
    return response.json()

Facilitator API (x402)¶

FacilitatorAPI ¶

FacilitatorAPI(options: PaymentOptions)

Bases: BasePaymentsAPI

The FacilitatorAPI class provides methods to verify and settle AI agent permissions. It enables AI agents to act as facilitators, managing credit verification and settlement for subscribers using X402 access tokens.

Source code in payments_py/api/base_payments.py

def __init__(self, options: PaymentOptions):
    """
    Initialize the base payments API.

    Args:
        options: The options to initialize the payments class
    """
    self.nvm_api_key = options.nvm_api_key
    self.return_url = options.return_url or ""
    # Preserve the raw (possibly None) ``environment`` option so internal
    # re-inits (e.g. ``Payments._build_options``) reproduce the caller's
    # intent without re-deriving ``custom`` into a spurious deprecation
    # warning.
    self._environment_option = options.environment
    self.environment_name = self._resolve_environment(
        options.nvm_api_key, options.environment
    )
    self.environment = get_environment(self.environment_name)
    self.app_id = options.app_id
    self.version = options.version
    # Backend API version (monorepo MAJOR.MINOR) declared on every
    # request via the ``Nevermined-Version`` header. Defaults to the
    # version this SDK release is built/tested against.
    self.api_version: str = options.api_version or LOCKED_API_VERSION
    self.account_address: Optional[str] = None
    self.helicone_api_key: str = None
    self.is_browser_instance = True
    self.current_organization_id: Optional[str] = options.organization_id
    self._parse_nvm_api_key()

get_instance `classmethod` ¶

get_instance(options: PaymentOptions) -> FacilitatorAPI

Get a singleton instance of the FacilitatorAPI class.

PARAMETER	DESCRIPTION
`options`	The options to initialize the payments class TYPE: `PaymentOptions`

RETURNS	DESCRIPTION
`FacilitatorAPI`	The instance of the FacilitatorAPI class

Source code in payments_py/x402/facilitator_api.py

@classmethod
def get_instance(cls, options: PaymentOptions) -> "FacilitatorAPI":
    """
    Get a singleton instance of the FacilitatorAPI class.

    Args:
        options: The options to initialize the payments class

    Returns:
        The instance of the FacilitatorAPI class
    """
    return cls(options)

verify_permissions ¶

verify_permissions(
    payment_required: X402PaymentRequired,
    x402_access_token: str,
    max_amount: Optional[str] = None,
) -> VerifyResponse

Verify if a subscriber has permission to use credits from a payment plan. This method simulates the credit usage without actually burning credits, checking if the subscriber has sufficient balance and permissions.

The planId and subscriberAddress are extracted from the x402AccessToken.

PARAMETER	DESCRIPTION
`payment_required`	x402 PaymentRequired from 402 response (required, for validation) TYPE: `X402PaymentRequired`
`x402_access_token`	The X402 access token (contains planId, subscriberAddress, agentId) TYPE: `str`
`max_amount`	The maximum number of credits to verify (as string, optional) TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`VerifyResponse`	VerifyResponse with is_valid boolean and optional error details

RAISES	DESCRIPTION
`PaymentsError`	If verification fails

Source code in payments_py/x402/facilitator_api.py

def verify_permissions(
    self,
    payment_required: X402PaymentRequired,
    x402_access_token: str,
    max_amount: Optional[str] = None,
) -> VerifyResponse:
    """
    Verify if a subscriber has permission to use credits from a payment plan.
    This method simulates the credit usage without actually burning credits,
    checking if the subscriber has sufficient balance and permissions.

    The planId and subscriberAddress are extracted from the x402AccessToken.

    Args:
        payment_required: x402 PaymentRequired from 402 response (required, for validation)
        x402_access_token: The X402 access token (contains planId, subscriberAddress, agentId)
        max_amount: The maximum number of credits to verify (as string, optional)

    Returns:
        VerifyResponse with is_valid boolean and optional error details

    Raises:
        PaymentsError: If verification fails
    """
    url = f"{self.environment.backend}{API_URL_VERIFY_PERMISSIONS}"

    body: dict = {
        "paymentRequired": payment_required.model_dump(by_alias=True),
        "x402AccessToken": x402_access_token,
    }

    if max_amount is not None:
        body["maxAmount"] = max_amount

    # Send the NVM API-key auth header (Authorization: Bearer <nvm_api_key>).
    # The backend /verify endpoint runs an OPTIONAL guard that tolerates the
    # header's absence today, so this is non-breaking; it pre-positions for
    # the later strict-guard flip. See nevermined-io/nvm-monorepo#1570.
    options = self.get_backend_http_options("POST", body)

    try:
        response = requests.post(url, **options)
        response.raise_for_status()
        return VerifyResponse.model_validate(response.json())
    except requests.HTTPError as err:
        raise x402_error_from_response(
            response, "Permission verification failed"
        ) from err
    except Exception as err:
        raise PaymentsError.from_backend(
            "Network error during permission verification",
            {"code": "network_error", "message": str(err)},
        ) from err

settle_permissions ¶

settle_permissions(
    payment_required: X402PaymentRequired,
    x402_access_token: str,
    max_amount: Optional[str] = None,
    agent_request_id: Optional[str] = None,
) -> SettleResponse

Settle (burn) credits from a subscriber's payment plan. This method executes the actual credit consumption, burning the specified number of credits from the subscriber's balance. If the subscriber doesn't have enough credits, it will attempt to order more before settling.

The planId and subscriberAddress are extracted from the x402AccessToken.

PARAMETER	DESCRIPTION
`payment_required`	x402 PaymentRequired from 402 response (required, for validation) TYPE: `X402PaymentRequired`
`x402_access_token`	The X402 access token (contains planId, subscriberAddress, agentId) TYPE: `str`
`max_amount`	The number of credits to burn (as string, optional) TYPE: `Optional[str]` DEFAULT: `None`
`agent_request_id`	Agent request ID for observability tracking (optional) TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`SettleResponse`	SettleResponse with success boolean and transaction details

RAISES	DESCRIPTION
`PaymentsError`	If settlement fails

Source code in payments_py/x402/facilitator_api.py

def settle_permissions(
    self,
    payment_required: X402PaymentRequired,
    x402_access_token: str,
    max_amount: Optional[str] = None,
    agent_request_id: Optional[str] = None,
) -> SettleResponse:
    """
    Settle (burn) credits from a subscriber's payment plan.
    This method executes the actual credit consumption, burning the specified
    number of credits from the subscriber's balance. If the subscriber doesn't
    have enough credits, it will attempt to order more before settling.

    The planId and subscriberAddress are extracted from the x402AccessToken.

    Args:
        payment_required: x402 PaymentRequired from 402 response (required, for validation)
        x402_access_token: The X402 access token (contains planId, subscriberAddress, agentId)
        max_amount: The number of credits to burn (as string, optional)
        agent_request_id: Agent request ID for observability tracking (optional)

    Returns:
        SettleResponse with success boolean and transaction details

    Raises:
        PaymentsError: If settlement fails
    """
    url = f"{self.environment.backend}{API_URL_SETTLE_PERMISSIONS}"

    body: dict = {
        "paymentRequired": payment_required.model_dump(by_alias=True),
        "x402AccessToken": x402_access_token,
    }

    if max_amount is not None:
        body["maxAmount"] = max_amount

    if agent_request_id is not None:
        body["agentRequestId"] = agent_request_id

    # Send the NVM API-key auth header (Authorization: Bearer <nvm_api_key>).
    # The backend /settle endpoint runs an OPTIONAL guard that tolerates the
    # header's absence today, so this is non-breaking; it pre-positions for
    # the later strict-guard flip. See nevermined-io/nvm-monorepo#1570.
    options = self.get_backend_http_options("POST", body)

    try:
        response = requests.post(url, **options)
        response.raise_for_status()
        return SettleResponse.model_validate(response.json())
    except requests.HTTPError as err:
        # A v3 token is single-use: the FIRST settle consumes it, and a
        # replay comes back as BCK.X402.0059. x402_error_from_response
        # promotes that one code to AccessTokenAlreadyUsedError so the
        # caller's remedy ("mint a new token") is not buried in the same
        # generic PaymentsError as a declined plan or a forged envelope.
        raise x402_error_from_response(
            response, "Permission settlement failed"
        ) from err
    except Exception as err:
        raise PaymentsError.from_backend(
            "Network error during permission settlement",
            {"code": "network_error", "message": str(err)},
        ) from err

MPP API¶

MppAPI ¶

MppAPI(options: PaymentOptions)

Bases: BasePaymentsAPI

Challenge issuance, credential redemption and the buyer-side helper.

Source code in payments_py/api/base_payments.py

def __init__(self, options: PaymentOptions):
    """
    Initialize the base payments API.

    Args:
        options: The options to initialize the payments class
    """
    self.nvm_api_key = options.nvm_api_key
    self.return_url = options.return_url or ""
    # Preserve the raw (possibly None) ``environment`` option so internal
    # re-inits (e.g. ``Payments._build_options``) reproduce the caller's
    # intent without re-deriving ``custom`` into a spurious deprecation
    # warning.
    self._environment_option = options.environment
    self.environment_name = self._resolve_environment(
        options.nvm_api_key, options.environment
    )
    self.environment = get_environment(self.environment_name)
    self.app_id = options.app_id
    self.version = options.version
    # Backend API version (monorepo MAJOR.MINOR) declared on every
    # request via the ``Nevermined-Version`` header. Defaults to the
    # version this SDK release is built/tested against.
    self.api_version: str = options.api_version or LOCKED_API_VERSION
    self.account_address: Optional[str] = None
    self.helicone_api_key: str = None
    self.is_browser_instance = True
    self.current_organization_id: Optional[str] = options.organization_id
    self._parse_nvm_api_key()

get_instance `classmethod` ¶

get_instance(options: PaymentOptions) -> MppAPI

Get an instance of the MppAPI class.

Source code in payments_py/mpp/mpp_api.py

@classmethod
def get_instance(cls, options: PaymentOptions) -> "MppAPI":
    """Get an instance of the MppAPI class."""
    return cls(options)

issue_challenge ¶

issue_challenge(
    params: IssueMppChallengeParams,
) -> Dict[str, Any]

Mint the challenge a plan-protected endpoint returns with its 402.

Each call returns a distinct challenge even for identical inputs — the id doubles as the burn idempotency key, so two requests sharing one would settle as a single burn.

RETURNS	DESCRIPTION
`Dict[str, Any]`	`{"challenge": <WWW-Authenticate value>, "id": <challenge id>}`

Source code in payments_py/mpp/mpp_api.py

def issue_challenge(self, params: IssueMppChallengeParams) -> Dict[str, Any]:
    """Mint the challenge a plan-protected endpoint returns with its 402.

    Each call returns a distinct challenge even for identical inputs — the
    id doubles as the burn idempotency key, so two requests sharing one
    would settle as a single burn.

    Returns:
        ``{"challenge": <WWW-Authenticate value>, "id": <challenge id>}``
    """
    body: Dict[str, Any] = {
        "planId": params.plan_id,
        "credits": normalize_credits(params.credits),
        "resource": params.resource,
        "httpVerb": params.http_verb,
    }
    if params.agent_id:
        body["agentId"] = params.agent_id
    if params.digest:
        body["digest"] = params.digest
    if params.description:
        body["description"] = params.description
    return self._post(API_URL_MPP_CHALLENGE, body)

verify_credential ¶

verify_credential(
    params: RedeemMppParams,
) -> Dict[str, Any]

Run the full credential and plan checks without burning anything.

Source code in payments_py/mpp/mpp_api.py

def verify_credential(self, params: RedeemMppParams) -> Dict[str, Any]:
    """Run the full credential and plan checks without burning anything."""
    return self._post(API_URL_MPP_VERIFY, self._redeem_body(params))

settle_credential ¶

settle_credential(
    params: RedeemMppParams,
) -> Dict[str, Any]

Verify and burn through the same chokepoint an x402 settlement uses, so the credits charged are identical on both protocols. Settling the same credential twice burns once.

RAISES	DESCRIPTION
`MppSettlementOutcomeUnknownError`	when the call ended without a definite answer — the burn may or may not have committed.

Source code in payments_py/mpp/mpp_api.py

def settle_credential(self, params: RedeemMppParams) -> Dict[str, Any]:
    """Verify and burn through the same chokepoint an x402 settlement uses,
    so the credits charged are identical on both protocols. Settling the
    same credential twice burns once.

    Raises:
        MppSettlementOutcomeUnknownError: when the call ended without a
            definite answer — the burn may or may not have committed.
    """
    return self._post(API_URL_MPP_SETTLE, self._redeem_body(params), burns=True)

get_mpp_access_token ¶

get_mpp_access_token(
    plan_id: str,
    agent_id: Optional[str] = None,
    token_options: Optional[MppTokenOptions] = None,
) -> Dict[str, Any]

Mint an access token signed under the Nevermined-MPP EIP-712 domain.

Same inputs and same settlement rail as :meth:X402TokenAPI.get_x402_access_token minus token_version; the token verifies only on the MPP routes, which is what keeps the two protocols isolated.

MPP carries no token version (nvm-monorepo#3266): its single-use unit is the challenge, not the token, so one MPP token is presented across many challenges by design. The parameter type says so, and a caller that sets token_version on an :class:X402TokenOptions and passes it here is refused before the request — the backend answers BCK.MPP.0007 for any value, 2 included.

RETURNS	DESCRIPTION
`Dict[str, Any]`	The mint response. Unlike the x402 mint it carries no
`Dict[str, Any]`	`tokenVersion` key: there is no version to report.

RAISES	DESCRIPTION
`PaymentsError`	(`code='validation'`) if `token_options` carries a `token_version`.

Source code in payments_py/mpp/mpp_api.py

def get_mpp_access_token(
    self,
    plan_id: str,
    agent_id: Optional[str] = None,
    token_options: Optional[MppTokenOptions] = None,
) -> Dict[str, Any]:
    """Mint an access token signed under the ``Nevermined-MPP`` EIP-712 domain.

    Same inputs and same settlement rail as
    :meth:`X402TokenAPI.get_x402_access_token` **minus** ``token_version``;
    the token verifies only on the MPP routes, which is what keeps the two
    protocols isolated.

    MPP carries **no token version** (nvm-monorepo#3266): its single-use
    unit is the challenge, not the token, so one MPP token is presented
    across many challenges by design. The parameter type says so, and a
    caller that sets ``token_version`` on an :class:`X402TokenOptions` and
    passes it here is refused before the request — the backend answers
    ``BCK.MPP.0007`` for any value, ``2`` included.

    Returns:
        The mint response. Unlike the x402 mint it carries no
        ``tokenVersion`` key: there is no version to report.

    Raises:
        PaymentsError: (``code='validation'``) if ``token_options`` carries
            a ``token_version``.
    """
    body = build_x402_token_request_body(
        plan_id=plan_id,
        agent_id=agent_id,
        token_options=token_options,
        environment_name=self.environment_name,
        protocol="mpp",
    )
    return self._post(API_URL_MPP_CREATE_PERMISSION, body)

fetch ¶

fetch(
    method: str,
    url: str,
    options: MppFetchOptions,
    **request_kwargs: Any
) -> MppFetchResult

Perform an HTTP request, paying an MPP challenge if the endpoint returns one.

The buyer needs no new plan, delegation or credential: the delegation that works for x402 works here unchanged. request_kwargs are handed to :func:requests.request unchanged (headers, json, data, params, timeout, stream, …).

A request body must be replayable if the endpoint may challenge the request: a generator, iterator or file-like data= raises a typed :class:PaymentsError once a 402 challenge actually requires a retry, since it cannot be resent. A request that is never challenged sends such a body exactly once, exactly like a plain requests call — the paid=False / untouched-response guarantee still holds.

options.delegation_config must carry a delegation_id — this call refuses the deprecated inline create-on-the-fly shape (no delegation_id) that :meth:X402TokenAPI.get_x402_access_token otherwise tolerates with a warning: the retry loop here can mint an access token twice per call, so that shape could silently create two delegations as a side effect of paying.

Example

result = payments.mpp.fetch(
    "POST",
    "https://agent.example/ask",
    MppFetchOptions(
        delegation_config=DelegationConfig(delegation_id=delegation_id),
        plan_id=plan_id,
    ),
    json={"q": "hello"},
)
print(result.paid, result.receipt)

Source code in payments_py/mpp/mpp_api.py

def fetch(
    self,
    method: str,
    url: str,
    options: MppFetchOptions,
    **request_kwargs: Any,
) -> MppFetchResult:
    """Perform an HTTP request, paying an MPP challenge if the endpoint
    returns one.

    The buyer needs no new plan, delegation or credential: the delegation
    that works for x402 works here unchanged. ``request_kwargs`` are handed
    to :func:`requests.request` unchanged (``headers``, ``json``, ``data``,
    ``params``, ``timeout``, ``stream``, …).

    A request body must be replayable **if the endpoint may challenge the
    request**: a generator, iterator or file-like ``data=`` raises a typed
    :class:`PaymentsError` once a 402 challenge actually requires a retry,
    since it cannot be resent. A request that is never challenged sends such
    a body exactly once, exactly like a plain ``requests`` call — the
    ``paid=False`` / untouched-response guarantee still holds.

    ``options.delegation_config`` must carry a ``delegation_id`` — this call
    refuses the deprecated inline create-on-the-fly shape (no
    ``delegation_id``) that
    :meth:`X402TokenAPI.get_x402_access_token` otherwise tolerates with a
    warning: the retry loop here can mint an access token twice per call, so
    that shape could silently create two delegations as a side effect of
    paying.

    Example:
        ```python
        result = payments.mpp.fetch(
            "POST",
            "https://agent.example/ask",
            MppFetchOptions(
                delegation_config=DelegationConfig(delegation_id=delegation_id),
                plan_id=plan_id,
            ),
            json={"q": "hello"},
        )
        print(result.paid, result.receipt)
        ```
    """
    delegation_config = getattr(options, "delegation_config", None)
    if not delegation_config or not getattr(
        delegation_config, "delegation_id", None
    ):
        raise PaymentsError.validation(
            "payments.mpp.fetch requires delegation_config.delegation_id. "
            "Create a delegation first with "
            "payments.delegation.create_delegation(), then pass "
            "DelegationConfig(delegation_id=...). An inline "
            "create-on-the-fly delegation_config (no delegation_id) is not "
            "accepted here — the retry loop can mint against it twice per "
            "call, which would create two delegations."
        )
    return mpp_fetch(
        self.get_mpp_access_token, method, url, options, **request_kwargs
    )

MppFetchOptions `dataclass` ¶

MppFetchOptions(
    delegation_config: DelegationConfig,
    agent_id: Optional[str] = None,
    plan_id: Optional[str] = None,
    max_credits: Optional[Union[str, int]] = None,
)

Options for :func:mpp_fetch / MppAPI.fetch.

.. warning:: Experimental. The MPP buyer surface may change in a minor release.

A request body must be replayable if the endpoint may challenge the request: a generator, iterator or file-like data=, or an open handle inside files=, raises a typed :class:PaymentsError once a 402 challenge actually requires a retry, since it cannot be resent. A request that is never challenged sends such a body exactly once, exactly like a plain requests call.

This helper mints nvm:erc4337 access tokens only in this release — a buyer holding an nvm:card-delegation delegation cannot use it yet.

MppFetchResult `dataclass` ¶

MppFetchResult(
    response: Response,
    settled: bool,
    paid: bool,
    credentials_presented: int = 0,
    credits_presented: Optional[str] = None,
    receipt: Optional[MppReceipt] = None,
)

What :func:mpp_fetch / MppAPI.fetch returns.

.. warning:: Experimental. Fields may be added or change meaning in a minor release.

X402 Token API¶

X402TokenAPI ¶

X402TokenAPI(options: PaymentOptions)

Bases: BasePaymentsAPI

X402 Token API for generating access tokens.

Handles X402 access token generation for subscribers to authorize payment operations with AI agents.

Source code in payments_py/api/base_payments.py

def __init__(self, options: PaymentOptions):
    """
    Initialize the base payments API.

    Args:
        options: The options to initialize the payments class
    """
    self.nvm_api_key = options.nvm_api_key
    self.return_url = options.return_url or ""
    # Preserve the raw (possibly None) ``environment`` option so internal
    # re-inits (e.g. ``Payments._build_options``) reproduce the caller's
    # intent without re-deriving ``custom`` into a spurious deprecation
    # warning.
    self._environment_option = options.environment
    self.environment_name = self._resolve_environment(
        options.nvm_api_key, options.environment
    )
    self.environment = get_environment(self.environment_name)
    self.app_id = options.app_id
    self.version = options.version
    # Backend API version (monorepo MAJOR.MINOR) declared on every
    # request via the ``Nevermined-Version`` header. Defaults to the
    # version this SDK release is built/tested against.
    self.api_version: str = options.api_version or LOCKED_API_VERSION
    self.account_address: Optional[str] = None
    self.helicone_api_key: str = None
    self.is_browser_instance = True
    self.current_organization_id: Optional[str] = options.organization_id
    self._parse_nvm_api_key()

get_instance `classmethod` ¶

get_instance(options: PaymentOptions) -> X402TokenAPI

Get a singleton instance of the X402TokenAPI class.

PARAMETER	DESCRIPTION
`options`	The options to initialize the API TYPE: `PaymentOptions`

RETURNS	DESCRIPTION
`X402TokenAPI`	The instance of the X402TokenAPI class

Source code in payments_py/x402/token.py

@classmethod
def get_instance(cls, options: PaymentOptions) -> "X402TokenAPI":
    """
    Get a singleton instance of the X402TokenAPI class.

    Args:
        options: The options to initialize the API

    Returns:
        The instance of the X402TokenAPI class
    """
    return cls(options)

get_x402_access_token ¶

get_x402_access_token(
    plan_id: str,
    agent_id: Optional[str] = None,
    token_options: Optional[X402TokenOptions] = None,
) -> Dict[str, Any]

Get an X402 access token for the given plan against a delegation.

This token allows the agent to verify and settle delegations on behalf of the subscriber.

Supported flow (create-first): create the delegation once via payments.delegation.create_delegation(...) and pass only its delegation_id here via token_options.delegation_config.

Passing spending limits / a payment method here instead (inline create-on-the-fly, i.e. a delegation_config with no delegation_id) is deprecated (#1674): this method emits a FutureWarning and the backend logs its own deprecation warning. The inline path will be removed in a future release.

A v3 token (single-use, bound to one seller and one endpoint) is requested with token_options.token_version=3 plus the resource / http_verb it should be bound to. Requesting v3 does not guarantee v3: a backend predating nvm-monorepo#2646 strips the field silently and returns v2. Read the tokenVersion key of the result — it is detected from the token that came back, never from what was asked for.

PARAMETER	DESCRIPTION
`plan_id`	The unique identifier of the payment plan TYPE: `str`
`agent_id`	The unique identifier of the AI agent (optional) TYPE: `Optional[str]` DEFAULT: `None`
`token_options`	Options controlling scheme, delegation, the resource/verb the token is bound to, and the requested token version (optional) TYPE: `Optional[X402TokenOptions]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Dict[str, Any]`	A dictionary containing: - accessToken: The X402 access token string - tokenVersion: `2` or `3`, detected from the returned token's `authorization.nonce`

RAISES	DESCRIPTION
`PaymentsError`	If the request fails, or (`code='validation'`) if `delegation_config.delegation_id` is an empty string — pass a valid delegation UUID or omit the field — or if `token_options.resource` carries a blank URL.

Example

# Create the delegation once (currency is required), then reuse it.
delegation = payments.delegation.create_delegation(
    CreateDelegationPayload(
        provider="erc4337",
        spending_limit_cents=10000,
        duration_secs=604800,
        currency="usdc",
    )
)

result = payments.x402.get_x402_access_token(
    plan_id, agent_id,
    token_options=X402TokenOptions(
        delegation_config=DelegationConfig(
            delegation_id=delegation.delegation_id
        )
    )
)

# Single-use, bound to one seller endpoint (v3):
result = payments.x402.get_x402_access_token(
    plan_id, agent_id,
    token_options=X402TokenOptions(
        delegation_config=DelegationConfig(
            delegation_id=delegation.delegation_id
        ),
        resource="https://seller.example/api/v1/tasks",
        http_verb="POST",
        token_version=3,
    ),
)
if result["tokenVersion"] == 3:
    ...  # single-use: mint a fresh token for the next paid request

Source code in payments_py/x402/token.py

def get_x402_access_token(
    self,
    plan_id: str,
    agent_id: Optional[str] = None,
    token_options: Optional[X402TokenOptions] = None,
) -> Dict[str, Any]:
    """
    Get an X402 access token for the given plan against a delegation.

    This token allows the agent to verify and settle delegations on behalf
    of the subscriber.

    Supported flow (**create-first**): create the delegation once via
    ``payments.delegation.create_delegation(...)`` and pass only its
    ``delegation_id`` here via ``token_options.delegation_config``.

    Passing spending limits / a payment method here instead (inline
    create-on-the-fly, i.e. a ``delegation_config`` with no
    ``delegation_id``) is **deprecated** (#1674): this method emits a
    ``FutureWarning`` and the backend logs its own deprecation warning.
    The inline path will be removed in a future release.

    A **v3** token (single-use, bound to one seller and one endpoint) is
    requested with ``token_options.token_version=3`` plus the
    ``resource`` / ``http_verb`` it should be bound to. Requesting v3 does
    not guarantee v3: a backend predating nvm-monorepo#2646 strips the
    field silently and returns v2. Read the ``tokenVersion`` key of the
    result — it is detected from the token that came back, never from what
    was asked for.

    Args:
        plan_id: The unique identifier of the payment plan
        agent_id: The unique identifier of the AI agent (optional)
        token_options: Options controlling scheme, delegation, the
            resource/verb the token is bound to, and the requested token
            version (optional)

    Returns:
        A dictionary containing:
            - accessToken: The X402 access token string
            - tokenVersion: ``2`` or ``3``, detected from the returned
              token's ``authorization.nonce``

    Raises:
        PaymentsError: If the request fails, or (``code='validation'``) if
            ``delegation_config.delegation_id`` is an empty string — pass a
            valid delegation UUID or omit the field — or if
            ``token_options.resource`` carries a blank URL.

    Example:
        ```python
        # Create the delegation once (currency is required), then reuse it.
        delegation = payments.delegation.create_delegation(
            CreateDelegationPayload(
                provider="erc4337",
                spending_limit_cents=10000,
                duration_secs=604800,
                currency="usdc",
            )
        )

        result = payments.x402.get_x402_access_token(
            plan_id, agent_id,
            token_options=X402TokenOptions(
                delegation_config=DelegationConfig(
                    delegation_id=delegation.delegation_id
                )
            )
        )

        # Single-use, bound to one seller endpoint (v3):
        result = payments.x402.get_x402_access_token(
            plan_id, agent_id,
            token_options=X402TokenOptions(
                delegation_config=DelegationConfig(
                    delegation_id=delegation.delegation_id
                ),
                resource="https://seller.example/api/v1/tasks",
                http_verb="POST",
                token_version=3,
            ),
        )
        if result["tokenVersion"] == 3:
            ...  # single-use: mint a fresh token for the next paid request
        ```
    """
    url = f"{self.environment.backend}{API_URL_CREATE_PERMISSION}"

    # Body shape is shared with the MPP mint (`payments.mpp`): same
    # inputs, same delegation rules, different EIP-712 domain at the
    # backend. Kept in one place so the two cannot drift.
    body = build_x402_token_request_body(
        plan_id=plan_id,
        agent_id=agent_id,
        token_options=token_options,
        environment_name=self.environment_name,
    )

    options = self.get_backend_http_options("POST", body)

    try:
        response = requests.post(url, **options)
        response.raise_for_status()
        # Report the version of the token we GOT, not the one we asked for:
        # `tokenVersion` is silently stripped by a backend that predates
        # nvm-monorepo#2646, so echoing the request would claim replay
        # protection that is not there.
        return with_detected_token_version(response.json())
    except requests.HTTPError as err:
        raise PaymentsError.from_response(
            response, "Failed to create X402 delegation token"
        ) from err
    except Exception as err:
        raise PaymentsError.internal(
            f"Network error while creating X402 delegation token: {str(err)}"
        ) from err

Requests API¶

AgentRequestsAPI ¶

AgentRequestsAPI(options: PaymentOptions)

Bases: BasePaymentsAPI

The AgentRequestsAPI class provides methods to manage the requests received by AI Agents integrated with Nevermined.

Note: For request validation and credit settlement, use the x402 API instead: - payments.facilitator.verify_permissions() - to verify token and permissions - payments.facilitator.settle_permissions() - to burn credits

Source code in payments_py/api/base_payments.py

def __init__(self, options: PaymentOptions):
    """
    Initialize the base payments API.

    Args:
        options: The options to initialize the payments class
    """
    self.nvm_api_key = options.nvm_api_key
    self.return_url = options.return_url or ""
    # Preserve the raw (possibly None) ``environment`` option so internal
    # re-inits (e.g. ``Payments._build_options``) reproduce the caller's
    # intent without re-deriving ``custom`` into a spurious deprecation
    # warning.
    self._environment_option = options.environment
    self.environment_name = self._resolve_environment(
        options.nvm_api_key, options.environment
    )
    self.environment = get_environment(self.environment_name)
    self.app_id = options.app_id
    self.version = options.version
    # Backend API version (monorepo MAJOR.MINOR) declared on every
    # request via the ``Nevermined-Version`` header. Defaults to the
    # version this SDK release is built/tested against.
    self.api_version: str = options.api_version or LOCKED_API_VERSION
    self.account_address: Optional[str] = None
    self.helicone_api_key: str = None
    self.is_browser_instance = True
    self.current_organization_id: Optional[str] = options.organization_id
    self._parse_nvm_api_key()

get_instance `classmethod` ¶

get_instance(options: PaymentOptions) -> AgentRequestsAPI

Get a singleton instance of the AgentRequestsAPI class.

PARAMETER	DESCRIPTION
`options`	The options to initialize the payments class TYPE: `PaymentOptions`

RETURNS	DESCRIPTION
`AgentRequestsAPI`	The instance of the AgentRequestsAPI class

Source code in payments_py/api/requests_api.py

@classmethod
def get_instance(cls, options: PaymentOptions) -> "AgentRequestsAPI":
    """
    Get a singleton instance of the AgentRequestsAPI class.

    Args:
        options: The options to initialize the payments class

    Returns:
        The instance of the AgentRequestsAPI class
    """
    return cls(options)

track_agent_sub_task ¶

track_agent_sub_task(
    track_agent_sub_task: TrackAgentSubTaskDto,
) -> Dict[str, Any]

Tracks an agent sub task.

This method is used by agent owners to track agent sub tasks for agent tasks. It records information about credit redemption, categorization tags, and processing descriptions.

PARAMETER	DESCRIPTION
`track_agent_sub_task`	The agent sub task data to track TYPE: `TrackAgentSubTaskDto`

RETURNS	DESCRIPTION
`Dict[str, Any]`	A promise that resolves to the result of the operation

RAISES	DESCRIPTION
`PaymentsError`	If unable to track the agent sub task

Source code in payments_py/api/requests_api.py

def track_agent_sub_task(
    self, track_agent_sub_task: TrackAgentSubTaskDto
) -> Dict[str, Any]:
    """
    Tracks an agent sub task.

    This method is used by agent owners to track agent sub tasks for agent tasks.
    It records information about credit redemption, categorization tags, and processing descriptions.

    Args:
        track_agent_sub_task: The agent sub task data to track

    Returns:
        A promise that resolves to the result of the operation

    Raises:
        PaymentsError: If unable to track the agent sub task
    """
    body = {
        "agentRequestId": track_agent_sub_task.agent_request_id,
        "creditsToRedeem": track_agent_sub_task.credits_to_redeem or 0,
        "tag": track_agent_sub_task.tag,
        "description": track_agent_sub_task.description,
        "status": (
            track_agent_sub_task.status.value
            if track_agent_sub_task.status
            else None
        ),
    }

    options = self.get_backend_http_options("POST", body)
    url = f"{self.environment.backend}{API_URL_TRACK_AGENT_SUB_TASK}"
    response = requests.post(url, **options)

    if not response.ok:
        raise PaymentsError.internal(
            f"Unable to track agent sub task. {response.status_code} - {response.text}"
        )

    return response.json()

start_simulation_request ¶

start_simulation_request(
    price_per_credit: float = 0.01,
    batch: bool = False,
    agent_name: str = None,
    plan_name: str = None,
) -> StartAgentRequest

This method simulates an agent request.

PARAMETER	DESCRIPTION
`price_per_credit`	The price per credit in USD TYPE: `float` DEFAULT: `0.01`
`batch`	Whether the request is a batch request TYPE: `bool` DEFAULT: `False`
`agent_name`	The name of the agent TYPE: `str` DEFAULT: `None`
`plan_name`	The name of the plan TYPE: `str` DEFAULT: `None`

RETURNS	DESCRIPTION
`StartAgentRequest`	The information about the simulation of the request

Source code in payments_py/api/requests_api.py

def start_simulation_request(
    self,
    price_per_credit: float = 0.01,
    batch: bool = False,
    agent_name: str = None,
    plan_name: str = None,
) -> StartAgentRequest:
    """
    This method simulates an agent request.

    Args:
        price_per_credit: The price per credit in USD
        batch: Whether the request is a batch request
        agent_name: The name of the agent
        plan_name: The name of the plan

    Returns:
        The information about the simulation of the request
    """

    body = {
        "pricePerCredit": price_per_credit,
        "batch": batch,
    }
    if agent_name is not None:
        body["agentName"] = agent_name
    if plan_name is not None:
        body["planName"] = plan_name
    options = self.get_backend_http_options("POST", body)
    url = urljoin(self.environment.backend, API_URL_SIMULATE_AGENT_REQUEST)
    response = requests.post(url, **options)

    if not response.ok:
        raise PaymentsError.internal(
            f"Unable to start simulation request. {response.status_code} - {response.text}"
        )

    response_data = response.json()
    return StartAgentRequest(**response_data)

finish_simulation_request ¶

finish_simulation_request(
    agent_request_id: str,
    margin_percent: float = 0.2,
    batch: bool = False,
) -> Dict[str, Any]

Simulates the redemption of credits for an agent request.

PARAMETER	DESCRIPTION
`agent_request_id`	The unique identifier of the agent request. TYPE: `str`
`margin_percent`	The margin percentage to apply. Defaults to 0.2. TYPE: `float` DEFAULT: `0.2`
`batch`	Whether the request is a batch request. Defaults to False. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Dict[str, Any]`	A dictionary containing the result of the simulation, including the credits to redeem and the success status.

RAISES	DESCRIPTION
`PaymentsError`	If unable to finish the simulation request.

Source code in payments_py/api/requests_api.py

def finish_simulation_request(
    self, agent_request_id: str, margin_percent: float = 0.2, batch: bool = False
) -> Dict[str, Any]:
    """
    Simulates the redemption of credits for an agent request.

    Args:
        agent_request_id: The unique identifier of the agent request.
        margin_percent: The margin percentage to apply. Defaults to 0.2.
        batch: Whether the request is a batch request. Defaults to False.

    Returns:
        A dictionary containing the result of the simulation, including the credits to redeem and the success status.

    Raises:
        PaymentsError: If unable to finish the simulation request.
    """

    body = {
        "agentRequestId": agent_request_id,
        "marginPercent": margin_percent,
        "batch": batch,
    }
    options = self.get_backend_http_options("POST", body)
    url = urljoin(self.environment.backend, API_URL_SIMULATE_REDEEM_AGENT_REQUEST)

    # Since this method is usually called immediately after the llm call
    # the request might not be immediately available on helicone, so we need to retry.
    max_retries = 3
    last_error = None

    for attempt in range(max_retries):
        try:
            response = requests.post(url, **options)
            if not response.ok:
                last_error = PaymentsError.internal(
                    f"Unable to finish simulation request. {response.status_code} - {response.text}"
                )
                if attempt < max_retries - 1:
                    time.sleep(1)
                    continue
                raise last_error
            return response.json()
        except requests.exceptions.RequestException as e:
            last_error = PaymentsError.internal(
                f"Unable to finish simulation request. Request failed: {str(e)}"
            )
            if attempt < max_retries - 1:
                time.sleep(1)
                continue
            raise last_error

Payments Class Reference¶

Payments¶

Payments ¶

get_instance classmethod ¶

get_browser_instance classmethod ¶

Plans API¶

PlansAPI ¶

get_instance classmethod ¶

register_plan ¶

register_credits_plan ¶

register_time_plan ¶

register_credits_trial_plan ¶

register_time_trial_plan ¶

get_plan ¶

get_user_plans ¶

get_plan_balance ¶

order_plan ¶

mint_plan_credits ¶

mint_plan_expirable ¶

burn_credits ¶

get_agents_associated_to_plan ¶

get_fiat_price_config staticmethod ¶

get_eurc_price_config staticmethod ¶

get_crypto_price_config staticmethod ¶

get_erc20_price_config staticmethod ¶

get_free_price_config staticmethod ¶

get_native_token_price_config staticmethod ¶

get_expirable_duration_config staticmethod ¶

get_non_expirable_duration_config staticmethod ¶

get_fixed_credits_config staticmethod ¶

get_dynamic_credits_config staticmethod ¶

set_redemption_type staticmethod ¶

set_onchain_mirror staticmethod ¶

get_pay_as_you_go_price_config ¶

get_pay_as_you_go_credits_config staticmethod ¶

order_fiat_plan ¶

redeem_credits ¶

Agents API¶

AgentsAPI ¶

get_instance classmethod ¶

register_agent ¶

register_agent_and_plan ¶

get_agent ¶

get_agent_plans ¶

get_user_agents ¶

add_plan_to_agent ¶

remove_plan_from_agent ¶

update_agent_metadata ¶

Facilitator API (x402)¶

FacilitatorAPI ¶

get_instance classmethod ¶

verify_permissions ¶

settle_permissions ¶

MPP API¶

MppAPI ¶

get_instance classmethod ¶

issue_challenge ¶

verify_credential ¶

settle_credential ¶

get_mpp_access_token ¶

fetch ¶

MppFetchOptions dataclass ¶

MppFetchResult dataclass ¶

X402 Token API¶

X402TokenAPI ¶

get_instance classmethod ¶

get_x402_access_token ¶

Requests API¶

AgentRequestsAPI ¶

get_instance classmethod ¶

track_agent_sub_task ¶

start_simulation_request ¶

finish_simulation_request ¶

get_instance `classmethod` ¶

get_browser_instance `classmethod` ¶

get_instance `classmethod` ¶

get_fiat_price_config `staticmethod` ¶

get_eurc_price_config `staticmethod` ¶

get_crypto_price_config `staticmethod` ¶

get_erc20_price_config `staticmethod` ¶

get_free_price_config `staticmethod` ¶

get_native_token_price_config `staticmethod` ¶

get_expirable_duration_config `staticmethod` ¶

get_non_expirable_duration_config `staticmethod` ¶

get_fixed_credits_config `staticmethod` ¶

get_dynamic_credits_config `staticmethod` ¶

set_redemption_type `staticmethod` ¶

set_onchain_mirror `staticmethod` ¶

get_pay_as_you_go_credits_config `staticmethod` ¶

get_instance `classmethod` ¶

get_instance `classmethod` ¶

get_instance `classmethod` ¶

MppFetchOptions `dataclass` ¶

MppFetchResult `dataclass` ¶

get_instance `classmethod` ¶

get_instance `classmethod` ¶