# Ysaere

> Prepaid multi-agent intelligence over REST and MCP. Async run → poll → provenance receipt (integrity, not verified fact). Five MCP status tools are free; intelligence runs debit credits.

Ysaere is Intelligence-as-a-Service for agents and humans: Company Intelligence, Angel screening, Market Intelligence, Due Diligence, CRE Deal Intelligence, Security Assessment, Retail Insights, and marketplace agents. Every paid report can ship with a Trust Receipt (pipeline integrity — not factual truth).

## Start here (machines)

- [MCP endpoint](https://mcp.ysaere.com/mcp): Streamable HTTP MCP — `Authorization: Bearer ysa_prod_*` or OAuth 2.1
- [MCP discovery](https://ysaere.com/.well-known/mcp.json): machine-readable MCP pointer
- [OAuth metadata](https://mcp.ysaere.com/.well-known/oauth-protected-resource): RFC 9728 protected-resource metadata
- [OpenAPI](https://api.ysaere.com/v1/openapi.json): REST `/v1` contract
- [Live catalog](https://api.ysaere.com/v1/pricing): authoritative SKU + credit list (free, unauthenticated)
- [Builders hub](https://ysaere.com/builders/): REST · CLI · TypeScript SDK · Python SDK · MCP doors
- [MCP human docs](https://ysaere.com/mcp/): connector setup (Claude / Cursor)
- [API / MCP terms](https://app.ysaere.com/legal/api-terms): machine-access terms
- [Credit top-up](https://app.ysaere.com/account/usage): Stripe prepaid credits (sole mint path)
- [Trust verify](https://app.ysaere.com/verify): public provenance verify

## Auth

**One header, both surfaces.** MCP and REST `/v1` accept exactly one credential header:

    Authorization: Bearer ysa_prod_...

An `x-api-key` header is **not** read on either surface and will return HTTP 401. Every
MCP request must carry the header — including requests on an already-established
`mcp-session-id`. There is no anonymous tool access.

- Production API keys: `ysa_prod_*`
- Sandbox keys: `ysa_test_*` — mock responses, no credits (may require opt-in env)
- OAuth 2.1 access tokens: `ysa_oa_*` — PKCE (S256) for host connectors. Dynamic client
  registration (RFC 7591) supported; static Client ID `claude.ai` also accepted. Access
  tokens may rotate mid-session; the server re-binds the session to the same principal.
- Signup: https://app.ysaere.com/auth/register — **150 free credits** on email-verified
  signup, no card. That is one Company Intelligence (100) or one Angel Intelligence (50)
  plus change, or 30 Vault Searches.

## Free (0-credit) surface

These never debit and are the right way to explore before spending:

| Surface | What is free |
|---|---|
| `GET /v1/pricing` | Live SKU + credit catalog. No auth required. |
| `GET /v1/openapi.json` | Full REST contract. No auth required. |
| MCP `estimate_credits` | Price any tool or endpoint before running it. |
| MCP `check_balance` | Current balance, lifetime spend, `mcp_enabled`. |
| MCP `check_report_status` | Poll a run and retrieve the finished report. |
| MCP `wait_for_report` | Block until a run reaches a terminal state. |
| MCP `verify_provenance` | Fetch a report's provenance chain for independent verification. |

The five MCP tools require a credential (any valid key or token) but cost 0 credits.

## Canonical agent loop

1. Discover (this file · `.well-known/mcp.json` · OpenAPI · `GET /v1/pricing`)
2. Auth (`Authorization: Bearer ysa_prod_*` or OAuth)
3. Optional: `check_balance` (MCP) or `GET /v1/account/balance` (REST) — 0 credits
4. Estimate: `POST /v1/intel/estimate` or MCP `estimate_credits` — 0 credits
5. Run: `POST /v1/intel/*` or an MCP intel tool → immediate `run_id` (swarm) or payload (sync)
6. Wait: MCP `wait_for_report` or poll `GET /v1/reports/{run_id}` / `check_report_status`
7. Receipt: verify provenance (integrity ≠ truth)
8. Budget: on HTTP 402 read `required`, `balance`, `topup_url`

Optional request header on debiting POSTs: `Idempotency-Key` (replay-safe retries).
Public examples: https://ysaere.com/builders/examples/ (estimate · run · wait · webhooks · skill opener).

## Credit costs (prepaid, $0.10/credit)

| Offering | Credits | Endpoint | Mode |
|---|---|---|---|
| Vault Search | 5 | /v1/intel/vault-search | sync |
| Entity Classify | 10 | /v1/intel/classify | sync |
| Quick Brief | 20 | /v1/intel/quick-brief | sync |
| Retail Insights | 25 | /v1/intel/retail-insights | swarm |
| Sourced Brief | 40 | /v1/intel/sourced-brief | sync |
| Angel Intelligence | 50 | /v1/intel/angel-report | swarm |
| Security Assessment | 75 | /v1/intel/security-scan | swarm |
| Retail Insights Deep Dive | 75 | /v1/intel/retail-insights-deep | swarm |
| Angel Deep | 90 | /v1/intel/angel-deep-report | swarm |
| Company Intelligence (CI) | 100 | /v1/intel/ci-report | swarm |
| Trust Check | 100 | /v1/intel/trust-check | swarm |
| Market Intelligence | 150 | /v1/intel/market-report | swarm |
| Due Diligence | 200 | /v1/intel/dd-report | swarm |
| CRE / Net-Lease / Multifamily / Self-Storage | 250 | /v1/intel/cre/* | swarm |

Sync SKUs return the payload in one response with no `run_id`. Swarm SKUs enqueue a
run — poll `/v1/runs/{run_id}` or use a webhook. `GET /v1/pricing` is the live catalog
and the authoritative source; the table above can lag it.

Trust Check and the CRE briefs run over REST, the CLI and the SDKs. They are not on the
default MCP tool list.

## Official clients

- TypeScript: `npm install @ysaere/sdk` — https://github.com/ysaere/sdk
- CLI: `npm install -g @ysaere/cli` — https://github.com/ysaere/cli
- Python: `pip install ysaere` — https://github.com/ysaere/sdk-python

All MIT, published from GitHub Actions with signed build provenance (npm attestations,
PyPI trusted publishing). Discovery and OpenAPI fetch are free. Intelligence runs debit
credits. Stripe checkout is the only credit mint path.

## Product pages (human)

- [Home](https://ysaere.com/)
- [Company Intelligence](https://ysaere.com/ci/)
- [Market Intelligence](https://ysaere.com/mi/)
- [Angel](https://ysaere.com/angel/)
- [Angel Deep](https://ysaere.com/angel-deep/)
- [Due Diligence](https://ysaere.com/dd/)
- [CRE](https://ysaere.com/cre/)
- [Marketplace](https://ysaere.com/marketplace/)
- [Trust](https://ysaere.com/trust/)

## Optional

- [ai-plugin.json](https://ysaere.com/.well-known/ai-plugin.json): legacy plugin-style discovery
- App: https://app.ysaere.com
- Contact: developers@ysaere.com