@totalis/hip4-client 0.0.0-stage → 0.65.2

package/dist/ui.d.ts

@@ -0,0 +1,54 @@
+import type { components } from "./generated/realtime.js";
+import { type Quote, type Totalis } from "./totalis.js";
+type Invalidation = components["schemas"]["Invalidation"];
+/** An account read a `readInvalidated` frame names: refetch the queries built on it. */
+export type AccountResource = Invalidation["resources"][number];
+export type UiAdapterOptions = {
+    /**
+     * Refetch these account reads, for example `queryClient.invalidateQueries`.
+     * Called for each newer `readInvalidated` revision (a session's account
+     * stream gets its own ACTIVITY and POSITIONS; other resources and
+     * scoped keys need `subscription: { account_reads: true }`), and with every
+     * resource each time the stream goes live, because invalidations sent while
+     * it was down are lost.
+     */
+    readonly onInvalidate?: (resources: readonly AccountResource[]) => void;
+    /**
+     * Refetch the market catalog (`/v1/markets`, `/v1/discovery`): a
+     * `marketRefresh` named a generation newer than the one passed to
+     * `catalogLoaded`. Called once per generation; every connection announces
+     * the current one, so a reconnect alone never refetches.
+     */
+    readonly onCatalogStale?: (generation: string) => void;
+};
+/** What `watchQuotes` renders: the live quotes, the best one still acceptable, and the venue clock they were judged at. */
+export type QuoteView = {
+    readonly quotes: readonly Quote[];
+    readonly best: Quote | undefined;
+    readonly serverNowMs: number;
+};
+/**
+ * A small framework-agnostic bridge from the account stream to a UI: quotes
+ * from the subscription, the venue clock, account invalidations for a query
+ * cache and generation-aware catalog refresh. It polls nothing and holds no
+ * framework dependency; wire the callbacks to your store.
+ */
+export declare function createUiAdapter(totalis: Pick<Totalis, "stream" | "watchQuotes">, options?: UiAdapterOptions): {
+    /** The venue clock in ms. Read it on every render tick; a timestamp kept from a callback freezes countdowns. */
+    serverNow: () => number;
+    /** Seconds the quote can still be accepted: an entry until its `accept_before`, a cash-out bid until its expiry. */
+    secondsLeft: (quote: Quote) => number;
+    /**
+     * Render an RFQ's live quotes from the stream (`totalis.watchQuotes`) with
+     * the best one: highest payout before its `accept_before` (`bestQuote`),
+     * or highest price with at least `minLifeSeconds` left (`bestBid`,
+     * default 25). `quotes` is `[]` while the stream is not live. Returns the unsubscribe.
+     */
+    watchQuotes(rfqId: string, listener: (view: QuoteView) => void, minLifeSeconds?: number): () => void;
+    /** Record the `catalog_generation` of the catalog you just loaded; `onCatalogStale` then fires only for a newer one. */
+    catalogLoaded(generation: string | number | bigint): void;
+    /** Detach the listeners; the stream stays open. */
+    close(): void;
+};
+export type UiAdapter = ReturnType<typeof createUiAdapter>;
+export {};

package/dist/ui.js

