@agentclear/sdk

Official SDK for Agent Clear — the AI agent service marketplace.

Agent Clear lets AI agents discover and pay for API services. This SDK provides:

• Provider middleware — protect your API with the 402 viral loop so agents can discover and pay for your service
• Consumer client — discover and call services through the Agent Clear metered proxy

Installation

npm install @agentclear/sdk

Quick Start: Consumer (AI Agent)

Discover and call services through Agent Clear:

import { AgentClearClient } from "@agentclear/sdk";

const client = new AgentClearClient({ apiKey: "axk_your_key_here" });

// Discover services by natural language query
const { services } = await client.discover("sentiment analysis");
console.log(services);

// Call a service through the metered proxy
const result = await client.call(services[0].id, {
  text: "I love this product!",
});
console.log(result.data);

Quick Start: Provider (402 Middleware)

Wrap your API so unauthorized agents receive a structured 402 response pointing them to Agent Clear:

Express

import express from "express";
import { requireAgentClear } from "@agentclear/sdk";

const app = express();

app.use(
  requireAgentClear({
    serviceId: "my-sentiment-api",
    pricePerCall: 0.005,
  })
);

app.post("/analyze", (req, res) => {
  // Your API logic — only reached by authenticated agents
  res.json({ sentiment: "positive", score: 0.95 });
});

app.listen(3000);

Any Framework (Generic Verifier)

import { verifyAgentClearRequest } from "@agentclear/sdk";

const verify = verifyAgentClearRequest({
  serviceId: "my-api",
  pricePerCall: 0.005,
});

// In your request handler:
const result = verify(request.headers);
if (!result.valid) {
  return new Response(JSON.stringify(result.error), {
    status: 402,
    headers: { "Content-Type": "application/json" },
  });
}

When an agent calls your API without a valid key, they receive:

{
  "error": "Payment Required",
  "message": "This API requires $0.005/call via Agent Clear.",
  "signup_url": "https://agentclear.dev/signup",
  "docs_url": "https://agentclear.dev/docs",
  "service_id": "my-sentiment-api",
  "price_per_call": 0.005,
  "platform": "agentclear"
}

API Reference

AgentClearClient

new AgentClearClient(options: {
  apiKey: string;       // Required — your axk_ API key
  baseUrl?: string;     // Default: "https://agentclear.dev"
  frameworkRef?: string; // Optional framework ref for rev-share
})

client.discover(query, options?)

Search for services by natural language.

| Parameter | Type | Default | Description | | --------------- | ---------- | ------- | --------------------- | | query | string | — | Semantic search query | | options.limit | number | 10 | Max results | | options.tags | string[] | — | Filter by tags |

Returns Promise<DiscoverResponse>.

client.call(serviceId, payload, options?)

Call a service through the metered proxy.

| Parameter | Type | Default | Description | | ----------------- | -------- | -------- | ---------------------- | | serviceId | string | — | Service to call | | payload | any | — | JSON body to forward | | options.timeout | number | 30000 | Timeout in ms |

Returns Promise<ServiceResponse>.

client.services(options?)

List available services with optional filtering.

| Parameter | Type | Default | Description | | ------------------ | -------- | ------- | ------------------------ | | options.limit | number | — | Max results | | options.offset | number | — | Pagination offset | | options.protocol | string | — | Filter by protocol |

Returns Promise<ServicesResponse>.

requireAgentClear(options)

Express/Connect middleware that returns 402 for unauthenticated requests.

verifyAgentClearRequest(options)

Framework-agnostic verifier. Returns a function that accepts headers and returns { valid, userId?, error? }.

Documentation

Full documentation at https://agentclear.dev/docs.

License

MIT — see LICENSE.