Agents

This guide covers how to register and manage AI agents using the Nevermined Payments Python SDK.

Overview

AI Agents are services that users can access through payment plans. The Agents API allows you to:

Register new agents with associated payment plans
Register agents and plans together in a single operation
Update agent metadata and endpoints
Manage plan associations

Agents API

Access the Agents API through payments.agents:

from payments_py import Payments, PaymentOptions

payments = Payments.get_instance(
    PaymentOptions(nvm_api_key="nvm:your-key", environment="sandbox")
)

# Access agents API
agents_api = payments.agents

Register Agents

Basic Agent Registration

import os

from payments_py.common.types import AgentMetadata, AgentAPIAttributes, AuthType

# Define agent metadata
agent_metadata = AgentMetadata(
    name="My AI Assistant",
    description="An intelligent assistant that helps with various tasks",
    tags=["ai", "assistant", "productivity"],
    author="Your Company"
)

# Define API configuration. All AgentAPIAttributes fields are optional —
# most builders only need to set authentication. See
# "AgentAPIAttributes Fields" below for opt-in Additional Security.
agent_api = AgentAPIAttributes(
    auth_type=AuthType.BEARER,
    token=os.environ["AGENT_BEARER_TOKEN"],
)

# List of plan IDs that grant access to this agent
payment_plans = [plan_id_1, plan_id_2]

# Register the agent
result = payments.agents.register_agent(
    agent_metadata=agent_metadata,
    agent_api=agent_api,
    payment_plans=payment_plans
)
print(f"Agent ID: {result['agentId']}")

Register Agent and Plan Together

Create both an agent and a payment plan in a single operation:

import os

from payments_py.common.types import (
    AgentMetadata,
    AgentAPIAttributes,
    AuthType,
    PlanMetadata,
)
from payments_py.plans import get_erc20_price_config, get_fixed_credits_config

# Agent configuration
agent_metadata = AgentMetadata(
    name="AI Code Reviewer",
    description="Automated code review assistant",
    tags=["code", "review", "ai"]
)

agent_api = AgentAPIAttributes(
    auth_type=AuthType.BEARER,
    token=os.environ["AGENT_BEARER_TOKEN"],
)

# Plan configuration
plan_metadata = PlanMetadata(
    name="Code Review Plan",
    description="100 code reviews"
)

price_config = get_erc20_price_config(
    amount=50,
    token_address="0xYourTokenAddress",
    receiver=payments.account_address
)

credits_config = get_fixed_credits_config(credits_granted=100)

# Register both in one call
result = payments.agents.register_agent_and_plan(
    agent_metadata=agent_metadata,
    agent_api=agent_api,
    plan_metadata=plan_metadata,
    price_config=price_config,
    credits_config=credits_config,
    access_limit="credits"  # or "time"
)

print(f"Agent ID: {result['agentId']}")
print(f"Plan ID: {result['planId']}")
print(f"Transaction: {result['txHash']}")

Agent Configuration

AgentMetadata Fields

Field	Type	Required	Description
`name`	`str`	Yes	Agent display name
`description`	`str`	No	Agent description
`author`	`str`	No	Author/company name
`tags`	`list[str]`	No	Categorization tags
`license`	`str`	No	License information
`sample_link`	`str`	No	Link to demo/sample
`api_description`	`str`	No	API documentation

AgentAPIAttributes Fields

All fields are optional. Provide only what your integration needs.

Field	Type	Required	Description
`auth_type`	`AuthType`	No	Authentication type (default: `AuthType.NONE`)
`token`	`str`	No	Bearer token (when `auth_type` is `BEARER` or `OAUTH`)
`username`	`str`	No	Basic-auth username
`password`	`str`	No	Basic-auth password
`endpoints`	`list[Endpoint]`	No	Additional Security allowlist — see below
`open_endpoints`	`list[str]`	No	Public endpoints (no subscription required)
`agent_definition_url`	`str`	No	Discoverable agent definition (OpenAPI / MCP / A2A)

Additional Security: Endpoint Allowlist (opt-in)