@@ -0,0 +1,77 @@
+import { acceptBefore, bestBid, bestQuote } from "./totalis.js";
+const everyResource = ["BALANCES", "CAPITAL", "ACTIVITY", "POSITIONS", "PERFORMANCE", "TELEMETRY", "QUOTES", "ACCESS"];
+const expiryOf = (quote) => (quote.kind === "ENTRY" ? quote.entry : quote.kind === "SELL_BACK" ? quote.sell_back : quote.transfer).expiry;
+/**
+ * A small framework-agnostic bridge from the account stream to a UI: quotes
+ * from the subscription, the venue clock, account invalidations for a query
+ * cache and generation-aware catalog refresh. It polls nothing and holds no
+ * framework dependency; wire the callbacks to your store.
+ */
+export function createUiAdapter(totalis, options = {}) {
+    const { stream } = totalis;
+    const revisions = new Map();
+    let catalog;
+    let staleCatalog;
+    const offs = [
+        stream.on("status", (status) => {
+            if (status !== "live")
+                return;
+            revisions.clear();
+            options.onInvalidate?.(everyResource);
+        }),
+        stream.on("frame", (frame) => {
+            if (frame.channel === "readInvalidated") {
+                const invalidation = frame.data;
+                const scope = JSON.stringify(invalidation.scope);
+                const revision = BigInt(invalidation.revision);
+                if (revision <= (revisions.get(scope) ?? -1n))
+                    return;
+                revisions.set(scope, revision);
+                options.onInvalidate?.(invalidation.resources);
+            }
+            else if (frame.channel === "marketRefresh") {
+                // Every connection announces the current generation; only a newer one than held (or already announced) is news.
+                const generation = BigInt(frame.data.catalog_generation);
+                if (generation <= (catalog ?? 0n) || generation <= (staleCatalog ?? 0n))
+                    return;
+                staleCatalog = generation;
+                options.onCatalogStale?.(generation.toString());
+            }
+        }),
+    ];
+    // Attached to a stream that is already live: no status event will come, and invalidations before now were missed.
+    if (stream.status === "live")
+        options.onInvalidate?.(everyResource);
+    stream.start();
+    return {
+        /** The venue clock in ms. Read it on every render tick; a timestamp kept from a callback freezes countdowns. */
+        serverNow: () => stream.serverNow(),
+        /** Seconds the quote can still be accepted: an entry until its `accept_before`, a cash-out bid until its expiry. */
+        secondsLeft: (quote) => Math.max(0, Math.floor(((quote.kind === "ENTRY" ? acceptBefore(quote) : Number(expiryOf(quote)) * 1000) - stream.serverNow()) / 1000)),
+        /**
+         * Render an RFQ's live quotes from the stream (`totalis.watchQuotes`) with
+         * the best one: highest payout before its `accept_before` (`bestQuote`),
+         * or highest price with at least `minLifeSeconds` left (`bestBid`,
+         * default 25). `quotes` is `[]` while the stream is not live. Returns the unsubscribe.
+         */
+        watchQuotes(rfqId, listener, minLifeSeconds) {
+            return totalis.watchQuotes(rfqId, (quotes, serverNowMs) => {
+                const entries = quotes.filter((quote) => quote.kind === "ENTRY");
+                const bids = quotes.filter((quote) => quote.kind !== "ENTRY");
+                const best = entries.length > 0 ? bestQuote()(entries, serverNowMs) : bestBid(minLifeSeconds)(bids, serverNowMs);
+                listener({ quotes, best, serverNowMs });
+            });
+        },
+        /** Record the `catalog_generation` of the catalog you just loaded; `onCatalogStale` then fires only for a newer one. */
+        catalogLoaded(generation) {
+            const loaded = BigInt(generation);
+            if (catalog === undefined || loaded > catalog)
+                catalog = loaded;
+        },
+        /** Detach the listeners; the stream stays open. */
+        close() {
+            for (const off of offs)
+                off();
+        },
+    };
+}

package/dist/wallet-session.d.ts

@@ -0,0 +1,45 @@
+import { type ApiClientOptions, type PublicEnvironment } from "./base.js";
+import type { components } from "./generated/client.js";
+import { type SignerInput } from "./signer.js";
+type Schemas = components["schemas"];
+export type WalletChallenge = Schemas["WalletChallenge"];
+/** A bearer session for the wallet's account: at most 30 days, ending after 7 idle days or at sign-out. */
+export type WalletSession = Schemas["WalletSession"];
+export type WalletSignInOptions = Omit<ApiClientOptions, "accessToken"> & {
+    readonly environment: PublicEnvironment;
+    /** The external wallet that signs in. It is the account (TT-1780); its key never leaves it. */
+    readonly signer: SignerInput;
+    /**
+     * The page's origin, defaulting to `location.origin` in a browser. Outside a
+     * browser it is sent as the Origin header: a maker passes the Totalis app's
+     * origin (`https://hip4.totalis.trade`, or `https://hip4-staging.totalis.trade`
+     * on staging), and a partner its registered origin. Send the same origin as
+     * the Origin header with every request on the session's token.
+     */
+    readonly origin?: string;
+};
+/**
+ * Check a sign-in challenge before the wallet signs it: the exact Totalis
+ * session message, for this origin, wallet and request, and not expired.
+ * A sign-in message authorizes no financial action, but a wallet should never
+ * sign one it did not ask for.
+ */
+export declare function checkSignInChallenge(challenge: WalletChallenge, expected: {
+    readonly address: string;
+    readonly origin: string;
+    readonly requestId: string;
+}, now?: number): void;
+/**
+ * Sign an external wallet in (TT-1676): ask for a challenge, have the wallet
+ * personal_sign it, and return the session. Use `access_token` as the
+ * `accessToken` of `createTotalis` with the same wallet as its signer. A wallet
+ * with no account yet needs a partner to admit it first (ACCESS_REQUIRED).
+ */
+export declare function signInWithWallet(options: WalletSignInOptions): Promise<WalletSession>;
+/** End the wallet session now; any later request with its token is UNAUTHENTICATED. */
+export declare function signOutWallet(options: Omit<ApiClientOptions, "accessToken"> & {
+    readonly environment: PublicEnvironment;
+    readonly accessToken: string;
+    readonly origin?: string;
+}): Promise<void>;
+export {};

