@ysaere/sdk

Typed TypeScript client for the Ysaere /v1 API — multi-agent research swarms for deal teams.

Every report ships with a Trust Receipt: a signed record with a public verify link.

A receipt attests that a report is unaltered and traces to its sources. It does not attest that every claim is fact.

npm install @ysaere/sdk

Requires Node 20+. ESM only — use import, not require.

Quick start

import { YsaereClient } from '@ysaere/sdk';

const client = YsaereClient.fromEnv(); // reads YSAERE_API_KEY

const balance = await client.getBalance();

const { run, offering } = await client.run('angel', 'Acme Robotics', {
  domain: 'acme.example',
});
console.log(`${offering.label} queued — ${offering.credits} credits`);

const report = await client.waitForReport(run.run_id);
const provenance = await client.getProvenance(run.run_id);

Get a key at app.ysaere.com — new accounts start with 150 free credits. No card required.

Configuration

Env var	Default	Notes
YSAERE_API_KEY	—	Required. ysa_prod_*
YSAERE_API_URL	https://api.ysaere.com	Must be https:// unless loopback
YSAERE_ALLOW_SANDBOX	off	Set to 1 to permit ysa_test_* keys (mock runs, no credits)
YSAERE_ALLOW_INSECURE_BASE_URL	off	Escape hatch for a local dev server over http://

Or construct directly:

const client = new YsaereClient({
  apiKey: process.env.YSAERE_API_KEY!,
  requestTimeoutMs: 30_000,
  maxRetries: 3,
});

The client refuses to send your API key over plain HTTP to a non-loopback host. The key travels in the Authorization header, so http:// to an arbitrary host would hand a live credential to that host.

Offerings

Alias	Credits	Report
classify / entity-classify	10	Entity Classify (sync)
quick-brief / brief	20	Quick Brief (sync)
sourced-brief / evidence-brief	40	Sourced Brief (sync)
vault-search	5	Vault Search (sync)
ci / company / competitive	100	Company Intelligence
market	150	Market Intelligence
angel	50	Angel Intelligence
angel-deep	90	Angel Deep
dd / due-diligence	200	Due Diligence
security	75	Security Assessment
retail	25	Retail Insights
retail-deep	75	Retail Insights Deep Dive

resolveOffering(alias) returns the path and credit cost; OFFERINGS is the full table. Call client.getPricing() for the live catalog — the authoritative source, since local constants can drift.

Retries and timeouts

Every request has a 30s timeout by default. Transient failures (429, 5xx, network errors) are retried with exponential backoff and full jitter, honoring Retry-After.

Only requests that cannot double-charge are retried: GETs, plus POSTs carrying an Idempotency-Key. A bare POST starts a paid run and is never replayed.

await client.raw('POST', '/v1/intel/angel-report', { target: 'Acme' }, {
  'Idempotency-Key': crypto.randomUUID(),
});

Errors

import { YsaereApiError, YsaereConfigError, YsaereTimeoutError } from '@ysaere/sdk';

try {
  await client.run('dd', 'Acme');
} catch (err) {
  if (err instanceof YsaereApiError && err.status === 402) {
    // insufficient credits — err.body carries balance, required, topup_url
  }
}

YsaereApiError.body carries the parsed response body. YsaereTimeoutError is a client-side deadline, distinct from any HTTP response.

x402 machine payments

For autonomous agents paying per call. You supply the signer — the SDK never custodies keys.

import { requestWithX402Pay } from '@ysaere/sdk';

const report = await requestWithX402Pay(
  (headers) => client.raw('POST', '/v1/intel/angel-report', { target: 'Acme' }, headers),
  {
    signer,
    maxAmount: 250_000n,                       // required — hard ceiling, in the challenge's base units
    expectedPayTo: '0xYourPinnedRecipient',    // required — the address you expect to pay
    expectedNetwork: 'base',                   // optional but recommended
    expectedResource: '/v1/intel/angel-report',
  },
);

maxAmount and expectedPayTo are required. A 402 body is attacker-influenceable input: without a ceiling it can ask your signer to authorize any amount, and without a pinned recipient it can send that amount anywhere. Every check fails closed — a challenge that omits a field is rejected, never waved through. Undated challenges are refused (they are replayable) unless you set allowMissingExpiry, and expectedResource binds the payment to the thing being bought.

Also available

REST (https://api.ysaere.com/v1/openapi.json) · CLI (@ysaere/cli) · MCP server (https://mcp.ysaere.com/mcp) · Builders hub

Disclaimer

Ysaere is in beta. Outputs are AI-generated for informational purposes only. They are not investment, legal, tax, accounting, real-estate appraisal, security-assessment, or other professional advice. Trust Receipts attest to the integrity of an output (that it is unaltered), not to the truth or accuracy of any statement. Independently check every factual claim against primary sources before acting.

MIT © Ysaere, Inc.