Setting endpoints opts the agent into a platform-enforced allowlist. When set, only requests matching one of the registered URLs are accepted during x402 verification; non-matching requests are rejected. When omitted, the platform performs no route-level allowlist check — your Payments library middleware (PaymentMiddleware, @requires_payment) remains the sole gate.

import os

from payments_py.common.types import AgentAPIAttributes, AuthType, Endpoint

agent_api = AgentAPIAttributes(
    auth_type=AuthType.BEARER,
    token=os.environ["AGENT_BEARER_TOKEN"],
    # Opt-in: route allowlist enforced by x402 verify
    endpoints=[
        Endpoint(verb="POST", url="https://api.example.com/agents/:agentId/tasks"),
        Endpoint(verb="GET", url="https://api.example.com/agents/:agentId/tasks/:taskId"),
        Endpoint(verb="DELETE", url="https://api.example.com/agents/:agentId/tasks/:taskId"),
    ],
    open_endpoints=["https://api.example.com/health"],
    agent_definition_url="https://api.example.com/openapi.json",
)

The :agentId and :taskId placeholders will be replaced with actual values during request validation.

Migration note: existing agents that registered before April 2026 still have these fields populated and continue to enforce the allowlist as before. No migration is needed.

Retrieve Agents

List Your Agents

List the agents you published. This is caller-scoped account management — it returns only the agents the authenticated account created, never other users’ agents (Nevermined is not a marketplace, so there is no global agent search). Useful for finding and managing your own agents (e.g. spotting duplicates).

from payments_py.common.types import PaginationOptions

# Your own agents
result = payments.agents.get_user_agents(
    pagination=PaginationOptions(page=1, offset=10)
)
print(f"Total: {result['total']}")
for agent in result["agents"]:
    print(agent["id"])

# Every agent in an organization you belong to
org_agents = payments.agents.get_user_agents(org_id="org-acme")

Get a Single Agent

agent = payments.agents.get_agent(agent_id="your-agent-id")
print(f"Agent name: {agent['name']}")
print(f"Agent endpoints: {agent['endpoints']}")

Get Plans for an Agent

from payments_py.common.types import PaginationOptions

plans = payments.agents.get_agent_plans(
    agent_id="your-agent-id",
    pagination=PaginationOptions(page=1, offset=10)
)
print(f"Associated plans: {plans}")

Update Agents

Update Agent Metadata

update_agent_metadata is also where builders typically opt in to Additional Security by adding an endpoints allowlist or agent_definition_url to an existing agent:

import os

from payments_py.common.types import (
    AgentMetadata,
    AgentAPIAttributes,
    AuthType,
    Endpoint,
)

updated_metadata = AgentMetadata(
    name="Updated Agent Name",
    description="Updated description with new features",
    tags=["ai", "updated", "v2"]
)

# Adding `endpoints` activates the platform-enforced allowlist for this
# agent. To return to allow-all, omit it on the next update.
updated_api = AgentAPIAttributes(
    auth_type=AuthType.BEARER,
    token=os.environ["AGENT_BEARER_TOKEN"],
    endpoints=[Endpoint(verb="POST", url="https://new-api.com/v2/tasks")],
    agent_definition_url="https://new-api.com/v2/openapi.json",
)

result = payments.agents.update_agent_metadata(
    agent_id="your-agent-id",
    agent_metadata=updated_metadata,
    agent_api=updated_api
)
print(f"Update successful: {result}")

Manage Plan Associations

Add a Plan to an Agent

result = payments.agents.add_plan_to_agent(
    plan_id="plan-to-add",
    agent_id="your-agent-id"
)
print(f"Plan added: {result}")

Remove a Plan from an Agent

result = payments.agents.remove_plan_from_agent(
    plan_id="plan-to-remove",
    agent_id="your-agent-id"
)
print(f"Plan removed: {result}")

Complete Example

from payments_py import Payments, PaymentOptions
from payments_py.common.types import AgentMetadata, AgentAPIAttributes, PlanMetadata
from payments_py.plans import (
    get_erc20_price_config,
    get_fixed_credits_config,
    get_free_price_config
)