package/dist/wallet-session.js

@@ -0,0 +1,61 @@
+import { audienceClient } from "./base.js";
+import { ApiError, unwrap, uuidv7 } from "./request.js";
+import { toTotalisSigner } from "./signer.js";
+const sessionStatement = "Create a Totalis venue transport session. This does not authorize a financial action.";
+const inBrowser = () => typeof globalThis.document !== "undefined";
+/**
+ * Check a sign-in challenge before the wallet signs it: the exact Totalis
+ * session message, for this origin, wallet and request, and not expired.
+ * A sign-in message authorizes no financial action, but a wallet should never
+ * sign one it did not ask for.
+ */
+export function checkSignInChallenge(challenge, expected, now = Date.now()) {
+    const lines = challenge.message.split("\n");
+    const field = (name) => lines.find((line) => line.startsWith(`${name}: `))?.slice(name.length + 2);
+    const expiration = field("Expiration Time");
+    const problems = [
+        // The venue names the origin's authority as sent, keeping an explicit default port.
+        lines[0] !== `${expected.origin.slice(expected.origin.indexOf("//") + 2)} wants you to sign in with your Ethereum account:` && "message is for another site",
+        lines[1]?.toLowerCase() !== expected.address.toLowerCase() && "message is for another wallet",
+        lines[3] !== sessionStatement && "message is not a Totalis sign-in",
+        field("URI") !== `${expected.origin}/v1/auth/wallet-sessions` && "message is for another URI",
+        field("Request ID") !== expected.requestId && "message is for another request",
+        (expiration === undefined || !(Date.parse(expiration) > now)) && "challenge expired",
+    ].filter(Boolean);
+    if (problems.length > 0)
+        throw new Error(`refusing to sign the sign-in message: ${problems.join("; ")}`);
+}
+/**
+ * Sign an external wallet in (TT-1676): ask for a challenge, have the wallet
+ * personal_sign it, and return the session. Use `access_token` as the
+ * `accessToken` of `createTotalis` with the same wallet as its signer. A wallet
+ * with no account yet needs a partner to admit it first (ACCESS_REQUIRED).
+ */
+export async function signInWithWallet(options) {
+    const { environment, signer: input, origin = globalThis.location?.origin, ...clientOptions } = options;
+    if (origin === undefined || origin === "")
+        throw new Error("signInWithWallet needs an origin outside a browser");
+    const signer = toTotalisSigner(input);
+    const address = await signer.address();
+    const client = audienceClient(environment, clientOptions);
+    // A browser sets Origin itself and refuses a script's value.
+    const originHeader = inBrowser() ? {} : { Origin: origin };
+    const requestId = uuidv7();
+    const challenge = unwrap(await client.POST("/v1/auth/wallet-challenges", {
+        params: { header: { "Idempotency-Key": requestId } }, body: { address, origin }, headers: originHeader,
+    }));
+    checkSignInChallenge(challenge, { address, origin, requestId });
+    const signature = await signer.signMessage(challenge.message);
+    return unwrap(await client.POST("/v1/auth/wallet-sessions", {
+        params: { header: { "Idempotency-Key": uuidv7() } }, body: { challenge_id: challenge.challenge_id, signature }, headers: originHeader,
+    }));
+}
+/** End the wallet session now; any later request with its token is UNAUTHENTICATED. */
+export async function signOutWallet(options) {
+    const { environment, origin = globalThis.location?.origin, ...clientOptions } = options;
+    const client = audienceClient(environment, clientOptions);
+    const headers = inBrowser() || origin === undefined ? {} : { Origin: origin };
+    const { error, response } = await client.DELETE("/v1/auth/wallet-sessions/current", { headers });
+    if (error !== undefined || !response.ok)
+        throw ApiError.from(response, error);
+}

package/examples/browser-wallet.html

