Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nevermined.app/llms.txt

Use this file to discover all available pages before exploring further.

This guide explains how to publish static resources (files, datasets) using the Nevermined Payments Python SDK.

​
Overview

Static resources are files or datasets that users can access through payment plans. Unlike AI agents that process requests, static resources are downloadable content such as:
  • Documents (PDFs, reports)
  • Datasets (CSV, JSON files)
  • Media files (images, videos)
  • Software packages

​
Register Static Resource Agents

Static resources are registered as a special type of agent with file endpoints: 
from payments_py.common.types import AgentMetadata, AgentAPIAttributes

# Resource metadata
resource_metadata = AgentMetadata(
    name="Premium Dataset Collection",
    description="A curated collection of ML training datasets",
    tags=["dataset", "machine-learning", "premium"]
)

# Static file endpoints
resource_api = AgentAPIAttributes(
    endpoints=[
        {"GET": "https://storage.example.com/datasets/training-data.csv"},
        {"GET": "https://storage.example.com/datasets/validation-data.csv"},
        {"GET": "https://storage.example.com/datasets/test-data.csv"}
    ],
    agent_definition_url="https://storage.example.com/datasets/manifest.json"
)

# Register with a payment plan
result = payments.agents.register_agent(
    agent_metadata=resource_metadata,
    agent_api=resource_api,
    payment_plans=[plan_id]
)
print(f"Resource ID: {result['agentId']}")

​
Using Wildcards for Multiple Files

When you have multiple files that follow a pattern, you can use wildcard URLs: 
# Single wildcard for dynamic file names
resource_api = AgentAPIAttributes(
    endpoints=[
        # Matches: /files/report-001.pdf, /files/report-2024.pdf, etc.
        {"GET": "https://storage.example.com/files/report-*.pdf"},

        # Matches: /data/dataset_v1.csv, /data/dataset_v2.csv, etc.
        {"GET": "https://storage.example.com/data/dataset_*.csv"}
    ],
    agent_definition_url="https://storage.example.com/manifest.json"
)

​
Wildcard Patterns

PatternMatches
*.pdfAny PDF file
report-*.pdfreport-001.pdf, report-2024.pdf
data/*.csvAll CSV files in data folder
v*/data.jsonv1/data.json, v2/data.json

​
Complete Example: Dataset Publishing

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

# 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 plan for the dataset
plan_result = payments.plans.register_credits_plan(
    plan_metadata=PlanMetadata(
        name="Dataset Access Plan",
        description="Access to premium ML datasets"
    ),
    price_config=get_erc20_price_config(100, ERC20_TOKEN, builder_address),
    credits_config=get_fixed_credits_config(10)  # 10 downloads
)
plan_id = plan_result['planId']

# 2. Register the dataset resource
dataset_result = payments.agents.register_agent(
    agent_metadata=AgentMetadata(
        name="ML Training Datasets",
        description="High-quality labeled datasets for machine learning",
        tags=["dataset", "ml", "training", "labeled"]
    ),
    agent_api=AgentAPIAttributes(
        endpoints=[
            {"GET": "https://storage.example.com/datasets/images/*.zip"},
            {"GET": "https://storage.example.com/datasets/text/*.jsonl"},
            {"GET": "https://storage.example.com/datasets/audio/*.tar.gz"}
        ],
        agent_definition_url="https://storage.example.com/datasets/catalog.json"
    ),
    payment_plans=[plan_id]
)
print(f"Dataset Resource ID: {dataset_result['agentId']}")

​
Example: Document Repository

# Publishing a document repository
doc_result = payments.agents.register_agent(
    agent_metadata=AgentMetadata(
        name="Research Papers Collection",
        description="Exclusive research papers and technical reports",
        tags=["research", "papers", "technical"]
    ),
    agent_api=AgentAPIAttributes(
        endpoints=[
            # Specific documents
            {"GET": "https://docs.example.com/papers/whitepaper-2024.pdf"},
            {"GET": "https://docs.example.com/papers/research-findings.pdf"},

            # Wildcard for quarterly reports
            {"GET": "https://docs.example.com/reports/q*-report.pdf"},

            # All supplementary materials
            {"GET": "https://docs.example.com/supplementary/*.zip"}
        ],
        agent_definition_url="https://docs.example.com/index.json"
    ),
    payment_plans=[plan_id]
)

​
Example: Software Distribution

# Publishing software packages
software_result = payments.agents.register_agent(
    agent_metadata=AgentMetadata(
        name="Premium Software Tools",
        description="Professional development tools and utilities",
        tags=["software", "tools", "professional"]
    ),
    agent_api=AgentAPIAttributes(
        endpoints=[
            # Version-specific downloads
            {"GET": "https://releases.example.com/tool/v*/tool-*.zip"},

            # Platform-specific binaries
            {"GET": "https://releases.example.com/tool/latest/tool-linux-*.tar.gz"},
            {"GET": "https://releases.example.com/tool/latest/tool-macos-*.dmg"},
            {"GET": "https://releases.example.com/tool/latest/tool-windows-*.exe"},

            # Documentation
            {"GET": "https://releases.example.com/tool/docs/*.pdf"}
        ],
        agent_definition_url="https://releases.example.com/tool/manifest.json"
    ),
    payment_plans=[plan_id]
)

​
Accessing Static Resources

For details on how subscribers access static resources using x402 access tokens, see Request Validation.

​
Best Practices

  1. Use descriptive metadata: Include clear names, descriptions, and tags for discoverability
  2. Organize files logically: Use consistent URL patterns that work well with wildcards
  3. Version your resources: Include version numbers in URLs for easy updates
  4. Provide a manifest: Create a JSON manifest at the agent_definition_url listing all available files
  5. Set appropriate credits: Consider the value and size of files when setting credit costs

​
Next Steps

Payments and Balance

Order plans and check balances

Querying an Agent

Access resources with tokens