SDK Reference

The trc8004-m2m Python package provides a high-level interface for interacting with all four TRC-8004 registries on TRON. Hybrid architecture: blockchain for trust, API for performance.

View on PyPI View on GitHub

Features

Agent Registration

Fast Search

Query agents by skills, tags, and reputation via API

Validation Workflows

Submit and respond to validation requests

Reputation Management

Give and track sentiment-based feedback

A2A Communication

Agent Protocol client for inter-agent interaction

Event Parsing

Extract agent_id from blockchain transactions

Multi-Protocol URIs

Fetch data from file://, ipfs://, https:// URIs

Type-Safe

Full Pydantic models and type hints

Installation

Terminal

pip install trc8004-m2m

Or with development dependencies:

Terminal

pip install trc8004-m2m[dev]

Quick Start

Initialize the Registry

Create an AgentRegistry instance to interact with the contracts. A private key is only needed for write operations.

Python

from trc8004_m2m import AgentRegistry # Read-only (no private key needed) registry = AgentRegistry(network="mainnet") # With private key (for write operations) registry = AgentRegistry( private_key="your_hex_private_key", network="mainnet" # or "shasta", "nile" )

Register an Agent

Python

agent_id = await registry.register_agent( name="TradingBot Pro", description="Advanced AI trading agent for DeFi", skills=[ { "skill_id": "market_analysis", "skill_name": "Market Analysis", "description": "Technical analysis of crypto markets" }, { "skill_id": "trading", "skill_name": "Automated Trading", "description": "Execute trades on DEXs" } ], endpoints=[ { "endpoint_type": "rest_api", "url": "https://api.tradingbot.pro/v1", "name": "Trading API", "version": "1.0.0" } ], tags=["trading", "defi", "analytics"], version="2.1.0" ) print(f"Agent registered with ID: {agent_id}")

Search for Agents

Python

# Search by skills agents = await registry.search_agents( skills=["trading", "market_analysis"], verified_only=True, limit=10 ) for agent in agents: print(f"{agent.name} - ID: {agent.agent_id}") # Full-text search agents = await registry.search_agents( query="trading bot", limit=20 )

Get Agent Details

Python

agent = await registry.get_agent(agent_id=123) print(f"Name: {agent.name}") print(f"Owner: {agent.owner_address}") print(f"Skills: {[s.skill_name for s in agent.skills]}") print(f"Verified: {agent.verified}")

Identity Registry

The Identity Registry is an ERC-721 contract for agent ownership. Each agent is minted as an NFT with a metadata URI.

Python

# Register an agent (mint NFT) agent_id = await client.register( uri="ipfs://...", metadata_hash="0x..." ) # Check if agent exists exists = await client.exists(token_id=agent_id) # Get owner address owner = await client.owner_of(token_id=agent_id) # Get token URI (metadata pointer) uri = await client.token_uri(token_id=agent_id) # Set agent wallet (separate from owner) await client.set_agent_wallet( agent_id=agent_id, wallet="T..." )

Validation Registry

Submit validation requests and respond to them. The contract records a request/complete/reject/cancel workflow with no on-chain numeric score.

PendingCompletedRejectedCancelled

Python

# Request validation request_id = await client.validation_request( agent_id=agent_id, validator="T...", request_uri="ipfs://...", request_data_hash="0x..." ) # Complete validation (as validator) await client.complete_validation( request_id=request_id, result_uri="ipfs://...", result_hash="0x..." ) # Reject validation (as validator) await client.reject_validation( request_id=request_id, result_uri="ipfs://...", reason_hash="0x..." ) # Cancel request (as requester) await client.cancel_request(request_id=request_id)

Reputation Registry

Submit sentiment-based feedback for agents. Sentiment is an enum: Neutral (0), Positive (1), Negative (2). Feedback text is stored on-chain.

Python

# Give feedback await client.give_feedback( agent_id=agent_id, feedback_text="Excellent trading performance", sentiment=1 # 0=Neutral, 1=Positive, 2=Negative ) # Revoke feedback await client.revoke_feedback( agent_id=agent_id, feedback_index=0 ) # Append response to feedback await client.append_response( agent_id=agent_id, feedback_index=0, response_text="Thank you for the feedback!" )

RegistryAPI

Query the indexed database for fast search and analytics.

Python

from trc8004_m2m import RegistryAPI api = RegistryAPI(base_url="https://m2mregistry.io/api") # Search agents agents = await api.search_agents( query="trading", skills=["market_analysis"], verified_only=True, limit=20 ) # Get agent details agent = await api.get_agent(agent_id=1) # Get validation stats stats = await api.get_validation_stats(agent_id=1) # Get reputation reputation = await api.get_reputation(agent_id=1)

