registry-broker

What this skill does

# Registry Broker

Search 72,000+ AI agents across AgentVerse, NANDA, OpenRouter, Virtuals Protocol, PulseMCP, Near AI, and more via the [Hashgraph Online Registry Broker](https://hol.org/registry).

## Setup

Get your API key at https://hol.org/registry and set:

```bash
export REGISTRY_BROKER_API_KEY="your-key"
```

## API Base

```
https://hol.org/registry/api/v1
```

## Discovery

### Keyword Search

```bash
# GET /search with query params
curl "https://hol.org/registry/api/v1/search?q=trading+bot&limit=5"

# With filters: registries, adapters, capabilities, protocols, minTrust, verified, online, sortBy, type
curl "https://hol.org/registry/api/v1/search?q=defi&registries=agentverse,nanda&verified=true&limit=10"
```

### Vector/Semantic Search

```bash
# POST /search with JSON body
curl -X POST "https://hol.org/registry/api/v1/search" \
  -H "Content-Type: application/json" \
  -d '{"query": "help me analyze financial data", "limit": 5}'
```

### Capability Search

```bash
# POST /search/capabilities
curl -X POST "https://hol.org/registry/api/v1/search/capabilities" \
  -H "Content-Type: application/json" \
  -d '{"capabilities": ["code-generation", "data-analysis"], "limit": 10}'
```

### Agent Details

```bash
# GET /agents/{uaid} - Get agent details
curl "https://hol.org/registry/api/v1/agents/uaid:aid:fetchai:..."

# GET /agents/{uaid}/similar - Find similar agents
curl "https://hol.org/registry/api/v1/agents/uaid:aid:fetchai:.../similar"

# GET /agents/{uaid}/feedback - Get agent feedback
curl "https://hol.org/registry/api/v1/agents/uaid:aid:fetchai:.../feedback"
```

### Routing & Resolution

```bash
# GET /resolve/{uaid} - Resolve UAID to agent metadata
curl "https://hol.org/registry/api/v1/resolve/uaid:aid:fetchai:..."

# GET /uaids/validate/{uaid} - Validate UAID format
curl "https://hol.org/registry/api/v1/uaids/validate/uaid:aid:fetchai:..."

# GET /uaids/connections/{uaid}/status - Check connection status
curl "https://hol.org/registry/api/v1/uaids/connections/uaid:aid:.../status"
```

### Registry Information

```bash
# GET /registries - List known registries
curl "https://hol.org/registry/api/v1/registries"

# GET /adapters - List available adapters
curl "https://hol.org/registry/api/v1/adapters"

# GET /adapters/details - Adapter metadata with chat capabilities
curl "https://hol.org/registry/api/v1/adapters/details"

# GET /stats - Platform statistics
curl "https://hol.org/registry/api/v1/stats"

# GET /providers - Provider catalog with protocols
curl "https://hol.org/registry/api/v1/providers"

# GET /popular - Popular search queries
curl "https://hol.org/registry/api/v1/popular"

# GET /search/facets - Available search facets
curl "https://hol.org/registry/api/v1/search/facets"

# GET /search/status - Search backend status
curl "https://hol.org/registry/api/v1/search/status"
```

## Chat

### Session Management

```bash
# POST /chat/session - Create session (by UAID or agentUrl)
curl -X POST "https://hol.org/registry/api/v1/chat/session" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $REGISTRY_BROKER_API_KEY" \
  -d '{"uaid": "uaid:aid:fetchai:..."}'

# Or by agent URL:
curl -X POST "https://hol.org/registry/api/v1/chat/session" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $REGISTRY_BROKER_API_KEY" \
  -d '{"agentUrl": "https://agent.example.com/api"}'
# Returns: {"sessionId": "sess_..."}
```

### Messaging

```bash
# POST /chat/message - Send message
curl -X POST "https://hol.org/registry/api/v1/chat/message" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $REGISTRY_BROKER_API_KEY" \
  -d '{"sessionId": "sess_...", "message": "Hello!"}'

# With streaming (SSE):
curl -X POST "https://hol.org/registry/api/v1/chat/message" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "x-api-key: $REGISTRY_BROKER_API_KEY" \
  -d '{"sessionId": "sess_...", "message": "Hello!", "stream": true}'
```

### History & Management

```bash
# GET /chat/session/{sessionId}/history - Get conversation history
curl "https://hol.org/registry/api/v1/chat/session/sess_.../history" \
  -H "x-api-key: $REGISTRY_BROKER_API_KEY"

# POST /chat/session/{sessionId}/compact - Summarize history (debits credits)
curl -X POST "https://hol.org/registry/api/v1/chat/session/sess_.../compact" \
  -H "x-api-key: $REGISTRY_BROKER_API_KEY"

# GET /chat/session/{sessionId}/encryption - Get encryption status
curl "https://hol.org/registry/api/v1/chat/session/sess_.../encryption" \
  -H "x-api-key: $REGISTRY_BROKER_API_KEY"

# DELETE /chat/session/{sessionId} - End session
curl -X DELETE "https://hol.org/registry/api/v1/chat/session/sess_..." \
  -H "x-api-key: $REGISTRY_BROKER_API_KEY"
```

## Registration

### Quote & Register

```bash
# GET /register/additional-registries - List available registries for registration
curl "https://hol.org/registry/api/v1/register/additional-registries" \
  -H "x-api-key: $REGISTRY_BROKER_API_KEY"

# POST /register/quote - Get credit cost estimate
curl -X POST "https://hol.org/registry/api/v1/register/quote" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $REGISTRY_BROKER_API_KEY" \
  -d '{"profile": {"name": "My Agent", "description": "..."}}'

# POST /register - Register agent (returns 200/202/207)
curl -X POST "https://hol.org/registry/api/v1/register" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $REGISTRY_BROKER_API_KEY" \
  -d '{
    "profile": {"name": "My Agent", "description": "..."},
    "endpoint": "https://my-agent.com/api",
    "protocol": "openai",
    "registry": "custom"
  }'
```

### Status & Updates

```bash
# GET /register/status/{uaid} - Check registration status
curl "https://hol.org/registry/api/v1/register/status/uaid:..." \
  -H "x-api-key: $REGISTRY_BROKER_API_KEY"

# GET /register/progress/{attemptId} - Poll registration progress
curl "https://hol.org/registry/api/v1/register/progress/{attemptId}" \
  -H "x-api-key: $REGISTRY_BROKER_API_KEY"

# PUT /register/{uaid} - Update agent
curl -X PUT "https://hol.org/registry/api/v1/register/uaid:..." \
  -H "Content-Type: application/json" \
  -H "x-api-key: $REGISTRY_BROKER_API_KEY" \
  -d '{"profile": {"name": "Updated Name"}}'

# DELETE /register/{uaid} - Unregister agent
curl -X DELETE "https://hol.org/registry/api/v1/register/uaid:..." \
  -H "x-api-key: $REGISTRY_BROKER_API_KEY"
```

## Credits & Payments

```bash
# GET /credits/balance - Check balance (optional accountId query param)
curl "https://hol.org/registry/api/v1/credits/balance" \
  -H "x-api-key: $REGISTRY_BROKER_API_KEY"

# GET /credits/providers - List payment providers
curl "https://hol.org/registry/api/v1/credits/providers" \
  -H "x-api-key: $REGISTRY_BROKER_API_KEY"

# POST /credits/payments/hbar/intent - Create HBAR payment intent
curl -X POST "https://hol.org/registry/api/v1/credits/payments/hbar/intent" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $REGISTRY_BROKER_API_KEY" \
  -d '{"credits": 100}'

# POST /credits/payments/intent - Create Stripe payment intent
curl -X POST "https://hol.org/registry/api/v1/credits/payments/intent" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $REGISTRY_BROKER_API_KEY" \
  -d '{"credits": 100}'
```

## Ledger Authentication (Wallet-based)

Authenticate with EVM or Hedera wallets instead of API keys:

```bash
# POST /auth/ledger/challenge - Get sign challenge
curl -X POST "https://hol.org/registry/api/v1/auth/ledger/challenge" \
  -H "Content-Type: application/json" \
  -d '{"network": "hedera-mainnet", "accountId": "0.0.12345"}'
# Returns: {"challengeId": "...", "challenge": "sign-this-message", "expiresAt": "..."}

# POST /auth/ledger/verify - Verify signature, get temp API key
curl -X POST "https://hol.org/registry/api/v1/auth/ledger/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "challengeId": "...",
    "accountId": "0.0.12345",
    "network": "hedera-mainnet",
    "signature": "...",
    "publicKey": "...",
    "signatureKind": "raw