@totalis/hip4-client 0.75.0 → 0.77.0

package/CHANGELOG.md

@@ -3,6 +3,80 @@
 `@totalis/hip4-client` follows [semantic versioning](https://semver.org).
 The contract version the generated types come from is `sdkVersion` in `./version`.
 
+## 0.77.0
+
+`openPosition` chooses its quote last and moves on to the next quote when an
+accept is refused, declined or times out (TT-2578, TT-2574). Makers replace
+quotes as they renew them, and an accept that took seconds to sign often found
+its quote gone (`QUOTE_REPLACED`). Additive: 0.76 code runs unchanged, but
+`openPosition` now sends up to `maxAttempts` accepts where it sent one or two.
+
+### Added
+
+- `prepareEntryFunding({ stake, core, cash, sourceDex, hypercoreNonce })`
+  plans and signs an entry's funding (the wallet's USDC authorization and any
+  bridge from Core) before a quote is chosen. `signEntry({ quote, prepared })`
+  then signs only the quote, so the accept can go straight out. A prepared
+  funding is for one accept.
+- `SignedEntry.refused`: the code of an accept the venue refused outright.
+  `recoverAcceptance` answers such a record `NOT_ADMITTED` from the record
+  alone, without reading the acceptance or cancelling the RFQ.
+- `openPosition` options `minPayout`, `refreshMs` (default 10 s) and
+  `maxAttempts` (default 4).
+
+### Changed
+
+- `openPosition` signs the funding first and chooses the quote after, then
+  signs it and sends the accept at once. Signing the funding counts against
+  `collectMs`.
+- On `QUOTE_REPLACED` or `QUOTE_EXPIRED`, `openPosition` hands `onSigned` the
+  record marked `refused`, then prepares the funding again and signs the best
+  other quote paying at least `minPayout` (left out: the first chosen quote's
+  payout). It keeps going until an accept is taken, `refreshMs` passes or
+  `maxAttempts` accepts were sent, and throws the last refusal. Before, it
+  retried once and took any payout.
+- A `DECLINED` or `TIMED_OUT` accept is followed the same way, within the
+  same `refreshMs` and `maxAttempts`: the maker's answer admitted nothing and
+  the RFQ stays open. With no other quote at or above `minPayout` in time,
+  `openPosition` returns that answer, as before.
+
+## 0.76.0
+
+Vault agents (TT-2554), one Combo leg per question (TT-2605) and no legs on
+unpriced markets (TT-2606). Generated from contract
+`205.0.0-device-vault-agents`. Additive: 0.75 code runs unchanged, but
+`createRfq` now refuses two legs from one question and legs with a null
+`chance`.
+
+### Added
+
+- Vault agents (TT-2554). `agent` in `createTotalis` takes a key the account
+  granted; it then signs the account's `TakerAccept`, `SellBack`,
+  `CashoutTransfer` and Exits to HyperCore or the account's wallet instead of
+  `signer`, so those need no wallet prompt. `signer` still names the account
+  and signs USDC authorizations, HyperCore actions, grants and run-off claims.
+- `grantVaultAgent({ agent, validUntil })` has the account sign an
+  `AgentGrant` and relays it (`POST /v1/me/vault-agents`); `revokeVaultAgent`
+  sends `validUntil` 0, and `vaultAgents()` iterates the live agents.
+- `agentGrantTypedData` in `typed-data`, checked against the vault's vectors.
+- A grant or revoke's default nonce rises past any nonce this client sent
+  explicitly for that agent, so it isn't refused for not exceeding it.
+
+### Changed
+
+- `createRfq` refuses a Combo with two legs from one native question
+  (TT-2605): the second such leg is named in `field_violations` as
+  `/legs/{i}/outcome_id` with reason `SAME_QUESTION` (`400
+  INVALID_REQUEST`). Makers never quoted these legs, so such an RFQ used
+  to open and get no quotes. Allow one leg per `native_question_id` in your
+  slip; standalone markets have none and always combine.
+- `createRfq` refuses a leg whose market has a side with a null `chance`
+  (an empty, dust or one-sided book with no recent evidence), with reason
+  `CHANCE_UNAVAILABLE` on `/legs/{i}/outcome_id` (`400 INVALID_REQUEST`).
+  Makers price from the book, and on such a book one small order sets the
+  price. Show `chance`, not `value`, and treat `chance: null` as unpriced
+  (TT-2606).
+
 ## 0.75.0
 
 Maker capital on the stream (TT-2584), a stream that cannot hang in

package/README.md