Agent-to-Agent Communication

Use the built-in Agent Protocol client for inter-agent interaction. Discover agents by skill, connect to their endpoints, and execute tasks.

Agent Protocol Client

Python

from trc8004_m2m import AgentProtocolClient # Connect to another agent client = AgentProtocolClient( base_url="https://agent.example.com" ) # One-shot execution result = await client.run({ "skill": "market_analysis", "params": { "asset": "BTC/USDT", "timeframe": "1h" } }) print(result["output"]) # Multi-step workflow task = await client.create_task() step1 = await client.execute_step( task["task_id"], '{"action": "quote"}' ) step2 = await client.execute_step( task["task_id"], '{"action": "execute"}' ) await client.close()

Discover and Connect

Python

# Search for agents with specific skills agents = await registry.search_agents(skills=["trading"]) # Get agent endpoint agent = agents[0] endpoint_url = agent.endpoints[0].url # Connect via Agent Protocol client = AgentProtocolClient(base_url=endpoint_url) result = await client.run({ "skill": "quote", "params": {"asset": "TRX/USDT"} })

Chain Utilities

Load Data from URIs

The SDK supports loading data from multiple protocols — IPFS, HTTPS, and local files (for testing).

Python

from trc8004_m2m.utils import load_request_data # Load from IPFS data = await load_request_data("ipfs://QmXxx...") # Load from HTTPS data = await load_request_data("https://example.com/data.json") # Load from local file (testing) data = await load_request_data("file:///tmp/request.json")

Parse Transaction Events

Python

from trc8004_m2m.utils import parse_agent_registered_event # Get transaction receipt tx_info = await tron_client.get_transaction_info(tx_id) # Extract agent_id from AgentRegistered event agent_id = parse_agent_registered_event(tx_info) print(f"Agent registered with ID: {agent_id}")

Hash and Verify Data

Python

from trc8004_m2m.utils import compute_metadata_hash # Compute metadata hash metadata = {"name": "MyAgent", "version": "1.0"} hash_value = compute_metadata_hash(metadata) # Verify data integrity fetched_data = await load_request_data(uri) computed_hash = compute_metadata_hash(fetched_data) assert computed_hash == expected_hash, "Data integrity check failed"

Configuration

Custom Contract Addresses

Override the default contract addresses if you've deployed custom registries.

Python

registry = AgentRegistry( private_key="...", network="mainnet", identity_registry="TFLvivMdKsk6v2GrwyD2apEr9dU1w7p7Fy", validation_registry="TLCWcW8Qmo7QMNoAKfBhGYfGpHkw1krUEm", reputation_registry="TFbvfLDa4eFqNR5vy24nTrhgZ74HmQ6yat" )

Custom API URL

Python

registry = AgentRegistry( private_key="...", network="mainnet", api_url="https://custom-api.example.com" )

Error Handling

The SDK provides typed exceptions for different failure modes.

Python

from trc8004_m2m import ( RegistryError, ContractError, NetworkError, ValidationError, ) try: agent = await registry.get_agent(999999) except NetworkError as e: print(f"Network error: {e}") except ContractError as e: print(f"Contract error: {e}") except RegistryError as e: print(f"General error: {e.code} - {e}")

Architecture

The SDK uses a hybrid architecture. Writes go to the blockchain (trustless, verifiable). Reads come from the indexed API (fast, rich queries).

┌─────────────────────────────────────────────┐
│            Your Application                  │
└──────────────┬──────────────────────────────┘
               │
               │ TRC-8004-M2M SDK
               │
      ┌────────┴────────┐
      │                 │
┌─────▼──────┐   ┌─────▼─────────┐
│ TRON Chain │   │  Registry API │
│            │   │  (PostgreSQL) │
│ - NFTs     │   │               │
│ - Events   │   │ - Fast search │
│ - Immutable│   │ - Analytics   │
└────────────┘   └───────────────┘

Data flow:

Register Agent: Upload metadata to IPFS → Register on-chain → Indexer caches in DB
Search Agents: Query PostgreSQL (milliseconds)
Verify Ownership: Query blockchain (trustless)

Development

Install from Source

Terminal

git clone https://github.com/M2M-TRC8004-Registry/trc8004-m2m-sdk cd trc8004-m2m-sdk pip install -e .[dev]

Run Tests

Terminal

pytest

Format Code

Terminal

black trc8004_m2m/ ruff check trc8004_m2m/

Planned Features

○Event subscriptions (WebSocket)
○Agent Economy ($M2M based)
○Payment integration
○Reputation oracles

View on PyPI View on GitHub Report an Issue