Lucid Client API Skill

This skill provides capabilities to interact with the Lucid Client API, which is a multi-agent runtime system hosted in the lucid-client codebase.

API Base URL

The API base URL is typically:

• Development: http://localhost:8787
• Production: Configured via VITE_API_URL environment variable

Authentication

Most endpoints require authentication via Better Auth:

• Session cookies are automatically sent with requests
• Protected routes: /api/agents/*, /api/secrets/*
• Public routes: /agents/{slug}, /agents/{agentId}/.well-known/agent-card.json

Key Endpoints

Agent Management

List Agents

GET /api/agents
Query params: ?page=1&limit=10&search=query&enabled=true

Returns paginated list of agents for the authenticated owner.

Create Agent

POST /api/agents
Content-Type: application/json

{
  "slug": "my-agent",
  "name": "My Agent",
  "description": "Agent description",
  "version": "1.0.0",
  "entrypoints": [...],
  "paymentsConfig": {...},
  "walletsConfig": {...}
}

Get Agent

GET /api/agents/{agentId}

Update Agent

PUT /api/agents/{agentId}
Content-Type: application/json

{
  "name": "Updated Name",
  "description": "Updated description",
  ...
}

Delete Agent

DELETE /api/agents/{agentId}

Get Public Agent by Slug

GET /agent/{slug}

Public endpoint (no auth required). Returns enabled agents only.

Agent Invocation

Get Agent Manifest

GET /agents/{agentId}/.well-known/agent-card.json

Returns A2A-compatible agent manifest/card.

List Entrypoints

GET /agents/{agentId}/entrypoints

Returns all entrypoints for an agent.

Invoke Entrypoint

POST /agents/{agentId}/entrypoints/{key}/invoke
Content-Type: application/json

{
  "input": {
    "field1": "value1",
    "field2": "value2"
  },
  "metadata": {
    "requestId": "optional-request-id"
  }
}

Payment Handling:

• If entrypoint requires payment, returns 402 Payment Required
• Response includes x402 payment headers:
  • X-Payment-Required: true
  • X-Payment-Price: "$0.001"
  • X-Payment-Network: "eip155:84532"
  • X-Payment-PayTo: "0x..."
• Client must complete payment and retry with payment headers:
  • PAYMENT-REQUIRED: Payment amount
  • PAYMENT-SIGNATURE: Payment signature
  • PAYMENT-RESPONSE: Payment response

Secrets Management

List Secrets

GET /api/agents/{agentId}/secrets

Create Secret

POST /api/agents/{agentId}/secrets
Content-Type: application/json

{
  "key": "API_KEY",
  "value": "secret-value"
}

Get Secret

GET /api/agents/{agentId}/secrets/{key}

Update Secret

PUT /api/agents/{agentId}/secrets/{key}
Content-Type: application/json

{
  "value": "new-secret-value"
}

Delete Secret

DELETE /api/agents/{agentId}/secrets/{key}

Analytics

Get Analytics Summary

GET /api/agents/{agentId}/analytics/summary
Query params: ?startDate=2024-01-01&endDate=2024-01-31

Get Analytics Transactions

GET /api/agents/{agentId}/analytics/transactions
Query params: ?page=1&limit=10&startDate=...&endDate=...

Invocations

List Invocations

GET /api/agents/{agentId}/invocations
Query params: ?page=1&limit=10&status=success&entrypointKey=echo

Get Invocation

GET /api/agents/{agentId}/invocations/{invocationId}

Get Invocation Stats

GET /api/agents/{agentId}/invocations/stats
Query params: ?startDate=...&endDate=...

Identity

Retry Identity Registration

POST /api/agents/{agentId}/identity/retry

Update Identity Metadata

PUT /api/agents/{agentId}/identity/metadata
Content-Type: application/json

{
  "metadata": {
    "key": "value"
  }
}

Rankings

Get Rankings

GET /api/rankings
Query params: ?window=24h&limit=10

Stream Rankings

GET /api/rankings/stream
Query params: ?window=24h

Server-Sent Events stream of live rankings.

Health & Stats

Health Check

GET /health

Redis Health

GET /health/redis

Network Stats

GET /api/stats/network

OpenAPI Documentation

The API provides full OpenAPI documentation:

• OpenAPI Spec: GET /doc (JSON)
• Swagger UI: Available when served (typically at /swagger)

Common Patterns

Making Authenticated Requests

When making requests from code, include credentials:

const response = await fetch(`${API_URL}/api/agents`, {
  method: 'GET',
  credentials: 'include', // Important for cookies
  headers: {
    'Content-Type': 'application/json',
  },
});

Handling Payment-Required Responses

let response = await fetch(`${API_URL}/agents/${agentId}/entrypoints/${key}/invoke`, {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ input: {...} }),
});

if (response.status === 402) {
  // Extract payment details from headers
  const price = response.headers.get('X-Payment-Price');
  const network = response.headers.get('X-Payment-Network');
  const payTo = response.headers.get('X-Payment-PayTo');
  
  // Complete payment using x402 client
  const paymentResponse = await completePayment({ price, network, payTo });
  
  // Retry with payment headers
  response = await fetch(`${API_URL}/agents/${agentId}/entrypoints/${key}/invoke`, {
    method: 'POST',
    credentials: 'include',
    headers: {
      'Content-Type': 'application/json',
      'PAYMENT-REQUIRED': price,
      'PAYMENT-SIGNATURE': paymentResponse.signature,
      'PAYMENT-RESPONSE': paymentResponse.response,
    },
    body: JSON.stringify({ input: {...} }),
  });
}

Error Handling

The API returns standard error responses:

{
  "error": "Error type",
  "message": "Human-readable error message",
  "details": {...} // Optional additional details
}

Common status codes:

• 400: Validation error
• 401: Unauthorized (not authenticated)
• 402: Payment required
• 404: Resource not found
• 409: Conflict (e.g., slug already exists)
• 500: Internal server error

When to Use This Skill

Use this skill when:

• User wants to interact with the Lucid Client API
• User needs to manage agents programmatically
• User wants to invoke agent entrypoints
• User needs to handle payments for agent invocations
• User wants to query analytics or rankings
• User needs to manage agent secrets

Notes

• The API is in the lucid-client codebase, not lucid-agents
• The API uses Hono with OpenAPI validation
• All agent operations are scoped to the authenticated owner
• Payments use the x402 protocol (HTTP-native payments)
• The runtime is stateless - agents are built dynamically from stored definitions