@@ -0,0 +1,69 @@
+<!doctype html>
+<!--
+  A browser-wallet taker on @totalis/hip4-client, with no bundler.
+  From clients/typescript: `npm run build`, serve this directory
+  (for example `python3 -m http.server 8000`), then open
+  http://localhost:8000/examples/browser-wallet.html with an injected wallet.
+  The import map below needs that checkout's dist/ and node_modules/, so this
+  page does not run from an installed copy; an app with a bundler imports
+  "@totalis/hip4-client" and browser-wallet.mjs instead.
+-->
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Totalis SDK: browser wallet</title>
+  <script type="importmap">
+    {
+      "imports": {
+        "@totalis/hip4-client": "../dist/client.js",
+        "openapi-fetch": "../node_modules/openapi-fetch/dist/index.mjs",
+        "@noble/hashes/sha3": "../node_modules/@noble/hashes/esm/sha3.js",
+        "@noble/hashes/crypto": "../node_modules/@noble/hashes/esm/crypto.js"
+      }
+    }
+  </script>
+  <style>
+    body { font: 14px system-ui, sans-serif; max-width: 42rem; margin: 2rem auto; }
+    label { display: block; margin: .5rem 0; }
+    input, textarea { width: 100%; font: inherit; }
+    pre { background: #f4f4f4; padding: 1rem; white-space: pre-wrap; }
+  </style>
+</head>
+<body>
+  <h1>Totalis SDK: browser wallet</h1>
+  <label>API origin <input id="baseUrl" value="https://hip4-api-staging.totalis.trade"></label>
+  <label>Session token (the app's access token) <input id="token" type="password"></label>
+  <label>Legs <textarea id="legs">[{"outcome_id": "1", "side": "YES"}]</textarea></label>
+  <label>Amount (USDC base units) <input id="amount" value="5000000"></label>
+  <label>Position ID (for a cash-out) <input id="position"></label>
+  <button id="bet">Place bet</button>
+  <button id="cashout">Cash out</button>
+  <pre id="out">Connect an injected wallet (window.ethereum) to begin.</pre>
+  <script type="module">
+    import { cashOut, connect, openPosition } from "./browser-wallet.mjs";
+
+    const $ = (id) => document.getElementById(id);
+    const show = (value) => { $("out").textContent = typeof value === "string" ? value : JSON.stringify(value, null, 2); };
+    const session = () => {
+      if (!window.ethereum) throw new Error("no injected wallet");
+      return connect({ provider: window.ethereum, accessToken: $("token").value, baseUrl: $("baseUrl").value });
+    };
+    const run = (action) => async () => {
+      const totalis = session();
+      totalis.stream.on("status", (status) => show(`stream ${status}`));
+      try {
+        show(await action(totalis));
+      } catch (error) {
+        show(`${error.name}: ${error.message}`);
+      } finally {
+        totalis.close();
+      }
+    };
+    $("bet").onclick = run((totalis) => openPosition(totalis, {
+      legs: JSON.parse($("legs").value), stake: $("amount").value,
+      onQuotes: (quotes) => show(`${quotes.length} quote(s)`),
+    }));
+    $("cashout").onclick = run((totalis) => cashOut(totalis, { positionId: $("position").value }));
+  </script>
+</body>
+</html>

package/examples/browser-wallet.mjs

@@ -0,0 +1,57 @@
+// Taker flows for any browser wallet (an EIP-1193 provider such as
+// window.ethereum or an embedded wallet's provider). browser-wallet.html wires
+// these to buttons; the local test harness runs the same functions in Node.
+import { createTotalis, entryFailure } from "@totalis/hip4-client";
+
+/**
+ * @typedef {object} ConnectOptions
+ * @property {import("@totalis/hip4-client/signer").Eip1193ProviderLike} provider The wallet.
+ * @property {import("@totalis/hip4-client").AccessToken} accessToken The app session, or a scoped ttk_ key.
+ * @property {import("@totalis/hip4-client").PublicEnvironment} [environment]
+ * @property {string} [baseUrl]
+ * @property {Record<string, string>} [headers] Extra headers outside a browser, such as a session's Origin.
+ * @property {import("@totalis/hip4-client/realtime").WebSocketFactory} [webSocket]
+ */
+
+/** @param {ConnectOptions} options */
+export function connect({ provider, accessToken, environment = "production", baseUrl, headers, webSocket }) {
+  return createTotalis({
+    environment, accessToken, signer: provider,
+    ...(baseUrl ? { baseUrl } : {}),
+    ...(headers ? { headers } : {}),
+    ...(webSocket ? { stream: { webSocket } } : {}),
+  });
+}
+
+/**
+ * Open a combo position and return the accept result with its operation's
+ * current status. The quotes come
+ * from the account stream; `onQuotes` sees each version of them. Any vault
+ * shortfall is funded from the wallet in the same accept.
+ */
+export async function openPosition(totalis, { legs, stake, onQuotes }) {
+  /** @type {import("@totalis/hip4-client").Chooser<import("@totalis/hip4-client").EntryQuote>} */
+  const choose = (quotes) => {
+    onQuotes?.(quotes);
+    return [...quotes]
+      .sort((a, b) => (BigInt(b.entry.payout) > BigInt(a.entry.payout) ? 1 : -1))[0];
+  };
+  const result = await totalis.openPosition({ legs, stake: BigInt(stake), choose });
+  if (result.status !== "ACCEPTED") return result;
+  // The operation's chain outcome arrives on the stream; read its current status once.
+  // Only COMMITTED opened the position; a failed one's `failure` names the message to show.
+  const { data } = await totalis.client.GET("/v1/me/operations/{operation_id}", { params: { path: { operation_id: result.operationId } } });
+  const operation = data?.operation;
+  return { ...result, operation, failure: operation === undefined ? undefined : entryFailure(result.record, operation) };
+}
+
+/**
+ * Cash out a position at the best quote. The wallet signs the quote's SellBack
+ * or CashoutTransfer before the accept; ACCEPTED means the sale is queued as
+ * `operationId`. Any other status (DECLINED, TIMED_OUT, CANCELLED, NOT_ADMITTED)
+ * sold nothing.
+ */
+export async function cashOut(totalis, { positionId }) {
+  const result = await totalis.cashOut({ positionId });
+  return { rfqId: result.rfqId, acceptanceId: result.acceptanceId, status: result.status, operationId: result.operationId };
+}

package/examples/node-bot.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// A Node maker bot on @totalis/hip4-client: quote every open entry RFQ,
+// bid to buy back its own positions on cash-out RFQs when given a `bid` price,
+// and confirm what takers accept while `willing` still holds.
+// Entry and cash-out quotes are published on the same route. Pricing here is a placeholder; a real
+// maker prices from its own market data and, in `willing`, re-checks its price
+// and free capacity before it confirms.
+//
+//   TOTALIS_ENVIRONMENT=staging TOTALIS_MAKER_ID=1 TOTALIS_MAKER_KEY=ttk_v1_stg_... \
+//   TOTALIS_WALLET_KEY=0x... node examples/node-bot.mjs
+import { pathToFileURL } from "node:url";
+import { createMaker } from "@totalis/hip4-client/maker";
+import { privateKeyToAccount } from "viem/accounts";
+
+/** Start quoting and confirming. Returns the maker; `close()` it to stop. */
+export function startBot({ environment = "production", baseUrl, apiKey, makerId, signer, payout = (rfq) => (BigInt(rfq.stake) * 18n) / 10n, bid, willing = () => true, log = console.log }) {
+  const maker = createMaker({ environment, ...(baseUrl === undefined ? {} : { baseUrl }), apiKey, makerId, signer });
+  maker.stream.on("status", (status) => log(`stream ${status}`));
+  // Returning the quote promise lets onRfq offer the RFQ again if publishing fails.
+  maker.onRfq(async (rfq) => {
+    if (rfq.status !== "OPEN") return;
+    if (rfq.kind === "ENTRY") {
+      const { quoteId } = await maker.quote(rfq, { payout: payout(rfq) });
+      log(`quoted ${rfq.rfq_id} ${quoteId}`);
+    } else if (rfq.kind === "CASHOUT" && bid !== undefined && rfq.maker_id === makerId) {
+      // A sell-back of a position this maker wrote, paid from the maker vault. Another
+      // maker's position would be a transfer, paid from this wallet's own account
+      // balance, which this bot does not fund.
+      const { quoteId } = await maker.bid(rfq, { price: bid(rfq) });
+      log(`bid ${rfq.rfq_id} ${quoteId}`);
+    }
+  }, (error) => log(`rfq handling failed: ${error.message}`));
+  // Acceptances arrive as QUOTE_ACCEPTED (and in the snapshot, paged past its
+  // cap); confirming a cash-out executes the owner-signed sale, answering ACCEPTED.
+  maker.onAcceptance(async (acceptance) => {
+    // Price or capital may have moved since the quote: decline rather than fill.
+    if (!(await willing(acceptance))) {
+      log(`declining ${acceptance.quote_id} on ${acceptance.rfq_id}`);
+      return "DECLINE";
+    }
+    log(`confirming ${acceptance.quote_id} on ${acceptance.rfq_id}`);
+    return "CONFIRM";
+  }, (error, acceptance) => log(`confirm ${acceptance?.quote_id ?? "read"} failed: ${error.message}`));
+  return maker;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const required = (name) => process.env[name] ?? (() => { throw new Error(`${name} is required`); })();
+  const maker = startBot({
+    environment: process.env.TOTALIS_ENVIRONMENT ?? "staging",
+    baseUrl: process.env.TOTALIS_BASE_URL,
+    apiKey: required("TOTALIS_MAKER_KEY"),
+    makerId: required("TOTALIS_MAKER_ID"),
+    signer: privateKeyToAccount(required("TOTALIS_WALLET_KEY")),
+  });
+  process.once("SIGINT", () => maker.close());
+}

package/examples/onboard.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+// Headless maker onboarding on @totalis/hip4-client, from the exported
+// key of your Totalis account's wallet: sign in, open and admit the maker,
+// issue the quoting bot's key, fund the maker vault, and start quoting. Run it
+// again to resume: each step skips what is already done.
+//
+// Before it, once in a browser: sign up at hip4.totalis.trade with your invite
+// code, then in Account choose Export private key. Fund that wallet on HyperEVM
+// with HYPE for gas (makers are never sponsored) and the USDC you will deposit.
+//
+//   TOTALIS_ENVIRONMENT=production TOTALIS_WALLET_KEY=0x... TOTALIS_DEPOSIT=1000000000 \
+//   node examples/onboard.mjs
+//
+// TOTALIS_DEPOSIT is the first deposit, in atomic USDC: it is made only while
+// the maker vault is empty on chain, so a rerun never deposits twice. Add more
+// later with controllerTransactions' approveUsdc and deposit.
+//
+// The quoting key's secret is printed once. Store it as TOTALIS_MAKER_KEY: a
+// rerun with it set quotes with it instead of issuing another, and from then on
+// examples/node-bot.mjs runs the bot on its own.
+import { pathToFileURL } from "node:url";
+import { createPublicClient, createWalletClient, defineChain, http, parseAbi } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { createClient, unwrap } from "@totalis/hip4-client";
+import { createApiKeyClient, issueApiKey, listApiKeys, QUOTING_BOT_SCOPES } from "@totalis/hip4-client/api-keys";
+import { controllerTransactions, openMakerVaultTransaction, waitForMaker } from "@totalis/hip4-client/maker";
+import { toTotalisSigner } from "@totalis/hip4-client/signer";
+import { signInWithWallet } from "@totalis/hip4-client/wallet-session";
+import { startBot } from "./node-bot.mjs";
+
+/** The Totalis app's origin: a maker's wallet session signs in from it, and every request on the session sends it as Origin. */
+export const appOrigins = { production: "https://hip4.totalis.trade", staging: "https://hip4-staging.totalis.trade" };
+/** Public HyperEVM RPCs by chain ID; pass your own `rpcUrl` for anything heavier than onboarding. */
+const publicRpcs = { "999": "https://rpc.hyperliquid.xyz/evm", "998": "https://rpc.hyperliquid-testnet.xyz/evm" };
+
+const vaultReads = parseAbi([
+  "function makerOf(address) view returns (uint64)",
+  "function makers(uint64) view returns (address controller, address quoteSigner, uint128 vault, uint128 stakeEscrow, uint128 payableOwed, uint128 grossOpen, uint128 discount, uint128 settledTurnover, uint64 lastReduceAt)",
+]);
+
+/**
+ * The wallet as onboarding uses it: send the SDK's zero-value vault calls and
+ * wait for each to succeed, sign one for a self-funded route, and read from the
+ * vault the maker this wallet opened (0 if none) and a maker's vault lane.
+ */
+export function hyperEvmWallet({ account, chainId, vault, rpcUrl = publicRpcs[chainId] }) {
+  const chain = defineChain({ id: Number(chainId), name: "HyperEVM", nativeCurrency: { name: "HYPE", symbol: "HYPE", decimals: 18 }, rpcUrls: { default: { http: [rpcUrl] } } });
+  const reader = createPublicClient({ chain, transport: http(rpcUrl) });
+  const writer = createWalletClient({ account, chain, transport: http(rpcUrl) });
+  const request = (call) => {
+    if (call.chain_id !== String(chain.id)) throw new Error(`the call is for chain ${call.chain_id}, not ${chain.id}`);
+    return { to: call.to, data: call.data, value: BigInt(call.value) };
+  };
+  return {
+    async send(call) {
+      const hash = await writer.sendTransaction(request(call));
+      const receipt = await reader.waitForTransactionReceipt({ hash });
+      if (receipt.status !== "success") throw new Error(`transaction ${hash} reverted`);
+      return hash;
+    },
+    sign: async (call) => writer.signTransaction(await writer.prepareTransactionRequest(request(call))),
+    makerOf: () => reader.readContract({ address: vault, abi: vaultReads, functionName: "makerOf", args: [account.address] }),
+    makerVault: async (makerId) => (await reader.readContract({ address: vault, abi: vaultReads, functionName: "makers", args: [BigInt(makerId)] }))[2],
+  };
+}
+
+/**
+ * Onboard the wallet's maker and return what the bot needs. `deposit` is the
+ * first deposit in atomic USDC (6 decimals), made only while the maker vault is
+ * empty on chain. Without `makerKey`, a "Quoting bot" key is issued and its
+ * secret returned once.
+ */
+export async function onboard({ environment = "production", baseUrl, origin = appOrigins[environment], walletKey, rpcUrl, deposit = 0n, makerKey, fetch, wallet: walletOverride, log = console.log }) {
+  const signer = privateKeyToAccount(walletKey);
+  const options = { ...(baseUrl === undefined ? {} : { baseUrl }), ...(fetch === undefined ? {} : { fetch }) };
+
+  // 1. Sign in with the wallet. The session lasts at most 30 days and ends after 7 idle days: run this again to sign in again.
+  const session = await signInWithWallet({ environment, ...options, signer, origin });
+  const onSession = { ...options, accessToken: session.access_token, headers: { Origin: origin } };
+  const client = createClient(environment, onSession);
+  const deployment = unwrap(await client.GET("/v1/deployment"));
+  const wallet = walletOverride ?? hyperEvmWallet({ account: signer, chainId: deployment.chain_id, vault: deployment.vault_address, rpcUrl });
+
+  // 2. Open the maker vault: one transaction from this wallet, which becomes its controller and quote signer. A wallet opens one maker.
+  if (BigInt(await wallet.makerOf()) === 0n) {
+    log("opening the maker vault");
+    await wallet.send(openMakerVaultTransaction(deployment, signer.address));
+  }
+
+  // 3. Admit it once Totalis has indexed it: no signature, and safe to repeat.
+  const readiness = await waitForMaker(client);
+  if (readiness.state !== "READY") throw new Error(`the maker is ${readiness.state}, not READY: email founders@totalis.trade`);
+  const { makerId } = readiness;
+  log(`maker ${makerId} is ready`);
+
+  // 4. The quoting bot's key: maker scopes that cannot move vault money, approved by this wallet's signature.
+  const keys = createApiKeyClient(environment, onSession);
+  let secret = makerKey;
+  if (secret === undefined) {
+    const active = (await listApiKeys(keys, { maker: makerId })).filter((key) => key.status === "ACTIVE");
+    if (active.length > 0) log(`maker ${makerId} already has ${active.length} active key(s); issuing another`);
+    const issued = await issueApiKey(keys, toTotalisSigner(signer), { maker: makerId, label: "Quoting bot", scopes: [...QUOTING_BOT_SCOPES], expires_in_days: 90 });
+    secret = issued.secret;
+    log(`issued key ${issued.key.id}; store its secret as TOTALIS_MAKER_KEY, it is shown only now:\n${secret}`);
+  }
+
+  // 5. Fund the maker vault: approve USDC, then deposit it, once. Withdrawing later is requestWithdraw, then executeWithdraw after the delay.
+  if (deposit > 0n && BigInt(await wallet.makerVault(makerId)) > 0n) log(`maker ${makerId}'s vault is already funded; depositing nothing`);
+  else if (deposit > 0n) {
+    const vault = controllerTransactions(deployment, makerId, signer.address);
+    log(`depositing ${deposit} atomic USDC`);
+    await wallet.send(vault.approveUsdc(deposit));
+    await wallet.send(vault.deposit(deposit));
+  }
+  return { makerId, makerKey: secret, signer, wallet };
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const required = (name) => process.env[name] ?? (() => { throw new Error(`${name} is required`); })();
+  const environment = process.env.TOTALIS_ENVIRONMENT ?? "production";
+  const { makerId, makerKey, signer } = await onboard({
+    environment,
+    baseUrl: process.env.TOTALIS_BASE_URL,
+    walletKey: required("TOTALIS_WALLET_KEY"),
+    rpcUrl: process.env.HYPEREVM_RPC_URL,
+    deposit: BigInt(process.env.TOTALIS_DEPOSIT ?? "0"),
+    makerKey: process.env.TOTALIS_MAKER_KEY,
+  });
+  // 6. Quote and confirm. The maker wallet signs every confirm; nothing fills without it.
+  const maker = startBot({ environment, baseUrl: process.env.TOTALIS_BASE_URL, apiKey: makerKey, makerId, signer });
+  process.once("SIGINT", () => maker.close());
+}

package/examples/partner-frontend.mjs

@@ -0,0 +1,44 @@
+// A partner's frontend (TT-1685): an external wallet signs in and trades as its
+// own account. The wallet is any EIP-1193 provider: an extension's
+// window.ethereum, or your own embedded wallet's provider. Totalis never holds
+// its key; every bet, cash-out and withdrawal is signed by the wallet itself.
+// A new wallet first consents to your partner opening its account, and your
+// server admits it with that consent (partner-server.mjs).
+import { createClient, createTotalis } from "@totalis/hip4-client";
+import { signAdmissionConsent } from "@totalis/hip4-client/partner";
+import { signInWithWallet, signOutWallet } from "@totalis/hip4-client/wallet-session";
+
+/**
+ * A new user's consent, for your server's admitWallet: the wallet signs that
+ * your partner (`slug`) may open its account. Once, before its first sign-in.
+ */
+export async function consentToPartner({ provider, slug, environment = "production" }) {
+  // The deployment is public: read it with no credential.
+  const { data: deployment } = await createClient(environment).GET("/v1/deployment");
+  return signAdmissionConsent({ signer: provider, partner: slug, environment, chainId: deployment.chain_id });
+}
+
+/**
+ * @param {object} options
+ * @param {import("@totalis/hip4-client/signer").Eip1193ProviderLike} options.provider The wallet.
+ * @param {string} options.partnerKey Your publishable `tpb_v1_…` key, honoured from your registered origins.
+ * @param {import("@totalis/hip4-client").PublicEnvironment} [options.environment]
+ */
+export async function connectPartner({ provider, partnerKey, environment = "production" }) {
+  // The wallet signs a sign-in message for this page's origin; it authorizes no financial action.
+  const session = await signInWithWallet({ environment, signer: provider, partnerKey });
+  const totalis = createTotalis({ environment, accessToken: session.access_token, signer: provider, partnerKey });
+  return {
+    session,
+    totalis,
+    async signOut() {
+      totalis.close();
+      await signOutWallet({ environment, accessToken: session.access_token, partnerKey });
+    },
+  };
+}
+
+// For example, with an extension wallet:
+//
+//   const { totalis } = await connectPartner({ provider: window.ethereum, partnerKey: "tpb_v1_prd_…" });
+//   await totalis.openPosition({ legs: [{ outcome_id: "13160", side: "YES" }], stake: 5_000_000n });

package/examples/partner-server.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// A partner's server (TT-1685): admit a wallet so its next sign-in creates its
+// Totalis account, attributed to you. During the invite-only launch this is the
+// only way a new wallet gets an account. The wallet's consent comes from your
+// frontend (partner-frontend.mjs consentToPartner). Run it where your tpk_
+// server key lives; never in a browser.
+//
+//   TOTALIS_ENVIRONMENT=staging TOTALIS_PARTNER_KEY=tpk_v1_stg_... node examples/partner-server.mjs '{"address":"0x…","consent":{…}}'
+import { pathToFileURL } from "node:url";
+import { createPartnerServer } from "@totalis/hip4-client/partner";
+
+/** Admit `address` with its consent; admitting it again returns the first admission. */
+export async function admit({ environment = "production", baseUrl, serverKey, address, consent }) {
+  const partner = createPartnerServer({ environment, serverKey, ...(baseUrl === undefined ? {} : { baseUrl }) });
+  return partner.admitWallet(address, consent);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const serverKey = process.env.TOTALIS_PARTNER_KEY ?? (() => { throw new Error("TOTALIS_PARTNER_KEY is required"); })();
+  const { address, consent } = JSON.parse(process.argv[2] ?? (() => { throw new Error("usage: partner-server.mjs '{\"address\":…,\"consent\":…}'"); })());
+  console.log(await admit({ environment: process.env.TOTALIS_ENVIRONMENT, serverKey, address, consent }));
+}