Product runtime

How Hyperscale fits

Hyperscale keeps the books and runs a company's Products. Providers hold the regulated money and make the lending, underwriting, credit, rating and claims decisions. Hyperscale never lends or holds funds.

Money moves once: each instruction has a durable identity and consumes provider evidence once. Every move conserves money within its book. A Build binds its providers; no scheduler picks one per move. Sandbox adapters report fixture outcomes, not real origination or custody.

Discover operations

Operations["product.objects.create"] in the SDK gives input, output, error and errorCode; SharedErrorCode lists the codes every operation shares. The types do not validate network data, so treat an unknown error as an unknown outcome. The SDK retries reads, and retries a write only under an idempotency key, which it makes when you pass none.

The HTTP API page owns the base URL, environments, idempotency, the error envelope, pagination and rate limits.

Who may call what

OpenAPI marks each operation with the credential it takes.

An agent calls only what its grant and the agent policy admit, and each call also checks the delegating person's current permissions. Sandbox work inside the grant runs at once; live work waits for browser approval. Sign in covers grants, approval and agent setup; access covers Product scope from the agent's side.

MCP results have their own shape:

A mutation tool takes idempotencyKey; send one to keep control of retries. rehearse: true runs it with no effect and answers the rehearsal as output, with null operationId and receiptId. A tool that needs confirmation advertises the exact value in its schema. No MCP tool returns a credential except the webhook signing secret: key_create and api_key_sandbox_create answer with hyperscale key create --product <productId> --name <name>, and live keys come only from the founder with hyperscale key create-live.

List shapes

Lists page with cursor and nextCursor as the HTTP API page says. Read each operation's schema for its limit and default. Most lists return items; these do not:

Product objects and actions

A Build defines object kinds, their metadata, attachments and public actions. Creating an object stores metadata only: it opens no agreement and moves no money.

The same steps from the CLI, with a Product key in HYPERSCALE_API_KEY:

hyperscale object kinds
hyperscale object create <kind> --fields-file fields.json
hyperscale object actions <kind> <object-id>
hyperscale object run <kind> <object-id> <action> --input-file input.json

The CLI takes and prints money in major units; REST and MCP take minor-unit strings. HSX money has the table.

Calling an action. kind, objectId and action are enough. Execute and preview fill in expectedRevision, productBuildId, digest and target from the record when you leave them out, and check them when you send them. The CLI's --attachment and --instance pick between agreements that offer the same action. api call reaches every other published route.

Acting for a customer. An object a Product key creates without onBehalfOf belongs to the Product, and money the Product pays itself is never an earning. When a customer pays, create the object and run the payer's steps with onBehalfOf naming that customer. A Product key, a member with desk.products.objects_write, or an agent inside its grant may send onBehalfOf on product.objects.create, actions, execute and preview. The call uses the customer's accounts, keeps the operator's view of records and records both identities.

Money and commits. An action checks input, authority and requirements, then commits its intent; ledger effects follow with durable recovery. A refused admission moves nothing; an uncertain outcome is not a refusal. The acting party pays from its cash account, which for a Product key is the Product pool, so fund the pool before the first money action. A completed action lists its transfers in outcome.moves, each with transferId, amount and accounts. Object schemas and action availability come from runtime discovery, never from the SDK. Admission counts each action's worst case, its own transfers plus every action it invokes, and refuses a Product create, compose or recompose with an action over 253 as execution_budget_exceeded, naming the action and its count. Std lending blocks end a payoff, default or refinance in one transfer per party and money purpose, and walk long lists in batches across clock steps, so a 360-month mortgage stays under the limit.

Customers and sandbox money

A customer belongs to one company and enrols in one Product. customer.create (POST /v1/customers) takes { productId, entity: { kind, displayName, country } }. A new customer's entity and access start pending, and money stays refused until a legal profile clears. In sandbox, test: true fills a fake profile and activates access in the same call; live refuses test. A test customer runs no identity check, so reads show entityStatus not_checked and identity test.

A customer can also customer.signup and customer.login for a session token. Sign-up needs a browser challenge, so a script acts for a customer with its Product key and onBehalfOf.

Your own app signs its customers up and in. It calls customer.signup (POST /v1/customer-identity/signup) or customer.login (POST /v1/customer-identity/login) with the productId, and gets back sessionToken and sessionExpiresAt. Signup leaves the entity and the enrolment pending: no account opens and no money moves until the entity clears and access is active. The session belongs to that Product. Send it as Authorization: Bearer on the customer's own calls, honour its expiry, and end it with customer.logout (POST /v1/customer-identity/logout).

