@totalis/hip4-client 0.0.0-stage → 0.65.2

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# `@totalis/hip4-client`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official TypeScript SDK for [Totalis](https://totalis.trade) on Hyperliquid (HIP-4).
+
+- **Typed clients** for every REST route, generated from the API contract
+- **Taker and maker flows** that run end to end: open a position, cash out, withdraw, quote, answer acceptances
+- **A realtime stream** that resumes from its cursor and reconnects on its own
+- **Builders for every signed message** (EIP-712, USDC authorizations, the Hyperliquid bridge)
+- **Safe retries**: every command keeps one `Idempotency-Key` and is resent byte for byte, so a retry never trades twice
+
+It never holds a key. Every signature goes to the signer you pass in: a viem account or wallet client, an
+EIP-1193 provider such as `window.ethereum`, or an ethers signer. It is ESM, runs in browsers and Node 22 or
+later, and has no wallet dependency.
+
+**Documentation: [docs.totalis.trade/hyperliquid/sdk](https://docs.totalis.trade/hyperliquid/sdk)**
+
+## Install
+
+```bash
+npm install @totalis/hip4-client viem
+```
+
+`viem` is optional. The examples below use it to turn a private key into a signer.
+
+## Make a first call
+
+Create a `ttk_` API key for your account
+([Authentication](https://docs.totalis.trade/hyperliquid/authentication)), then:
+
+```ts
+import { createClient, unwrap } from "@totalis/hip4-client";
+
+const client = createClient("production", { accessToken: process.env.TOTALIS_API_KEY! });
+
+const me = unwrap(await client.GET("/v1/me"));
+console.log(me.wallet);
+```
+
+Every route in the [API reference](https://docs.totalis.trade/hyperliquid/api-reference/introduction) is on
+`client`, typed. `unwrap` returns the body or throws an `ApiError`.
+
+## Open and cash out a position
+
+```ts
+import { createTotalis } from "@totalis/hip4-client";
+import { privateKeyToAccount } from "viem/accounts";
+
+const totalis = createTotalis({
+  environment: "production",
+  accessToken: process.env.TOTALIS_API_KEY!,
+  signer: privateKeyToAccount(process.env.TOTALIS_WALLET_KEY as `0x${string}`),
+});
+
+const opened = await totalis.openPosition({
+  legs: [{ outcome_id: "13160", side: "YES" }],
+  stake: 5_000_000n, // 5 USDC
+});
+
+if (opened.operationId) {
+  const { status } = await totalis.waitForOperation(opened.operationId);
+  if (status === "COMMITTED") {
+    const sale = await totalis.cashOut({ positionId: opened.positionId });
+  }
+}
+
+totalis.close();
+```
+
+`openPosition` creates the RFQ, takes the best quote, signs the acceptance and funds any shortfall from the
+wallet. Only `COMMITTED` means the trade happened. A decided position settles and pays out on its own.
+
+## Make markets
+
+```ts
+import { createMaker, type MakerAcceptance } from "@totalis/hip4-client/maker";
+import { privateKeyToAccount } from "viem/accounts";
+
+const maker = createMaker({
+  environment: "production",
+  apiKey: process.env.TOTALIS_MAKER_KEY!,
+  makerId: process.env.TOTALIS_MAKER_ID!,
+  signer: privateKeyToAccount(process.env.TOTALIS_WALLET_KEY as `0x${string}`),
+});
+
+maker.onRfq(async (rfq) => {
+  if (rfq.kind === "ENTRY") {
+    await maker.quote(rfq, { payout: (BigInt(rfq.stake) * 18n) / 10n }); // placeholder price
+  }
+});
+
+// Re-check your price and capital before you commit. This placeholder only checks the deadline.
+const stillGood = async (acceptance: MakerAcceptance) => Date.parse(acceptance.deadline) > maker.stream.serverNow();
+
+maker.onAcceptance(async (acceptance) => ((await stillGood(acceptance)) ? "CONFIRM" : "DECLINE"));
+```
+
+Set up the maker first ([Market making](https://docs.totalis.trade/hyperliquid/guides/market-making)).
+`examples/onboard.mjs` onboards a maker headless, and `examples/node-bot.mjs` is a fuller bot.
+
+## Environments
+
+| `environment` | REST | WebSocket |
+| --- | --- | --- |
+| `"production"` | `https://hip4-api.totalis.trade` | `wss://hip4-ws.totalis.trade` |
+| `"staging"` | `https://hip4-api-staging.totalis.trade` | `wss://hip4-ws-staging.totalis.trade` |
+
+Staging runs on Hyperliquid testnet ([Staging](https://docs.totalis.trade/hyperliquid/build/staging)). Pass
+`baseUrl` to point at another origin.
+
+Money is atomic USDC (6 decimals): `25_000_000n` is 25 USDC.
+
+## Entry points
+
+| Import | Holds |
+| --- | --- |
+| `@totalis/hip4-client` | `createClient`, `createTotalis`, errors, pagination, `TotalisStream`, the money and UI helpers |
+| `.../maker` | `createMaker`, `createMakerClient`, maker onboarding |
+| `.../wallet-session` | `signInWithWallet`, `signOutWallet` |
+| `.../partner` | `signAdmissionConsent`, `createPartnerServer` |
+| `.../api-keys` | Issuing, rotating, listing and revoking keys |
+| `.../typed-data` | Builders and hashing for every signed message |
+| `.../signer` | `toTotalisSigner` |
+| `.../realtime` | `TotalisStream` and the frame types |
+| `.../errors` | The error registry, `ApiError`, `NetworkError` |
+
+## Examples
+
+The package ships runnable examples in `examples/`:
+
+| File | Shows |
+| --- | --- |
+| `onboard.mjs` | Headless maker onboarding: sign in, open and admit the maker, issue its key, deposit, start the bot |
+| `node-bot.mjs` | A maker bot that quotes entries, buys back cash-outs and confirms acceptances |
+| `browser-wallet.html`, `browser-wallet.mjs` | Opening and cashing out from an injected wallet, with no bundler |
+| `partner-frontend.mjs` | A partner page that collects consent, signs a wallet in and trades |
+| `partner-server.mjs` | A partner server that admits a wallet with its `tpk_` key |
+
+## Versioning
+
+The SDK follows semver. See [`CHANGELOG.md`](CHANGELOG.md).
+
+## License
+
+Apache-2.0

package/dist/api-keys.d.ts

@@ -0,0 +1,118 @@
+import { type ApiClientOptions, type PublicEnvironment } from "./base.js";
+import type { components, paths } from "./generated/api-keys.js";
+import type { TotalisSigner } from "./signer.js";
+export type { components, operations, paths } from "./generated/api-keys.js";
+/**
+ * Key lifecycle uses a session: an app session in a browser, or a wallet
+ * session (`signInWithWallet`) headless, with its Origin as a header. Secrets
+ * are returned once; POST retries cannot recover them.
+ */
+export declare function createApiKeyClient(environment: PublicEnvironment, options?: ApiClientOptions): import("openapi-fetch").Client<paths, `${string}/${string}`>;
+export type ApiKeyClient = ReturnType<typeof createApiKeyClient>;
+type Schemas = components["schemas"];
+export type KeyChallenge = Schemas["KeyChallenge"];
+/** Whose key: the session's personal account, or a maker vault (signed by its controller). */
+export type KeyAccount = {
+    readonly maker?: string;
+};
+export type KeyScope = Schemas["Scope"];
+export type KeyMetadata = Schemas["KeyMetadata"];
+/**
+ * The maker scopes for a quoting bot: it reads RFQs, quotes and confirms, and
+ * reads its capital, but none of these move vault money, so a leaked key can
+ * quote but never withdraw.
+ */
+export declare const QUOTING_BOT_SCOPES: readonly ["rfq:read", "quote:read", "quote:write", "replay:read", "vault:read"];
+/** The maker scopes for lowering collateral (`reduceCollateral`). Keep this key apart from the quoting bot's. */
+export declare const COLLATERAL_SCOPES: readonly ["vault:read", "vault:write", "operations:submit"];
+/**
+ * Check a challenge before the owner signs it: the exact issue_key template,
+ * signed by the expected owner, for this account and action, granting exactly
+ * `scopes` when given, and not expired.
+ */
+export declare function checkKeyChallenge(challenge: KeyChallenge, expected: {
+    readonly owner: string;
+    readonly action: "create" | "rotate";
+    readonly maker?: string | undefined;
+    readonly keyId?: string | undefined;
+    readonly scopes?: readonly string[] | undefined;
+}, now?: number): void;
+/**
+ * Issue a scoped `ttk_` key through the owner-signed challenge (TT-1791): ask
+ * for a challenge, check it, personal_sign it with the account owner, then
+ * create the key. The secret is returned once; a lost response surfaces
+ * SECRET_UNAVAILABLE (list, revoke and replace, never retry).
+ */
+export declare function issueApiKey(client: ApiKeyClient, owner: TotalisSigner, request: Schemas["UnsignedCreateKeyRequest"] & KeyAccount): Promise<{
+    readonly key: {
+        readonly id: components["schemas"]["Uuid"];
+        readonly account: {
+            readonly kind: "PARTICIPANT";
+            readonly id: components["schemas"]["Uuid"];
+        };
+        readonly environment: "development" | "staging" | "production";
+        readonly label: components["schemas"]["KeyLabel"];
+        readonly scopes: readonly ("identity:read" | "account:read" | "account:stream" | "rfq:read" | "rfq:write" | "quote:write" | "quote:read" | "replay:read" | "vault:read" | "vault:write" | "quote:accept" | "position:cashout" | "funding:deposit" | "funding:withdraw" | "sponsorship:use" | "maker:access:read" | "operations:read" | "operations:submit")[];
+        readonly status: "ACTIVE";
+        readonly created_at: components["schemas"]["Timestamp"];
+        readonly expires_at: components["schemas"]["Timestamp"] | null;
+    };
+    readonly secret: string;
+} | {
+    readonly key: {
+        readonly id: components["schemas"]["Uuid"];
+        readonly account: {
+            readonly kind: "MAKER";
+            readonly id: components["schemas"]["NonZeroUInt64String"];
+            readonly chain_id: "998" | "999";
+            readonly vault_address: components["schemas"]["LowercaseNonZeroAddress"];
+        };
+        readonly environment: "development" | "staging" | "production";
+        readonly label: components["schemas"]["KeyLabel"];
+        readonly scopes: readonly ("identity:read" | "account:read" | "account:stream" | "rfq:read" | "rfq:write" | "quote:write" | "quote:read" | "replay:read" | "vault:read" | "vault:write" | "quote:accept" | "position:cashout" | "funding:deposit" | "funding:withdraw" | "sponsorship:use" | "maker:access:read" | "operations:read" | "operations:submit")[];
+        readonly status: "ACTIVE";
+        readonly created_at: components["schemas"]["Timestamp"];
+        readonly expires_at: components["schemas"]["Timestamp"] | null;
+    };
+    readonly secret: string;
+}>;
+/** Rotate a key the same way: the owner signs a ROTATE challenge for that key. */
+export declare function rotateApiKey(client: ApiKeyClient, owner: TotalisSigner, keyId: string, request?: Schemas["UnsignedRotateKeyRequest"] & KeyAccount): Promise<{
+    readonly key: {
+        readonly id: components["schemas"]["Uuid"];
+        readonly account: {
+            readonly kind: "PARTICIPANT";
+            readonly id: components["schemas"]["Uuid"];
+        };
+        readonly environment: "development" | "staging" | "production";
+        readonly label: components["schemas"]["KeyLabel"];
+        readonly scopes: readonly ("identity:read" | "account:read" | "account:stream" | "rfq:read" | "rfq:write" | "quote:write" | "quote:read" | "replay:read" | "vault:read" | "vault:write" | "quote:accept" | "position:cashout" | "funding:deposit" | "funding:withdraw" | "sponsorship:use" | "maker:access:read" | "operations:read" | "operations:submit")[];
+        readonly status: "ACTIVE";
+        readonly created_at: components["schemas"]["Timestamp"];
+        readonly expires_at: components["schemas"]["Timestamp"] | null;
+        readonly rotated_from: string;
+    };
+    readonly secret: string;
+} | {
+    readonly key: {
+        readonly id: components["schemas"]["Uuid"];
+        readonly account: {
+            readonly kind: "MAKER";
+            readonly id: components["schemas"]["NonZeroUInt64String"];
+            readonly chain_id: "998" | "999";
+            readonly vault_address: components["schemas"]["LowercaseNonZeroAddress"];
+        };
+        readonly environment: "development" | "staging" | "production";
+        readonly label: components["schemas"]["KeyLabel"];
+        readonly scopes: readonly ("identity:read" | "account:read" | "account:stream" | "rfq:read" | "rfq:write" | "quote:write" | "quote:read" | "replay:read" | "vault:read" | "vault:write" | "quote:accept" | "position:cashout" | "funding:deposit" | "funding:withdraw" | "sponsorship:use" | "maker:access:read" | "operations:read" | "operations:submit")[];
+        readonly status: "ACTIVE";
+        readonly created_at: components["schemas"]["Timestamp"];
+        readonly expires_at: components["schemas"]["Timestamp"] | null;
+        readonly rotated_from: string;
+    };
+    readonly secret: string;
+}>;
+/** Every key of the account, or of `maker`, oldest first, revoked and expired ones included, read page by page. */
+export declare function listApiKeys(client: ApiKeyClient, account?: KeyAccount): Promise<KeyMetadata[]>;
+/** Revoke a key at once, with any key it is rotating to or from. No signature is needed, and revoking a revoked key succeeds again. */
+export declare function revokeApiKey(client: ApiKeyClient, keyId: string, account?: KeyAccount): Promise<void>;

package/dist/api-keys.js

@@ -0,0 +1,104 @@
+import { audienceClient } from "./base.js";
+import { items } from "./pagination.js";
+import { ApiError, unwrap, uuidv7 } from "./request.js";
+import { parseIssueKeyMessage } from "./typed-data.js";
+/**
+ * Key lifecycle uses a session: an app session in a browser, or a wallet
+ * session (`signInWithWallet`) headless, with its Origin as a header. Secrets
+ * are returned once; POST retries cannot recover them.
+ */
+export function createApiKeyClient(environment, options) {
+    return audienceClient(environment, options);
+}
+/**
+ * The maker scopes for a quoting bot: it reads RFQs, quotes and confirms, and
+ * reads its capital, but none of these move vault money, so a leaked key can
+ * quote but never withdraw.
+ */
+export const QUOTING_BOT_SCOPES = ["rfq:read", "quote:read", "quote:write", "replay:read", "vault:read"];
+/** The maker scopes for lowering collateral (`reduceCollateral`). Keep this key apart from the quoting bot's. */
+export const COLLATERAL_SCOPES = ["vault:read", "vault:write", "operations:submit"];
+/**
+ * Check a challenge before the owner signs it: the exact issue_key template,
+ * signed by the expected owner, for this account and action, granting exactly
+ * `scopes` when given, and not expired.
+ */
+export function checkKeyChallenge(challenge, expected, now = Date.now()) {
+    const message = parseIssueKeyMessage(challenge.message);
+    const path = expected.maker === undefined ? "/v1/me/api-keys" : `/v1/makers/${expected.maker}/api-keys`;
+    const scopePrefix = "urn:totalis:scope:";
+    const granted = message.resources.filter((resource) => resource.startsWith(scopePrefix)).map((resource) => resource.slice(scopePrefix.length)).sort().join(" ");
+    const wanted = expected.scopes && [...expected.scopes].sort().join(" ");
+    const problems = [
+        message.address.toLowerCase() !== challenge.owner && "message address is not the challenge owner",
+        challenge.owner !== expected.owner.toLowerCase() && `challenge owner ${challenge.owner} is not the signer ${expected.owner}`,
+        !message.uri.endsWith(path) && `message is for ${message.uri}, not ${path}`,
+        expected.maker !== undefined && !message.resources.includes(`urn:totalis:account:maker:${expected.maker}`) && "message is for another account",
+        !message.resources.includes(`urn:totalis:action:${expected.action}`) && `message is not for ${expected.action}`,
+        expected.keyId !== undefined && !message.resources.includes(`urn:totalis:key:${expected.keyId}`) && "message is for another key",
+        wanted !== undefined && granted !== wanted && `message grants ${granted || "no scopes"}, not ${wanted}`,
+        message.requestId !== challenge.challenge_id && "message is for another challenge",
+        Date.parse(message.expirationTime) <= now && "challenge expired",
+    ].filter(Boolean);
+    if (problems.length > 0)
+        throw new Error(`refusing to sign the key challenge: ${problems.join("; ")}`);
+}
+/**
+ * Steps 1 and 2 for both create and rotate: ask the account's challenge route,
+ * check the challenge, and have the owner personal_sign it.
+ */
+async function ownerProof(client, owner, maker, request) {
+    const params = { header: { "Idempotency-Key": uuidv7() } };
+    const challenge = unwrap(maker === undefined
+        ? await client.POST("/v1/me/api-key-challenges", { params, body: request })
+        : await client.POST("/v1/makers/{maker_id}/api-key-challenges", { params: { ...params, path: { maker_id: maker } }, body: request }));
+    checkKeyChallenge(challenge, {
+        owner: await owner.address(), action: request.action === "CREATE" ? "create" : "rotate", maker,
+        keyId: request.action === "ROTATE" ? request.key_id : undefined,
+        scopes: request.action === "CREATE" ? request.request.scopes : undefined,
+    });
+    return { challenge_id: challenge.challenge_id, signature: await owner.signMessage(challenge.message) };
+}
+/**
+ * Issue a scoped `ttk_` key through the owner-signed challenge (TT-1791): ask
+ * for a challenge, check it, personal_sign it with the account owner, then
+ * create the key. The secret is returned once; a lost response surfaces
+ * SECRET_UNAVAILABLE (list, revoke and replace, never retry).
+ */
+export async function issueApiKey(client, owner, request) {
+    const { maker, ...body } = request;
+    const proof = await ownerProof(client, owner, maker, { action: "CREATE", request: body });
+    const params = { header: { "Idempotency-Key": uuidv7() } };
+    return maker === undefined
+        ? unwrap(await client.POST("/v1/me/api-keys", { params, body: { ...body, proof } }))
+        : unwrap(await client.POST("/v1/makers/{maker_id}/api-keys", { params: { ...params, path: { maker_id: maker } }, body: { ...body, proof } }));
+}
+/** Rotate a key the same way: the owner signs a ROTATE challenge for that key. */
+export async function rotateApiKey(client, owner, keyId, request = {}) {
+    const { maker, ...body } = request;
+    const proof = await ownerProof(client, owner, maker, { action: "ROTATE", key_id: keyId, request: body });
+    const params = { header: { "Idempotency-Key": uuidv7() } };
+    return maker === undefined
+        ? unwrap(await client.POST("/v1/me/api-keys/{key_id}/rotations", { params: { ...params, path: { key_id: keyId } }, body: { ...body, proof } }))
+        : unwrap(await client.POST("/v1/makers/{maker_id}/api-keys/{key_id}/rotations", { params: { ...params, path: { maker_id: maker, key_id: keyId } }, body: { ...body, proof } }));
+}
+/** Every key of the account, or of `maker`, oldest first, revoked and expired ones included, read page by page. */
+export async function listApiKeys(client, account = {}) {
+    const { maker } = account;
+    const keys = [];
+    const read = async (query) => unwrap(maker === undefined
+        ? await client.GET("/v1/me/api-keys", { params: { query: { ...query, limit: 200 } } })
+        : await client.GET("/v1/makers/{maker_id}/api-keys", { params: { path: { maker_id: maker }, query: { ...query, limit: 200 } } }));
+    for await (const key of items(read, (page) => page.items))
+        keys.push(key);
+    return keys;
+}
+/** Revoke a key at once, with any key it is rotating to or from. No signature is needed, and revoking a revoked key succeeds again. */
+export async function revokeApiKey(client, keyId, account = {}) {
+    const { maker } = account;
+    const { error, response } = maker === undefined
+        ? await client.DELETE("/v1/me/api-keys/{key_id}", { params: { path: { key_id: keyId } } })
+        : await client.DELETE("/v1/makers/{maker_id}/api-keys/{key_id}", { params: { path: { maker_id: maker, key_id: keyId } } });
+    if (error !== undefined || !response.ok)
+        throw ApiError.from(response, error);
+}

package/dist/audience-contract.d.ts

@@ -0,0 +1,52 @@
+import type { operations as ClientOperations } from "./generated/client.js";
+import type { operations as MakerOperations } from "./generated/maker.js";
+import type { components as OpenApiComponents } from "./generated/openapi.js";
+import type { operations as OperatorOperations } from "./generated/operator.js";
+type Assert<T extends true> = T;
+type Includes<Operations, Name extends string> = Name extends keyof Operations ? true : false;
+type Excludes<Operations, Name extends string> = Name extends keyof Operations ? false : true;
+type RequiredBranch<Branch, Shape> = [Branch] extends [never] ? false : Branch extends Shape ? true : false;
+type ClientContract = [
+    Assert<Includes<ClientOperations, "listMarkets">>,
+    Assert<Includes<ClientOperations, "createRfq">>,
+    Assert<Excludes<ClientOperations, "createQuote">>,
+    Assert<Excludes<ClientOperations, "live">>
+];
+type MakerContract = [
+    Assert<Includes<MakerOperations, "listMarkets">>,
+    Assert<Includes<MakerOperations, "createQuote">>,
+    Assert<Includes<MakerOperations, "confirmQuote">>,
+    Assert<Excludes<MakerOperations, "acceptQuote">>,
+    Assert<Excludes<MakerOperations, "createRfq">>,
+    Assert<Excludes<MakerOperations, "live">>
+];
+type OperatorContract = [
+    Assert<Includes<OperatorOperations, "live">>,
+    Assert<Excludes<OperatorOperations, "listMarkets">>
+];
+type CashoutContract = Assert<OpenApiComponents["schemas"]["CashoutRfq"] extends {
+    readonly decision_block: string;
+    readonly decision_read_gas: "500000";
+    readonly net_stake: string;
+    readonly payout: string;
+} ? true : false>;
+type QuoteContract = [
+    Assert<RequiredBranch<Extract<OpenApiComponents["schemas"]["Quote"], {
+        readonly kind: "ENTRY";
+    }>, {
+        readonly quote_id: unknown;
+        readonly entry?: unknown;
+    }>>,
+    Assert<OpenApiComponents["schemas"]["QuoteTerms"]["legs"][number] extends {
+        readonly outcome_id: string;
+        readonly side: "YES" | "NO";
+    } ? true : false>,
+    Assert<OpenApiComponents["schemas"]["SellBackTerms"] extends {
+        readonly position_id: string;
+    } ? true : false>,
+    Assert<OpenApiComponents["schemas"]["TransferTerms"] extends {
+        readonly position_id: string;
+    } ? true : false>
+];
+export type AudienceContract = [ClientContract, MakerContract, OperatorContract, CashoutContract, QuoteContract];
+export {};

package/dist/audience-contract.js

@@ -0,0 +1 @@
+export {};