@@ -66,8 +66,9 @@ if (opened.operationId) {
 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.
+`openPosition` creates the RFQ, signs the funding for any shortfall from the wallet, then takes the best quote
+and signs the acceptance. If the maker replaced the quote first, declined it or didn't answer, it signs the best
+other quote paying at least the first one's payout (`minPayout`) and tries again. Only `COMMITTED` means the trade happened. A decided position settles and pays out on its own.
 
 ## Make markets
 

package/dist/client.d.ts

@@ -5,7 +5,7 @@ export type { components, operations, paths } from "./generated/client.js";
 export type { AccessToken, ApiClientOptions, PublicEnvironment } from "./base.js";
 /** The typed HTTP client for the `client` audience. `createTotalis` adds the flows. */
 export declare function createClient(environment: PublicEnvironment, options?: ApiClientOptions): import("openapi-fetch").Client<paths, `${string}/${string}`>;
-export { bestBid, bestQuote, createTotalis, EntryError, entryFailure, follow, type Acceptance, type AcceptanceResult, type Amount, type BridgeState, type CashoutBid, type Chooser, type Deployment, type DepositAccepted, type EntryCash, type EntryFailure, type EntryQuote, type CoreExit, type LegacySignedEntry, type Leg, type NotAdmitted, type RecordListener, type Operation, type Quote, type ResponseOf, type SellBackQuote, type SignedAcceptance, type SignedCashout, type SignedCoreExit, type SignedDeposit, type SignedEntry, type SignedReturnToCore, type Totalis, type TotalisOptions, type TransferQuote, type WalletCall, type Withdrawal, } from "./totalis.js";
+export { bestBid, bestQuote, createTotalis, EntryError, entryFailure, follow, type Acceptance, type AcceptanceResult, type Amount, type BridgeState, type CashoutBid, type Chooser, type Deployment, type DepositAccepted, type EntryCash, type EntryFailure, type EntryQuote, type CoreExit, type LegacySignedEntry, type Leg, type PreparedEntryFunding, type NotAdmitted, type RecordListener, type Operation, type Quote, type ResponseOf, type SellBackQuote, type SignedAcceptance, type SignedCashout, type SignedCoreExit, type SignedDeposit, type SignedEntry, type SignedReturnToCore, type Totalis, type TotalisOptions, type TransferQuote, type WalletCall, type Withdrawal, } from "./totalis.js";
 export { bridgeAction, bridgeGasBuffer, classifyHypercoreAnswer, hyperevmUsdcBridge, hyperliquidExchange, hyperliquidNetwork, hypercoreNonce, hypercoreSignature, sendAssetTypedData, settleHypercore, signSendAsset, submitHypercore, usdcText, type BridgedCash, type HypercoreAnswer, type HypercoreSignature, type HypercoreTransport, type HyperliquidNetwork, type SendAssetAction, type SignedSendAsset, } from "./hypercore.js";
 export { ApiError, envelope, NetworkError, randomBytes32, retryingFetch, sendOnce, unwrap, uuidv7, type Fetch, type Repaired, type RetryPolicy } from "./request.js";
 export { items, pages, type Page, type PageQuery } from "./pagination.js";

package/dist/generated/openapi.d.ts

@@ -2843,7 +2843,7 @@ export type components = {
         readonly CreateRfqCommand: {
             /** @description Stake in atomic USDC (6 decimals), before taker fees; must be positive. Quotes carry the same stake. */
             readonly stake: components["schemas"]["$defs-Amount"];
-            /** @description 1 to 5 legs in strictly increasing outcome_id order. */
+            /** @description 1 to 5 legs in strictly increasing outcome_id order, at most one per native question. Every leg's market must have eligibility ENABLED and combo OPEN, and a chance on each side. */
             readonly legs: readonly components["schemas"]["$defs-Leg"][];
             /** @description Optional partner attribution code, from any credential. From an account a partner admitted, it must be one of that partner's active codes and needs no signature; with none, the partner's account code is recorded. From any other account it needs builder_authorization_expiry and builder_signature from the partner's registered signer and is honoured only from the code's registered browser origin, so an API-key request (no Origin) from such an account cannot send one. A refused code returns INVALID_REQUEST naming /builder_code. Revocation rejects new RFQs without vetoing an already-created RFQ. Partners get codes from Totalis. */
             readonly builder_code?: string;
@@ -9558,7 +9558,7 @@ export interface operations {
                     readonly "application/json": components["schemas"]["RfqCreated"];
                 };
             };
-            /** @description `INVALID_REQUEST`: the body is malformed, or a leg's market refuses new positions now. A refused leg is named in `field_violations` as `/legs/{i}/outcome_id`, and the message gives the reason, such as `REFERENCE_UNAVAILABLE` or `OUTSIDE_WINDOW`; the market's `eligibility` and `combo` show when it clears. */
+            /** @description `INVALID_REQUEST`: the body is malformed, or a leg's market refuses new positions now. A refused leg is named in `field_violations` as `/legs/{i}/outcome_id`, and the message gives the reason, such as `REFERENCE_UNAVAILABLE`, `OUTSIDE_WINDOW`, `CHANCE_UNAVAILABLE` for a side whose `chance` is null, or `SAME_QUESTION` for a leg whose `native_question_id` an earlier leg already has; the market's `eligibility` and `combo` show when it clears. */
             readonly 400: components["responses"]["Error"];
             readonly 401: components["responses"]["Error"];
             readonly 403: components["responses"]["Error"];

package/dist/generated/version.d.ts

@@ -1,5 +1,5 @@
 export declare const sdkVersion = "205.0.0-device-vault-agents";
-export declare const openapiSha256 = "e742feade28ca115077a4275e4a6260646278e9adcf0839987b8566a2221c8f5";
+export declare const openapiSha256 = "93141e0bf50949fc37ebceef7c64555eb50a70f69c71c89c8fdc12780e0dd168";
 export declare const realtimeSha256 = "1cac740e108e84ad1979f6ccc71089efd840404cb72d1612a86edc02769637e3";
 export declare const jsonSchemaSha256: {
     readonly "account.schema.json": "5106e2d53abef190990eff113f6692dd27df5848439cf5a80a42c11e89f2bef6";

package/dist/generated/version.js

@@ -1,6 +1,6 @@
 // Generated by scripts/generate.mjs; do not edit.
 export const sdkVersion = "205.0.0-device-vault-agents";
-export const openapiSha256 = "e742feade28ca115077a4275e4a6260646278e9adcf0839987b8566a2221c8f5";
+export const openapiSha256 = "93141e0bf50949fc37ebceef7c64555eb50a70f69c71c89c8fdc12780e0dd168";
 export const realtimeSha256 = "1cac740e108e84ad1979f6ccc71089efd840404cb72d1612a86edc02769637e3";
 export const jsonSchemaSha256 = {
     "account.schema.json": "5106e2d53abef190990eff113f6692dd27df5848439cf5a80a42c11e89f2bef6",

package/dist/totalis.d.ts

@@ -102,6 +102,27 @@ export type SignedEntry = RecordScope & {
     readonly command: AcceptCommand;
     readonly bridge?: SignedSendAsset;
     readonly bridgeState?: BridgeState;
+    /**
+     * Set when the venue refused this accept outright (`QUOTE_REPLACED`,
+     * `QUOTE_EXPIRED`): nothing was admitted, so `recoverAcceptance` answers
+     * `NOT_ADMITTED` without reading or cancelling the RFQ, which a later
+     * attempt may be using.
+     */
+    readonly refused?: string;
+};
+/**
+ * An entry's funding, signed before its quote is chosen
+ * (`prepareEntryFunding`). Pass it to `signEntry` as `prepared`, so only the
+ * quote is left to sign once it is chosen. It funds one accept: prepare again
+ * for another.
+ */
+export type PreparedEntryFunding = {
+    readonly stake: string;
+    readonly account: Hex;
+    readonly chainId: string;
+    readonly vault: Hex;
+    readonly funding?: Funding;
+    readonly bridge?: SignedSendAsset;
 };
 /** An entry record from SDK 0.63 or older, which sent its bridge before the accept: `recoverAcceptance` reads it and sends nothing, and `sendAcceptance` refuses it. */
 export type LegacySignedEntry = Omit<SignedEntry, "version" | "bridgeState">;
@@ -185,6 +206,15 @@ export type TotalisOptions = Omit<ApiClientOptions, "accessToken"> & {
     readonly accessToken: AccessToken;
     /** The account's signer (GET /v1/me `wallet`); required for flows that sign. Never stored. */
     readonly signer?: SignerInput;
+    /**
+     * A key the account granted as a vault agent (`grantVaultAgent`). When set,
+     * it signs the account's TakerAccept, SellBack, CashoutTransfer and Exits to
+     * its wallet or HyperCore instead of `signer`, so those need no wallet
+     * prompt. `signer` still names the account and signs everything else: USDC
+     * authorizations, HyperCore actions, grants and run-off claims. The venue
+     * refuses an agent whose grant ends before the signed expiry.
+     */
+    readonly agent?: SignerInput;
     /** Stream options; `subscription` adds account subscription fields such as `open_rfqs`. */
     readonly stream?: Omit<StreamOptions, "subscription" | "accessToken" | "environment" | "baseUrl" | "streamBaseUrl"> & {
         readonly subscription?: Omit<Extract<StreamSubscription, {
@@ -237,7 +267,7 @@ export declare function createTotalis(options: TotalisOptions): {
         readonly legs: readonly Leg[];
         readonly stake: Amount;
         readonly choose?: Chooser<EntryQuote>;
-        /** How long quotes may keep arriving after the first one `choose` would take, before it picks; 0 takes it at once. */
+        /** How long quotes may keep arriving after the first one `choose` would take, before it picks; 0 takes it at once. Time spent signing the funding counts. */
         readonly collectMs?: number;
         /** `"wallet"` (default) plans the shortfall from the wallet and `core`; `"none"` never funds; or pass a funding command. */
         readonly funding?: "wallet" | "none" | Funding;
@@ -245,9 +275,9 @@ export declare function createTotalis(options: TotalisOptions): {
         readonly core?: Amount | null;
         readonly sourceDex?: "spot" | "";
         readonly transport?: HypercoreTransport;
-        /** The cash to plan from (see `signEntry`); left out, the balances are read while the quotes arrive. */
+        /** The cash to plan from (see `signEntry`); left out, the balances are read while the RFQ is created, and again for each refresh. */
         readonly cash?: EntryCash;
-        /** Awaited with the signed record before anything is sent, then with each change to its bridge (`onRecord`): persist it to `recoverAcceptance` after a restart. */
+        /** Awaited with the signed record before anything is sent, then with each change to its bridge (`onRecord`) or its refusal: persist it to `recoverAcceptance` after a restart. */
         readonly onSigned?: RecordListener;
         /** Automatic-quote intent identity, as the Totalis app sends it. */
         readonly intent?: {
@@ -255,6 +285,12 @@ export declare function createTotalis(options: TotalisOptions): {
             readonly intent_generation: string;
         };
         readonly quoteTimeoutMs?: number;
+        /** The least payout a quote may pay, in USDC base units. Left out, it is the first chosen quote's: a refresh never takes less. */
+        readonly minPayout?: Amount;
+        /** How long after the first quote is chosen a refused, declined or timed-out accept may still be followed by another (default 10 s). */
+        readonly refreshMs?: number;
+        /** The most accepts sent, the first included (default 4); 1 never refreshes. */
+        readonly maxAttempts?: number;
         readonly signal?: AbortSignal;
     }) => Promise<{
         entry: {
@@ -288,6 +324,14 @@ export declare function createTotalis(options: TotalisOptions): {
         readonly quoteTimeoutMs?: number;
         readonly signal?: AbortSignal;
     }) => Promise<AcceptanceResult>;
+    prepareEntryFunding: (request: {
+        readonly stake: Amount;
+        readonly core?: Amount | null | undefined;
+        readonly cash?: EntryCash | undefined;
+        readonly sourceDex?: "spot" | "" | undefined;
+        readonly hypercoreNonce?: number | undefined;
+        readonly signal?: AbortSignal | undefined;
+    }) => Promise<PreparedEntryFunding>;
     signEntry: (request: {
         readonly quote: EntryQuote;
         readonly core?: Amount | null;
@@ -295,6 +339,7 @@ export declare function createTotalis(options: TotalisOptions): {
         readonly sourceDex?: "spot" | "";
         readonly acceptanceId?: string;
         readonly hypercoreNonce?: number;
+        readonly prepared?: PreparedEntryFunding;
     }) => Promise<SignedEntry>;
     signCashout: (request: {
         readonly quote: CashoutBid;
@@ -638,6 +683,27 @@ export declare function createTotalis(options: TotalisOptions): {
         readonly signal?: AbortSignal;
     }) => Promise<CoreExit>;
     directDepositCalls: (amount: Amount) => Promise<readonly WalletCall[]>;
+    grantVaultAgent: (request: {
+        readonly agent: string;
+        readonly validUntil: number | string;
+        readonly nonce?: number | string;
+        readonly idempotencyKey?: string;
+    }) => Promise<{
+        readonly operation_id: import("./generated/openapi.js").components["schemas"]["Hash32"];
+    }>;
+    revokeVaultAgent: (request: {
+        readonly agent: string;
+        readonly nonce?: number | string;
+        readonly idempotencyKey?: string;
+    }) => Promise<{
+        readonly operation_id: import("./generated/openapi.js").components["schemas"]["Hash32"];
+    }>;
+    vaultAgents: (limit?: number) => AsyncGenerator<{
+        readonly agent: import("./generated/openapi.js").components["schemas"]["Address"];
+        readonly valid_until: import("./generated/openapi.js").components["schemas"]["UInt64String"];
+        readonly nonce: import("./generated/openapi.js").components["schemas"]["UInt64String"];
+        readonly copy_agent: boolean;
+    }, void, any>;
     /** Render an RFQ's live quotes (entry or cash-out) from the stream; `[]` while the stream is down. */
     watchQuotes: (rfqId: string, listener: (quotes: readonly Quote[], serverNowMs: number) => void) => () => void;
     /** Issue a personal `ttk_` key; the signer must be the account wallet (embedded, or a wallet-only account's own). */

package/dist/totalis.js

@@ -7,7 +7,8 @@ import { spendableCash } from "./money.js";
 import { ApiError, backoffDelay, envelope, NetworkError, randomBytes32, resendable, retryingFetch, sendOnce, singleFetch, sleep, unwrap, uuidv7 } from "./request.js";
 import { toTotalisSigner } from "./signer.js";
 import { TotalisStream } from "./stream.js";
-import { address, cashoutTransferTypedData, exitTypedData, receiveWithAuthorizationTypedData, sellBackTypedData, takerAcceptTypedData, payoutNonce, transferWithAuthorizationTypedData, } from "./typed-data.js";
+import { items } from "./pagination.js";
+import { address, agentGrantTypedData, cashoutTransferTypedData, exitTypedData, receiveWithAuthorizationTypedData, sellBackTypedData, takerAcceptTypedData, payoutNonce, transferWithAuthorizationTypedData, } from "./typed-data.js";
 /**
  * What an entry's bridge may have moved to its wallet, by its state: nothing
  * before it is sent, once discarded or refused. Only `LANDED` proves it
@@ -86,6 +87,11 @@ const minimumDeposit = 1000000n;
  * best of them win instead of the fastest.
  */
 const defaultCollectMs = 1_000;
+const defaultRefreshMs = 10_000;
+const defaultMaxAttempts = 4;
+/** Accept refusals that mean the chosen quote went away before the accept, not that the position cannot open. */
+const refreshCodes = new Set(["QUOTE_EXPIRED", "QUOTE_REPLACED"]);
+const passedOn = new Set(["DECLINED", "TIMED_OUT"]);
 const timerSlackMs = 250;
 function termsOf(quote) {
     return quote.kind === "ENTRY" ? quote.entry : quote.kind === "SELL_BACK" ? quote.sell_back : quote.transfer;
@@ -314,7 +320,7 @@ function streamQuotes(stream, read) {
  * stream; HTTP reads recover after a reconnect or answer a doorbell.
  */
 export function createTotalis(options) {
-    const { environment, signer: signerInput, stream: streamOptions, streamBaseUrl, accessToken, ...clientOptions } = options;
+    const { environment, signer: signerInput, agent: agentInput, stream: streamOptions, streamBaseUrl, accessToken, ...clientOptions } = options;
     const client = audienceClient(environment, { ...clientOptions, accessToken });
     const keys = createApiKeyClient(environment, { ...clientOptions, accessToken });
     const stream = new TotalisStream({
@@ -337,6 +343,22 @@ export function createTotalis(options) {
     };
     const signer = signerInput === undefined ? undefined : toTotalisSigner(signerInput);
     const requireSigner = () => signer ?? Promise.reject(new Error("this flow needs a signer"));
+    const agent = agentInput === undefined ? undefined : toTotalisSigner(agentInput);
+    // The vault reverts a grant whose nonce does not exceed the agent's last, so
+    // two grants for one agent in one second (a grant, then its revoke) must not
+    // share one, and a default after an explicit nonce must exceed it too. The
+    // vault counts per agent, so the mark is per agent.
+    const lastGrantNonce = new Map();
+    const grantNonce = (agentAddress, explicit) => {
+        const last = lastGrantNonce.get(agentAddress) ?? 0n;
+        const clock = BigInt(now());
+        const nonce = explicit !== undefined ? BigInt(explicit) : clock > last ? clock : last + 1n;
+        if (nonce < 1n || nonce > 2n ** 64n - 1n)
+            throw new Error(`grant nonce ${nonce} is outside 1..2^64-1`);
+        if (nonce > last)
+            lastGrantNonce.set(agentAddress, nonce);
+        return String(nonce);
+    };
     let deploymentRead;
     const deployment = () => (deploymentRead ??= client.GET("/v1/deployment").then(unwrap).catch((error) => {
         deploymentRead = undefined;
@@ -585,7 +607,7 @@ export function createTotalis(options) {
         const signer = await requireSigner();
         const account = await signer.address();
         const chain = await deployment();
-        return { signer, account, chain, scope: { account, chainId: chain.chain_id, vault: address(chain.vault_address.toLowerCase()) } };
+        return { signer, vaultSigner: agent ?? signer, account, chain, scope: { account, chainId: chain.chain_id, vault: address(chain.vault_address.toLowerCase()) } };
     }
     /** A stored record signs nothing more, so without a signer the session's wallet (GET /v1/me) stands for the account. */
     async function checkScope(signed) {
@@ -624,16 +646,51 @@ export function createTotalis(options) {
             throw new EntryError("INSUFFICIENT_FUNDS", `${bridge - (routable > 0n ? routable : 0n)} USDC base units short for this stake`);
         return { wallet: shortfall, bridge };
     }
-    async function signEntryWith(request, funding) {
-        const { quote, cash } = request;
+    function signBridge(signer, chain, amount, request) {
+        return amount > 0n ? signSendAsset(signer, bridgeAction(hyperliquidNetwork(chain.chain_id), amount, {
+            ...(request.hypercoreNonce === undefined ? {} : { nonce: request.hypercoreNonce }),
+            ...(request.sourceDex === undefined ? {} : { sourceDex: request.sourceDex }),
+        })) : undefined;
+    }
+    /**
+     * Plan and sign an entry's funding before choosing its quote: the wallet's
+     * USDC authorization and any bridge from `core`, planned from `cash` or a
+     * fresh balances read as `signEntry` plans them. Neither names a quote, so
+     * once one is chosen `signEntry({ quote, prepared })` signs only the quote
+     * and the accept can go straight out.
+     */
+    async function prepareEntryFunding(request) {
         const { signer, account, chain, scope } = await recordScope();
+        const stake = BigInt(request.stake);
+        const core = request.core === undefined || request.core === null ? request.core : BigInt(request.core);
+        const plan = planEntry(stake, core, request.cash ?? await readSpendableCash(request.signal));
+        const [bridge, funding] = await Promise.all([
+            signBridge(signer, chain, plan.bridge, request),
+            plan.wallet > 0n ? depositAuthorization(chain, account, plan.wallet) : undefined,
+        ]);
+        return { stake: stake.toString(), ...scope, ...(funding === undefined ? {} : { funding }), ...(bridge === undefined ? {} : { bridge }) };
+    }
+    async function signEntryWith(request, funding) {
+        const { quote, cash, prepared } = request;
+        const { signer, vaultSigner, account, chain, scope } = await recordScope();
         if (quote.entry.taker.toLowerCase() !== account)
             throw new Error("the quote is for another taker");
+        const record = (taker_signature, fundingCommand, bridge) => ({
+            kind: "ENTRY", version: 2, acceptanceId: request.acceptanceId ?? uuidv7(), rfqId: quote.rfq_id, quoteId: quote.quote_id, ...scope, expiry: quote.entry.expiry,
+            command: { taker_signature, ...(fundingCommand === undefined ? {} : { funding: fundingCommand }) },
+            ...(bridge === undefined ? {} : { bridge }),
+        });
+        if (prepared !== undefined) {
+            if (prepared.stake !== quote.entry.stake || prepared.account !== scope.account || prepared.chainId !== scope.chainId || prepared.vault !== scope.vault) {
+                throw new Error("the prepared funding is for another stake, account or deployment");
+            }
+            return record(await vaultSigner.signTypedData(takerAcceptTypedData(chain, quote.entry)), prepared.funding, prepared.bridge);
+        }
         const stake = BigInt(quote.entry.stake);
         const core = request.core === undefined || request.core === null ? request.core : BigInt(request.core);
         // Known cash is planned before any prompt, so a plan that fails asks the wallet for nothing.
         let plan = funding === "plan" && cash !== undefined ? planEntry(stake, core, cash) : undefined;
-        const signing = signer.signTypedData(takerAcceptTypedData(chain, quote.entry));
+        const signing = vaultSigner.signTypedData(takerAcceptTypedData(chain, quote.entry));
         if (funding === "plan" && cash === undefined) {
             // The quote signature names no amount, so the wallet signs it while the balances are read; a refusal stops the read and is the call's error.
             const reading = new AbortController();
@@ -647,18 +704,11 @@ export function createTotalis(options) {
         const walletAmount = plan?.wallet ?? 0n;
         const [taker_signature, bridge, walletFunding] = await Promise.all([
             signing,
-            bridgeAmount > 0n ? signSendAsset(signer, bridgeAction(hyperliquidNetwork(chain.chain_id), bridgeAmount, {
-                ...(request.hypercoreNonce === undefined ? {} : { nonce: request.hypercoreNonce }),
-                ...(request.sourceDex === undefined ? {} : { sourceDex: request.sourceDex }),
-            })) : undefined,
+            signBridge(signer, chain, bridgeAmount, request),
             walletAmount > 0n ? depositAuthorization(chain, account, walletAmount) : undefined,
         ]);
         const fundingCommand = plan === undefined ? (funding === "none" || funding === "plan" ? undefined : funding) : walletFunding;
-        return {
-            kind: "ENTRY", version: 2, acceptanceId: request.acceptanceId ?? uuidv7(), rfqId: quote.rfq_id, quoteId: quote.quote_id, ...scope, expiry: quote.entry.expiry,
-            command: { taker_signature, ...(fundingCommand === undefined ? {} : { funding: fundingCommand }) },
-            ...(bridge === undefined ? {} : { bridge }),
-        };
+        return record(taker_signature, fundingCommand, bridge);
     }
     /**
      * Sign a Combo entry for a quote without sending it. Funding is planned
@@ -674,7 +724,8 @@ export function createTotalis(options) {
      * shows them in turn. `sourceDex: ""` bridges from perps instead of spot.
      * Persist the record, then `sendAcceptance` it; after a restart,
      * `recoverAcceptance` it. Pass `hypercoreNonce` if your app reserves
-     * Hyperliquid nonces itself.
+     * Hyperliquid nonces itself. With `prepared` (`prepareEntryFunding`), only
+     * the quote is signed, and its funding is the prepared one.
      */
     function signEntry(request) {
         return signEntryWith(request, "plan");
@@ -682,12 +733,12 @@ export function createTotalis(options) {
     /** Sign a cash-out quote as the position's owner without sending it: the same SellBack or CashoutTransfer digest the maker signs. */
     async function signCashout(request) {
         const { quote } = request;
-        const { signer, account, chain, scope } = await recordScope();
+        const { vaultSigner, account, chain, scope } = await recordScope();
         const seller = quote.kind === "SELL_BACK" ? quote.sell_back.owner : quote.transfer.seller;
         if (seller.toLowerCase() !== account)
             throw new Error("the quote sells another owner's position");
         const typedData = quote.kind === "SELL_BACK" ? sellBackTypedData(chain, quote.sell_back) : cashoutTransferTypedData(chain, quote.transfer);
-        const taker_signature = await signer.signTypedData(typedData);
+        const taker_signature = await vaultSigner.signTypedData(typedData);
         return {
             kind: "CASHOUT", acceptanceId: request.acceptanceId ?? uuidv7(), rfqId: quote.rfq_id, quoteId: quote.quote_id, ...scope,
             positionId: termsOf(quote).position_id, command: { taker_signature },
@@ -756,9 +807,13 @@ export function createTotalis(options) {
      * record from SDK 0.63 or older is only read. One still `PENDING_CONFIRM`
      * is read again after the maker's deadline, or every 250 ms until 2 s past
      * it while a bridge is unsent; `wait: false` returns it as it stands instead.
+     * A record marked `refused` is `NOT_ADMITTED`, read from the record alone.
      */
     async function recoverAcceptance(signed, options = {}) {
         await checkScope(signed);
+        if (signed.kind === "ENTRY" && "refused" in signed && signed.refused !== undefined) {
+            return resultOf(signed, { status: "NOT_ADMITTED", quote_id: signed.quoteId, rfq_id: signed.rfqId }, {});
+        }
         const clock = venueClock();
         const outcome = await fenceAcceptance(signed, clock, undefined, options.wait ?? true, bridgeUnsent(signed));
         return resultOf(signed, outcome, await moveBridge(signed, outcome, clock, options));
@@ -774,21 +829,30 @@ export function createTotalis(options) {
         }
     }
     /**
-     * Open a combo position: create the RFQ, take a quote from those the stream
-     * pushes, sign it (`signEntry`), hand the record to `onSigned` to persist,
-     * then `sendAcceptance`. Returns the acceptance's status (`ACCEPTED` with
+     * Open a combo position: create the RFQ, sign its funding
+     * (`prepareEntryFunding`), then take a quote from those the stream pushes,
+     * sign it (`signEntry`), hand the record to `onSigned` to persist, and
+     * `sendAcceptance` at once: the quote is chosen last, so the one signed is
+     * as fresh as the book allows. Returns the acceptance's status (`ACCEPTED` with
      * `operationId`; `FILLED` or `FAILED`, also with it, when a lost answer was
      * read after the trade settled; `DECLINED` / `TIMED_OUT` / `CANCELLED`; or
      * `NOT_ADMITTED` when a lost accept never arrived). The position opens
      * under `positionId`, the quote's ID, once `waitForOperation(operationId)`
      * resolves `COMMITTED`; pass its operation and the result's `record` to
      * `entryFailure` to name a failure. Any vault shortfall is funded from the
-     * wallet, and from `core` by bridge, unless `funding` says otherwise. An accept refused with
-     * `QUOTE_EXPIRED` or `QUOTE_REPLACED` takes and signs a fresh quote once
-     * (`onSigned` gets the new record); a second refusal is thrown.
+     * wallet, and from `core` by bridge, unless `funding` says otherwise.
+     *
+     * Makers replace their quotes as they renew them, so an accept can find its
+     * quote gone (`QUOTE_REPLACED`, `QUOTE_EXPIRED`); then `onSigned` gets the
+     * record marked `refused`. A maker can also turn its quote down (`DECLINED`)
+     * or not answer in time (`TIMED_OUT`). Either way nothing was admitted, so
+     * the best other quote paying at least `minPayout` is signed and sent,
+     * funding first, until one is taken, `refreshMs` has passed since the first
+     * quote was chosen, or `maxAttempts` accepts were sent. Then the last
+     * refusal is thrown, or the last decline or timeout returned.
      */
     async function openPosition(request) {
-        const { legs, stake, choose = bestQuote(), collectMs = defaultCollectMs, funding = "wallet", intent, quoteTimeoutMs = 20_000, signal } = request;
+        const { legs, stake, choose = bestQuote(), collectMs = defaultCollectMs, funding = "wallet", intent, quoteTimeoutMs = 20_000, refreshMs = defaultRefreshMs, maxAttempts = defaultMaxAttempts, signal } = request;
         const reading = funding === "wallet" && request.cash === undefined ? readSpendableCash(signal) : undefined;
         reading?.catch(() => undefined);
         const account = await (await requireSigner()).address();
@@ -797,20 +861,32 @@ export function createTotalis(options) {
         const wanted = { taker: account, stake: String(stake), legs: [...legs].sort((a, b) => Number(a.outcome_id) - Number(b.outcome_id)).map(({ outcome_id, side }) => ({ outcome_id, side })) };
         const entry = { stake: wanted.stake, legs: wanted.legs };
         const rfqId = await createRfq(intent === undefined ? entry : { ...entry, ...intent });
-        // Only quotes for exactly this position are offered to the chooser, and the chosen one is checked again before signing.
-        const matches = (quote) => quote.kind === "ENTRY" && quote.rfq_id === rfqId &&
+        const createdAt = performance.now();
+        let floor = request.minPayout === undefined ? undefined : BigInt(request.minPayout);
+        const refused = new Set();
+        const offered = (quote) => quote.kind === "ENTRY" && quote.rfq_id === rfqId &&
             quote.entry.taker.toLowerCase() === wanted.taker && quote.entry.stake === wanted.stake &&
-            JSON.stringify(quote.entry.legs.map(({ outcome_id, side }) => ({ outcome_id, side }))) === JSON.stringify(wanted.legs);
-        const take = (refused) => signedOrCancel(rfqId, async () => {
-            const offered = (quote) => matches(quote) && quote.quote_id !== refused;
-            const selected = await awaitOffer(rfqId, offered, choose, collectMs, quoteTimeoutMs, signal);
+            JSON.stringify(quote.entry.legs.map(({ outcome_id, side }) => ({ outcome_id, side }))) === JSON.stringify(wanted.legs) &&
+            !refused.has(quote.quote_id) && (floor === undefined || BigInt(quote.entry.payout) >= floor);
+        // Counted from the first choice, not from its signature, so a slow wallet cannot stretch the window.
+        let refreshUntil;
+        const take = () => signedOrCancel(rfqId, async () => {
+            const prepared = funding === "wallet"
+                ? await prepareEntryFunding({ stake: wanted.stake, core: request.core, cash: request.cash ?? await (refreshUntil === undefined ? reading : readSpendableCash(signal)), sourceDex: request.sourceDex, signal })
+                : undefined;
+            const selected = refreshUntil === undefined
+                ? await awaitOffer(rfqId, offered, choose, Math.max(0, Math.round(collectMs - (performance.now() - createdAt))), quoteTimeoutMs, signal)
+                : await awaitOffer(rfqId, offered, choose, 0, Math.max(0, Math.round(refreshUntil - performance.now())), signal);
+            refreshUntil ??= performance.now() + refreshMs;
             if (!offered(selected))
                 throw new Error("the chosen quote is not for the requested position");
-            const signed = await signEntryWith({ quote: selected, core: request.core, cash: request.cash ?? await reading, sourceDex: request.sourceDex }, funding === "wallet" ? "plan" : funding);
+            const signed = await signEntryWith({ quote: selected, prepared }, funding === "wallet" ? "plan" : funding);
             await request.onSigned?.(signed);
             return { selected, signed };
         });
         let { selected, signed } = await take();
+        floor ??= BigInt(selected.entry.payout);
+        const refreshEnds = refreshUntil ?? 0;
         let record = signed;
         const send = () => sendAcceptance(signed, {
             ...(request.transport === undefined ? {} : { transport: request.transport }),
@@ -820,18 +896,56 @@ export function createTotalis(options) {
                 await request.onSigned?.(next);
             },
         });
-        let result;
-        try {
-            result = await send();
-        }
-        catch (error) {
-            if (!(error instanceof ApiError) || error.code !== "QUOTE_EXPIRED" && error.code !== "QUOTE_REPLACED")
-                throw error;
-            // The quote went away before the accept (sendAcceptance discarded its bridge): sign a fresh one, once. No fresh quote in time is still that refusal.
-            ({ selected, signed } = await take(signed.quoteId).catch((retried) => Promise.reject(retried instanceof Error && retried.name === "TimeoutError" ? error : retried)));
-            record = signed;
-            result = await send();
-        }
+        const settle = async () => {
+            for (let attempt = 1;; attempt += 1) {
+                // The maker turned the quote down, or never answered: nothing was admitted and the RFQ stays open.
+                let lost;
+                try {
+                    lost = await send();
+                    if (!passedOn.has(lost.status))
+                        return lost;
+                }
+                catch (error) {
+                    if (!(error instanceof ApiError) || !refreshCodes.has(error.code))
+                        throw error;
+                    // Refused outright, so nothing was admitted and sendAcceptance discarded any bridge.
+                    lost = error;
+                    record = { ...record, refused: error.code };
+                    await request.onSigned?.(record);
+                }
+                refused.add(signed.quoteId);
+                const last = record;
+                const end = async () => {
+                    if (record !== last) {
+                        record = last;
+                        await request.onSigned?.(last);
+                    }
+                    if (lost instanceof ApiError)
+                        throw lost;
+                    return lost;
+                };
+                if (attempt >= maxAttempts || performance.now() >= refreshEnds)
+                    return end();
+                let next;
+                try {
+                    next = await take();
+                }
+                catch (retried) {
+                    // No fresh quote at or above the floor in time leaves this outcome standing.
+                    if (retried instanceof Error && retried.name === "TimeoutError")
+                        return end();
+                    throw retried;
+                }
+                // Signing and persisting can outlast the window: a record signed too late is never sent, and the last sent one is persisted again.
+                if (performance.now() >= refreshEnds) {
+                    record = next.signed;
+                    return end();
+                }
+                ({ selected, signed } = next);
+                record = signed;
+            }
+        };
+        const result = await settle();
         const { bridged: _bridged, ...settled } = result;
         return {
             ...settled,
@@ -913,7 +1027,7 @@ export function createTotalis(options) {
         let vault_withdrawal;
         if (shortfall > 0n) {
             const exit = { amount: shortfall.toString(), expiry: String(issued + 600), salt: BigInt(randomBytes32()).toString() };
-            vault_withdrawal = { ...exit, signature: await signer.signTypedData(exitTypedData(chain, { account, to: account, ...exit })) };
+            vault_withdrawal = { ...exit, signature: await (agent ?? signer).signTypedData(exitTypedData(chain, { account, to: account, ...exit })) };
             deadline = issued + 600;
         }
         // The venue requires the payout to outlive the vault leg by 300 s; a minute more absorbs clock skew.
@@ -1065,7 +1179,7 @@ export function createTotalis(options) {
         const to = address(route.router_address.toLowerCase());
         // A minute inside the venue's maximum life absorbs clock skew.
         const exit = { amount: BigInt(request.amount).toString(), expiry: String(now() + Math.min(route.maximum_life_seconds - 60, 600)), salt: BigInt(randomBytes32()).toString() };
-        const signature = await signer.signTypedData(exitTypedData(chain, { account, to, ...exit }));
+        const signature = await (agent ?? signer).signTypedData(exitTypedData(chain, { account, to, ...exit }));
         const body = envelope({ account, to, ...exit, signature, purpose: request.purpose ?? "ORDER", ...(request.activationFeeAccepted ? { activation_fee_accepted: true } : {}) });
         return { exitId, account, body };
     }
@@ -1190,6 +1304,36 @@ export function createTotalis(options) {
             throw new Error(`core exit ${exitId} ended ${exit.status}, not credited on HyperCore`);
         return exit;
     }
+    /**
+     * Grant `agent`, a key one of the account's devices holds, as a vault agent
+     * until `validUntil` (unix seconds, at most 180 days away): the account's
+     * `signer` signs the AgentGrant and Totalis relays it to the vault, paying
+     * the gas. Pass that key as `agent` to sign accepts, cash-outs and Exits
+     * back to the account without a wallet prompt. The nonce defaults to the
+     * venue's clock in seconds, and rises past this client's last grant, so a
+     * later grant or revoke supersedes an earlier one. The
+     * 202 is admission: follow `operation_id` with `waitForOperation`; the agent
+     * signs once it lands. A resend of the same `idempotencyKey` returns the
+     * same operation.
+     */
+    async function grantVaultAgent(request) {
+        const signer = await requireSigner();
+        const account = address((await signer.address()).toLowerCase());
+        const agentAddress = address(request.agent.toLowerCase());
+        const grant = { account, agent: agentAddress, valid_until: String(request.validUntil), nonce: grantNonce(agentAddress, request.nonce) };
+        const signature = await signer.signTypedData(agentGrantTypedData(await deployment(), grant));
+        const key = request.idempotencyKey ?? uuidv7();
+        return sendOnce(() => client.POST("/v1/me/vault-agents", { params: { header: idempotency(key) },
+            body: { agent: grant.agent, valid_until: grant.valid_until, nonce: grant.nonce, signature } }));
+    }
+    /** The agent keeps signing until the revoke's operation lands; `waitForOperation` before treating it as gone. */
+    function revokeVaultAgent(request) {
+        return grantVaultAgent({ ...request, validUntil: 0 });
+    }
+    /** The account's live vault agents, every page; `copy_agent` marks a Combo copy agent's key. */
+    function vaultAgents(limit = 200) {
+        return items((query) => client.GET("/v1/me/vault-agents", { params: { query: { ...query, limit } } }).then(unwrap), (page) => page.agents);
+    }
     /**
      * The transactions a wallet sends itself to deposit USDC from HyperEVM into
      * its vault balance, paying its own gas: approve the vault for `amount`, then
@@ -1218,6 +1362,7 @@ export function createTotalis(options) {
         spendableCash: readSpendableCash,
         openPosition,
         cashOut,
+        prepareEntryFunding,
         signEntry,
         signCashout,
         sendAcceptance,
@@ -1239,6 +1384,9 @@ export function createTotalis(options) {
         sendReturnToCore,
         returnToCore,
         directDepositCalls,
+        grantVaultAgent,
+        revokeVaultAgent,
+        vaultAgents,
         /** Render an RFQ's live quotes (entry or cash-out) from the stream; `[]` while the stream is down. */
         watchQuotes,
         /** Issue a personal `ttk_` key; the signer must be the account wallet (embedded, or a wallet-only account's own). */

package/dist/typed-data.d.ts

@@ -127,15 +127,34 @@ export declare const totalisTypes: {
         readonly name: "salt";
         readonly type: "uint256";
     }];
+    readonly AgentGrant: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }, {
+        readonly name: "agent";
+        readonly type: "address";
+    }, {
+        readonly name: "validUntil";
+        readonly type: "uint64";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint64";
+    }];
 };
 export type TotalisPrimaryType = Exclude<keyof typeof totalisTypes, "Leg">;
-/** Who signs each struct: the maker's signer, the taker's signer, or either side of a cash-out. */
+/**
+ * Who signs each struct: the maker's signer, the taker's signer, or either
+ * side of a cash-out. A vault agent the account granted may sign the taker's
+ * TakerAccept, SellBack and CashoutTransfer, and an Exit back to the account;
+ * only the account itself signs an AgentGrant.
+ */
 export declare const signedBy: {
     readonly Quote: "maker";
     readonly TakerAccept: "taker";
     readonly SellBack: "maker_and_taker";
     readonly CashoutTransfer: "maker_and_taker";
     readonly Exit: "taker";
+    readonly AgentGrant: "taker";
 };
 /** The vault deployment a signature binds to: GET /v1/deployment. */
 export type TotalisDeployment = Pick<Schemas["Deployment"], "chain_id" | "vault_address">;
@@ -201,6 +220,17 @@ export declare function exitTypedData(deployment: TotalisDeployment, exit: {
     expiry: string;
     salt: string;
 }): TotalisTypedData<"Exit">;
+/**
+ * The account's grant to a vault agent: a key it holds signs for the account
+ * until `valid_until` (unix seconds, at most 180 days away; 0 revokes). The
+ * nonce must exceed the agent's last grant. Relay it with POST /v1/me/vault-agents.
+ */
+export declare function agentGrantTypedData(deployment: TotalisDeployment, grant: {
+    account: Hex;
+    agent: Hex;
+    valid_until: string;
+    nonce: string;
+}): TotalisTypedData<"AgentGrant">;
 export declare const domainTypes: {
     readonly EIP712Domain: readonly [{
         readonly name: "name";

package/dist/typed-data.js

@@ -47,14 +47,26 @@ export const totalisTypes = {
         { name: "expiry", type: "uint64" },
         { name: "salt", type: "uint256" },
     ],
+    AgentGrant: [
+        { name: "account", type: "address" },
+        { name: "agent", type: "address" },
+        { name: "validUntil", type: "uint64" },
+        { name: "nonce", type: "uint64" },
+    ],
 };
-/** Who signs each struct: the maker's signer, the taker's signer, or either side of a cash-out. */
+/**
+ * Who signs each struct: the maker's signer, the taker's signer, or either
+ * side of a cash-out. A vault agent the account granted may sign the taker's
+ * TakerAccept, SellBack and CashoutTransfer, and an Exit back to the account;
+ * only the account itself signs an AgentGrant.
+ */
 export const signedBy = {
     Quote: "maker",
     TakerAccept: "taker",
     SellBack: "maker_and_taker",
     CashoutTransfer: "maker_and_taker",
     Exit: "taker",
+    AgentGrant: "taker",
 };
 /** A 20-byte hex address, or a TypeError. */
 export function address(value) {
@@ -122,6 +134,17 @@ export function exitTypedData(deployment, exit) {
         message: { account: exit.account, to: exit.to, amount: BigInt(exit.amount), expiry: BigInt(exit.expiry), salt: BigInt(exit.salt) },
     };
 }
+/**
+ * The account's grant to a vault agent: a key it holds signs for the account
+ * until `valid_until` (unix seconds, at most 180 days away; 0 revokes). The
+ * nonce must exceed the agent's last grant. Relay it with POST /v1/me/vault-agents.
+ */
+export function agentGrantTypedData(deployment, grant) {
+    return {
+        domain: domain(deployment), types: { AgentGrant: totalisTypes.AgentGrant }, primaryType: "AgentGrant",
+        message: { account: address(grant.account), agent: address(grant.agent), validUntil: BigInt(grant.valid_until), nonce: BigInt(grant.nonce) },
+    };
+}
 // ---------------------------------------------------------------------------
 // EIP-712 hashing, so makers can compute quote_digest and every signer can be
 // checked against the contract's vectors without a wallet library.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalis/hip4-client",
-  "version": "0.75.0",
+  "version": "0.77.0",
   "description": "Totalis HIP-4 SDK: typed HTTP clients, signer-agnostic typed data, a retrying request layer, pagination, a realtime stream and taker/maker flows",
   "type": "module",
   "files": [