# Initialize
payments = Payments.get_instance(
    PaymentOptions(nvm_api_key="nvm:your-key", environment="sandbox")
)

ERC20_TOKEN = "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d"
builder_address = payments.account_address

# 1. Create a payment plan first
plan_result = payments.plans.register_credits_plan(
    plan_metadata=PlanMetadata(name="AI Agent Plan"),
    price_config=get_erc20_price_config(20, ERC20_TOKEN, builder_address),
    credits_config=get_fixed_credits_config(100)
)
plan_id = plan_result['planId']

# 2. Register an agent with the plan
agent_result = payments.agents.register_agent(
    agent_metadata=AgentMetadata(
        name="My First AI Agent",
        description="A demo AI agent",
        tags=["demo", "ai"]
    ),
    agent_api=AgentAPIAttributes(
        endpoints=[{"POST": "https://api.example.com/agents/:agentId/tasks"}],
        agent_definition_url="https://api.example.com/openapi.json"
    ),
    payment_plans=[plan_id]
)
agent_id = agent_result['agentId']
print(f"Created agent: {agent_id}")

# 3. Or create both together
combo_result = payments.agents.register_agent_and_plan(
    agent_metadata=AgentMetadata(name="Combo Agent"),
    agent_api=AgentAPIAttributes(
        endpoints=[{"POST": "https://api.example.com/combo"}],
        agent_definition_url="https://api.example.com/openapi.json"
    ),
    plan_metadata=PlanMetadata(name="Combo Plan"),
    price_config=get_free_price_config(),
    credits_config=get_fixed_credits_config(10)
)
print(f"Combo Agent: {combo_result['agentId']}, Plan: {combo_result['planId']}")

# 4. Retrieve agent details
agent = payments.agents.get_agent(agent_id)
print(f"Agent details: {agent}")

# 5. Get associated plans
plans = payments.agents.get_agent_plans(agent_id)
print(f"Agent plans: {plans}")

# 6. Update agent metadata
payments.agents.update_agent_metadata(
    agent_id=agent_id,
    agent_metadata=AgentMetadata(name="Updated Agent Name"),
    agent_api=AgentAPIAttributes(
        endpoints=[{"POST": "https://api.example.com/v2/agents/:agentId/tasks"}],
        agent_definition_url="https://api.example.com/v2/openapi.json"
    )
)

TypeScript SDK

Python SDK

CLI

OpenClaw Plugin

Overview

Agents API

Register Agents

Basic Agent Registration

Register Agent and Plan Together

Agent Configuration

AgentMetadata Fields

AgentAPIAttributes Fields

Additional Security: Endpoint Allowlist (opt-in)

Retrieve Agents

List Your Agents

Get a Single Agent

Get Plans for an Agent

Update Agents

Update Agent Metadata

Manage Plan Associations

Add a Plan to an Agent

Remove a Plan from an Agent

Complete Example

Next Steps

Publishing Static Resources

Querying an Agent

​Overview

​Agents API

​Register Agents

​Basic Agent Registration

​Register Agent and Plan Together

​Agent Configuration

​AgentMetadata Fields

​AgentAPIAttributes Fields

​Additional Security: Endpoint Allowlist (opt-in)

​Retrieve Agents

​List Your Agents

​Get a Single Agent

​Get Plans for an Agent

​Update Agents

​Update Agent Metadata

​Manage Plan Associations

​Add a Plan to an Agent

​Remove a Plan from an Agent

​Complete Example

​Next Steps

Publishing Static Resources

Querying an Agent

Overview

Agents API

Register Agents

Basic Agent Registration

Register Agent and Plan Together

Agent Configuration

AgentMetadata Fields

AgentAPIAttributes Fields

Additional Security: Endpoint Allowlist (opt-in)

Retrieve Agents

List Your Agents

Get a Single Agent

Get Plans for an Agent

Update Agents

Update Agent Metadata

Manage Plan Associations

Add a Plan to an Agent

Remove a Plan from an Agent

Complete Example

Next Steps