Every sandbox account starts at zero. sandbox.account.fund (POST /v1/sandbox/account-funding) takes { destinationAccountId, amount, currency }, with amount in minor units: "10000" is SAR 100.00. A Product key or a session with transfer:write calls it, never in live. The key names the company, so a key call that also sends tenantId gets invalid_request. The console's Add test money button and the CLI's fund call it in major units.

hyperscale customer create "Noura Alharbi" --test
hyperscale account open <customer-id>
hyperscale fund <account-id> 500

account.deposit (POST /v1/account-deposits) takes { destinationAccountId, adapter, amount, currency } and runs in sandbox and live. The adapter delivers the deposit and returns its credit reference as bankReference, and the account is credited from the company's bank mirror, so the finance report stays complete. The fixture_bank adapter moves fake money. In live it answers only on an estate that sets HYPERSCALE_LIVE_MONEY=fixture; otherwise the call gets capability_not_configured.

Both calls store the bank's credit as a provider fact on the transfer: provider fixture_bank, reference credit:<transferId>, with the amount and value date. A bank statement that lists the top-up then matches it, by that reference or by amount and value date, so a sandbox company rehearses reconciliation against its own funding.

Sandbox clock

Each sandbox Product has its own clock. sandbox.clock.advance (POST /v1/sandbox/clock/advance, CLI hyperscale clock advance 3d) moves it forward to at; release: true (hyperscale clock reset) returns it to wall time from any point. Records stamped while the clock ran ahead keep their stamps.

What an advance does. It runs every clock action due by at before it answers, and lists them in ran: instrument, action, objectId, instanceId, dueAt, amount for money, status, and reason when refused. Each piece's transfer carries its own dueAt as its value date, and one transaction packs one calendar month (UTC), so a two-month jump files each month's dues in that month, in the books, activity and statements. A piece that waited on an acceptance or another write to its own agreement posts at that write; a write to another agreement never moves it. A retried charge posts at the Product clock.

In live, and on a sandbox Product whose clock reads wall time, a piece runs within a minute of its dueAt with no request.

Refused clock work. A refusal is either retryable or lasting.

Before a caller's action runs, the Product's due clock work runs. If that work cannot finish, the action returns 409 state_conflict with details.reason clock_work_pending and changes nothing: either 8 scheduled updates were refused in that request and each is now set aside with its reason, or the Product is further behind than one request catches up. Retry: each attempt runs more of the due work.

Piece states in schedule list.

A start date written as today's date, such as startsAt: "2026-10-10", means now on the Product clock, so accepting a schedule that starts today collects its first piece in the same request. work list holds only what is due or refused and waits for a person; an action with no due date, such as ending a membership, stays an option on the record. A due date on any other action only makes it runnable, and a passed deadline refuses it. work list --staff-role credit_underwriter keeps only the decisions authored for that staff role, with the customer, amount and request time, and needs a role that grants credit:underwrite.

Which time a read shows. Sandbox reads date money on the Product clock: money summary, account balance, statements, the finance report, margin, treasury and block reads, activity, the request log and object timelines. asOf, occurredAt and a statement period are Product time; a host time is observedAt (recordedAt on a log row). In live the two are the same.

Refunds and returns

refund.create (POST /v1/refunds, CLI hyperscale transfer refund) gives a posted payment into a Product's pool back to the account that paid it, over the same two accounts. It takes { tenantId, paymentTransferId }, an optional amount in minor units for part of it, and an optional reason: duplicate, fraudulent or requested_by_customer. A founder session calls it; a Product key and a personal access token cannot. A full refund first gives back the earn-rate fees the Product took; a partial one keeps them.

hyperscale transfer refund --payment-transfer-id <transfer-id> --amount 25

transfer_return.create opens a return and moves no money until it completes. waitsFor says what completes it: sandbox_clock_advance in sandbox, where the next advance or the minute sweep completes every open return, and provider_settlement in live. A transfer with a refund or reversal takes no return.

Team invitations and API keys

These are company operations for people signed in to the portals, so /openapi.json, which lists the Product API and the routes a CLI login or agent token calls, does not list them. Reach them with the CLI (hyperscale key list), MCP or a browser session.

• team.member.list returns { teamId, members, nextCursor? }.
• team.invitation.list (GET /v1/team/invitations) takes { tenantId, cursor?, limit? } and returns { teamId, items, nextCursor? }. Items have invitationId, email, role, invitedByUserId, expiresAt and createdAt; only pending, unexpired invitations appear, oldest first, then by ID descending. limit is 1 to 100, default 50. The cursor binds environment, tenant and team, and a foreign one returns invalid_request. It needs the same team read permission as the member list. Neither read returns invitation tokens.
• api_key.list and api_key.retrieve items carry expiresAt and lastUsedAt, an ISO UTC time or null. A use is recorded at most once every five minutes, so a key used a minute ago can show an older time.