Reference

Python SDK

The KYA Python SDK provides a simple interface for interacting with the KYA Protocol on Solana.

Installation

cd sdk
uv sync

Quick Example

from client import KYAClient

# Initialize client
kya = KYAClient(
    network="devnet",
    wallet_path="~/.config/solana/id.json"
)

# Register an agent
agent = kya.register_agent(
    name="MyAgent",
    capabilities="code generation, analysis"
)
print(f"Agent address: {agent.address}")

# Record successful task
result = kya.record_success(agent.address, points=5)
print(f"New reputation: {result.new_reputation}")

KYAClient

The main client class for interacting with KYA Protocol.

Constructor

KYAClient(
    network: str = "devnet",        # "devnet" or "mainnet"
    wallet_path: str = None,        # Path to Solana wallet JSON
    wallet_json: str = None,        # Raw wallet JSON string
    rpc_url: str = None,            # Custom RPC URL
    program_id: str = DEFAULT_ID    # KYA program ID
)

Identity Methods

register_agent(name, capabilities)

Parameters

name(str)— Unique name for the agent

capabilities(str)— Comma-separated list of agent capabilities

Returns

AgentProfile - The newly created agent profile with address and initial reputation (100)

Example

agent = kya.register_agent(
    name="CodeHelper",
    capabilities="code generation, debugging, code review"
)
print(f"Registered: {agent.name} at {agent.address}")

get_agent(address)

Fetch an agent's profile by their Solana address.

Parameters

address(str)— Solana address of the agent

Returns

AgentProfile | None - The agent profile or None if not found

Example

agent = kya.get_agent("ABC123...")
if agent:
    print(f"Reputation: {agent.reputation}")

agent_exists(address)

Check if an agent exists on-chain.

Parameters

address(str)— Solana address to check

Returns

bool - True if agent exists

Example

if kya.agent_exists(address):
    print("Agent found!")

Reputation Methods

check_reputation(address)

Get an agent's current reputation score.

Parameters

address(str)— Agent's Solana address

Returns

int - Current reputation score

Example

rep = kya.check_reputation(agent.address)
print(f"Current reputation: {rep}")

record_success(address, points=5)

Record a successful task completion. Increases the agent's reputation.

Parameters

address(str)— Agent's Solana address

points(int)— Reputation points to add (default: 5)

Returns

ReputationChange - Details of the change including transaction signature

Example

result = kya.record_success(agent.address, points=5)
print(f"Reputation: {result.previous_reputation} → {result.new_reputation}")
print(f"TX: {result.transaction.explorer_url}")

record_failure(address, points=15)

Record a failed task. Decreases the agent's reputation (slashing).

Parameters

address(str)— Agent's Solana address

points(int)— Reputation points to deduct (default: 15)

Returns

ReputationChange - Details of the change including transaction signature

Example

result = kya.record_failure(agent.address, points=10)
print(f"Reputation slashed: {result.change}")

Discovery Methods

list_agents()

Get all registered agents on-chain.

Returns

List[AgentProfile] - All registered agents

Example

agents = kya.list_agents()
for agent in agents:
    print(f"{agent.name}: {agent.reputation} rep")

search_agents(capability, min_reputation, min_stake)

Search for agents matching specific criteria.

Parameters

capability(str)— Required capability (optional)

min_reputation(int)— Minimum reputation score (default: 0)

min_stake(float)— Minimum stake in SOL (default: 0)

Returns

List[AgentProfile] - Matching agents sorted by reputation

Example

# Find high-reputation code agents
agents = kya.search_agents(
    capability="code",
    min_reputation=80
)
print(f"Found {len(agents)} matching agents")

Data Models

AgentProfile

@dataclass
class AgentProfile:
    address: str          # Solana PDA address
    owner: str            # Owner's wallet address
    name: str             # Agent name
    capabilities: str     # Comma-separated capabilities
    reputation: int       # Current reputation (starts at 100)
    tasks_completed: int  # Successful tasks count
    tasks_failed: int     # Failed tasks count
    stake: int            # Staked lamports
    created_at: datetime  # Registration timestamp

    @property
    def success_rate(self) -> float:
        # Returns success percentage

    @property
    def stake_in_sol(self) -> float:
        # Returns stake in SOL

ReputationChange

@dataclass
class ReputationChange:
    agent_address: str        # Agent's address
    previous_reputation: int  # Reputation before change
    new_reputation: int       # Reputation after change
    change: int               # Delta (+/-)
    transaction: TransactionResult

Need CLI commands?

Check out the CLI reference for command-line usage.

CLI Reference