Service Discovery

Discover MPP-enabled services programmatically so agents can autonomously find and pay for APIs without manual configuration.

Overview

Service discovery enables agents to:

• Find MPP-enabled services based on capability requirements

• Detect payment support via HTTP headers

• Parse pricing and payment method requirements

• Build dynamic service catalogs

MPP Service Directory

The official MPP directory maintains a catalog of services accepting Machine Payments Protocol.

Query the directory

import { MoltMPPClient } from '@moltmpp/sdk'

const mpp = new MoltMPPClient({
  solanaRpc: 'https://api.mainnet-beta.solana.com',
  wallet: wallet
})

// Search for services by category
const services = await mpp.discoverServices({
  category: 'weather',
  paymentMethods: ['solana/usdc'],
  maxPriceUSD: 10.00
})

console.log(`Found ${services.length} services:`)
for (const service of services) {
  console.log(`- ${service.name}: $${service.priceUSD} per request`)
  console.log(`  URL: ${service.endpoint}`)
  console.log(`  Rating: ${service.rating}/5`)
}

Service metadata

Each service listing includes:

interface MPPService {
  name: string
  description: string
  endpoint: string
  category: string[]
  priceUSD: number
  paymentMethods: PaymentMethod[]
  rating: number
  verified: boolean
  documentation: string
}

HTTP Header Detection

Services advertise MPP support via HTTP headers.

Check for MPP support

async function supportsMPP(url: string): Promise<boolean> {
  const response = await fetch(url, { method: 'OPTIONS' })

  // Check for MPP-Version header
  const mppVersion = response.headers.get('MPP-Version')

  return mppVersion !== null
}

// Usage
const supported = await supportsMPP('https://api.weather.com/premium')
console.log(`MPP supported: ${supported}`)

Detect payment methods

async function getPaymentMethods(url: string): Promise<PaymentMethod[]> {
  const response = await fetch(url, { method: 'OPTIONS' })

  const methods = response.headers.get('MPP-Payment-Methods')
  if (!methods) return []

  return JSON.parse(methods)
}

// Returns: [{ type: 'crypto', blockchain: 'solana', token: 'USDC' }]

HTTP 402 Payment Required

When requesting a resource, MPP services return 402 with pricing details.

Request resource

GET /api/premium/forecast?location=NYC HTTP/1.1
Host: api.weather.com

Parse 402 response

async function getPaymentRequirements(url: string): Promise<PaymentRequest> {
  const response = await fetch(url)

  if (response.status === 402) {
    const paymentData = await response.json()

    return {
      amount: parseFloat(paymentData.amount),
      currency: paymentData.currency,
      methods: paymentData.payment_methods,
      description: paymentData.description
    }
  }

  throw new Error('Resource does not require payment')
}

// Usage
const requirements = await getPaymentRequirements(
  'https://api.weather.com/premium/forecast?location=NYC'
)

console.log(`Price: $${requirements.amount} ${requirements.currency}`)
console.log(`Methods: ${JSON.stringify(requirements.methods)}`)

Complete 402 response

{
  "amount": "5.00",
  "currency": "USD",
  "payment_methods": [
    {
      "type": "crypto",
      "blockchain": "solana",
      "token": "USDC",
      "recipient": "DsV...mK9",
      "memo": "payment-id-abc123"
    }
  ],
  "description": "7-day weather forecast for NYC",
  "expires_at": "2026-04-02T18:00:00Z"
}

Agent Service Discovery

Enable agents to discover services based on natural language requirements.

OpenClaw integration

from openclaw import Agent
from moltmpp import SolanaPaymentProvider

provider = SolanaPaymentProvider(
    network="mainnet-beta",
    wallet_path="~/.config/solana/id.json",
    enable_discovery=True  # Enable service discovery
)

agent = Agent(
    name="service_explorer",
    providers=[provider]
)

# Agent discovers services autonomously
result = agent.run("""
I need to analyze sentiment for customer reviews.
Find the best sentiment analysis API that:
1. Accepts MPP payments via Solana
2. Costs less than $0.01 per request
3. Has a rating above 4.0
4. Returns results in JSON format

Execute a test request and return results.
""")

