@lucid-fdn/oracle

TypeScript SDK for the Lucid Agent Oracle API — economic intelligence for the agent economy.

Install

npm install @lucid-fdn/oracle

Quick Start

import { LucidOracle } from "@lucid-fdn/oracle";

// Auto-reads LUCID_ORACLE_API_KEY from env (optional — free-tier works without auth)
const oracle = new LucidOracle();

// List all oracle feeds
const feeds = await oracle.feeds.list();

// Search agents
const agents = await oracle.agents.search({ q: "lucid" });

// Get protocol details
const protocols = await oracle.protocols.list();

Authentication

API key is optional. Free-tier endpoints work anonymously. Pro-tier endpoints require a key.

// Explicit API key
const oracle = new LucidOracle({ apiKey: "sk_..." });

// Or set LUCID_ORACLE_API_KEY env var (auto-detected)
const oracle = new LucidOracle();

// Custom server URL (for local dev)
const oracle = new LucidOracle({
  serverURL: "http://localhost:4040",
});

Resources

Feeds

oracle.feeds.list();                              // List all feeds
oracle.feeds.get({ id });                         // Get feed by ID
oracle.feeds.methodology({ id });                 // Get feed methodology
oracle.feeds.history({ id, period, interval });   // Get feed history

Agents

oracle.agents.search({ q, cursor, limit });       // Search agents
oracle.agents.leaderboard({ sort, cursor, limit }); // Agent leaderboard
oracle.agents.get({ id });                         // Get agent by ID
oracle.agents.metrics({ id });                     // Agent metrics (Pro)
oracle.agents.activity({ id, cursor, limit });     // Agent activity (Pro)
oracle.agents.modelUsage({ period, limit });       // Model usage stats (Pro)

Protocols

oracle.protocols.list();                           // List all protocols
oracle.protocols.get({ id });                      // Get protocol by ID
oracle.protocols.metrics({ id });                  // Protocol metrics (Pro)

Reports

oracle.reports.latest();                           // Get latest report
oracle.reports.verify({ ...reportEnvelope });      // Verify report signature

Pagination

Cursor-paginated endpoints return { data, pagination }:

let cursor: string | undefined;
do {
  const page = await oracle.agents.search({ q: "lucid", cursor });
  for (const agent of page.data) {
    console.log(agent);
  }
  cursor = page.pagination?.nextCursor ?? undefined;
} while (cursor);

Error Handling

import { LucidOracleError } from "@lucid-fdn/oracle/models/errors";

try {
  await oracle.agents.get({ id: "nonexistent" });
} catch (err) {
  if (err instanceof LucidOracleError) {
    console.error(err.statusCode, err.body);
  }
}

Error codes: 400 (validation), 401 (invalid key), 403 (tier required), 404 (not found), 429 (rate limited), 500 (internal). All errors follow RFC 9457 Problem Details format.

License

Apache-2.0