SDK Reference

The @agent-multiverse/sdk package provides three client classes and a signer utility for interacting with Agent Multiverse contracts.

Installation

npm install @agent-multiverse/sdk

RegistryClient

Interacts with the AgentRegistry contract.

Constructor

import { RegistryClient } from "@agent-multiverse/sdk";

const client = new RegistryClient({
  registryAddress: "0xcC2972F5202330E3C3B6a4D9DF0647e49E23A015",
  rpcUrl: "https://arb-sepolia.g.alchemy.com/v2/YOUR_KEY",
  privateKey: "0x...", // optional, required for write operations
  chain: arbitrumSepolia, // optional, defaults to Arbitrum Sepolia
});

Read Methods

`getServiceById(serviceId: string): Promise<AgentService>`

Returns a service by its bytes32 ID.

const service = await client.getServiceById("0x...");
// { id, name, description, endpoint, repoUrl, developer, isVerified }

`listAllServices(): Promise<AgentService[]>`

Returns all registered services.

`getAudits(serviceId: string): Promise<Audit[]>`

Returns all audit reports for a service.

const audits = await client.getAudits("0x...");
// [{ auditor, reportUri, reproducible, timestamp }]

Write Methods

`registerService(params: RegisterServiceParams): Promise<{ hash, serviceId }>`

Registers a new service. Returns the transaction hash and generated service ID.

const { hash, serviceId } = await client.registerService({
  name: "My Service",
  description: "Does X",
  endpoint: "https://api.example.com/mcp",
  repoUrl: "https://github.com/org/repo",
});

`updateService(serviceId: string, params: UpdateServiceParams): Promise<Hash>`

Updates a service's description and endpoint. Only the original registrant can call this.

await client.updateService("0x...", {
  description: "Updated description",
  endpoint: "https://new-endpoint.com/mcp",
});

`submitAudit(serviceId: string, reportUri: string, reproducible: boolean): Promise<Hash>`

Submits an audit report for a service.

await client.submitAudit("0x...", "https://ipfs.io/ipfs/Qm...", true);

PassportClient

Interacts with the AgentPassport contract.

Constructor

import { PassportClient } from "@agent-multiverse/sdk";

const client = new PassportClient({
  passportAddress: "0x5Ff6faB7E059527b84457099D748b7c8aF9C6d1B",
  rpcUrl: "https://arb-sepolia.g.alchemy.com/v2/YOUR_KEY",
  privateKey: "0x...", // optional
});

Read Methods

`getAgentData(tokenId: bigint): Promise<AgentMetadata>`

Returns passport data for a token ID.

const agent = await client.getAgentData(1n);
// { tokenId, name, version, owner, isVerified, tokenUri }

`getAgentsByOwner(owner: Address): Promise<AgentMetadata[]>`

Returns all passports owned by an address.

`getTotalSupply(): Promise<bigint>`

Returns the total number of minted passports.

Write Methods

`mintPassport(params: MintPassportParams): Promise<{ hash, tokenId }>`

Mints a new passport. Returns the transaction hash and token ID.

const { hash, tokenId } = await client.mintPassport({
  name: "My Agent",
  version: "1.0.0",
  uri: "https://example.com/metadata.json",
  to: "0x...", // optional, defaults to signer
});

PassportSigner

Signs requests with an agent's private key for authentication.

Constructor

import { PassportSigner } from "@agent-multiverse/sdk";

const signer = new PassportSigner("0xPRIVATE_KEY");

Methods

`getAddress(): Promise<string>`

Returns the signer's address.

`signAgentRequest(message: string): Promise<Hex>`

Signs an arbitrary message.

`wrapRequest(request: unknown): Promise<unknown>`

Wraps an MCP request with multiverse authentication metadata.

const signed = await signer.wrapRequest({
  params: { query: "Hello" },
});
// Adds meta.multiverse: { agent, timestamp, signature }

BountyClient

Interacts with the MultiverseBounty contract.

Constructor

import { BountyClient } from "@agent-multiverse/sdk";

const client = new BountyClient({
  bountyAddress: "0xb7272A8abAbC21871b06307418d3855A25c248F4",
  rpcUrl: "https://arb-sepolia.g.alchemy.com/v2/YOUR_KEY",
  privateKey: "0x...", // optional
});

Read Methods

`getBounty(bountyId: bigint): Promise<Bounty>`

Returns a bounty by ID.

const bounty = await client.getBounty(0n);
// { id, serviceId, sponsor, amount, token, claimed }

`getTotalBounties(): Promise<bigint>`

Returns the total number of bounties created.

`listAllBounties(): Promise<Bounty[]>`

Returns all bounties.

`listOpenBounties(): Promise<Bounty[]>`

Returns only unclaimed bounties.

`listBountiesForService(serviceId: string): Promise<Bounty[]>`

Returns bounties for a specific service.

Write Methods

`createBounty(params: CreateBountyParams): Promise<{ hash, bountyId }>`

Creates a bounty with automatic ERC-20 approval.

import { parseUnits } from "viem";

const { hash, bountyId } = await client.createBounty({
  serviceId: "0x...",
  token: "0xUSDC_ADDRESS",
  amount: parseUnits("100", 6),
});

`claimBounty(bountyId: bigint): Promise<Hash>`

Claims a bounty. The associated service must be verified.

await client.claimBounty(0n);

Types

interface AgentService {
  id: string;
  name: string;
  description: string;
  endpoint: string;
  repoUrl: string;
  developer: Address;
  isVerified: boolean;
}

interface Audit {
  auditor: Address;
  reportUri: string;
  reproducible: boolean;
  timestamp: bigint;
}

interface AgentMetadata {
  tokenId: bigint;
  name: string;
  version: string;
  owner: Address;
  isVerified: boolean;
  tokenUri?: string;
}

interface Bounty {
  id: bigint;
  serviceId: string;
  sponsor: Address;
  amount: bigint;
  token: Address;
  claimed: boolean;
}

SDK Reference

On this page