print(f"Selected service: {result.service.name}")
print(f"Price: ${result.service.price}")
print(f"Test result: {result.test_data}")

Custom discovery logic

class ServiceDiscoveryEngine {
  private mpp: MoltMPPClient

  constructor(mpp: MoltMPPClient) {
    this.mpp = mpp
  }

  async findBestService(requirements: {
    capability: string
    maxPriceUSD: number
    minRating: number
  }): Promise<MPPService> {
    // Query directory
    const services = await this.mpp.discoverServices({
      category: requirements.capability,
      maxPriceUSD: requirements.maxPriceUSD
    })

    // Filter by rating
    const qualified = services.filter(s => s.rating >= requirements.minRating)

    if (qualified.length === 0) {
      throw new Error('No services match requirements')
    }

    // Sort by rating (descending), then price (ascending)
    qualified.sort((a, b) => {
      if (a.rating !== b.rating) return b.rating - a.rating
      return a.priceUSD - b.priceUSD
    })

    // Return best match
    return qualified[0]
  }

  async testService(service: MPPService): Promise<boolean> {
    try {
      // Make test request
      const result = await this.mpp.payForResource({
        url: service.endpoint + '/test',
        parameters: { test: true }
      })

      return result.resource !== null
    } catch (error) {
      console.error(`Test failed for ${service.name}:`, error)
      return false
    }
  }
}

// Usage
const discovery = new ServiceDiscoveryEngine(mpp)

const service = await discovery.findBestService({
  capability: 'sentiment-analysis',
  maxPriceUSD: 0.01,
  minRating: 4.0
})

const works = await discovery.testService(service)
console.log(`Service ${service.name} is ${works ? 'operational' : 'unavailable'}`)

Building a Service Catalog

Maintain a local catalog of discovered services for faster lookups.

Catalog structure

interface ServiceCatalog {
  services: Map<string, MPPService>
  lastUpdated: number
  ttl: number  // Time to live in ms
}

class CatalogManager {
  private catalog: ServiceCatalog

  constructor() {
    this.catalog = {
      services: new Map(),
      lastUpdated: Date.now(),
      ttl: 3600000  // 1 hour
    }
  }

  async refresh(mpp: MoltMPPClient) {
    // Fetch all services
    const services = await mpp.discoverServices({})

    // Update catalog
    this.catalog.services.clear()
    for (const service of services) {
      this.catalog.services.set(service.endpoint, service)
    }

    this.catalog.lastUpdated = Date.now()
  }

  isStale(): boolean {
    return Date.now() - this.catalog.lastUpdated > this.catalog.ttl
  }

  async getOrRefresh(
    mpp: MoltMPPClient,
    endpoint: string
  ): Promise<MPPService | null> {
    // Refresh if stale
    if (this.isStale()) {
      await this.refresh(mpp)
    }

    return this.catalog.services.get(endpoint) || null
  }

  search(query: {
    category?: string
    maxPrice?: number
    minRating?: number
  }): MPPService[] {
    let results = Array.from(this.catalog.services.values())

    if (query.category) {
      results = results.filter(s => s.category.includes(query.category!))
    }

    if (query.maxPrice) {
      results = results.filter(s => s.priceUSD <= query.maxPrice!)
    }

    if (query.minRating) {
      results = results.filter(s => s.rating >= query.minRating!)
    }

    return results
  }
}

MCP Server Discovery

Model Context Protocol (MCP) servers can advertise MPP payment support.

MCP manifest with MPP

{
  "name": "premium-weather-mcp",
  "version": "1.0.0",
  "tools": [
    {
      "name": "get_forecast",
      "description": "Get weather forecast",
      "payment": {
        "protocol": "mpp",
        "amount": "5.00",
        "currency": "USD",
        "methods": [
          {
            "type": "crypto",
            "blockchain": "solana",
            "token": "USDC"
          }
        ]
      }
    }
  ]
}

Discover MCP servers

async function discoverMCPServers(): Promise<MCPServer[]> {
  const response = await fetch('https://mcp-directory.com/api/servers')
  const servers = await response.json()

  // Filter for MPP-enabled servers
  return servers.filter(server =>
    server.tools.some(tool => tool.payment?.protocol === 'mpp')
  )
}

// Use with agent
const mcpServers = await discoverMCPServers()

