// sdk.md

> TypeScript SDK

// Official SDK for Node.js and browser environments.

// installation

npm install @entroute/sdk-agent-ts

// initialize (discovery only)

import { EntRouteClient } from '@entroute/sdk-agent-ts';

const client = new EntRouteClient({
  baseUrl: 'https://api.entroute.com',
});

// initialize with payments (x402 v2)

To automatically handle x402 payment challenges, provide an EVM private key or a viem WalletClient. The SDK uses @x402/fetch to transparently sign and retry 402 responses.

// Option 1: Private key (simplest)
import { createPayingClientFromKey } from '@entroute/sdk-agent-ts';

const client = createPayingClientFromKey(
  process.env.EVM_PRIVATE_KEY,
  {
    maxPaymentPerRequest: 0.05,  // max $0.05 per request
  }
);

// Option 2: viem WalletClient
import { createPayingClient } from '@entroute/sdk-agent-ts';
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';

const wallet = createWalletClient({
  account: privateKeyToAccount(process.env.EVM_PRIVATE_KEY),
  chain: base,
  transport: http(),
});

const client = createPayingClient(wallet, {
  maxPaymentPerRequest: 0.05,
});

// available methods

async discover(options)

Discover endpoints by intent or capability ID. Returns ranked and fallback endpoints.

const result = await client.discover({
  intent: 'get ETH token price',
  constraints: {
    max_price: 0.01,
    verified_only: true
  },
  preferences: {
    ranking_preset: 'reliability'
  }
});

// result.ranked_endpoints[0].url
// result.ranked_endpoints[0].payment.price_per_call
// result.resolved.capability_id

async discoverByCapability(capabilityId, options?)

Shorthand for discovering endpoints by a known capability ID.

const result = await client.discoverByCapability('defi.token_price');

async discoverByIntent(intent, options?)

Shorthand for discovering endpoints by natural language intent.

const result = await client.discoverByIntent('search the web for AI news');

async discoverAndCall(discoverOptions, callOptions?)

Discover an endpoint and call it in one step. Handles automatic retries and fallback to the next-ranked endpoint on failure. If a wallet is configured, x402 payments are handled transparently.

const result = await client.discoverAndCall({
  capability_id: 'defi.token_price'
});

console.log(result.data);       // API response
console.log(result.payment);    // payment receipt (if paid)
console.log(result.latencyMs);  // round-trip time
console.log(result.attempts);   // endpoints tried

async callEndpoint(endpoint, options)

Call a single discovered endpoint directly. Useful when you want manual control over which endpoint to call after discovery.

const discovery = await client.discover({
  capability_id: 'web.search'
});

const endpoint = discovery.ranked_endpoints[0];

const result = await client.callEndpoint(endpoint, {
  body: { query: 'AI news' },
  timeout: 15000,
  autoPay: true,
});

async listCapabilities(options?)

List all available capabilities with optional filtering.

const { capabilities } = await client.listCapabilities({
  tag: 'defi',
  search: 'token'
});

capabilities.forEach(cap => {
  console.log(cap.id, cap.title);
});

// payment handling

When a wallet is configured, the SDK automatically handles the x402 payment flow using the v2 protocol:

1. SDK calls the endpoint normally

2. Endpoint returns 402 with a PAYMENT-REQUIRED header

3. SDK signs payment via EIP-3009 (TransferWithAuthorization)

4. SDK retries the request with a PAYMENT-SIGNATURE header

5. Endpoint verifies payment and returns data

If no wallet is configured, a PaymentRequiredError is thrown with the payment challenge details.

import { PaymentRequiredError, PaymentExceedsLimitError }
  from '@entroute/sdk-agent-ts';

try {
  const result = await client.discoverAndCall({
    intent: 'get ETH price'
  });
} catch (err) {
  if (err instanceof PaymentRequiredError) {
    console.log(err.paymentChallenge.payTo);
    console.log(err.paymentChallenge.maxAmountRequired);
  }
  if (err instanceof PaymentExceedsLimitError) {
    console.log(`$${err.requestedAmount} exceeds limit`);
  }
}

// config reference

Option	Type	Default	Description
baseUrl	string	api.entroute.com	EntRoute API URL
evmPrivateKey	string	-	Hex private key (0x...) for x402 payments
wallet	WalletClient	-	viem WalletClient (alternative to evmPrivateKey)
maxPaymentPerRequest	number	0.10	Spending limit per request in USD
maxRetries	number	2	Fallback endpoint attempts
timeout	number	30000	Request timeout in ms
autoReportOutcomes	boolean	true	Report call results for ranking improvement

// constraints reference

Field	Type	Description
max_price	number	Maximum price per call in USD
network	string	Payment network (e.g. "base")
verified_only	boolean	Only return verified endpoints
ranking_preset	string	"default" \| "reliability" \| "speed" \| "budget"

MCP Server Back to Docs