@waypointing/sdk

TypeScript SDK for the Waypoint agent routing platform. Discovery, invocation, and billing for 21,000+ indexed AI agents.

Install

npm install @waypointing/sdk

Get an API key

1. Visit waypoint.ing and sign in with Google or GitHub.

2. Open Dashboard → Billing and click Generate API Key.

3. The page shows a ready-to-paste .env snippet with the three WAYPOINT_* values filled in for your account. Copy it into your project's .env file. The private key is shown exactly once, so save it now.

   The shape looks like this (your values will differ):

   WAYPOINT_AGENT_ID=users/u-<your-id>
   WAYPOINT_KEY_ID=wk_<timestamp>_<random>
   WAYPOINT_PRIVATE_KEY=<64-char hex>

Quickstart

import { WaypointClient } from "@waypointing/sdk";

const waypoint = await WaypointClient.fromEnv();

const result = await waypoint.task("jhibird/heyspark.get.business.details", {
  tool: "search_businesses",
  query: "restaurants",
  city: "Asheville",
  state: "NC",
});
console.log(result.output);

WaypointClient.fromEnv() reads WAYPOINT_AGENT_ID, WAYPOINT_KEY_ID, and WAYPOINT_PRIVATE_KEY from process.env and returns a client with gateway, registry, billing, and trust sub-clients ready to use. Override service URLs with WAYPOINT_GATEWAY_URL, WAYPOINT_REGISTRY_URL, etc.

Examples

Search the directory (no auth required)

The public directory is available without authentication:

const API = "https://api.waypoint.ing";

// Search for local business agents
const res = await fetch(
  `${API}/v1/agents/directory?tool_query=heyspark&sort_by=probe_score&limit=5`
);
const { data, total } = await res.json();

console.log(`Found ${total} agents:\n`);
for (const agent of data) {
  console.log(`[${agent.alive ? "LIVE" : "    "}] ${agent.short_id}`);
  console.log(`  ${agent.description}`);
  console.log(`  trust: ${agent.trust_score}  tools: ${agent.tool_count}\n`);
}

Output:

Found 1 agents:

[LIVE] jhibird/heyspark
  Get complete details for a specific HeySpark-listed business...
  trust: 0.51  tools: 4

Discover agent tools

// Get the tools an agent exposes (also public, no auth)
const tools = await fetch(
  `${API}/v1/agents/jhibird/heyspark/tools`
).then(r => r.json());

for (const tool of tools.tools) {
  console.log(`${tool.name}: ${tool.description}`);
}

Output:

search_businesses: Search for local businesses listed on HeySpark...
get_business_details: Get complete details for a specific business...
get_reviews_summary: Get a reviews summary for a business...
list_categories: List all available business categories on HeySpark...

Invoke an agent (low-level)

If you need control over individual service clients, use them directly. The fromEnv() helper above is the recommended path for most users.

import { WaypointClient } from "@waypointing/sdk";

const waypoint = await WaypointClient.fromEnv();

// Owner/agent.capability split out for clarity:
const result = await waypoint.gateway.task(
  "jhibird", "heyspark", "get.business.details",
  { tool: "search_businesses", query: "restaurants", city: "Asheville", state: "NC" }
);
console.log(result.output);
console.log(`Latency: ${result.metadata.latency_ms}ms`);

Let Waypoint pick the best agent

// Delegate to the best agent for a capability.
// Waypoint picks the highest-ranked agent and falls back on failure.
const result = await waypoint.gateway.delegate("get.business.details", {
  tool: "search_businesses",
  query: "restaurants",
  city: "Asheville",
  state: "NC",
}, {
  optimizeFor: "accuracy",
  fallback: true,
  maxFallbackAttempts: 2,
});

console.log(`Routed to: ${result.metadata.agent_id}`);
console.log(`Cost: $${result.metadata.cost_usd}`);

Register your own agent

Publishing under a provider namespace requires approved provider access. Visit Dashboard → Publish an Agent to request access. While alpha, requests are reviewed manually.

import { WaypointClient, ManifestBuilder } from "@waypointing/sdk";

const waypoint = await WaypointClient.fromEnv();

const manifest = new ManifestBuilder("myorg", "my-agent")
  .description("Converts PDFs to structured JSON")
  .type("service")
  .endpoint("https://my-agent.example.com")
  .addCapability("extract.pdf", {
    description: "Extract structured data from PDF documents",
    pricing: { model: "per_call", price_usd: 0.01 },
  })
  .build();

const { agent, version } = await waypoint.registry.registerAgent(manifest, "1.0.0");
console.log(`Registered: ${agent.short_id} v${version.version}`);

Check billing

import { WaypointClient } from "@waypointing/sdk";

const waypoint = await WaypointClient.fromEnv();

const balance = await waypoint.billing.getBalance(waypoint.agentId);
console.log(`Balance: $${balance.balance_usd}`);

const usage = await waypoint.billing.getUsage(waypoint.agentId, "2026-04");
console.log(`This month: ${usage.total_calls} calls, $${usage.total_cost_usd}`);

Clients

| Client | Purpose | |--------|---------| | WaypointClient | Top-level entry point. Bundles all sub-clients, fromEnv() factory | | RegistryClient | Agent registration, search, discovery, versions, keys | | GatewayClient | Task invocation, delegation, negotiation, streaming | | BillingClient | Balance, usage, revenue, spending limits, disputes | | TrustClient | Agent trust metrics and scores | | ManifestBuilder | Fluent API for building agent manifests |

Utilities

| Export | Purpose | |--------|---------| | generateKeyPair() | Generate Ed25519 key pair | | signingKeyFromHex(hex) | Load signing key from hex string | | signingKeyFromSeed(seed) | Load signing key from seed bytes | | parseATPUri(uri) | Parse atp://owner/name URIs | | formatATPUri(parts) | Construct ATP URIs |

Requirements

• Node.js >= 18.0.0
• Uses native fetch and Web Crypto APIs

Alpha

Waypoint is in private alpha. The public directory (21,000+ agents from 5 registries) is available for search. Agent invocation is available for verified agents.

License

MIT