for (const server of mcpServers) {
  console.log(`${server.name}: ${server.description}`)
  console.log(`  Payment required: ${server.tools[0].payment.amount} ${server.tools[0].payment.currency}`)
}

Service Reputation

Track service performance to build reputation scores.

Reputation tracking

interface ServiceReputation {
  endpoint: string
  totalRequests: number
  successfulRequests: number
  averageLatency: number
  lastFailure: number | null
  userRating: number
}

class ReputationTracker {
  private data: Map<string, ServiceReputation>

  constructor() {
    this.data = new Map()
  }

  record(endpoint: string, success: boolean, latency: number) {
    const rep = this.data.get(endpoint) || {
      endpoint,
      totalRequests: 0,
      successfulRequests: 0,
      averageLatency: 0,
      lastFailure: null,
      userRating: 0
    }

    rep.totalRequests++
    if (success) {
      rep.successfulRequests++
    } else {
      rep.lastFailure = Date.now()
    }

    // Update average latency (exponential moving average)
    const alpha = 0.3
    rep.averageLatency = alpha * latency + (1 - alpha) * rep.averageLatency

    this.data.set(endpoint, rep)
  }

  getSuccessRate(endpoint: string): number {
    const rep = this.data.get(endpoint)
    if (!rep || rep.totalRequests === 0) return 0

    return rep.successfulRequests / rep.totalRequests
  }

  isReliable(endpoint: string, threshold: number = 0.95): boolean {
    return this.getSuccessRate(endpoint) >= threshold
  }

  getBestServices(category: string): string[] {
    const services = Array.from(this.data.values())
      .filter(s => this.isReliable(s.endpoint))
      .sort((a, b) => {
        // Sort by success rate, then latency
        const successDiff = b.successfulRequests / b.totalRequests -
                           a.successfulRequests / a.totalRequests
        if (Math.abs(successDiff) > 0.01) return successDiff > 0 ? 1 : -1
        return a.averageLatency - b.averageLatency
      })

    return services.map(s => s.endpoint)
  }
}

Production Example

Complete service discovery system for production agents.

import { MoltMPPClient } from '@moltmpp/sdk'

class ProductionServiceDiscovery {
  private mpp: MoltMPPClient
  private catalog: CatalogManager
  private reputation: ReputationTracker

  constructor(mpp: MoltMPPClient) {
    this.mpp = mpp
    this.catalog = new CatalogManager()
    this.reputation = new ReputationTracker()
  }

  async findAndPayForService(requirements: {
    capability: string
    maxPriceUSD: number
    minRating: number
    parameters: any
  }): Promise<any> {
    // Find candidate services
    const candidates = this.catalog.search({
      category: requirements.capability,
      maxPrice: requirements.maxPriceUSD,
      minRating: requirements.minRating
    })

    // Filter by reputation
    const reliable = candidates.filter(s =>
      this.reputation.isReliable(s.endpoint)
    )

    if (reliable.length === 0) {
      throw new Error('No reliable services available')
    }

    // Try services in order of reputation
    for (const service of reliable) {
      try {
        const start = Date.now()

        const result = await this.mpp.payForResource({
          url: service.endpoint,
          parameters: requirements.parameters
        })

        const latency = Date.now() - start

        // Record success
        this.reputation.record(service.endpoint, true, latency)

        return result.resource

      } catch (error) {
        // Record failure
        this.reputation.record(service.endpoint, false, 0)
        console.warn(`Service ${service.name} failed, trying next...`)
        continue
      }
    }

    throw new Error('All services failed')
  }
}

// Usage
const discovery = new ProductionServiceDiscovery(mpp)

const result = await discovery.findAndPayForService({
  capability: 'weather',
  maxPriceUSD: 10.00,
  minRating: 4.0,
  parameters: { location: 'NYC', days: 7 }
})

console.log('Weather forecast:', result)

Next Steps

• OpenClaw Integration: Build autonomous agent workflows

• Approval Policies: Configure payment authorization

• MPP Protocol Deep-Dive: Advanced protocol details

Resources

• MPP Directory: mpp.dev/directory

• MCP Directory: mcp-directory.com

• Discord: discord.gg/moltmpp - #service-discovery