<!-- x-generated: Generated by the Hyperscale artifact pipeline; do not edit by hand -->

# Hyperscale Quickstart

> Make the first authenticated call against one frozen Product Build. Generated from the Hyperscale contract. Every command and code sample below comes from the current contract.

Hyperscale is an agent-native fintech infrastructure control plane. Founders and agents compose companies in HSX, then operate the resulting Product through CLI, hosted MCP, generated SDKs, or direct API calls. This guide provisions access, makes a first read call, and explains the separate activation path.

Hyperscale is not a bank or money handler. No tenant is live, neither [hosted estate](https://hyperscale0.ai/glossary#estate) is production, and no real bank connection exists.

## Provisioning in the portal

SDK calls need a product-scoped Hyperscale credential, and install alone is not enough. These setup steps run in the Hyperscale portal, not through the product SDK. Do them once, then every code sample below is a real SDK call:

1. Request access at https://hyperscale0.ai/request-access.
2. Create the Product through Composer authoring, compose a Blueprint from the catalog, or provision horizontal primitives directly.
3. Mint a sandbox API key for that Product from its Developers desk and copy its secret.
4. Download the Hyperscale Kit for that Product from the same Developers desk; the Kit unpacks to a directory carrying the generated SDK packages under sdks/.
5. Install the generated TypeScript SDK. Run this from inside the unpacked Kit directory (sdks/typescript is a Kit-relative path; the copy committed in this repository is source-review only):

```bash
npm install ./sdks/typescript
```

Every snippet below imports from `@hyperscale/tenant-sdk-your-capabilities`, which stands in for your own package name: the Kit names its TypeScript package after your Product's capabilities. Your exact name is the `name` field of `sdks/typescript/package.json` in the unpacked Kit, and an authenticated `GET /v1/llms.txt` returns it for the hosted copy of the same package.

6. Export the key so the SDK samples below can read it:

```bash
export HYPERSCALE_API_KEY=hyperscale_...
```

The sample IDs below are setup-owned sandbox IDs. Replace them with the Product, product, customer, trust review, and evidence IDs returned by your Hyperscale setup.

Live calls require the same Product promoted and a live API key minted for the live environment.

## Your first call

Start with the read `account.list`. List Accounts The generated TypeScript SDK call is:

```ts
import { createHyperscale } from "@hyperscale/tenant-sdk-your-capabilities";

const hyperscale = createHyperscale({
  environment: "sandbox",
  auth: () => process.env.HYPERSCALE_API_KEY ?? "",
});

// Replace sample IDs with IDs returned by your Hyperscale setup.

const result = await hyperscale.operations.accountList({});
```

The client reads your key from the environment variable set above and targets the sandbox environment; the call reads data and changes nothing.

## Receive webhooks

Create a webhook endpoint with `webhook.endpoint.create` and store the returned `whsec_` signing secret in your secret manager: it is surfaced exactly once in the create response. `webhook.endpoint.secret.rotate` mints a replacement the same way and keeps the prior secret verifying for a short overlap window.

Every delivery is an HTTP `POST` with an `application/json` body and three headers:

- `webhook-id`: the immutable event/message identifier and consumer idempotency key. It matches the JSON body's `id` and remains unchanged across automatic retries, manual resends, expired-lease reclaim, and endpoint recovery. It is not `webhookDeliveryId`, which identifies one delivery attempt for list and resend APIs.
- `webhook-timestamp`: Unix seconds at send time.
- `webhook-signature`: one or more space-separated `v1,<base64>` entries. Each entry is an HMAC-SHA256 keyed with the base64-decoded portion of a `whsec_` secret (the bytes after the `whsec_` prefix, per the Standard Webhooks spec), computed over the UTF-8 string `<webhook-id>.<webhook-timestamp>.` followed by the raw request body bytes. During a secret rotation the previous secret co-signs until it expires, so a delivery can carry more than one entry.

Verify before you parse: recompute the signature over the RAW body bytes, compare in constant time, accept the delivery if ANY entry matches ANY of your secrets, and reject timestamps more than 300 seconds from your clock (the replay guard). The generated SDK packages in the downloaded Hyperscale Kit export `verifyWebhook` with these defaults. The Kit also ships a standalone copy at `testing/webhook-verifier.ts`. Use either instead of writing another verifier.

Delivery and retry policy:

- Requests time out after 10s; only a 2xx response counts as delivered. Redirects are never followed.
- A failed delivery retries on a fixed backoff of 1m, 5m, 30m, 2h, 6h, 24h, 72h after successive failures, for 8 attempts in total. The worker then marks the delivery `exhausted`. `webhook.delivery.resend` queues a fresh attempt for any prior delivery.
- Deliveries go only to public hosts: internal and loopback targets are refused by the egress guard (loopback is allowed only against a local development sandbox, never live).

## Take a Product live

Everything above ran in the sandbox. Live access is underwritten, not toggled. You open a trust review, the platform reviews it, and only an approved review carries a product capability into live use. `trust_review.create`, `trust_evidence.attach`, and `trust_review.submit` happen in the portal's Go-Live flow because they have no SDK route; `trust_requirement.list` and `trust_requirement.respond` run over the SDK:

1. `trust_review.create`. Create a trust review declare who you are (business identity) and how money will flow (money-flow model). The platform underwrites this concrete story; every later step cites the returned `trustReviewId`.
2. `trust_evidence.attach`. Attach trust evidence upload supporting documents before anyone asks. Evidence lands in pending review and satisfies nothing by itself; keep the returned `trustEvidenceId`. Your requirement responses cite it.
3. `trust_review.submit`. Submit a trust review hand the review to platform review. From here the review is read-only for you; the dialogue continues through requirements.
4. The platform raises requirements: during review it records named requirements against your review (`trust_requirement.record`, platform-side). Submission starts the underwriting dialogue; it does not finish it.
5. `trust_requirement.list`. List Trust Review requirements watch the review for open requirements; each names the proof the platform needs before it can approve.
6. `trust_requirement.respond`. Respond to a trust requirement answer an open requirement by citing attached evidence, free text, or both; the requirement advances toward `satisfied` pending review.

Responding to an open requirement cites the evidence you attached earlier:

```ts
import { createHyperscale } from "@hyperscale/tenant-sdk-your-capabilities";

const hyperscale = createHyperscale({
  environment: "sandbox",
  auth: () => process.env.HYPERSCALE_API_KEY ?? "",
});

// Replace sample IDs with IDs returned by your Hyperscale setup.

const result = await hyperscale.operations.trustRequirementRespond({
  path: {
    trustRequirementId: "vreq_sandbox_bankletter01",
  },
  body: {
    trustReviewId: "vcs_sandbox_livekyb001",
    trustEvidenceId: "vev_sandbox_wathq0001",
    response: "Bank letter uploaded for review.",
    metadata: {
      channel: "product",
    },
  },
});
```

Approval is the platform's decision, not an API call you make: `trust_review.approve` records the terminal decision platform-side, and `product.promote` on the approved review carries every product capability into live use in one stroke. Live traffic still needs the product promoted and a live API key, as the provisioning section above notes. Every call in this journey ships as a worked request/response pair in [Examples](examples.md).

## Where to go next

- [Language](language.md): the HSX reserved words, the declaration forms the parser accepts, and the UDL clause vocabulary.
- [Full index](../llms.txt): every instrument page, Product page, and money flow, each with a one-line description.
- [Examples](examples.md): worked request examples rendered as SDK calls.
- [Errors](errors.md): the error catalog with retry and idempotency guidance.
- [Plans](plans.md): the one plan, complexity-priced fees, the published usage rate card, and earn-rate fee legs.
- [Blueprints](blueprints.md): ready-made company shapes composed from the catalog in the portal; primitives Products provision capabilities directly.
- [SDK packages](sdks.md): install commands and READMEs for every generated language SDK.
- [MCP](mcp.md): connect an agent to the Product's MCP tools, including model-safe mutations with idempotency and confirmation fields.
- CLI: install `@hyperscale0/cli`, then run `hyperscale compose check`, `hyperscale compose plan`, and `hyperscale compose apply` for an HSX program.