@pathcourse/sdk

Official JavaScript SDK for the PathCourse Health AI gateway.

Official JavaScript SDK for the PCH AI gateway. Autonomous API key provisioning, pay-per-inference billing in USDC on Base L2, and agent certification—no human signup required.

Install

npm install @pathcourse/sdk

How PathCourse works (in 30 seconds)

PathCourse is built for autonomous agents. You don't sign up. There's no dashboard. You fund an on-chain wallet, claim an API key, and make inference calls — all programmatically.

1. Your agent has (or creates) a Base L2 wallet holding at least 25 USDC.
2. You send that USDC to the PCH treasury wallet.
3. You call claimKey({ txHash, wallet }) to retrieve your API key.
4. You construct new PathCourseClient({ apiKey }) and make inference calls.
5. Balance is deducted per request. Check it any time with client.getBalance().

No credit card. No KYC. No human in the loop.

First-time setup — get an API key

Requirements: a Base L2 wallet and at least 25 USDC in it. Treasury wallet address is published at gateway.pathcoursehealth.com/.well-known/agent.json under payment.treasury_wallet.

import { claimKey, PathCourseClient } from '@pathcourse/sdk';

// Step 1: You've already sent >= 25 USDC to the PCH treasury wallet on Base.
//         Capture the tx_hash and the wallet address you sent from.

// Step 2: Claim your API key. Polls up to ~3 minutes while the deposit
//         confirms and your account provisions.
const result = await claimKey({
  txHash: '0xYourDepositTxHash',
  wallet: '0xYourSendingWallet',
});

console.log(result.api_key);      // pch_prod_b_...
console.log(result.tier);         // uncertified | bronze | silver | gold
console.log(result.balance_usdc); // e.g. "25.00000000"

// Store result.api_key securely. It won't be shown again via this endpoint.

Set the key as an environment variable for future runs:

export PCH_API_KEY="pch_prod_b_..."

Quick Start (once you have a key)

import { PathCourseClient, PCH_FAST } from '@pathcourse/sdk';

const client = new PathCourseClient();  // reads PCH_API_KEY from env
await client.verifyKey();                // confirms the key works (cheap, no billing)

const response = await client.chat({
  model: PCH_FAST,
  messages: [{ role: 'user', content: 'Explain x402 micropayments in one paragraph.' }],
});
console.log(response.text);

One-call self-profile

// Everything a headless agent needs to know about itself in one request
const me = await client.me();
console.log(me.tier, me.balance.balance_usdc, me.reputation.path_score);
console.log(me.models_available);   // models this tier can actually call

Let the gateway pick the model

const hint = await client.suggestModel({
  messages: [{ role: 'user', content: 'Refactor this function and explain the trade-offs' }],
  maxTokens: 2000,
});
// { recommended_model: 'pch-coder', complexity: 0.52, alternatives: [...] }

Embeddings, translation, rerank

const emb = await client.embed({ input: 'The quick brown fox jumps over the lazy dog.' });
console.log(emb.embeddings[0].length); // embedding dimension

const fr = await client.translate({ text: 'Hello world', targetLanguage: 'fr' });
console.log(fr.translated_text);       // "Bonjour le monde"

const ranked = await client.rerank({
  query: 'how does x402 work?',
  documents: ['USDC is a stablecoin...', 'x402 is an HTTP status code...', 'Base is an L2...'],
  topN: 2,
});

Account controls

// Current balance + top-up instructions
const bal = await client.getBalance();
console.log(bal.balance_usdc, bal.low_balance);

// Spend history from the on-chain ledger
const usage = await client.getUsage({ limit: 20 });
console.log(usage.summary.total_spend_usdc);

// Days of service at current burn rate
const runway = await client.getRunway();
console.log(runway.runway_days, runway.status);

// Server-side daily spend cap (resets at UTC midnight; pass 0 to remove)
await client.setBudget({ dailyLimitUsdc: 10.00 });

// Webhook alerts when balance drops below threshold
await client.registerWebhook({
  url: 'https://my-agent.example.com/pch-events',
  thresholdUsdc: 25.00,
});

Models

| Constant | Model | Use Case | Price | |---|---|---|---| | PCH_FAST | pch-fast | Fast reasoning, classification, routing | $0.44/M tokens | | PCH_PRO | pch-pro | Deep reasoning, multi-step planning | $1.96/M tokens | | PCH_CODER | pch-coder | Code generation, debugging | $3.50/M tokens | | PCH_IMAGE | pch-image | Text-to-image generation | $0.028/image | | PCH_AUDIO | pch-audio | Text-to-speech (standard) | $1.85/M chars | | PCH_AUDIO_PREMIUM | pch-audio-premium | Text-to-speech (premium) | $37.00/M chars | | PCH_DOCUMENTS | pch-documents | Document parsing, OCR | $0.26 in / $1.48 out per M tokens | | PCH_TALK | pch-talk | Voice conversation | $0.001/min | | CLAUDE_HAIKU | claude-haiku | Third-party (Silver+) | Common rate | | CLAUDE_SONNET | claude-sonnet | Third-party (Gold) | Common rate | | PCH_EMBED | pch-embed | Text embeddings | $0.015/M tokens | | PCH_TRANSCRIBE | pch-transcribe | Speech-to-text | $0.0008/min | | PCH_TRANSLATE | pch-translate | Translation | $0.08/M chars | | PCH_EXTRACT | pch-extract | Zero-shot entity extraction | $0.012/M tokens | | PCH_RERANK | pch-rerank | Retrieval reranking | $0.025/M tokens |

Machine-readable rate sheet: gateway.pathcoursehealth.com/v1/pricing.

Call client.getModels({ scope: 'my_tier' }) to list only the models your current tier can access.

Additional capabilities

Every PCH API key unlocks four more capabilities beyond inference. Full working examples in pch-integration-examples.

• client.memory — persistent embedding store with semantic retrieval (store, retrieve, update, forget, summarize, namespaces)
• client.reputation — on-chain-compatible agent identity + Path Score (score, check, history, erc8004)
• client.obs — trace/span lifecycle, anomalies, analytics, cost attribution (traceStart, traceEnd, analytics, costAttribution)
• client.routing — agent discovery + registration (find, register, heartbeat, available)

Environment variables

• PCH_API_KEY — your PathCourse API key
• PCH_BASE_URL — override gateway URL (default: https://gateway.pathcoursehealth.com)

Error handling

import {
  PathCourseClient,
  InsufficientBalanceError, AuthenticationError,
  ModelNotInTierError, InferenceUnavailableError,
} from '@pathcourse/sdk';

const client = new PathCourseClient();

try {
  await client.chat({ model: 'pch-pro', messages: [{ role: 'user', content: 'hi' }] });
} catch (err) {
  if (err instanceof InsufficientBalanceError) {
    // balance hit the $10 floor — top up via the treasury_wallet
  } else if (err instanceof AuthenticationError) {
    // key is invalid or the service is suspended
  } else if (err instanceof ModelNotInTierError) {
    // this tier can't access the requested model — upgrade cert or pick another
  } else {
    throw err;
  }
}

Settlement

All billing is in USDC on Base L2 (chain_id 8453) via the x402 payment protocol. USDC contract: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913. No accounts, no credit cards, no KYC.

Links

• PathCourse Platform
• Agent Card (A2A discovery)
• Live rate sheet
• Model listing (OpenAI-compatible)
• GitHub